GRPC Core  18.0.0
ssl_transport_security.h
Go to the documentation of this file.
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 
23 
25 #include "absl/strings/string_view.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. */
53 
54 /* Given a NULL-terminated string containing the PEM encoding of the root
55  certificates, creates a tsi_ssl_root_certs_store object. */
57  const char* pem_roots);
58 
59 /* Destroys the tsi_ssl_root_certs_store object. */
61 
62 /* --- tsi_ssl_session_cache object ---
63 
64  Cache for SSL sessions for sessions resumption. */
65 
67 
68 /* Create LRU cache for SSL sessions with \a capacity. */
70 
71 /* Increment reference counter of \a cache. */
73 
74 /* Decrement reference counter of \a 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 
84 
85 /* Object that holds a private key / certificate chain pair in PEM format. */
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. */
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,
121 
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. */
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. */
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. */
149  /* ssl_session_cache is a cache for reusable client-side sessions. */
151 
152  /* skip server certificate verification. */
154 
155  /* The min and max TLS versions that will be negotiated by the handshaker. */
158 
160  : pem_key_cert_pair(nullptr),
161  pem_root_certs(nullptr),
162  root_store(nullptr),
163  cipher_suites(nullptr),
164  alpn_protocols(nullptr),
166  session_cache(nullptr),
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. */
179  const tsi_ssl_client_handshaker_options* options,
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. */
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. */
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 
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. */
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,
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 */
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 
252  /* pem_key_cert_pairs is an array private key / certificate chains of the
253  server. */
255  /* num_key_cert_pairs is the number of items in the pem_key_cert_pairs
256  array. */
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. */
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. */
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. */
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. */
285  /* The min and max TLS versions that will be negotiated by the handshaker. */
288 
290  : pem_key_cert_pairs(nullptr),
292  pem_client_root_certs(nullptr),
294  cipher_suites(nullptr),
295  alpn_protocols(nullptr),
297  session_ticket_key(nullptr),
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. */
310  const tsi_ssl_server_handshaker_options* options,
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. */
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. */
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. */
341 
342 /* Function pointer to handshaker_factory destructor. */
344  tsi_ssl_handshaker_factory* factory);
345 
346 /* Virtual table for tsi_ssl_handshaker_factory. */
349 };
350 /* Set destructor of handshaker_factory to new_destructor, returns previous
351  destructor. */
355 
356 /* Exposed for testing only. */
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 */
tsi_result tsi_create_ssl_client_handshaker_factory(const tsi_ssl_pem_key_cert_pair *pem_key_cert_pair, const char *pem_root_certs, const char *cipher_suites, const char **alpn_protocols, uint16_t num_alpn_protocols, tsi_ssl_client_handshaker_factory **factory)
Definition: ssl_transport_security.cc:1892
void(* tsi_ssl_handshaker_factory_destructor)(tsi_ssl_handshaker_factory *factory)
Definition: ssl_transport_security.h:343
int tsi_ssl_peer_matches_name(const tsi_peer *peer, absl::string_view name)
Definition: ssl_transport_security.cc:2201
struct tsi_ssl_session_cache tsi_ssl_session_cache
Definition: ssl_transport_security.h:66
tsi_ssl_session_cache * tsi_ssl_session_cache_create_lru(size_t capacity)
Definition: ssl_transport_security.cc:1005
void tsi_ssl_client_handshaker_factory_unref(tsi_ssl_client_handshaker_factory *factory)
Definition: ssl_transport_security.cc:1714
void tsi_ssl_session_cache_ref(tsi_ssl_session_cache *cache)
Definition: ssl_transport_security.cc:1011
void tsi_ssl_server_handshaker_factory_unref(tsi_ssl_server_handshaker_factory *factory)
Definition: ssl_transport_security.cc:1752
void tsi_ssl_root_certs_store_destroy(tsi_ssl_root_certs_store *self)
Definition: ssl_transport_security.cc:997
const tsi_ssl_handshaker_factory_vtable * tsi_ssl_handshaker_factory_swap_vtable(tsi_ssl_handshaker_factory *factory, tsi_ssl_handshaker_factory_vtable *new_vtable)
Definition: ssl_transport_security.cc:2241
void tsi_ssl_session_cache_unref(tsi_ssl_session_cache *cache)
Definition: ssl_transport_security.cc:1016
tsi_result tsi_create_ssl_server_handshaker_factory_with_options(const tsi_ssl_server_handshaker_options *options, tsi_ssl_server_handshaker_factory **factory)
Definition: ssl_transport_security.cc:2047
tsi_result tsi_create_ssl_server_handshaker_factory_ex(const tsi_ssl_pem_key_cert_pair *pem_key_cert_pairs, size_t num_key_cert_pairs, const char *pem_client_root_certs, tsi_client_certificate_request_type client_certificate_request, const char *cipher_suites, const char **alpn_protocols, uint16_t num_alpn_protocols, tsi_ssl_server_handshaker_factory **factory)
Definition: ssl_transport_security.cc:2029
tsi_ssl_root_certs_store * tsi_ssl_root_certs_store_create(const char *pem_roots)
Definition: ssl_transport_security.cc:968
tsi_result tsi_ssl_extract_x509_subject_names_from_pem_cert(const char *pem_cert, tsi_peer *peer)
Definition: ssl_transport_security.cc:845
tsi_result tsi_create_ssl_client_handshaker_factory_with_options(const tsi_ssl_client_handshaker_options *options, tsi_ssl_client_handshaker_factory **factory)
Definition: ssl_transport_security.cc:1907
tsi_result tsi_ssl_get_cert_chain_contents(STACK_OF(X509) *peer_chain, tsi_peer_property *property)
Definition: ssl_transport_security.cc:1214
tsi_result tsi_ssl_server_handshaker_factory_create_handshaker(tsi_ssl_server_handshaker_factory *factory, tsi_handshaker **handshaker)
Definition: ssl_transport_security.cc:1743
tsi_result tsi_ssl_client_handshaker_factory_create_handshaker(tsi_ssl_client_handshaker_factory *factory, const char *server_name_indication, tsi_handshaker **handshaker)
Definition: ssl_transport_security.cc:1706
tsi_result tsi_create_ssl_server_handshaker_factory(const tsi_ssl_pem_key_cert_pair *pem_key_cert_pairs, size_t num_key_cert_pairs, const char *pem_client_root_certs, int force_client_auth, const char *cipher_suites, const char **alpn_protocols, uint16_t num_alpn_protocols, tsi_ssl_server_handshaker_factory **factory)
Definition: ssl_transport_security.cc:2016
Definition: transport_security.h:77
Definition: transport_security_interface.h:208
Definition: transport_security_interface.h:216
Definition: ssl_transport_security.cc:92
Definition: ssl_transport_security.h:122
const tsi_ssl_root_certs_store * root_store
Definition: ssl_transport_security.h:134
tsi_tls_version min_tls_version
Definition: ssl_transport_security.h:156
tsi_ssl_client_handshaker_options()
Definition: ssl_transport_security.h:159
const char * pem_root_certs
Definition: ssl_transport_security.h:129
bool skip_server_certificate_verification
Definition: ssl_transport_security.h:153
tsi_tls_version max_tls_version
Definition: ssl_transport_security.h:157
const char * cipher_suites
Definition: ssl_transport_security.h:140
const char ** alpn_protocols
Definition: ssl_transport_security.h:144
tsi_ssl_session_cache * session_cache
Definition: ssl_transport_security.h:150
size_t num_alpn_protocols
Definition: ssl_transport_security.h:148
const tsi_ssl_pem_key_cert_pair * pem_key_cert_pair
Definition: ssl_transport_security.h:126
Definition: ssl_transport_security.h:347
tsi_ssl_handshaker_factory_destructor destroy
Definition: ssl_transport_security.h:348
Definition: ssl_transport_security.cc:87
Definition: ssl_transport_security.h:86
const char * cert_chain
Definition: ssl_transport_security.h:93
const char * private_key
Definition: ssl_transport_security.h:89
Definition: ssl_transport_security.cc:83
Definition: ssl_transport_security.cc:100
Definition: ssl_transport_security.h:251
const char * cipher_suites
Definition: ssl_transport_security.h:271
size_t session_ticket_key_size
Definition: ssl_transport_security.h:284
tsi_tls_version max_tls_version
Definition: ssl_transport_security.h:287
const tsi_ssl_pem_key_cert_pair * pem_key_cert_pairs
Definition: ssl_transport_security.h:254
size_t num_key_cert_pairs
Definition: ssl_transport_security.h:257
const char * session_ticket_key
Definition: ssl_transport_security.h:282
const char ** alpn_protocols
Definition: ssl_transport_security.h:275
tsi_ssl_server_handshaker_options()
Definition: ssl_transport_security.h:289
tsi_tls_version min_tls_version
Definition: ssl_transport_security.h:286
uint16_t num_alpn_protocols
Definition: ssl_transport_security.h:279
tsi_client_certificate_request_type client_certificate_request
Definition: ssl_transport_security.h:265
const char * pem_client_root_certs
Definition: ssl_transport_security.h:261
tsi_result
Definition: transport_security_interface.h:31
tsi_tls_version
Definition: transport_security_interface.h:67
@ TSI_TLS1_2
Definition: transport_security_interface.h:68
@ TSI_TLS1_3
Definition: transport_security_interface.h:69
tsi_client_certificate_request_type
Definition: transport_security_interface.h:58
@ TSI_DONT_REQUEST_CLIENT_CERTIFICATE
Definition: transport_security_interface.h:60