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_CORE_TSI_ALTS_HANDSHAKER_ALTS_HANDSHAKER_SERVICE_API_H 20 #define GRPC_CORE_TSI_ALTS_HANDSHAKER_ALTS_HANDSHAKER_SERVICE_API_H 21 22 #include <grpc/support/port_platform.h> 23 24 #include "src/core/tsi/alts/handshaker/alts_handshaker_service_api_util.h" 25 26 /** 27 * An implementation of nanopb thin wrapper used to set/get and 28 * serialize/de-serialize of ALTS handshake requests and responses. 29 * 30 * All APIs in the header are thread-compatible. A typical usage of this API at 31 * the client side is as follows: 32 * 33 * ----------------------------------------------------------------------------- 34 * // Create, populate, and serialize an ALTS client_start handshake request to 35 * // send to the server. 36 * grpc_gcp_handshaker_req* req = 37 * grpc_gcp_handshaker_req_create(CLIENT_START_REQ); 38 * grpc_gcp_handshaker_req_set_handshake_protocol( 39 req, grpc_gcp_HandshakeProtocol_ALTS); 40 * grpc_gcp_handshaker_req_add_application_protocol(req, "grpc"); 41 * grpc_gcp_handshaker_req_add_record_protocol(req, "ALTSRP_GCM_AES128"); 42 * grpc_slice client_slice; 43 * if (!grpc_gcp_handshaker_req_encode(req, &client_slice)) { 44 * fprintf(stderr, "ALTS handshake request encoding failed."; 45 * } 46 * 47 * // De-serialize a data stream received from the server, and store the result 48 * // at ALTS handshake response. 49 * grpc_gcp_handshaker_resp* resp = grpc_gcp_handshaker_resp_create(); 50 * if (!grpc_gcp_handshaker_resp_decode(server_slice, resp)) { 51 * fprintf(stderr, "ALTS handshake response decoding failed."); 52 * } 53 * // To access a variable-length datatype field (i.e., pb_callback_t), 54 * // access its "arg" subfield (if it has been set). 55 * if (resp->out_frames.arg != nullptr) { 56 * grpc_slice* slice = resp->out_frames.arg; 57 * } 58 * // To access a fixed-length datatype field (i.e., not pb_calback_t), 59 * // access the field directly (if it has been set). 60 * if (resp->has_status && resp->status->has_code) { 61 * uint32_t code = resp->status->code; 62 * } 63 *------------------------------------------------------------------------------ 64 */ 65 66 /** 67 * This method creates an ALTS handshake request. 68 * 69 * - type: an enum type value that can be either CLIENT_START_REQ, 70 * SERVER_START_REQ, or NEXT_REQ to indicate the created instance will be 71 * client_start, server_start, and next handshake request message 72 * respectively. 73 * 74 * The method returns a pointer to the created instance. 75 */ 76 grpc_gcp_handshaker_req* grpc_gcp_handshaker_req_create( 77 grpc_gcp_handshaker_req_type type); 78 79 /** 80 * This method sets the value for handshake_security_protocol field of ALTS 81 * client_start handshake request. 82 * 83 * - req: an ALTS handshake request. 84 * - handshake_protocol: a enum type value representing the handshake security 85 * protocol. 86 * 87 * The method returns true on success and false otherwise. 88 */ 89 bool grpc_gcp_handshaker_req_set_handshake_protocol( 90 grpc_gcp_handshaker_req* req, 91 grpc_gcp_handshake_protocol handshake_protocol); 92 93 /** 94 * This method sets the value for target_name field of ALTS client_start 95 * handshake request. 96 * 97 * - req: an ALTS handshake request. 98 * - target_name: a target name to be set. 99 * 100 * The method returns true on success and false otherwise. 101 */ 102 bool grpc_gcp_handshaker_req_set_target_name(grpc_gcp_handshaker_req* req, 103 const char* target_name); 104 105 /** 106 * This method adds an application protocol supported by the server (or 107 * client) to ALTS server_start (or client_start) handshake request. 108 * 109 * - req: an ALTS handshake request. 110 * - application_protocol: an application protocol (e.g., grpc) to be added. 111 * 112 * The method returns true on success and false otherwise. 113 */ 114 bool grpc_gcp_handshaker_req_add_application_protocol( 115 grpc_gcp_handshaker_req* req, const char* application_protocol); 116 117 /** 118 * This method adds a record protocol supported by the client to ALTS 119 * client_start handshake request. 120 * 121 * - req: an ALTS handshake request. 122 * - record_protocol: a record protocol (e.g., ALTSRP_GCM_AES128) to be 123 * added. 124 * 125 * The method returns true on success and false otherwise. 126 */ 127 bool grpc_gcp_handshaker_req_add_record_protocol(grpc_gcp_handshaker_req* req, 128 const char* record_protocol); 129 130 /** 131 * This method adds a target server identity represented as hostname and 132 * acceptable by a client to ALTS client_start handshake request. 133 * 134 * - req: an ALTS handshake request. 135 * - hostname: a string representation of hostname at the connection 136 * endpoint to be added. 137 * 138 * The method returns true on success and false otherwise. 139 */ 140 bool grpc_gcp_handshaker_req_add_target_identity_hostname( 141 grpc_gcp_handshaker_req* req, const char* hostname); 142 143 /** 144 * This method adds a target server identity represented as service account and 145 * acceptable by a client to ALTS client_start handshake request. 146 * 147 * - req: an ALTS handshake request. 148 * - service_account: a string representation of service account at the 149 * connection endpoint to be added. 150 * 151 * The method returns true on success and false otherwise. 152 */ 153 bool grpc_gcp_handshaker_req_add_target_identity_service_account( 154 grpc_gcp_handshaker_req* req, const char* service_account); 155 156 /** 157 * This method sets the hostname for local_identity field of ALTS client_start 158 * handshake request. 159 * 160 * - req: an ALTS handshake request. 161 * - hostname: a string representation of hostname. 162 * 163 * The method returns true on success and false otherwise. 164 */ 165 bool grpc_gcp_handshaker_req_set_local_identity_hostname( 166 grpc_gcp_handshaker_req* req, const char* hostname); 167 168 /** 169 * This method sets the service account for local_identity field of ALTS 170 * client_start handshake request. 171 * 172 * - req: an ALTS handshake request. 173 * - service_account: a string representation of service account. 174 * 175 * The method returns true on success and false otherwise. 176 */ 177 bool grpc_gcp_handshaker_req_set_local_identity_service_account( 178 grpc_gcp_handshaker_req* req, const char* service_account); 179 180 /** 181 * This method sets the value for local_endpoint field of either ALTS 182 * client_start or server_start handshake request. 183 * 184 * - req: an ALTS handshake request. 185 * - ip_address: a string representation of ip address associated with the 186 * local endpoint, that could be either IPv4 or IPv6. 187 * - port: a port number associated with the local endpoint. 188 * - protocol: a network protocol (e.g., TCP or UDP) associated with the 189 * local endpoint. 190 * 191 * The method returns true on success and false otherwise. 192 */ 193 bool grpc_gcp_handshaker_req_set_local_endpoint( 194 grpc_gcp_handshaker_req* req, const char* ip_address, size_t port, 195 grpc_gcp_network_protocol protocol); 196 197 /** 198 * This method sets the value for remote_endpoint field of either ALTS 199 * client_start or server_start handshake request. 200 * 201 * - req: an ALTS handshake request. 202 * - ip_address: a string representation of ip address associated with the 203 * remote endpoint, that could be either IPv4 or IPv6. 204 * - port: a port number associated with the remote endpoint. 205 * - protocol: a network protocol (e.g., TCP or UDP) associated with the 206 * remote endpoint. 207 * 208 * The method returns true on success and false otherwise. 209 */ 210 bool grpc_gcp_handshaker_req_set_remote_endpoint( 211 grpc_gcp_handshaker_req* req, const char* ip_address, size_t port, 212 grpc_gcp_network_protocol protocol); 213 214 /** 215 * This method sets the value for in_bytes field of either ALTS server_start or 216 * next handshake request. 217 * 218 * - req: an ALTS handshake request. 219 * - in_bytes: a buffer containing bytes taken from out_frames of the peer's 220 * ALTS handshake response. It is possible that the peer's out_frames are 221 * split into multiple handshake request messages. 222 * - size: size of in_bytes buffer. 223 * 224 * The method returns true on success and false otherwise. 225 */ 226 bool grpc_gcp_handshaker_req_set_in_bytes(grpc_gcp_handshaker_req* req, 227 const char* in_bytes, size_t size); 228 229 /** 230 * This method adds a record protocol to handshake parameters mapped by the 231 * handshake protocol for ALTS server_start handshake request. 232 * 233 * - req: an ALTS handshake request. 234 * - key: an enum type value representing a handshake security protocol. 235 * - record_protocol: a record protocol to be added. 236 * 237 * The method returns true on success and false otherwise. 238 */ 239 bool grpc_gcp_handshaker_req_param_add_record_protocol( 240 grpc_gcp_handshaker_req* req, grpc_gcp_handshake_protocol key, 241 const char* record_protocol); 242 243 /** 244 * This method adds a local identity represented as hostname to handshake 245 * parameters mapped by the handshake protocol for ALTS server_start handshake 246 * request. 247 * 248 * - req: an ALTS handshake request. 249 * - key: an enum type value representing a handshake security protocol. 250 * - hostname: a string representation of hostname to be added. 251 * 252 * The method returns true on success and false otherwise. 253 */ 254 bool grpc_gcp_handshaker_req_param_add_local_identity_hostname( 255 grpc_gcp_handshaker_req* req, grpc_gcp_handshake_protocol key, 256 const char* hostname); 257 258 /** 259 * This method adds a local identity represented as service account to handshake 260 * parameters mapped by the handshake protocol for ALTS server_start handshake 261 * request. 262 * 263 * - req: an ALTS handshake request. 264 * - key: an enum type value representing a handshake security protocol. 265 * - service_account: a string representation of service account to be added. 266 * 267 * The method returns true on success and false otherwise. 268 */ 269 bool grpc_gcp_handshaker_req_param_add_local_identity_service_account( 270 grpc_gcp_handshaker_req* req, grpc_gcp_handshake_protocol key, 271 const char* service_account); 272 273 /** 274 * This method sets the value for rpc_versions field of either ALTS 275 * client_start or server_start handshake request. 276 * 277 * - req: an ALTS handshake request. 278 * - max_major: a major version of maximum supported RPC version. 279 * - max_minor: a minor version of maximum supported RPC version. 280 * - min_major: a major version of minimum supported RPC version. 281 * - min_minor: a minor version of minimum supported RPC version. 282 * 283 * The method returns true on success and false otherwise. 284 */ 285 bool grpc_gcp_handshaker_req_set_rpc_versions(grpc_gcp_handshaker_req* req, 286 uint32_t max_major, 287 uint32_t max_minor, 288 uint32_t min_major, 289 uint32_t min_minor); 290 291 /** 292 * This method serializes an ALTS handshake request and returns a data stream. 293 * 294 * - req: an ALTS handshake request. 295 * - slice: a data stream where the serialized result will be written. 296 * 297 * The method returns true on success and false otherwise. 298 */ 299 bool grpc_gcp_handshaker_req_encode(grpc_gcp_handshaker_req* req, 300 grpc_slice* slice); 301 302 /* This method destroys an ALTS handshake request. */ 303 void grpc_gcp_handshaker_req_destroy(grpc_gcp_handshaker_req* req); 304 305 /* This method creates an ALTS handshake response. */ 306 grpc_gcp_handshaker_resp* grpc_gcp_handshaker_resp_create(void); 307 308 /** 309 * This method de-serializes a data stream and stores the result 310 * in an ALTS handshake response. 311 * 312 * - slice: a data stream containing a serialized ALTS handshake response. 313 * - resp: an ALTS handshake response used to hold de-serialized result. 314 * 315 * The method returns true on success and false otherwise. 316 */ 317 bool grpc_gcp_handshaker_resp_decode(grpc_slice slice, 318 grpc_gcp_handshaker_resp* resp); 319 320 /* This method destroys an ALTS handshake response. */ 321 void grpc_gcp_handshaker_resp_destroy(grpc_gcp_handshaker_resp* resp); 322 323 #endif /* GRPC_CORE_TSI_ALTS_HANDSHAKER_ALTS_HANDSHAKER_SERVICE_API_H */ 324