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