legacy-libs/grpc-cloned/deps/grpc/src/core/tsi/ssl_transport_security.h

   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_SSL_TRANSPORT_SECURITY_H
  20 #define GRPC_CORE_TSI_SSL_TRANSPORT_SECURITY_H
  21
  22 #include <grpc/support/port_platform.h>
  23
  24 #include "src/core/lib/gprpp/string_view.h"
  25 #include "src/core/tsi/transport_security_interface.h"
  26
  27 /* Value for the TSI_CERTIFICATE_TYPE_PEER_PROPERTY property for X509 certs. */
  28 #define TSI_X509_CERTIFICATE_TYPE "X509"
  29
  30 /* This property is of type TSI_PEER_PROPERTY_STRING.  */
  31 #define TSI_X509_SUBJECT_COMMON_NAME_PEER_PROPERTY "x509_subject_common_name"
  32 #define TSI_X509_SUBJECT_ALTERNATIVE_NAME_PEER_PROPERTY \
  33   "x509_subject_alternative_name"
  34 #define TSI_SSL_SESSION_REUSED_PEER_PROPERTY "ssl_session_reused"
  35
  36 #define TSI_X509_PEM_CERT_PROPERTY "x509_pem_cert"
  37
  38 #define TSI_SSL_ALPN_SELECTED_PROTOCOL "ssl_alpn_selected_protocol"
  39
  40 /* --- tsi_ssl_root_certs_store object ---
  41
  42    This object stores SSL root certificates. It can be shared by multiple SSL
  43    context. */
  44 typedef struct tsi_ssl_root_certs_store tsi_ssl_root_certs_store;
  45
  46 /* Given a NULL-terminated string containing the PEM encoding of the root
  47    certificates, creates a tsi_ssl_root_certs_store object. */
  48 tsi_ssl_root_certs_store* tsi_ssl_root_certs_store_create(
  49     const char* pem_roots);
  50
  51 /* Destroys the tsi_ssl_root_certs_store object. */
  52 void tsi_ssl_root_certs_store_destroy(tsi_ssl_root_certs_store* self);
  53
  54 /* --- tsi_ssl_session_cache object ---
  55
  56    Cache for SSL sessions for sessions resumption.  */
  57
  58 typedef struct tsi_ssl_session_cache tsi_ssl_session_cache;
  59
  60 /* Create LRU cache for SSL sessions with \a capacity.  */
  61 tsi_ssl_session_cache* tsi_ssl_session_cache_create_lru(size_t capacity);
  62
  63 /* Increment reference counter of \a cache.  */
  64 void tsi_ssl_session_cache_ref(tsi_ssl_session_cache* cache);
  65
  66 /* Decrement reference counter of \a cache.  */
  67 void tsi_ssl_session_cache_unref(tsi_ssl_session_cache* cache);
  68
  69 /* --- tsi_ssl_client_handshaker_factory object ---
  70
  71    This object creates a client tsi_handshaker objects implemented in terms of
  72    the TLS 1.2 specificiation.  */
  73
  74 typedef struct tsi_ssl_client_handshaker_factory
  75     tsi_ssl_client_handshaker_factory;
  76
  77 /* Object that holds a private key / certificate chain pair in PEM format. */
  78 typedef struct {
  79   /* private_key is the NULL-terminated string containing the PEM encoding of
  80      the client's private key. */
  81   const char* private_key;
  82
  83   /* cert_chain is the NULL-terminated string containing the PEM encoding of
  84      the client's certificate chain. */
  85   const char* cert_chain;
  86 } tsi_ssl_pem_key_cert_pair;
  87
  88 /* TO BE DEPRECATED.
  89    Creates a client handshaker factory.
  90    - pem_key_cert_pair is a pointer to the object containing client's private
  91      key and certificate chain. This parameter can be NULL if the client does
  92      not have such a key/cert pair.
  93    - pem_roots_cert is the NULL-terminated string containing the PEM encoding of
  94      the server root certificates.
  95    - cipher_suites contains an optional list of the ciphers that the client
  96      supports. The format of this string is described in:
  97      https://www.openssl.org/docs/apps/ciphers.html.
  98      This parameter can be set to NULL to use the default set of ciphers.
  99      TODO(jboeuf): Revisit the format of this parameter.
 100    - alpn_protocols is an array containing the NULL terminated protocol names
 101      that the handshakers created with this factory support. This parameter can
 102      be NULL.
 103    - num_alpn_protocols is the number of alpn protocols and associated lengths
 104      specified. If this parameter is 0, the other alpn parameters must be NULL.
 105    - factory is the address of the factory pointer to be created.
 106
 107    - This method returns TSI_OK on success or TSI_INVALID_PARAMETER in the case
 108      where a parameter is invalid.  */
 109 tsi_result tsi_create_ssl_client_handshaker_factory(
 110     const tsi_ssl_pem_key_cert_pair* pem_key_cert_pair,
 111     const char* pem_root_certs, const char* cipher_suites,
 112     const char** alpn_protocols, uint16_t num_alpn_protocols,
 113     tsi_ssl_client_handshaker_factory** factory);
 114
 115 struct tsi_ssl_client_handshaker_options {
 116   /* pem_key_cert_pair is a pointer to the object containing client's private
 117      key and certificate chain. This parameter can be NULL if the client does
 118      not have such a key/cert pair. */
 119   const tsi_ssl_pem_key_cert_pair* pem_key_cert_pair;
 120   /* pem_roots_cert is the NULL-terminated string containing the PEM encoding of
 121      the client root certificates. */
 122   const char* pem_root_certs;
 123   /* root_store is a pointer to the ssl_root_certs_store object. If root_store
 124     is not nullptr and SSL implementation permits, root_store will be used as
 125     root certificates. Otherwise, pem_roots_cert will be used to load server
 126     root certificates. */
 127   const tsi_ssl_root_certs_store* root_store;
 128   /* cipher_suites contains an optional list of the ciphers that the client
 129      supports. The format of this string is described in:
 130      https://www.openssl.org/docs/apps/ciphers.html.
 131      This parameter can be set to NULL to use the default set of ciphers.
 132      TODO(jboeuf): Revisit the format of this parameter. */
 133   const char* cipher_suites;
 134   /* alpn_protocols is an array containing the NULL terminated protocol names
 135      that the handshakers created with this factory support. This parameter can
 136      be NULL. */
 137   const char** alpn_protocols;
 138   /* num_alpn_protocols is the number of alpn protocols and associated lengths
 139      specified. If this parameter is 0, the other alpn parameters must be
 140      NULL. */
 141   size_t num_alpn_protocols;
 142   /* ssl_session_cache is a cache for reusable client-side sessions. */
 143   tsi_ssl_session_cache* session_cache;
 144
 145   tsi_ssl_client_handshaker_options()
 146       : pem_key_cert_pair(nullptr),
 147         pem_root_certs(nullptr),
 148         root_store(nullptr),
 149         cipher_suites(nullptr),
 150         alpn_protocols(nullptr),
 151         num_alpn_protocols(0),
 152         session_cache(nullptr) {}
 153 };
 154
 155 /* Creates a client handshaker factory.
 156    - options is the options used to create a factory.
 157    - factory is the address of the factory pointer to be created.
 158
 159    - This method returns TSI_OK on success or TSI_INVALID_PARAMETER in the case
 160      where a parameter is invalid. */
 161 tsi_result tsi_create_ssl_client_handshaker_factory_with_options(
 162     const tsi_ssl_client_handshaker_options* options,
 163     tsi_ssl_client_handshaker_factory** factory);
 164
 165 /* Creates a client handshaker.
 166   - self is the factory from which the handshaker will be created.
 167   - server_name_indication indicates the name of the server the client is
 168     trying to connect to which will be relayed to the server using the SNI
 169     extension.
 170   - handshaker is the address of the handshaker pointer to be created.
 171
 172   - This method returns TSI_OK on success or TSI_INVALID_PARAMETER in the case
 173     where a parameter is invalid.  */
 174 tsi_result tsi_ssl_client_handshaker_factory_create_handshaker(
 175     tsi_ssl_client_handshaker_factory* self, const char* server_name_indication,
 176     tsi_handshaker** handshaker);
 177
 178 /* Decrements reference count of the handshaker factory. Handshaker factory will
 179  * be destroyed once no references exist. */
 180 void tsi_ssl_client_handshaker_factory_unref(
 181     tsi_ssl_client_handshaker_factory* factory);
 182
 183 /* --- tsi_ssl_server_handshaker_factory object ---
 184
 185    This object creates a client tsi_handshaker objects implemented in terms of
 186    the TLS 1.2 specificiation.  */
 187
 188 typedef struct tsi_ssl_server_handshaker_factory
 189     tsi_ssl_server_handshaker_factory;
 190
 191 /* TO BE DEPRECATED.
 192    Creates a server handshaker factory.
 193    - pem_key_cert_pairs is an array private key / certificate chains of the
 194      server.
 195    - num_key_cert_pairs is the number of items in the pem_key_cert_pairs array.
 196    - pem_root_certs is the NULL-terminated string containing the PEM encoding
 197      of the client root certificates. This parameter may be NULL if the server
 198      does not want the client to be authenticated with SSL.
 199    - cipher_suites contains an optional list of the ciphers that the server
 200      supports. The format of this string is described in:
 201      https://www.openssl.org/docs/apps/ciphers.html.
 202      This parameter can be set to NULL to use the default set of ciphers.
 203      TODO(jboeuf): Revisit the format of this parameter.
 204    - alpn_protocols is an array containing the NULL terminated protocol names
 205      that the handshakers created with this factory support. This parameter can
 206      be NULL.
 207    - num_alpn_protocols is the number of alpn protocols and associated lengths
 208      specified. If this parameter is 0, the other alpn parameters must be NULL.
 209    - factory is the address of the factory pointer to be created.
 210
 211    - This method returns TSI_OK on success or TSI_INVALID_PARAMETER in the case
 212      where a parameter is invalid.  */
 213 tsi_result tsi_create_ssl_server_handshaker_factory(
 214     const tsi_ssl_pem_key_cert_pair* pem_key_cert_pairs,
 215     size_t num_key_cert_pairs, const char* pem_client_root_certs,
 216     int force_client_auth, const char* cipher_suites,
 217     const char** alpn_protocols, uint16_t num_alpn_protocols,
 218     tsi_ssl_server_handshaker_factory** factory);
 219
 220 /* TO BE DEPRECATED.
 221    Same as tsi_create_ssl_server_handshaker_factory method except uses
 222    tsi_client_certificate_request_type to support more ways to handle client
 223    certificate authentication.
 224    - client_certificate_request, if set to non-zero will force the client to
 225      authenticate with an SSL cert. Note that this option is ignored if
 226      pem_client_root_certs is NULL or pem_client_roots_certs_size is 0 */
 227 tsi_result tsi_create_ssl_server_handshaker_factory_ex(
 228     const tsi_ssl_pem_key_cert_pair* pem_key_cert_pairs,
 229     size_t num_key_cert_pairs, const char* pem_client_root_certs,
 230     tsi_client_certificate_request_type client_certificate_request,
 231     const char* cipher_suites, const char** alpn_protocols,
 232     uint16_t num_alpn_protocols, tsi_ssl_server_handshaker_factory** factory);
 233
 234 struct tsi_ssl_server_handshaker_options {
 235   /* pem_key_cert_pairs is an array private key / certificate chains of the
 236      server. */
 237   const tsi_ssl_pem_key_cert_pair* pem_key_cert_pairs;
 238   /* num_key_cert_pairs is the number of items in the pem_key_cert_pairs
 239      array. */
 240   size_t num_key_cert_pairs;
 241   /* pem_root_certs is the NULL-terminated string containing the PEM encoding
 242      of the server root certificates. This parameter may be NULL if the server
 243      does not want the client to be authenticated with SSL. */
 244   const char* pem_client_root_certs;
 245   /* client_certificate_request, if set to non-zero will force the client to
 246      authenticate with an SSL cert. Note that this option is ignored if
 247      pem_client_root_certs is NULL or pem_client_roots_certs_size is 0. */
 248   tsi_client_certificate_request_type client_certificate_request;
 249   /* cipher_suites contains an optional list of the ciphers that the server
 250      supports. The format of this string is described in:
 251      https://www.openssl.org/docs/apps/ciphers.html.
 252      This parameter can be set to NULL to use the default set of ciphers.
 253      TODO(jboeuf): Revisit the format of this parameter. */
 254   const char* cipher_suites;
 255   /* alpn_protocols is an array containing the NULL terminated protocol names
 256      that the handshakers created with this factory support. This parameter can
 257      be NULL. */
 258   const char** alpn_protocols;
 259   /* num_alpn_protocols is the number of alpn protocols and associated lengths
 260      specified. If this parameter is 0, the other alpn parameters must be
 261      NULL. */
 262   uint16_t num_alpn_protocols;
 263   /* session_ticket_key is optional key for encrypting session keys. If paramter
 264      is not specified it must be NULL. */
 265   const char* session_ticket_key;
 266   /* session_ticket_key_size is a size of session ticket encryption key. */
 267   size_t session_ticket_key_size;
 268
 269   tsi_ssl_server_handshaker_options()
 270       : pem_key_cert_pairs(nullptr),
 271         num_key_cert_pairs(0),
 272         pem_client_root_certs(nullptr),
 273         client_certificate_request(TSI_DONT_REQUEST_CLIENT_CERTIFICATE),
 274         cipher_suites(nullptr),
 275         alpn_protocols(nullptr),
 276         num_alpn_protocols(0),
 277         session_ticket_key(nullptr),
 278         session_ticket_key_size(0) {}
 279 };
 280
 281 /* Creates a server handshaker factory.
 282    - options is the options used to create a factory.
 283    - factory is the address of the factory pointer to be created.
 284
 285    - This method returns TSI_OK on success or TSI_INVALID_PARAMETER in the case
 286      where a parameter is invalid. */
 287 tsi_result tsi_create_ssl_server_handshaker_factory_with_options(
 288     const tsi_ssl_server_handshaker_options* options,
 289     tsi_ssl_server_handshaker_factory** factory);
 290
 291 /* Creates a server handshaker.
 292   - self is the factory from which the handshaker will be created.
 293   - handshaker is the address of the handshaker pointer to be created.
 294
 295   - This method returns TSI_OK on success or TSI_INVALID_PARAMETER in the case
 296     where a parameter is invalid.  */
 297 tsi_result tsi_ssl_server_handshaker_factory_create_handshaker(
 298     tsi_ssl_server_handshaker_factory* self, tsi_handshaker** handshaker);
 299
 300 /* Decrements reference count of the handshaker factory. Handshaker factory will
 301  * be destroyed once no references exist. */
 302 void tsi_ssl_server_handshaker_factory_unref(
 303     tsi_ssl_server_handshaker_factory* self);
 304
 305 /* Util that checks that an ssl peer matches a specific name.
 306    Still TODO(jboeuf):
 307    - handle mixed case.
 308    - handle %encoded chars.
 309    - handle public suffix wildchar more strictly (e.g. *.co.uk) */
 310 int tsi_ssl_peer_matches_name(const tsi_peer* peer, grpc_core::StringView name);
 311
 312 /* --- Testing support. ---
 313
 314    These functions and typedefs are not intended to be used outside of testing.
 315    */
 316
 317 /* Base type of client and server handshaker factories. */
 318 typedef struct tsi_ssl_handshaker_factory tsi_ssl_handshaker_factory;
 319
 320 /* Function pointer to handshaker_factory destructor. */
 321 typedef void (*tsi_ssl_handshaker_factory_destructor)(
 322     tsi_ssl_handshaker_factory* factory);
 323
 324 /* Virtual table for tsi_ssl_handshaker_factory. */
 325 typedef struct {
 326   tsi_ssl_handshaker_factory_destructor destroy;
 327 } tsi_ssl_handshaker_factory_vtable;
 328
 329 /* Set destructor of handshaker_factory to new_destructor, returns previous
 330    destructor. */
 331 const tsi_ssl_handshaker_factory_vtable* tsi_ssl_handshaker_factory_swap_vtable(
 332     tsi_ssl_handshaker_factory* factory,
 333     tsi_ssl_handshaker_factory_vtable* new_vtable);
 334
 335 /* Exposed for testing only. */
 336 tsi_result tsi_ssl_extract_x509_subject_names_from_pem_cert(
 337     const char* pem_cert, tsi_peer* peer);
 338
 339 #endif /* GRPC_CORE_TSI_SSL_TRANSPORT_SECURITY_H */