• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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