legacy-libs/grpc/deps/grpc/src/core/tsi/alts/handshaker/alts_handshaker_client.h

   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/byte_buffer.h>
  25 #include <grpc/byte_buffer_reader.h>
  26 #include <grpc/grpc.h>
  27
  28 #include "src/core/tsi/alts/handshaker/alts_tsi_handshaker.h"
  29 #include "src/core/tsi/transport_security_interface.h"
  30
  31 #include "src/core/lib/iomgr/closure.h"
  32 #include "src/core/lib/iomgr/pollset_set.h"
  33
  34 #define ALTS_SERVICE_METHOD "/grpc.gcp.HandshakerService/DoHandshake"
  35 #define ALTS_APPLICATION_PROTOCOL "grpc"
  36 #define ALTS_RECORD_PROTOCOL "ALTSRP_GCM_AES128_REKEY"
  37 #define ALTS_HANDSHAKER_SERVICE_URL_FOR_TESTING "lame"
  38
  39 const size_t kAltsAes128GcmRekeyKeyLength = 44;
  40
  41 typedef struct alts_tsi_handshaker alts_tsi_handshaker;
  42 /**
  43  * A ALTS handshaker client interface. It is used to communicate with
  44  * ALTS handshaker service by scheduling a handshaker request that could be one
  45  * of client_start, server_start, and next handshaker requests. All APIs in the
  46  * header are thread-compatible.
  47  */
  48 typedef struct alts_handshaker_client alts_handshaker_client;
  49
  50 /* A function that makes the grpc call to the handshaker service. */
  51 typedef grpc_call_error (*alts_grpc_caller)(grpc_call* call, const grpc_op* ops,
  52                                             size_t nops, grpc_closure* tag);
  53
  54 /* V-table for ALTS handshaker client operations. */
  55 typedef struct alts_handshaker_client_vtable {
  56   tsi_result (*client_start)(alts_handshaker_client* client);
  57   tsi_result (*server_start)(alts_handshaker_client* client,
  58                              grpc_slice* bytes_received);
  59   tsi_result (*next)(alts_handshaker_client* client,
  60                      grpc_slice* bytes_received);
  61   void (*shutdown)(alts_handshaker_client* client);
  62   void (*destruct)(alts_handshaker_client* client);
  63 } alts_handshaker_client_vtable;
  64
  65 /**
  66  * This method schedules a client_start handshaker request to ALTS handshaker
  67  * service.
  68  *
  69  * - client: ALTS handshaker client instance.
  70  *
  71  * It returns TSI_OK on success and an error status code on failure.
  72  */
  73 tsi_result alts_handshaker_client_start_client(alts_handshaker_client* client);
  74
  75 /**
  76  * This method schedules a server_start handshaker request to ALTS handshaker
  77  * service.
  78  *
  79  * - client: ALTS handshaker client 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                                                grpc_slice* bytes_received);
  87
  88 /**
  89  * This method schedules a next handshaker request to ALTS handshaker service.
  90  *
  91  * - client: ALTS handshaker client instance.
  92  * - bytes_received: bytes in out_frames returned from the peer's handshaker
  93  *   response.
  94  *
  95  * It returns TSI_OK on success and an error status code on failure.
  96  */
  97 tsi_result alts_handshaker_client_next(alts_handshaker_client* client,
  98                                        grpc_slice* bytes_received);
  99
 100 /**
 101  * This method cancels previously scheduled, but yet executed handshaker
 102  * requests to ALTS handshaker service. After this operation, the handshake
 103  * will be shutdown, and no more handshaker requests will get scheduled.
 104  *
 105  * - client: ALTS handshaker client instance.
 106  */
 107 void alts_handshaker_client_shutdown(alts_handshaker_client* client);
 108
 109 /**
 110  * This method destroys an ALTS handshaker client.
 111  *
 112  * - client: an ALTS handshaker client instance.
 113  */
 114 void alts_handshaker_client_destroy(alts_handshaker_client* client);
 115
 116 /**
 117  * This method creates an ALTS handshaker client.
 118  *
 119  * - handshaker: ALTS TSI handshaker to which the created handshaker client
 120  * belongs to.
 121  * - channel: grpc channel to ALTS handshaker service.
 122  * - handshaker_service_url: address of ALTS handshaker service in the format of
 123  *   "host:port".
 124  * - interested_parties: set of pollsets interested in this connection.
 125  * - options: ALTS credentials options containing information passed from TSI
 126  *   caller (e.g., rpc protocol versions)
 127  * - target_name: the name of the endpoint that the channel is connecting to,
 128  *   and will be used for secure naming check
 129  * - grpc_cb: gRPC provided callbacks passed from TSI handshaker.
 130  * - cb: callback to be executed when tsi_handshaker_next API compltes.
 131  * - user_data: argument passed to cb.
 132  * - vtable_for_testing: ALTS handshaker client vtable instance used for
 133  *   testing purpose.
 134  * - is_client: a boolean value indicating if the created handshaker client is
 135  * used at the client (is_client = true) or server (is_client = false) side. It
 136  * returns the created ALTS handshaker client on success, and NULL on failure.
 137  */
 138 alts_handshaker_client* alts_grpc_handshaker_client_create(
 139     alts_tsi_handshaker* handshaker, grpc_channel* channel,
 140     const char* handshaker_service_url, grpc_pollset_set* interested_parties,
 141     grpc_alts_credentials_options* options, const grpc_slice& target_name,
 142     grpc_iomgr_cb_func grpc_cb, tsi_handshaker_on_next_done_cb cb,
 143     void* user_data, alts_handshaker_client_vtable* vtable_for_testing,
 144     bool is_client);
 145
 146 /**
 147  * This method handles handshaker response returned from ALTS handshaker
 148  * service. Note that the only reason the API is exposed is that it is used in
 149  * alts_shared_resources.cc.
 150  *
 151  * - client: an ALTS handshaker client instance.
 152  * - is_ok: a boolean value indicating if the handshaker response is ok to read.
 153  */
 154 void alts_handshaker_client_handle_response(alts_handshaker_client* client,
 155                                             bool is_ok);
 156
 157 #endif /* GRPC_CORE_TSI_ALTS_HANDSHAKER_ALTS_HANDSHAKER_CLIENT_H */