Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 1 | /* |
| 2 | * |
Craig Tiller | 6169d5f | 2016-03-31 07:46:18 -0700 | [diff] [blame] | 3 | * Copyright 2015, Google Inc. |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 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 | |
Craig Tiller | 730ddc2 | 2017-03-29 08:38:47 -0700 | [diff] [blame] | 34 | #ifndef GRPC_CORE_TSI_SSL_TRANSPORT_SECURITY_H |
| 35 | #define GRPC_CORE_TSI_SSL_TRANSPORT_SECURITY_H |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 36 | |
Craig Tiller | b29f1fe | 2017-03-28 15:49:23 -0700 | [diff] [blame] | 37 | #include "src/core/tsi/transport_security_interface.h" |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 38 | |
| 39 | #ifdef __cplusplus |
Craig Tiller | a82950e | 2015-09-22 12:33:20 -0700 | [diff] [blame] | 40 | extern "C" { |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 41 | #endif |
| 42 | |
| 43 | /* Value for the TSI_CERTIFICATE_TYPE_PEER_PROPERTY property for X509 certs. */ |
| 44 | #define TSI_X509_CERTIFICATE_TYPE "X509" |
| 45 | |
jboeuf | c212585 | 2015-01-12 16:42:28 -0800 | [diff] [blame] | 46 | /* This property is of type TSI_PEER_PROPERTY_STRING. */ |
| 47 | #define TSI_X509_SUBJECT_COMMON_NAME_PEER_PROPERTY "x509_subject_common_name" |
Julien Boeuf | 77e8c1c | 2015-05-13 13:50:59 -0700 | [diff] [blame] | 48 | #define TSI_X509_SUBJECT_ALTERNATIVE_NAME_PEER_PROPERTY \ |
| 49 | "x509_subject_alternative_name" |
jboeuf | c212585 | 2015-01-12 16:42:28 -0800 | [diff] [blame] | 50 | |
Deepak Lukose | e61cbe3 | 2016-03-14 14:10:44 -0700 | [diff] [blame] | 51 | #define TSI_X509_PEM_CERT_PROPERTY "x509_pem_cert" |
| 52 | |
jboeuf | c212585 | 2015-01-12 16:42:28 -0800 | [diff] [blame] | 53 | #define TSI_SSL_ALPN_SELECTED_PROTOCOL "ssl_alpn_selected_protocol" |
| 54 | |
Julien Boeuf | 935d02e | 2017-04-09 00:07:09 -0700 | [diff] [blame] | 55 | /* --- tsi_ssl_client_handshaker_factory object --- |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 56 | |
Julien Boeuf | 935d02e | 2017-04-09 00:07:09 -0700 | [diff] [blame] | 57 | This object creates a client tsi_handshaker objects implemented in terms of |
| 58 | the TLS 1.2 specificiation. */ |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 59 | |
Julien Boeuf | 935d02e | 2017-04-09 00:07:09 -0700 | [diff] [blame] | 60 | typedef struct tsi_ssl_client_handshaker_factory |
| 61 | tsi_ssl_client_handshaker_factory; |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 62 | |
Julien Boeuf | b71ef65 | 2017-04-12 21:44:49 -0700 | [diff] [blame^] | 63 | /* Object that holds a private key / certificate chain pair in PEM format. */ |
| 64 | typedef struct { |
| 65 | /* private_key is the NULL-terminated string containing the PEM encoding of |
| 66 | the client's private key. */ |
| 67 | const char *private_key; |
| 68 | |
| 69 | /* cert_chain is the NULL-terminated string containing the PEM encoding of |
| 70 | the client's certificate chain. */ |
| 71 | const char *cert_chain; |
| 72 | } tsi_ssl_pem_key_cert_pair; |
| 73 | |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 74 | /* Creates a client handshaker factory. |
Julien Boeuf | b71ef65 | 2017-04-12 21:44:49 -0700 | [diff] [blame^] | 75 | - pem_key_cert_pair is a pointer to the object containing client's private |
| 76 | key and certificate chain. This parameter can be NULL if the client does |
| 77 | not have such a key/cert pair. |
| 78 | - pem_roots_cert is the NULL-terminated string containing the PEM encoding of |
| 79 | the client root certificates. This parameter may be NULL if the server does |
| 80 | not want the client to be authenticated with SSL. |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 81 | - cipher_suites contains an optional list of the ciphers that the client |
| 82 | supports. The format of this string is described in: |
| 83 | https://www.openssl.org/docs/apps/ciphers.html. |
| 84 | This parameter can be set to NULL to use the default set of ciphers. |
| 85 | TODO(jboeuf): Revisit the format of this parameter. |
Julien Boeuf | b71ef65 | 2017-04-12 21:44:49 -0700 | [diff] [blame^] | 86 | - alpn_protocols is an array containing the NULL terminated protocol names |
| 87 | that the handshakers created with this factory support. This parameter can |
| 88 | be NULL. |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 89 | - num_alpn_protocols is the number of alpn protocols and associated lengths |
| 90 | specified. If this parameter is 0, the other alpn parameters must be NULL. |
| 91 | - factory is the address of the factory pointer to be created. |
| 92 | |
| 93 | - This method returns TSI_OK on success or TSI_INVALID_PARAMETER in the case |
| 94 | where a parameter is invalid. */ |
Craig Tiller | a82950e | 2015-09-22 12:33:20 -0700 | [diff] [blame] | 95 | tsi_result tsi_create_ssl_client_handshaker_factory( |
Julien Boeuf | b71ef65 | 2017-04-12 21:44:49 -0700 | [diff] [blame^] | 96 | const tsi_ssl_pem_key_cert_pair *pem_key_cert_pair, |
| 97 | const char *pem_root_certs, const char *cipher_suites, |
| 98 | const char **alpn_protocols, uint16_t num_alpn_protocols, |
Julien Boeuf | 935d02e | 2017-04-09 00:07:09 -0700 | [diff] [blame] | 99 | tsi_ssl_client_handshaker_factory **factory); |
| 100 | |
| 101 | /* Creates a client handshaker. |
| 102 | - self is the factory from which the handshaker will be created. |
| 103 | - server_name_indication indicates the name of the server the client is |
| 104 | trying to connect to which will be relayed to the server using the SNI |
| 105 | extension. |
| 106 | - handshaker is the address of the handshaker pointer to be created. |
| 107 | |
| 108 | - This method returns TSI_OK on success or TSI_INVALID_PARAMETER in the case |
| 109 | where a parameter is invalid. */ |
| 110 | tsi_result tsi_ssl_client_handshaker_factory_create_handshaker( |
| 111 | tsi_ssl_client_handshaker_factory *self, const char *server_name_indication, |
| 112 | tsi_handshaker **handshaker); |
| 113 | |
| 114 | /* Destroys the handshaker factory. WARNING: it is unsafe to destroy a factory |
| 115 | while handshakers created with this factory are still in use. */ |
| 116 | void tsi_ssl_client_handshaker_factory_destroy( |
| 117 | tsi_ssl_client_handshaker_factory *self); |
| 118 | |
| 119 | /* --- tsi_ssl_server_handshaker_factory object --- |
| 120 | |
| 121 | This object creates a client tsi_handshaker objects implemented in terms of |
| 122 | the TLS 1.2 specificiation. */ |
| 123 | |
| 124 | typedef struct tsi_ssl_server_handshaker_factory |
| 125 | tsi_ssl_server_handshaker_factory; |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 126 | |
| 127 | /* Creates a server handshaker factory. |
Julien Boeuf | b71ef65 | 2017-04-12 21:44:49 -0700 | [diff] [blame^] | 128 | - pem_key_cert_pairs is an array private key / certificate chains of the |
| 129 | server. |
| 130 | - num_key_cert_pairs is the number of items in the pem_key_cert_pairs array. |
| 131 | - pem_root_certs is the NULL-terminated string containing the PEM encoding |
| 132 | of the server root certificates. |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 133 | - cipher_suites contains an optional list of the ciphers that the server |
| 134 | supports. The format of this string is described in: |
| 135 | https://www.openssl.org/docs/apps/ciphers.html. |
| 136 | This parameter can be set to NULL to use the default set of ciphers. |
| 137 | TODO(jboeuf): Revisit the format of this parameter. |
Julien Boeuf | b71ef65 | 2017-04-12 21:44:49 -0700 | [diff] [blame^] | 138 | - alpn_protocols is an array containing the NULL terminated protocol names |
| 139 | that the handshakers created with this factory support. This parameter can |
| 140 | be NULL. |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 141 | - num_alpn_protocols is the number of alpn protocols and associated lengths |
| 142 | specified. If this parameter is 0, the other alpn parameters must be NULL. |
| 143 | - factory is the address of the factory pointer to be created. |
| 144 | |
| 145 | - This method returns TSI_OK on success or TSI_INVALID_PARAMETER in the case |
| 146 | where a parameter is invalid. */ |
Craig Tiller | a82950e | 2015-09-22 12:33:20 -0700 | [diff] [blame] | 147 | tsi_result tsi_create_ssl_server_handshaker_factory( |
Julien Boeuf | b71ef65 | 2017-04-12 21:44:49 -0700 | [diff] [blame^] | 148 | const tsi_ssl_pem_key_cert_pair *pem_key_cert_pairs, |
| 149 | size_t num_key_cert_pairs, const char *pem_client_root_certs, |
| 150 | int force_client_auth, const char *cipher_suites, |
| 151 | const char **alpn_protocols, uint16_t num_alpn_protocols, |
Julien Boeuf | 935d02e | 2017-04-09 00:07:09 -0700 | [diff] [blame] | 152 | tsi_ssl_server_handshaker_factory **factory); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 153 | |
Deepak Lukose | dba4c5f | 2016-03-25 12:54:25 -0700 | [diff] [blame] | 154 | /* Same as tsi_create_ssl_server_handshaker_factory method except uses |
| 155 | tsi_client_certificate_request_type to support more ways to handle client |
| 156 | certificate authentication. |
| 157 | - client_certificate_request, if set to non-zero will force the client to |
| 158 | authenticate with an SSL cert. Note that this option is ignored if |
| 159 | pem_client_root_certs is NULL or pem_client_roots_certs_size is 0 */ |
| 160 | tsi_result tsi_create_ssl_server_handshaker_factory_ex( |
Julien Boeuf | b71ef65 | 2017-04-12 21:44:49 -0700 | [diff] [blame^] | 161 | const tsi_ssl_pem_key_cert_pair *pem_key_cert_pairs, |
| 162 | size_t num_key_cert_pairs, const char *pem_client_root_certs, |
Deepak Lukose | dba4c5f | 2016-03-25 12:54:25 -0700 | [diff] [blame] | 163 | tsi_client_certificate_request_type client_certificate_request, |
Julien Boeuf | b71ef65 | 2017-04-12 21:44:49 -0700 | [diff] [blame^] | 164 | const char *cipher_suites, const char **alpn_protocols, |
| 165 | uint16_t num_alpn_protocols, tsi_ssl_server_handshaker_factory **factory); |
Deepak Lukose | dba4c5f | 2016-03-25 12:54:25 -0700 | [diff] [blame] | 166 | |
Julien Boeuf | 935d02e | 2017-04-09 00:07:09 -0700 | [diff] [blame] | 167 | /* Creates a server handshaker. |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 168 | - self is the factory from which the handshaker will be created. |
Julien Boeuf | 935d02e | 2017-04-09 00:07:09 -0700 | [diff] [blame] | 169 | - handshaker is the address of the handshaker pointer to be created. |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 170 | |
| 171 | - This method returns TSI_OK on success or TSI_INVALID_PARAMETER in the case |
| 172 | where a parameter is invalid. */ |
Julien Boeuf | 935d02e | 2017-04-09 00:07:09 -0700 | [diff] [blame] | 173 | tsi_result tsi_ssl_server_handshaker_factory_create_handshaker( |
| 174 | tsi_ssl_server_handshaker_factory *self, tsi_handshaker **handshaker); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 175 | |
| 176 | /* Destroys the handshaker factory. WARNING: it is unsafe to destroy a factory |
| 177 | while handshakers created with this factory are still in use. */ |
Julien Boeuf | 935d02e | 2017-04-09 00:07:09 -0700 | [diff] [blame] | 178 | void tsi_ssl_server_handshaker_factory_destroy( |
| 179 | tsi_ssl_server_handshaker_factory *self); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 180 | |
Julien Boeuf | 9fff77e | 2015-02-24 16:50:35 -0800 | [diff] [blame] | 181 | /* Util that checks that an ssl peer matches a specific name. |
| 182 | Still TODO(jboeuf): |
| 183 | - handle mixed case. |
| 184 | - handle %encoded chars. |
Paul Querna | 47d841d | 2016-03-10 11:19:17 -0800 | [diff] [blame] | 185 | - handle public suffix wildchar more strictly (e.g. *.co.uk) */ |
Craig Tiller | a82950e | 2015-09-22 12:33:20 -0700 | [diff] [blame] | 186 | int tsi_ssl_peer_matches_name(const tsi_peer *peer, const char *name); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 187 | |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 188 | #ifdef __cplusplus |
| 189 | } |
| 190 | #endif |
| 191 | |
Craig Tiller | 730ddc2 | 2017-03-29 08:38:47 -0700 | [diff] [blame] | 192 | #endif /* GRPC_CORE_TSI_SSL_TRANSPORT_SECURITY_H */ |