Home | History | Annotate | Download | only in handshaker
      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_CLIENT_H
     20 #define GRPC_CORE_TSI_ALTS_HANDSHAKER_ALTS_HANDSHAKER_CLIENT_H
     21 
     22 #include <grpc/support/port_platform.h>
     23 
     24 #include <grpc/grpc.h>
     25 
     26 #include "src/core/tsi/alts/handshaker/alts_tsi_event.h"
     27 
     28 #define ALTS_SERVICE_METHOD "/grpc.gcp.HandshakerService/DoHandshake"
     29 #define ALTS_APPLICATION_PROTOCOL "grpc"
     30 #define ALTS_RECORD_PROTOCOL "ALTSRP_GCM_AES128_REKEY"
     31 
     32 const size_t kAltsAes128GcmRekeyKeyLength = 44;
     33 
     34 /**
     35  * A ALTS handshaker client interface. It is used to communicate with
     36  * ALTS handshaker service by scheduling a handshaker request that could be one
     37  * of client_start, server_start, and next handshaker requests. All APIs in the
     38  * header are thread-compatible.
     39  */
     40 typedef struct alts_handshaker_client alts_handshaker_client;
     41 
     42 /* A function that makes the grpc call to the handshaker service. */
     43 typedef grpc_call_error (*alts_grpc_caller)(grpc_call* call, const grpc_op* ops,
     44                                             size_t nops, void* tag);
     45 
     46 /* V-table for ALTS handshaker client operations. */
     47 typedef struct alts_handshaker_client_vtable {
     48   tsi_result (*client_start)(alts_handshaker_client* client,
     49                              alts_tsi_event* event);
     50   tsi_result (*server_start)(alts_handshaker_client* client,
     51                              alts_tsi_event* event, grpc_slice* bytes_received);
     52   tsi_result (*next)(alts_handshaker_client* client, alts_tsi_event* event,
     53                      grpc_slice* bytes_received);
     54   void (*shutdown)(alts_handshaker_client* client);
     55   void (*destruct)(alts_handshaker_client* client);
     56 } alts_handshaker_client_vtable;
     57 
     58 struct alts_handshaker_client {
     59   const alts_handshaker_client_vtable* vtable;
     60 };
     61 
     62 /**
     63  * This method schedules a client_start handshaker request to ALTS handshaker
     64  * service.
     65  *
     66  * - client: ALTS handshaker client instance.
     67  * - event: ALTS TSI event instance.
     68  *
     69  * It returns TSI_OK on success and an error status code on failure.
     70  */
     71 tsi_result alts_handshaker_client_start_client(alts_handshaker_client* client,
     72                                                alts_tsi_event* event);
     73 
     74 /**
     75  * This method schedules a server_start handshaker request to ALTS handshaker
     76  * service.
     77  *
     78  * - client: ALTS handshaker client instance.
     79  * - event: ALTS TSI event instance.
     80  * - bytes_received: bytes in out_frames returned from the peer's handshaker
     81  *   response.
     82  *
     83  * It returns TSI_OK on success and an error status code on failure.
     84  */
     85 tsi_result alts_handshaker_client_start_server(alts_handshaker_client* client,
     86                                                alts_tsi_event* event,
     87                                                grpc_slice* bytes_received);
     88 
     89 /**
     90  * This method schedules a next handshaker request to ALTS handshaker service.
     91  *
     92  * - client: ALTS handshaker client instance.
     93  * - event: ALTS TSI event instance.
     94  * - bytes_received: bytes in out_frames returned from the peer's handshaker
     95  *   response.
     96  *
     97  * It returns TSI_OK on success and an error status code on failure.
     98  */
     99 tsi_result alts_handshaker_client_next(alts_handshaker_client* client,
    100                                        alts_tsi_event* event,
    101                                        grpc_slice* bytes_received);
    102 
    103 /**
    104  * This method cancels previously scheduled, but yet executed handshaker
    105  * requests to ALTS handshaker service. After this operation, the handshake
    106  * will be shutdown, and no more handshaker requests will get scheduled.
    107  *
    108  * - client: ALTS handshaker client instance.
    109  */
    110 void alts_handshaker_client_shutdown(alts_handshaker_client* client);
    111 
    112 /**
    113  * This method destroys a ALTS handshaker client.
    114  *
    115  * - client: a ALTS handshaker client instance.
    116  */
    117 void alts_handshaker_client_destroy(alts_handshaker_client* client);
    118 
    119 /**
    120  * This method creates a ALTS handshaker client.
    121  *
    122  * - channel: grpc channel to ALTS handshaker service.
    123  * - queue: grpc completion queue.
    124  * - handshaker_service_url: address of ALTS handshaker service in the format of
    125  *   "host:port".
    126  *
    127  * It returns the created ALTS handshaker client on success, and NULL on
    128  * failure.
    129  */
    130 alts_handshaker_client* alts_grpc_handshaker_client_create(
    131     grpc_channel* channel, grpc_completion_queue* queue,
    132     const char* handshaker_service_url);
    133 
    134 namespace grpc_core {
    135 namespace internal {
    136 
    137 /**
    138  * Unsafe, use for testing only. It allows the caller to change the way that
    139  * GRPC calls are made to the handshaker service.
    140  */
    141 void alts_handshaker_client_set_grpc_caller_for_testing(
    142     alts_handshaker_client* client, alts_grpc_caller caller);
    143 
    144 }  // namespace internal
    145 }  // namespace grpc_core
    146 
    147 #endif /* GRPC_CORE_TSI_ALTS_HANDSHAKER_ALTS_HANDSHAKER_CLIENT_H */
    148