GRPC Core  0.11.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
ssl_transport_security.h
Go to the documentation of this file.
1 /*
2  *
3  * Copyright 2015, Google Inc.
4  * All rights reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions are
8  * met:
9  *
10  * * Redistributions of source code must retain the above copyright
11  * notice, this list of conditions and the following disclaimer.
12  * * Redistributions in binary form must reproduce the above
13  * copyright notice, this list of conditions and the following disclaimer
14  * in the documentation and/or other materials provided with the
15  * distribution.
16  * * Neither the name of Google Inc. nor the names of its
17  * contributors may be used to endorse or promote products derived from
18  * this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  *
32  */
33 
34 #ifndef GRPC_INTERNAL_CORE_TSI_SSL_TRANSPORT_SECURITY_H
35 #define GRPC_INTERNAL_CORE_TSI_SSL_TRANSPORT_SECURITY_H
36 
38 
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42 
43 /* Value for the TSI_CERTIFICATE_TYPE_PEER_PROPERTY property for X509 certs. */
44 #define TSI_X509_CERTIFICATE_TYPE "X509"
45 
46 /* This property is of type TSI_PEER_PROPERTY_STRING. */
47 #define TSI_X509_SUBJECT_COMMON_NAME_PEER_PROPERTY "x509_subject_common_name"
48 #define TSI_X509_SUBJECT_ALTERNATIVE_NAME_PEER_PROPERTY \
49  "x509_subject_alternative_name"
50 
51 #define TSI_SSL_ALPN_SELECTED_PROTOCOL "ssl_alpn_selected_protocol"
52 
53 /* --- tsi_ssl_handshaker_factory object ---
54 
55  This object creates tsi_handshaker objects implemented in terms of the
56  TLS 1.2 specificiation. */
57 
59 
60 /* Creates a client handshaker factory.
61  - pem_private_key is the buffer containing the PEM encoding of the client's
62  private key. This parameter can be NULL if the client does not have a
63  private key.
64  - pem_private_key_size is the size of the associated buffer.
65  - pem_cert_chain is the buffer containing the PEM encoding of the client's
66  certificate chain. This parameter can be NULL if the client does not have
67  a certificate chain.
68  - pem_cert_chain_size is the size of the associated buffer.
69  - pem_roots_cert is the buffer containing the PEM encoding of the server
70  root certificates. This parameter cannot be NULL.
71  - pem_roots_cert_size is the size of the associated buffer.
72  - cipher_suites contains an optional list of the ciphers that the client
73  supports. The format of this string is described in:
74  https://www.openssl.org/docs/apps/ciphers.html.
75  This parameter can be set to NULL to use the default set of ciphers.
76  TODO(jboeuf): Revisit the format of this parameter.
77  - alpn_protocols is an array containing the protocol names that the
78  handshakers created with this factory support. This parameter can be NULL.
79  - alpn_protocols_lengths is an array containing the lengths of the alpn
80  protocols specified in alpn_protocols. This parameter can be NULL.
81  - num_alpn_protocols is the number of alpn protocols and associated lengths
82  specified. If this parameter is 0, the other alpn parameters must be NULL.
83  - factory is the address of the factory pointer to be created.
84 
85  - This method returns TSI_OK on success or TSI_INVALID_PARAMETER in the case
86  where a parameter is invalid. */
88  const unsigned char* pem_private_key, size_t pem_private_key_size,
89  const unsigned char* pem_cert_chain, size_t pem_cert_chain_size,
90  const unsigned char* pem_root_certs, size_t pem_root_certs_size,
91  const char* cipher_suites, const unsigned char** alpn_protocols,
92  const unsigned char* alpn_protocols_lengths, uint16_t num_alpn_protocols,
93  tsi_ssl_handshaker_factory** factory);
94 
95 /* Creates a server handshaker factory.
96  - version indicates which version of the specification to use.
97  - pem_private_keys is an array containing the PEM encoding of the server's
98  private keys. This parameter cannot be NULL. The size of the array is
99  given by the key_cert_pair_count parameter.
100  - pem_private_keys_sizes is the array containing the sizes of the associated
101  buffers.
102  - pem_cert_chains is an array containing the PEM encoding of the server's
103  cert chains. This parameter cannot be NULL. The size of the array is
104  given by the key_cert_pair_count parameter.
105  - pem_cert_chains_sizes is the array containing the sizes of the associated
106  buffers.
107  - key_cert_pair_count indicates the number of items in the private_key_files
108  and cert_chain_files parameters.
109  - pem_client_roots is the buffer containing the PEM encoding of the client
110  root certificates. This parameter may be NULL in which case the server will
111  not authenticate the client. If not NULL, the force_client_auth parameter
112  specifies if the server will accept only authenticated clients or both
113  authenticated and non-authenticated clients.
114  - pem_client_root_certs_size is the size of the associated buffer.
115  - force_client_auth, if set to non-zero will force the client to authenticate
116  with an SSL cert. Note that this option is ignored if pem_client_root_certs
117  is NULL or pem_client_roots_certs_size is 0
118  - cipher_suites contains an optional list of the ciphers that the server
119  supports. The format of this string is described in:
120  https://www.openssl.org/docs/apps/ciphers.html.
121  This parameter can be set to NULL to use the default set of ciphers.
122  TODO(jboeuf): Revisit the format of this parameter.
123  - alpn_protocols is an array containing the protocol names that the
124  handshakers created with this factory support. This parameter can be NULL.
125  - alpn_protocols_lengths is an array containing the lengths of the alpn
126  protocols specified in alpn_protocols. This parameter can be NULL.
127  - num_alpn_protocols is the number of alpn protocols and associated lengths
128  specified. If this parameter is 0, the other alpn parameters must be NULL.
129  - factory is the address of the factory pointer to be created.
130 
131  - This method returns TSI_OK on success or TSI_INVALID_PARAMETER in the case
132  where a parameter is invalid. */
134  const unsigned char** pem_private_keys,
135  const size_t* pem_private_keys_sizes, const unsigned char** pem_cert_chains,
136  const size_t* pem_cert_chains_sizes, size_t key_cert_pair_count,
137  const unsigned char* pem_client_root_certs,
138  size_t pem_client_root_certs_size, int force_client_auth,
139  const char* cipher_suites, const unsigned char** alpn_protocols,
140  const unsigned char* alpn_protocols_lengths, uint16_t num_alpn_protocols,
141  tsi_ssl_handshaker_factory** factory);
142 
143 /* Creates a handshaker.
144  - self is the factory from which the handshaker will be created.
145  - server_name_indication indicates the name of the server the client is
146  trying to connect to which will be relayed to the server using the SNI
147  extension.
148  This parameter must be NULL for a server handshaker factory.
149  - handhshaker is the address of the handshaker pointer to be created.
150 
151  - This method returns TSI_OK on success or TSI_INVALID_PARAMETER in the case
152  where a parameter is invalid. */
154  tsi_ssl_handshaker_factory* self, const char* server_name_indication,
155  tsi_handshaker** handshaker);
156 
157 /* Destroys the handshaker factory. WARNING: it is unsafe to destroy a factory
158  while handshakers created with this factory are still in use. */
160 
161 /* Util that checks that an ssl peer matches a specific name.
162  Still TODO(jboeuf):
163  - handle mixed case.
164  - handle %encoded chars.
165  - handle public suffix wildchar more strictly (e.g. *.co.uk)
166  - handle IP addresses in SAN. */
167 int tsi_ssl_peer_matches_name(const tsi_peer* peer, const char* name);
168 
169 #ifdef __cplusplus
170 }
171 #endif
172 
173 #endif /* GRPC_INTERNAL_CORE_TSI_SSL_TRANSPORT_SECURITY_H */
tsi_result tsi_create_ssl_client_handshaker_factory(const unsigned char *pem_private_key, size_t pem_private_key_size, const unsigned char *pem_cert_chain, size_t pem_cert_chain_size, const unsigned char *pem_root_certs, size_t pem_root_certs_size, const char *cipher_suites, const unsigned char **alpn_protocols, const unsigned char *alpn_protocols_lengths, uint16_t num_alpn_protocols, tsi_ssl_handshaker_factory **factory)
Definition: ssl_transport_security.c:1217
tsi_result tsi_create_ssl_server_handshaker_factory(const unsigned char **pem_private_keys, const size_t *pem_private_keys_sizes, const unsigned char **pem_cert_chains, const size_t *pem_cert_chains_sizes, size_t key_cert_pair_count, const unsigned char *pem_client_root_certs, size_t pem_client_root_certs_size, int force_client_auth, const char *cipher_suites, const unsigned char **alpn_protocols, const unsigned char *alpn_protocols_lengths, uint16_t num_alpn_protocols, tsi_ssl_handshaker_factory **factory)
Definition: ssl_transport_security.c:1294
Definition: ssl_transport_security.c:70
tsi_result tsi_ssl_handshaker_factory_create_handshaker(tsi_ssl_handshaker_factory *self, const char *server_name_indication, tsi_handshaker **handshaker)
Definition: ssl_transport_security.c:956
Definition: transport_security_interface.h:194
tsi_result
Definition: transport_security_interface.h:46
void tsi_ssl_handshaker_factory_destroy(tsi_ssl_handshaker_factory *self)
Definition: ssl_transport_security.c:963
int tsi_ssl_peer_matches_name(const tsi_peer *peer, const char *name)
Definition: ssl_transport_security.c:1399
Definition: transport_security.h:86