• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  *
3  * Copyright 2015 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_TRANSPORT_SECURITY_INTERFACE_H
20 #define GRPC_CORE_TSI_TRANSPORT_SECURITY_INTERFACE_H
21 
22 #include <grpc/support/port_platform.h>
23 
24 #include <stdint.h>
25 #include <stdlib.h>
26 
27 #include "src/core/lib/debug/trace.h"
28 
29 /* --- tsi result ---  */
30 
31 typedef enum {
32   TSI_OK = 0,
33   TSI_UNKNOWN_ERROR = 1,
34   TSI_INVALID_ARGUMENT = 2,
35   TSI_PERMISSION_DENIED = 3,
36   TSI_INCOMPLETE_DATA = 4,
37   TSI_FAILED_PRECONDITION = 5,
38   TSI_UNIMPLEMENTED = 6,
39   TSI_INTERNAL_ERROR = 7,
40   TSI_DATA_CORRUPTED = 8,
41   TSI_NOT_FOUND = 9,
42   TSI_PROTOCOL_FAILURE = 10,
43   TSI_HANDSHAKE_IN_PROGRESS = 11,
44   TSI_OUT_OF_RESOURCES = 12,
45   TSI_ASYNC = 13,
46   TSI_HANDSHAKE_SHUTDOWN = 14,
47 } tsi_result;
48 
49 typedef enum {
50   // Default option
51   TSI_DONT_REQUEST_CLIENT_CERTIFICATE,
52   TSI_REQUEST_CLIENT_CERTIFICATE_BUT_DONT_VERIFY,
53   TSI_REQUEST_CLIENT_CERTIFICATE_AND_VERIFY,
54   TSI_REQUEST_AND_REQUIRE_CLIENT_CERTIFICATE_BUT_DONT_VERIFY,
55   TSI_REQUEST_AND_REQUIRE_CLIENT_CERTIFICATE_AND_VERIFY,
56 } tsi_client_certificate_request_type;
57 
58 const char* tsi_result_to_string(tsi_result result);
59 
60 /* --- tsi tracing --- */
61 
62 extern grpc_core::TraceFlag tsi_tracing_enabled;
63 
64 /* -- tsi_zero_copy_grpc_protector object --
65 
66   This object protects and unprotects grpc slice buffers with zero or minimized
67   memory copy once the handshake is done. Implementations of this object must be
68   thread compatible. This object depends on grpc and the details of this object
69   is defined in transport_security_grpc.h.  */
70 
71 typedef struct tsi_zero_copy_grpc_protector tsi_zero_copy_grpc_protector;
72 
73 /* --- tsi_frame_protector object ---
74 
75   This object protects and unprotects buffers once the handshake is done.
76   Implementations of this object must be thread compatible.  */
77 
78 typedef struct tsi_frame_protector tsi_frame_protector;
79 
80 /* Outputs protected frames.
81    - unprotected_bytes is an input only parameter and points to the data
82      to be protected.
83    - unprotected_bytes_size is an input/output parameter used by the caller to
84      specify how many bytes are available in unprotected_bytes. The output
85      value is the number of bytes consumed during the call.
86    - protected_output_frames points to a buffer allocated by the caller that
87      will be written.
88    - protected_output_frames_size is an input/output parameter used by the
89      caller to specify how many bytes are available in protected_output_frames.
90      As an output, this value indicates the number of bytes written.
91    - This method returns TSI_OK in case of success or a specific error code in
92      case of failure. Note that even if all the input unprotected bytes are
93      consumed, they may not have been processed into the returned protected
94      output frames. The caller should call the protect_flush method
95      to make sure that there are no more protected bytes buffered in the
96      protector.
97 
98    A typical way to call this method would be:
99 
100    ------------------------------------------------------------------------
101    unsigned char protected_buffer[4096];
102    size_t protected_buffer_size = sizeof(protected_buffer);
103    tsi_result result = TSI_OK;
104    while (message_size > 0) {
105      size_t protected_buffer_size_to_send = protected_buffer_size;
106      size_t processed_message_size = message_size;
107      result = tsi_frame_protector_protect(protector,
108                                           message_bytes,
109                                           &processed_message_size,
110                                           protected_buffer,
111                                           &protected_buffer_size_to_send);
112      if (result != TSI_OK) break;
113      send_bytes_to_peer(protected_buffer, protected_buffer_size_to_send);
114      message_bytes += processed_message_size;
115      message_size -= processed_message_size;
116 
117      // Don't forget to flush.
118      if (message_size == 0) {
119        size_t still_pending_size;
120        do {
121          protected_buffer_size_to_send = protected_buffer_size;
122          result = tsi_frame_protector_protect_flush(
123              protector, protected_buffer,
124              &protected_buffer_size_to_send, &still_pending_size);
125          if (result != TSI_OK) break;
126          send_bytes_to_peer(protected_buffer, protected_buffer_size_to_send);
127        } while (still_pending_size > 0);
128      }
129    }
130 
131    if (result != TSI_OK) HandleError(result);
132    ------------------------------------------------------------------------  */
133 tsi_result tsi_frame_protector_protect(tsi_frame_protector* self,
134                                        const unsigned char* unprotected_bytes,
135                                        size_t* unprotected_bytes_size,
136                                        unsigned char* protected_output_frames,
137                                        size_t* protected_output_frames_size);
138 
139 /* Indicates that we need to flush the bytes buffered in the protector and get
140    the resulting frame.
141    - protected_output_frames points to a buffer allocated by the caller that
142      will be written.
143    - protected_output_frames_size is an input/output parameter used by the
144      caller to specify how many bytes are available in protected_output_frames.
145    - still_pending_bytes is an output parameter indicating the number of bytes
146      that still need to be flushed from the protector.*/
147 tsi_result tsi_frame_protector_protect_flush(
148     tsi_frame_protector* self, unsigned char* protected_output_frames,
149     size_t* protected_output_frames_size, size_t* still_pending_size);
150 
151 /* Outputs unprotected bytes.
152    - protected_frames_bytes is an input only parameter and points to the
153      protected frames to be unprotected.
154    - protected_frames_bytes_size is an input/output only parameter used by the
155      caller to specify how many bytes are available in protected_bytes. The
156      output value is the number of bytes consumed during the call.
157      Implementations will buffer up to a frame of protected data.
158    - unprotected_bytes points to a buffer allocated by the caller that will be
159      written.
160    - unprotected_bytes_size is an input/output parameter used by the caller to
161      specify how many bytes are available in unprotected_bytes. This
162      value is expected to be at most max_protected_frame_size minus overhead
163      which means that max_protected_frame_size is a safe bet. The output value
164      is the number of bytes actually written.
165      If *unprotected_bytes_size is unchanged, there may be more data remaining
166      to unprotect, and the caller should call this function again.
167 
168    - This method returns TSI_OK in case of success. Success includes cases where
169      there is not enough data to output a frame in which case
170      unprotected_bytes_size will be set to 0 and cases where the internal buffer
171      needs to be read before new protected data can be processed in which case
172      protected_frames_size will be set to 0.  */
173 tsi_result tsi_frame_protector_unprotect(
174     tsi_frame_protector* self, const unsigned char* protected_frames_bytes,
175     size_t* protected_frames_bytes_size, unsigned char* unprotected_bytes,
176     size_t* unprotected_bytes_size);
177 
178 /* Destroys the tsi_frame_protector object.  */
179 void tsi_frame_protector_destroy(tsi_frame_protector* self);
180 
181 /* --- tsi_peer objects ---
182 
183    tsi_peer objects are a set of properties. The peer owns the properties.  */
184 
185 /* This property is of type TSI_PEER_PROPERTY_STRING.  */
186 #define TSI_CERTIFICATE_TYPE_PEER_PROPERTY "certificate_type"
187 
188 /* Property values may contain NULL characters just like C++ strings.
189    The length field gives the length of the string. */
190 typedef struct tsi_peer_property {
191   char* name;
192   struct {
193     char* data;
194     size_t length;
195   } value;
196 } tsi_peer_property;
197 
198 typedef struct {
199   tsi_peer_property* properties;
200   size_t property_count;
201 } tsi_peer;
202 
203 /* Destructs the tsi_peer object. */
204 void tsi_peer_destruct(tsi_peer* self);
205 
206 /*  --- tsi_handshaker_result object ---
207 
208   This object contains all necessary handshake results and data such as peer
209   info, negotiated keys, unused handshake bytes, when the handshake completes.
210   Implementations of this object must be thread compatible.  */
211 
212 typedef struct tsi_handshaker_result tsi_handshaker_result;
213 
214 /* This method extracts tsi peer. It returns TSI_OK assuming there is no fatal
215    error.
216    The caller is responsible for destructing the peer.  */
217 tsi_result tsi_handshaker_result_extract_peer(const tsi_handshaker_result* self,
218                                               tsi_peer* peer);
219 
220 /* This method creates a tsi_frame_protector object. It returns TSI_OK assuming
221    there is no fatal error.
222    The caller is responsible for destroying the protector.  */
223 tsi_result tsi_handshaker_result_create_frame_protector(
224     const tsi_handshaker_result* self, size_t* max_output_protected_frame_size,
225     tsi_frame_protector** protector);
226 
227 /* This method returns the unused bytes from the handshake. It returns TSI_OK
228    assuming there is no fatal error.
229    Ownership of the bytes is retained by the handshaker result. As a
230    consequence, the caller must not free the bytes.  */
231 tsi_result tsi_handshaker_result_get_unused_bytes(
232     const tsi_handshaker_result* self, const unsigned char** bytes,
233     size_t* byte_size);
234 
235 /* This method releases the tsi_handshaker_handshaker object. After this method
236    is called, no other method can be called on the object.  */
237 void tsi_handshaker_result_destroy(tsi_handshaker_result* self);
238 
239 /* --- tsi_handshaker objects ----
240 
241    Implementations of this object must be thread compatible.
242 
243    ------------------------------------------------------------------------
244 
245    A typical usage supporting both synchronous and asynchronous TSI handshaker
246    implementations would be:
247 
248    ------------------------------------------------------------------------
249 
250    typedef struct {
251      tsi_handshaker *handshaker;
252      tsi_handshaker_result *handshaker_result;
253      unsigned char *handshake_buffer;
254      size_t handshake_buffer_size;
255      ...
256    } security_handshaker;
257 
258    void do_handshake(security_handshaker *h, ...) {
259      // Start the handshake by the calling do_handshake_next.
260      do_handshake_next(h, NULL, 0);
261      ...
262    }
263 
264    // This method is the callback function when data is received from the
265    // peer. This method will read bytes into the handshake buffer and call
266    // do_handshake_next.
267    void on_handshake_data_received_from_peer(void *user_data) {
268      security_handshaker *h = (security_handshaker *)user_data;
269      size_t bytes_received_size = h->handshake_buffer_size;
270      read_bytes_from_peer(h->handshake_buffer, &bytes_received_size);
271      do_handshake_next(h, h->handshake_buffer, bytes_received_size);
272    }
273 
274    // This method processes a step of handshake, calling tsi_handshaker_next.
275    void do_handshake_next(security_handshaker *h,
276                           const unsigned char* bytes_received,
277                           size_t bytes_received_size) {
278      tsi_result status = TSI_OK;
279      unsigned char *bytes_to_send = NULL;
280      size_t bytes_to_send_size = 0;
281      tsi_handshaker_result *result = NULL;
282      status = tsi_handshaker_next(
283          handshaker, bytes_received, bytes_received_size, &bytes_to_send,
284          &bytes_to_send_size, &result, on_handshake_next_done, h);
285      // If TSI handshaker is asynchronous, on_handshake_next_done will be
286      // executed inside tsi_handshaker_next.
287      if (status == TSI_ASYNC) return;
288      // If TSI handshaker is synchronous, invoke callback directly in this
289      // thread.
290      on_handshake_next_done(status, (void *)h, bytes_to_send,
291                             bytes_to_send_size, result);
292    }
293 
294    // This is the callback function to execute after tsi_handshaker_next.
295    // It is passed to tsi_handshaker_next as a function parameter.
296    void on_handshake_next_done(
297        tsi_result status, void *user_data, const unsigned char *bytes_to_send,
298        size_t bytes_to_send_size, tsi_handshaker_result *result) {
299      security_handshaker *h = (security_handshaker *)user_data;
300      if (status == TSI_INCOMPLETE_DATA) {
301        // Schedule an asynchronous read from the peer. If handshake data are
302        // received, on_handshake_data_received_from_peer will be called.
303        async_read_from_peer(..., ..., on_handshake_data_received_from_peer);
304        return;
305      }
306      if (status != TSI_OK) return;
307 
308      if (bytes_to_send_size > 0) {
309        send_bytes_to_peer(bytes_to_send, bytes_to_send_size);
310      }
311 
312      if (result != NULL) {
313        // Handshake completed.
314        h->result = result;
315        // Check the Peer.
316        tsi_peer peer;
317        status = tsi_handshaker_result_extract_peer(result, &peer);
318        if (status != TSI_OK) return;
319        status = check_peer(&peer);
320        tsi_peer_destruct(&peer);
321        if (status != TSI_OK) return;
322 
323        // Create the protector.
324        tsi_frame_protector* protector = NULL;
325        status = tsi_handshaker_result_create_frame_protector(result, NULL,
326                                                              &protector);
327        if (status != TSI_OK) return;
328 
329        // Do not forget to unprotect outstanding data if any.
330        ....
331      }
332    }
333    ------------------------------------------------------------------------   */
334 typedef struct tsi_handshaker tsi_handshaker;
335 
336 /* TODO(jiangtaoli2016): Cleans up deprecated methods when we are ready. */
337 
338 /* TO BE DEPRECATED SOON. Use tsi_handshaker_next instead.
339    Gets bytes that need to be sent to the peer.
340    - bytes is the buffer that will be written with the data to be sent to the
341      peer.
342    - bytes_size is an input/output parameter specifying the capacity of the
343      bytes parameter as input and the number of bytes written as output.
344    Returns TSI_OK if all the data to send to the peer has been written or if
345    nothing has to be sent to the peer (in which base bytes_size outputs to 0),
346    otherwise returns TSI_INCOMPLETE_DATA which indicates that this method
347    needs to be called again to get all the bytes to send to the peer (there
348    was more data to write than the specified bytes_size). In case of a fatal
349    error in the handshake, another specific error code is returned.  */
350 tsi_result tsi_handshaker_get_bytes_to_send_to_peer(tsi_handshaker* self,
351                                                     unsigned char* bytes,
352                                                     size_t* bytes_size);
353 
354 /* TO BE DEPRECATED SOON. Use tsi_handshaker_next instead.
355    Processes bytes received from the peer.
356    - bytes is the buffer containing the data.
357    - bytes_size is an input/output parameter specifying the size of the data as
358      input and the number of bytes consumed as output.
359    Return TSI_OK if the handshake has all the data it needs to process,
360    otherwise return TSI_INCOMPLETE_DATA which indicates that this method
361    needs to be called again to complete the data needed for processing. In
362    case of a fatal error in the handshake, another specific error code is
363    returned.  */
364 tsi_result tsi_handshaker_process_bytes_from_peer(tsi_handshaker* self,
365                                                   const unsigned char* bytes,
366                                                   size_t* bytes_size);
367 
368 /* TO BE DEPRECATED SOON.
369    Gets the result of the handshaker.
370    Returns TSI_OK if the hanshake completed successfully and there has been no
371    errors. Returns TSI_HANDSHAKE_IN_PROGRESS if the handshaker is not done yet
372    but no error has been encountered so far. Otherwise the handshaker failed
373    with the returned error.  */
374 tsi_result tsi_handshaker_get_result(tsi_handshaker* self);
375 
376 /* TO BE DEPRECATED SOON.
377    Returns 1 if the handshake is in progress, 0 otherwise.  */
378 #define tsi_handshaker_is_in_progress(h) \
379   (tsi_handshaker_get_result((h)) == TSI_HANDSHAKE_IN_PROGRESS)
380 
381 /* TO BE DEPRECATED SOON. Use tsi_handshaker_result_extract_peer instead.
382    This method may return TSI_FAILED_PRECONDITION if
383    tsi_handshaker_is_in_progress returns 1, it returns TSI_OK otherwise
384    assuming the handshaker is not in a fatal error state.
385    The caller is responsible for destructing the peer.  */
386 tsi_result tsi_handshaker_extract_peer(tsi_handshaker* self, tsi_peer* peer);
387 
388 /* TO BE DEPRECATED SOON. Use tsi_handshaker_result_create_frame_protector
389    instead.
390    This method creates a tsi_frame_protector object after the handshake phase
391    is done. After this method has been called successfully, the only method
392    that can be called on this object is Destroy.
393    - max_output_protected_frame_size is an input/output parameter specifying the
394      desired max output protected frame size as input and outputing the actual
395      max output frame size as the output. Passing NULL is OK and will result in
396      the implementation choosing the default maximum protected frame size. Note
397      that this size only applies to outgoing frames (generated with
398      tsi_frame_protector_protect) and not incoming frames (input of
399      tsi_frame_protector_unprotect).
400    - protector is an output parameter pointing to the newly created
401      tsi_frame_protector object.
402    This method may return TSI_FAILED_PRECONDITION if
403    tsi_handshaker_is_in_progress returns 1, it returns TSI_OK otherwise assuming
404    the handshaker is not in a fatal error state.
405    The caller is responsible for destroying the protector.  */
406 tsi_result tsi_handshaker_create_frame_protector(
407     tsi_handshaker* self, size_t* max_output_protected_frame_size,
408     tsi_frame_protector** protector);
409 
410 /* Callback function definition for tsi_handshaker_next.
411    - status indicates the status of the next operation.
412    - user_data is the argument to callback function passed from the caller.
413    - bytes_to_send is the data buffer to be sent to the peer.
414    - bytes_to_send_size is the size of data buffer to be sent to the peer.
415    - handshaker_result is the result of handshake when the handshake completes,
416      is NULL otherwise.  */
417 typedef void (*tsi_handshaker_on_next_done_cb)(
418     tsi_result status, void* user_data, const unsigned char* bytes_to_send,
419     size_t bytes_to_send_size, tsi_handshaker_result* handshaker_result);
420 
421 /* Conduct a next step of the handshake.
422    - received_bytes is the buffer containing the data received from the peer.
423    - received_bytes_size is the size of the data received from the peer.
424    - bytes_to_send is the data buffer to be sent to the peer.
425    - bytes_to_send_size is the size of data buffer to be sent to the peer.
426    - handshaker_result is the result of handshake if the handshake completes.
427    - cb is the callback function defined above. It can be NULL for synchronous
428      TSI handshaker implementation.
429    - user_data is the argument to callback function passed from the caller.
430    This method returns TSI_ASYNC if the TSI handshaker implementation is
431    asynchronous, and in this case, the callback is guaranteed to run in another
432    thread owned by TSI. It returns TSI_OK if the handshake completes or if
433    there are data to send to the peer, otherwise returns TSI_INCOMPLETE_DATA
434    which indicates that this method needs to be called again with more data
435    from the peer. In case of a fatal error in the handshake, another specific
436    error code is returned.
437    The caller is responsible for destroying the handshaker_result. However,
438    the caller should not free bytes_to_send, as the buffer is owned by the
439    tsi_handshaker object.  */
440 tsi_result tsi_handshaker_next(
441     tsi_handshaker* self, const unsigned char* received_bytes,
442     size_t received_bytes_size, const unsigned char** bytes_to_send,
443     size_t* bytes_to_send_size, tsi_handshaker_result** handshaker_result,
444     tsi_handshaker_on_next_done_cb cb, void* user_data);
445 
446 /* This method shuts down a TSI handshake that is in progress.
447  *
448  * This method will be invoked when TSI handshake should be terminated before
449  * being finished in order to free any resources being used.
450  */
451 void tsi_handshaker_shutdown(tsi_handshaker* self);
452 
453 /* This method releases the tsi_handshaker object. After this method is called,
454    no other method can be called on the object.  */
455 void tsi_handshaker_destroy(tsi_handshaker* self);
456 
457 /* This method initializes the necessary shared objects used for tsi
458    implementation.  */
459 void tsi_init();
460 
461 /* This method destroys the shared objects created by tsi_init.  */
462 void tsi_destroy();
463 
464 #endif /* GRPC_CORE_TSI_TRANSPORT_SECURITY_INTERFACE_H */
465