1 // 2 // 3 // Copyright 2018 gRPC authors. 4 // 5 // Licensed under the Apache License, Version 2.0 (the "License"); 6 // you may not use this file except in compliance with the License. 7 // You may obtain a copy of the License at 8 // 9 // http://www.apache.org/licenses/LICENSE-2.0 10 // 11 // Unless required by applicable law or agreed to in writing, software 12 // distributed under the License is distributed on an "AS IS" BASIS, 13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 // See the License for the specific language governing permissions and 15 // limitations under the License. 16 // 17 // 18 19 #ifndef GRPC_SRC_CORE_TSI_ALTS_HANDSHAKER_ALTS_HANDSHAKER_CLIENT_H 20 #define GRPC_SRC_CORE_TSI_ALTS_HANDSHAKER_ALTS_HANDSHAKER_CLIENT_H 21 22 #include <grpc/support/port_platform.h> 23 24 #include <grpc/byte_buffer.h> 25 #include <grpc/byte_buffer_reader.h> 26 #include <grpc/grpc.h> 27 28 #include "src/core/lib/iomgr/closure.h" 29 #include "src/core/lib/iomgr/pollset_set.h" 30 #include "src/core/tsi/alts/handshaker/alts_tsi_handshaker.h" 31 #include "src/core/tsi/transport_security_interface.h" 32 33 #define ALTS_SERVICE_METHOD "/grpc.gcp.HandshakerService/DoHandshake" 34 #define ALTS_APPLICATION_PROTOCOL "grpc" 35 #define ALTS_RECORD_PROTOCOL "ALTSRP_GCM_AES128_REKEY" 36 #define ALTS_HANDSHAKER_SERVICE_URL_FOR_TESTING "lame" 37 38 const size_t kAltsAes128GcmRekeyKeyLength = 44; 39 40 typedef struct alts_tsi_handshaker alts_tsi_handshaker; 41 /// 42 /// A ALTS handshaker client interface. It is used to communicate with 43 /// ALTS handshaker service by scheduling a handshaker request that could be one 44 /// of client_start, server_start, and next handshaker requests. All APIs in the 45 /// header are thread-compatible. 46 /// 47 typedef struct alts_handshaker_client alts_handshaker_client; 48 49 // A function that makes the grpc call to the handshaker service. 50 typedef grpc_call_error (*alts_grpc_caller)(grpc_call* call, const grpc_op* ops, 51 size_t nops, grpc_closure* tag); 52 53 // V-table for ALTS handshaker client operations. 54 typedef struct alts_handshaker_client_vtable { 55 tsi_result (*client_start)(alts_handshaker_client* client); 56 tsi_result (*server_start)(alts_handshaker_client* client, 57 grpc_slice* bytes_received); 58 tsi_result (*next)(alts_handshaker_client* client, 59 grpc_slice* bytes_received); 60 void (*shutdown)(alts_handshaker_client* client); 61 void (*destruct)(alts_handshaker_client* client); 62 } alts_handshaker_client_vtable; 63 64 /// 65 /// This method schedules a client_start handshaker request to ALTS handshaker 66 /// service. 67 /// 68 ///- client: ALTS handshaker client instance. 69 /// 70 /// It returns TSI_OK on success and an error status code on failure. 71 /// 72 tsi_result alts_handshaker_client_start_client(alts_handshaker_client* client); 73 74 /// 75 /// This method schedules a server_start handshaker request to ALTS handshaker 76 /// service. 77 /// 78 ///- client: ALTS handshaker client instance. 79 ///- bytes_received: bytes in out_frames returned from the peer's handshaker 80 /// response. 81 /// 82 /// It returns TSI_OK on success and an error status code on failure. 83 /// 84 tsi_result alts_handshaker_client_start_server(alts_handshaker_client* client, 85 grpc_slice* bytes_received); 86 87 /// 88 /// This method schedules a next handshaker request to ALTS handshaker service. 89 /// 90 ///- client: ALTS handshaker client instance. 91 ///- bytes_received: bytes in out_frames returned from the peer's handshaker 92 /// response. 93 /// 94 /// It returns TSI_OK on success and an error status code on failure. 95 /// 96 tsi_result alts_handshaker_client_next(alts_handshaker_client* client, 97 grpc_slice* bytes_received); 98 99 /// 100 /// This method cancels previously scheduled, but yet executed handshaker 101 /// requests to ALTS handshaker service. After this operation, the handshake 102 /// will be shutdown, and no more handshaker requests will get scheduled. 103 /// 104 ///- client: ALTS handshaker client instance. 105 /// 106 void alts_handshaker_client_shutdown(alts_handshaker_client* client); 107 108 /// 109 /// This method destroys an ALTS handshaker client. 110 /// 111 ///- client: an ALTS handshaker client instance. 112 /// 113 void alts_handshaker_client_destroy(alts_handshaker_client* client); 114 115 /// 116 /// This method creates an ALTS handshaker client. 117 /// 118 ///- handshaker: ALTS TSI handshaker to which the created handshaker client 119 /// belongs to. 120 ///- channel: grpc channel to ALTS handshaker service. 121 ///- handshaker_service_url: address of ALTS handshaker service in the format of 122 /// "host:port". 123 ///- interested_parties: set of pollsets interested in this connection. 124 ///- options: ALTS credentials options containing information passed from TSI 125 /// caller (e.g., rpc protocol versions) 126 ///- target_name: the name of the endpoint that the channel is connecting to, 127 /// and will be used for secure naming check 128 ///- grpc_cb: gRPC provided callbacks passed from TSI handshaker. 129 ///- cb: callback to be executed when tsi_handshaker_next API compltes. 130 ///- user_data: argument passed to cb. 131 ///- vtable_for_testing: ALTS handshaker client vtable instance used for 132 /// testing purpose. 133 ///- is_client: a boolean value indicating if the created handshaker client is 134 /// used at the client (is_client = true) or server (is_client = false) side. 135 ///- max_frame_size: Maximum frame size used by frame protector (User specified 136 /// maximum frame size if present or default max frame size). 137 /// 138 /// It returns the created ALTS handshaker client on success, and NULL 139 /// on failure. 140 /// 141 alts_handshaker_client* alts_grpc_handshaker_client_create( 142 alts_tsi_handshaker* handshaker, grpc_channel* channel, 143 const char* handshaker_service_url, grpc_pollset_set* interested_parties, 144 grpc_alts_credentials_options* options, const grpc_slice& target_name, 145 grpc_iomgr_cb_func grpc_cb, tsi_handshaker_on_next_done_cb cb, 146 void* user_data, alts_handshaker_client_vtable* vtable_for_testing, 147 bool is_client, size_t max_frame_size, std::string* error); 148 149 /// 150 /// This method handles handshaker response returned from ALTS handshaker 151 /// service. Note that the only reason the API is exposed is that it is used in 152 /// alts_shared_resources.cc. 153 /// 154 ///- client: an ALTS handshaker client instance. 155 ///- is_ok: a boolean value indicating if the handshaker response is ok to read. 156 /// 157 void alts_handshaker_client_handle_response(alts_handshaker_client* client, 158 bool is_ok); 159 160 // Returns the max number of concurrent handshakes that are permitted. 161 // 162 // Exposed for testing purposes only. 163 size_t MaxNumberOfConcurrentHandshakes(); 164 165 #endif // GRPC_SRC_CORE_TSI_ALTS_HANDSHAKER_ALTS_HANDSHAKER_CLIENT_H 166