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