GRPC Core 0.10.0.0

- Main Page
- Data Structures
- Files

- File List
- Globals

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
37 #include "src/core/tsi/transport_security_interface.h"
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
58 typedef struct tsi_ssl_handshaker_factory tsi_ssl_handshaker_factory;
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. */
87 tsi_result tsi_create_ssl_client_handshaker_factory(
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. */
133 tsi_result tsi_create_ssl_server_handshaker_factory(
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. */
153 tsi_result tsi_ssl_handshaker_factory_create_handshaker(
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. */
159 void tsi_ssl_handshaker_factory_destroy(tsi_ssl_handshaker_factory* self);
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_create_ssl_client_handshaker_factory
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:1214
transport_security_interface.h
tsi_create_ssl_server_handshaker_factory
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:1291
tsi_ssl_handshaker_factory
Definition: ssl_transport_security.c:71
tsi_ssl_handshaker_factory_create_handshaker
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:955
tsi_peer
Definition: transport_security_interface.h:192
tsi_result
tsi_result
Definition: transport_security_interface.h:46
tsi_ssl_handshaker_factory_destroy
void tsi_ssl_handshaker_factory_destroy(tsi_ssl_handshaker_factory *self)
Definition: ssl_transport_security.c:962
tsi_ssl_peer_matches_name
int tsi_ssl_peer_matches_name(const tsi_peer *peer, const char *name)
Definition: ssl_transport_security.c:1396
tsi_handshaker
Definition: transport_security.h:86