GRPC Core  9.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 
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. */
45 
46 /* Given a NULL-terminated string containing the PEM encoding of the root
47  certificates, creates a tsi_ssl_root_certs_store object. */
49  const char* pem_roots);
50 
51 /* Destroys the tsi_ssl_root_certs_store object. */
53 
54 /* --- tsi_ssl_session_cache object ---
55 
56  Cache for SSL sessions for sessions resumption. */
57 
59 
60 /* Create LRU cache for SSL sessions with \a capacity. */
62 
63 /* Increment reference counter of \a cache. */
65 
66 /* Decrement reference counter of \a 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 
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;
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. */
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,
114 
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. */
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. */
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. */
142  /* ssl_session_cache is a cache for reusable client-side sessions. */
144 
146  : pem_key_cert_pair(nullptr),
147  pem_root_certs(nullptr),
148  root_store(nullptr),
149  cipher_suites(nullptr),
150  alpn_protocols(nullptr),
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. */
162  const tsi_ssl_client_handshaker_options* options,
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. */
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. */
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 
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. */
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,
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 */
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 
235  /* pem_key_cert_pairs is an array private key / certificate chains of the
236  server. */
238  /* num_key_cert_pairs is the number of items in the pem_key_cert_pairs
239  array. */
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. */
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. */
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. */
263  /* session_ticket_key is optional key for encrypting session keys. If
264  parameter 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. */
268 
270  : pem_key_cert_pairs(nullptr),
272  pem_client_root_certs(nullptr),
274  cipher_suites(nullptr),
275  alpn_protocols(nullptr),
277  session_ticket_key(nullptr),
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. */
288  const tsi_ssl_server_handshaker_options* options,
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. */
299 
300 /* Decrements reference count of the handshaker factory. Handshaker factory will
301  * be destroyed once no references exist. */
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) */
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. */
319 
320 /* Function pointer to handshaker_factory destructor. */
322  tsi_ssl_handshaker_factory* factory);
323 
324 /* Virtual table for tsi_ssl_handshaker_factory. */
325 typedef struct {
328 
329 /* Set destructor of handshaker_factory to new_destructor, returns previous
330  destructor. */
334 
335 /* Exposed for testing only. */
337  const char* pem_cert, tsi_peer* peer);
338 
339 #endif /* GRPC_CORE_TSI_SSL_TRANSPORT_SECURITY_H */
Definition: string_view.h:69
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:1631
void(* tsi_ssl_handshaker_factory_destructor)(tsi_ssl_handshaker_factory *factory)
Definition: ssl_transport_security.h:321
tsi_result tsi_ssl_server_handshaker_factory_create_handshaker(tsi_ssl_server_handshaker_factory *self, tsi_handshaker **handshaker)
Definition: ssl_transport_security.cc:1480
void tsi_ssl_server_handshaker_factory_unref(tsi_ssl_server_handshaker_factory *self)
Definition: ssl_transport_security.cc:1489
struct tsi_ssl_session_cache tsi_ssl_session_cache
Definition: ssl_transport_security.h:58
tsi_ssl_session_cache * tsi_ssl_session_cache_create_lru(size_t capacity)
Definition: ssl_transport_security.cc:820
void tsi_ssl_client_handshaker_factory_unref(tsi_ssl_client_handshaker_factory *factory)
Definition: ssl_transport_security.cc:1451
void tsi_ssl_session_cache_ref(tsi_ssl_session_cache *cache)
Definition: ssl_transport_security.cc:826
void tsi_ssl_root_certs_store_destroy(tsi_ssl_root_certs_store *self)
Definition: ssl_transport_security.cc:812
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:1965
void tsi_ssl_session_cache_unref(tsi_ssl_session_cache *cache)
Definition: ssl_transport_security.cc:831
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:1777
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:1759
tsi_ssl_root_certs_store * tsi_ssl_root_certs_store_create(const char *pem_roots)
Definition: ssl_transport_security.cc:783
tsi_result tsi_ssl_extract_x509_subject_names_from_pem_cert(const char *pem_cert, tsi_peer *peer)
Definition: ssl_transport_security.cc:715
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:1646
tsi_result tsi_ssl_client_handshaker_factory_create_handshaker(tsi_ssl_client_handshaker_factory *self, const char *server_name_indication, tsi_handshaker **handshaker)
Definition: ssl_transport_security.cc:1444
int tsi_ssl_peer_matches_name(const tsi_peer *peer, grpc_core::StringView name)
Definition: ssl_transport_security.cc:1924
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:1746
Definition: transport_security.h:79
Definition: transport_security_interface.h:198
Definition: ssl_transport_security.cc:86
Definition: ssl_transport_security.h:115
const tsi_ssl_root_certs_store * root_store
Definition: ssl_transport_security.h:127
tsi_ssl_client_handshaker_options()
Definition: ssl_transport_security.h:145
const char * pem_root_certs
Definition: ssl_transport_security.h:122
const char * cipher_suites
Definition: ssl_transport_security.h:133
const char ** alpn_protocols
Definition: ssl_transport_security.h:137
tsi_ssl_session_cache * session_cache
Definition: ssl_transport_security.h:143
size_t num_alpn_protocols
Definition: ssl_transport_security.h:141
const tsi_ssl_pem_key_cert_pair * pem_key_cert_pair
Definition: ssl_transport_security.h:119
Definition: ssl_transport_security.h:325
tsi_ssl_handshaker_factory_destructor destroy
Definition: ssl_transport_security.h:326
Definition: ssl_transport_security.cc:81
Definition: ssl_transport_security.h:78
const char * cert_chain
Definition: ssl_transport_security.h:85
const char * private_key
Definition: ssl_transport_security.h:81
Definition: ssl_transport_security.cc:77
Definition: ssl_transport_security.cc:94
Definition: ssl_transport_security.h:234
const char * cipher_suites
Definition: ssl_transport_security.h:254
size_t session_ticket_key_size
Definition: ssl_transport_security.h:267
const tsi_ssl_pem_key_cert_pair * pem_key_cert_pairs
Definition: ssl_transport_security.h:237
size_t num_key_cert_pairs
Definition: ssl_transport_security.h:240
const char * session_ticket_key
Definition: ssl_transport_security.h:265
const char ** alpn_protocols
Definition: ssl_transport_security.h:258
tsi_ssl_server_handshaker_options()
Definition: ssl_transport_security.h:269
uint16_t num_alpn_protocols
Definition: ssl_transport_security.h:262
tsi_client_certificate_request_type client_certificate_request
Definition: ssl_transport_security.h:248
const char * pem_client_root_certs
Definition: ssl_transport_security.h:244
tsi_result
Definition: transport_security_interface.h:31
tsi_client_certificate_request_type
Definition: transport_security_interface.h:49
@ TSI_DONT_REQUEST_CLIENT_CERTIFICATE
Definition: transport_security_interface.h:51