Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 1 | /* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com) |
| 2 | * All rights reserved. |
| 3 | * |
| 4 | * This package is an SSL implementation written |
| 5 | * by Eric Young (eay@cryptsoft.com). |
| 6 | * The implementation was written so as to conform with Netscapes SSL. |
| 7 | * |
| 8 | * This library is free for commercial and non-commercial use as long as |
| 9 | * the following conditions are aheared to. The following conditions |
| 10 | * apply to all code found in this distribution, be it the RC4, RSA, |
| 11 | * lhash, DES, etc., code; not just the SSL code. The SSL documentation |
| 12 | * included with this distribution is covered by the same copyright terms |
| 13 | * except that the holder is Tim Hudson (tjh@cryptsoft.com). |
| 14 | * |
| 15 | * Copyright remains Eric Young's, and as such any Copyright notices in |
| 16 | * the code are not to be removed. |
| 17 | * If this package is used in a product, Eric Young should be given attribution |
| 18 | * as the author of the parts of the library used. |
| 19 | * This can be in the form of a textual message at program startup or |
| 20 | * in documentation (online or textual) provided with the package. |
| 21 | * |
| 22 | * Redistribution and use in source and binary forms, with or without |
| 23 | * modification, are permitted provided that the following conditions |
| 24 | * are met: |
| 25 | * 1. Redistributions of source code must retain the copyright |
| 26 | * notice, this list of conditions and the following disclaimer. |
| 27 | * 2. Redistributions in binary form must reproduce the above copyright |
| 28 | * notice, this list of conditions and the following disclaimer in the |
| 29 | * documentation and/or other materials provided with the distribution. |
| 30 | * 3. All advertising materials mentioning features or use of this software |
| 31 | * must display the following acknowledgement: |
| 32 | * "This product includes cryptographic software written by |
| 33 | * Eric Young (eay@cryptsoft.com)" |
| 34 | * The word 'cryptographic' can be left out if the rouines from the library |
| 35 | * being used are not cryptographic related :-). |
| 36 | * 4. If you include any Windows specific code (or a derivative thereof) from |
| 37 | * the apps directory (application code) you must include an acknowledgement: |
| 38 | * "This product includes software written by Tim Hudson (tjh@cryptsoft.com)" |
| 39 | * |
| 40 | * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND |
| 41 | * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 42 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| 43 | * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
| 44 | * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| 45 | * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| 46 | * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| 47 | * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| 48 | * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| 49 | * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| 50 | * SUCH DAMAGE. |
| 51 | * |
| 52 | * The licence and distribution terms for any publically available version or |
| 53 | * derivative of this code cannot be changed. i.e. this code cannot simply be |
| 54 | * copied and put under another distribution licence |
| 55 | * [including the GNU Public Licence.] |
| 56 | */ |
| 57 | /* ==================================================================== |
| 58 | * Copyright (c) 1998-2007 The OpenSSL Project. All rights reserved. |
| 59 | * |
| 60 | * Redistribution and use in source and binary forms, with or without |
| 61 | * modification, are permitted provided that the following conditions |
| 62 | * are met: |
| 63 | * |
| 64 | * 1. Redistributions of source code must retain the above copyright |
| 65 | * notice, this list of conditions and the following disclaimer. |
| 66 | * |
| 67 | * 2. Redistributions in binary form must reproduce the above copyright |
| 68 | * notice, this list of conditions and the following disclaimer in |
| 69 | * the documentation and/or other materials provided with the |
| 70 | * distribution. |
| 71 | * |
| 72 | * 3. All advertising materials mentioning features or use of this |
| 73 | * software must display the following acknowledgment: |
| 74 | * "This product includes software developed by the OpenSSL Project |
| 75 | * for use in the OpenSSL Toolkit. (http://www.openssl.org/)" |
| 76 | * |
| 77 | * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to |
| 78 | * endorse or promote products derived from this software without |
| 79 | * prior written permission. For written permission, please contact |
| 80 | * openssl-core@openssl.org. |
| 81 | * |
| 82 | * 5. Products derived from this software may not be called "OpenSSL" |
| 83 | * nor may "OpenSSL" appear in their names without prior written |
| 84 | * permission of the OpenSSL Project. |
| 85 | * |
| 86 | * 6. Redistributions of any form whatsoever must retain the following |
| 87 | * acknowledgment: |
| 88 | * "This product includes software developed by the OpenSSL Project |
| 89 | * for use in the OpenSSL Toolkit (http://www.openssl.org/)" |
| 90 | * |
| 91 | * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY |
| 92 | * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 93 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR |
| 94 | * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR |
| 95 | * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| 96 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT |
| 97 | * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; |
| 98 | * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| 99 | * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, |
| 100 | * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| 101 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED |
| 102 | * OF THE POSSIBILITY OF SUCH DAMAGE. |
| 103 | * ==================================================================== |
| 104 | * |
| 105 | * This product includes cryptographic software written by Eric Young |
| 106 | * (eay@cryptsoft.com). This product includes software written by Tim |
| 107 | * Hudson (tjh@cryptsoft.com). |
| 108 | * |
| 109 | */ |
| 110 | /* ==================================================================== |
| 111 | * Copyright 2002 Sun Microsystems, Inc. ALL RIGHTS RESERVED. |
| 112 | * ECC cipher suite support in OpenSSL originally developed by |
| 113 | * SUN MICROSYSTEMS, INC., and contributed to the OpenSSL project. |
| 114 | */ |
| 115 | /* ==================================================================== |
| 116 | * Copyright 2005 Nokia. All rights reserved. |
| 117 | * |
| 118 | * The portions of the attached software ("Contribution") is developed by |
| 119 | * Nokia Corporation and is licensed pursuant to the OpenSSL open source |
| 120 | * license. |
| 121 | * |
| 122 | * The Contribution, originally written by Mika Kousa and Pasi Eronen of |
| 123 | * Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites |
| 124 | * support (see RFC 4279) to OpenSSL. |
| 125 | * |
| 126 | * No patent licenses or other rights except those expressly stated in |
| 127 | * the OpenSSL open source license shall be deemed granted or received |
| 128 | * expressly, by implication, estoppel, or otherwise. |
| 129 | * |
| 130 | * No assurances are provided by Nokia that the Contribution does not |
| 131 | * infringe the patent or other intellectual property rights of any third |
| 132 | * party or that the license provides you with all the necessary rights |
| 133 | * to make use of the Contribution. |
| 134 | * |
| 135 | * THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN |
| 136 | * ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA |
| 137 | * SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY |
| 138 | * OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR |
| 139 | * OTHERWISE. |
| 140 | */ |
| 141 | |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 142 | #ifndef OPENSSL_HEADER_SSL_H |
| 143 | #define OPENSSL_HEADER_SSL_H |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 144 | |
| 145 | #include <openssl/base.h> |
| 146 | |
| 147 | #include <openssl/bio.h> |
| 148 | #include <openssl/buf.h> |
| 149 | #include <openssl/hmac.h> |
| 150 | #include <openssl/lhash.h> |
| 151 | #include <openssl/pem.h> |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 152 | #include <openssl/ssl3.h> |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 153 | #include <openssl/thread.h> |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 154 | #include <openssl/tls1.h> |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 155 | #include <openssl/x509.h> |
| 156 | |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 157 | #if !defined(OPENSSL_WINDOWS) |
| 158 | #include <sys/time.h> |
| 159 | #endif |
| 160 | |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 161 | /* Forward-declare struct timeval. On Windows, it is defined in winsock2.h and |
| 162 | * Windows headers define too many macros to be included in public headers. |
| 163 | * However, only a forward declaration is needed. */ |
| 164 | struct timeval; |
| 165 | |
| 166 | #if defined(__cplusplus) |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 167 | extern "C" { |
| 168 | #endif |
| 169 | |
| 170 | |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 171 | /* SSL implementation. */ |
| 172 | |
| 173 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 174 | /* SSL contexts. |
| 175 | * |
| 176 | * |SSL_CTX| objects manage shared state and configuration between multiple TLS |
| 177 | * or DTLS connections. Whether the connections are TLS or DTLS is selected by |
| 178 | * an |SSL_METHOD| on creation. |
| 179 | * |
| 180 | * |SSL_CTX| are reference-counted and may be shared by connections across |
| 181 | * multiple threads. Once shared, functions which change the |SSL_CTX|'s |
| 182 | * configuration may not be used. */ |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 183 | |
| 184 | /* TLS_method is the |SSL_METHOD| used for TLS (and SSLv3) connections. */ |
| 185 | OPENSSL_EXPORT const SSL_METHOD *TLS_method(void); |
| 186 | |
| 187 | /* DTLS_method is the |SSL_METHOD| used for DTLS connections. */ |
| 188 | OPENSSL_EXPORT const SSL_METHOD *DTLS_method(void); |
| 189 | |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 190 | /* TLS_with_buffers_method is like |TLS_method|, but avoids all use of |
| 191 | * crypto/x509. */ |
| 192 | OPENSSL_EXPORT const SSL_METHOD *TLS_with_buffers_method(void); |
| 193 | |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 194 | /* SSL_CTX_new returns a newly-allocated |SSL_CTX| with default settings or NULL |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 195 | * on error. */ |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 196 | OPENSSL_EXPORT SSL_CTX *SSL_CTX_new(const SSL_METHOD *method); |
| 197 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 198 | /* SSL_CTX_up_ref increments the reference count of |ctx|. It returns one. */ |
| 199 | OPENSSL_EXPORT int SSL_CTX_up_ref(SSL_CTX *ctx); |
| 200 | |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 201 | /* SSL_CTX_free releases memory associated with |ctx|. */ |
| 202 | OPENSSL_EXPORT void SSL_CTX_free(SSL_CTX *ctx); |
| 203 | |
| 204 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 205 | /* SSL connections. |
| 206 | * |
| 207 | * An |SSL| object represents a single TLS or DTLS connection. Although the |
| 208 | * shared |SSL_CTX| is thread-safe, an |SSL| is not thread-safe and may only be |
| 209 | * used on one thread at a time. */ |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 210 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 211 | /* SSL_new returns a newly-allocated |SSL| using |ctx| or NULL on error. The new |
| 212 | * connection inherits settings from |ctx| at the time of creation. Settings may |
| 213 | * also be individually configured on the connection. |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 214 | * |
| 215 | * On creation, an |SSL| is not configured to be either a client or server. Call |
| 216 | * |SSL_set_connect_state| or |SSL_set_accept_state| to set this. */ |
| 217 | OPENSSL_EXPORT SSL *SSL_new(SSL_CTX *ctx); |
| 218 | |
| 219 | /* SSL_free releases memory associated with |ssl|. */ |
| 220 | OPENSSL_EXPORT void SSL_free(SSL *ssl); |
| 221 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 222 | /* SSL_get_SSL_CTX returns the |SSL_CTX| associated with |ssl|. If |
| 223 | * |SSL_set_SSL_CTX| is called, it returns the new |SSL_CTX|, not the initial |
| 224 | * one. */ |
| 225 | OPENSSL_EXPORT SSL_CTX *SSL_get_SSL_CTX(const SSL *ssl); |
| 226 | |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 227 | /* SSL_set_connect_state configures |ssl| to be a client. */ |
| 228 | OPENSSL_EXPORT void SSL_set_connect_state(SSL *ssl); |
| 229 | |
| 230 | /* SSL_set_accept_state configures |ssl| to be a server. */ |
| 231 | OPENSSL_EXPORT void SSL_set_accept_state(SSL *ssl); |
| 232 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 233 | /* SSL_is_server returns one if |ssl| is configured as a server and zero |
| 234 | * otherwise. */ |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 235 | OPENSSL_EXPORT int SSL_is_server(const SSL *ssl); |
| 236 | |
| 237 | /* SSL_is_dtls returns one if |ssl| is a DTLS connection and zero otherwise. */ |
| 238 | OPENSSL_EXPORT int SSL_is_dtls(const SSL *ssl); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 239 | |
| 240 | /* SSL_set_bio configures |ssl| to read from |rbio| and write to |wbio|. |ssl| |
| 241 | * takes ownership of the two |BIO|s. If |rbio| and |wbio| are the same, |ssl| |
| 242 | * only takes ownership of one reference. |
| 243 | * |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 244 | * In DTLS, |rbio| must be non-blocking to properly handle timeouts and |
| 245 | * retransmits. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 246 | * |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 247 | * If |rbio| is the same as the currently configured |BIO| for reading, that |
| 248 | * side is left untouched and is not freed. |
| 249 | * |
| 250 | * If |wbio| is the same as the currently configured |BIO| for writing AND |ssl| |
| 251 | * is not currently configured to read from and write to the same |BIO|, that |
| 252 | * side is left untouched and is not freed. This asymmetry is present for |
| 253 | * historical reasons. |
| 254 | * |
| 255 | * Due to the very complex historical behavior of this function, calling this |
| 256 | * function if |ssl| already has |BIO|s configured is deprecated. Prefer |
| 257 | * |SSL_set0_rbio| and |SSL_set0_wbio| instead. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 258 | OPENSSL_EXPORT void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio); |
| 259 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 260 | /* SSL_set0_rbio configures |ssl| to write to |rbio|. It takes ownership of |
| 261 | * |rbio|. |
| 262 | * |
| 263 | * Note that, although this function and |SSL_set0_wbio| may be called on the |
| 264 | * same |BIO|, each call takes a reference. Use |BIO_up_ref| to balance this. */ |
| 265 | OPENSSL_EXPORT void SSL_set0_rbio(SSL *ssl, BIO *rbio); |
| 266 | |
| 267 | /* SSL_set0_wbio configures |ssl| to write to |wbio|. It takes ownership of |
| 268 | * |wbio|. |
| 269 | * |
| 270 | * Note that, although this function and |SSL_set0_rbio| may be called on the |
| 271 | * same |BIO|, each call takes a reference. Use |BIO_up_ref| to balance this. */ |
| 272 | OPENSSL_EXPORT void SSL_set0_wbio(SSL *ssl, BIO *wbio); |
| 273 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 274 | /* SSL_get_rbio returns the |BIO| that |ssl| reads from. */ |
| 275 | OPENSSL_EXPORT BIO *SSL_get_rbio(const SSL *ssl); |
| 276 | |
| 277 | /* SSL_get_wbio returns the |BIO| that |ssl| writes to. */ |
| 278 | OPENSSL_EXPORT BIO *SSL_get_wbio(const SSL *ssl); |
| 279 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 280 | /* SSL_get_fd calls |SSL_get_rfd|. */ |
| 281 | OPENSSL_EXPORT int SSL_get_fd(const SSL *ssl); |
| 282 | |
| 283 | /* SSL_get_rfd returns the file descriptor that |ssl| is configured to read |
| 284 | * from. If |ssl|'s read |BIO| is not configured or doesn't wrap a file |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 285 | * descriptor then it returns -1. |
| 286 | * |
| 287 | * Note: On Windows, this may return either a file descriptor or a socket (cast |
| 288 | * to int), depending on whether |ssl| was configured with a file descriptor or |
| 289 | * socket |BIO|. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 290 | OPENSSL_EXPORT int SSL_get_rfd(const SSL *ssl); |
| 291 | |
| 292 | /* SSL_get_wfd returns the file descriptor that |ssl| is configured to write |
| 293 | * to. If |ssl|'s write |BIO| is not configured or doesn't wrap a file |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 294 | * descriptor then it returns -1. |
| 295 | * |
| 296 | * Note: On Windows, this may return either a file descriptor or a socket (cast |
| 297 | * to int), depending on whether |ssl| was configured with a file descriptor or |
| 298 | * socket |BIO|. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 299 | OPENSSL_EXPORT int SSL_get_wfd(const SSL *ssl); |
| 300 | |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 301 | /* SSL_set_fd configures |ssl| to read from and write to |fd|. It returns one |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 302 | * on success and zero on allocation error. The caller retains ownership of |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 303 | * |fd|. |
| 304 | * |
| 305 | * On Windows, |fd| is cast to a |SOCKET| and used with Winsock APIs. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 306 | OPENSSL_EXPORT int SSL_set_fd(SSL *ssl, int fd); |
| 307 | |
| 308 | /* SSL_set_rfd configures |ssl| to read from |fd|. It returns one on success and |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 309 | * zero on allocation error. The caller retains ownership of |fd|. |
| 310 | * |
| 311 | * On Windows, |fd| is cast to a |SOCKET| and used with Winsock APIs. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 312 | OPENSSL_EXPORT int SSL_set_rfd(SSL *ssl, int fd); |
| 313 | |
| 314 | /* SSL_set_wfd configures |ssl| to write to |fd|. It returns one on success and |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 315 | * zero on allocation error. The caller retains ownership of |fd|. |
| 316 | * |
| 317 | * On Windows, |fd| is cast to a |SOCKET| and used with Winsock APIs. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 318 | OPENSSL_EXPORT int SSL_set_wfd(SSL *ssl, int fd); |
| 319 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 320 | /* SSL_do_handshake continues the current handshake. If there is none or the |
| 321 | * handshake has completed or False Started, it returns one. Otherwise, it |
| 322 | * returns <= 0. The caller should pass the value into |SSL_get_error| to |
| 323 | * determine how to proceed. |
| 324 | * |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 325 | * In DTLS, the caller must drive retransmissions. Whenever |SSL_get_error| |
| 326 | * signals |SSL_ERROR_WANT_READ|, use |DTLSv1_get_timeout| to determine the |
| 327 | * current timeout. If it expires before the next retry, call |
| 328 | * |DTLSv1_handle_timeout|. Note that DTLS handshake retransmissions use fresh |
| 329 | * sequence numbers, so it is not sufficient to replay packets at the transport. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 330 | * |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 331 | * TODO(davidben): Ensure 0 is only returned on transport EOF. |
| 332 | * https://crbug.com/466303. */ |
| 333 | OPENSSL_EXPORT int SSL_do_handshake(SSL *ssl); |
| 334 | |
| 335 | /* SSL_connect configures |ssl| as a client, if unconfigured, and calls |
| 336 | * |SSL_do_handshake|. */ |
| 337 | OPENSSL_EXPORT int SSL_connect(SSL *ssl); |
| 338 | |
| 339 | /* SSL_accept configures |ssl| as a server, if unconfigured, and calls |
| 340 | * |SSL_do_handshake|. */ |
| 341 | OPENSSL_EXPORT int SSL_accept(SSL *ssl); |
| 342 | |
| 343 | /* SSL_read reads up to |num| bytes from |ssl| into |buf|. It implicitly runs |
| 344 | * any pending handshakes, including renegotiations when enabled. On success, it |
| 345 | * returns the number of bytes read. Otherwise, it returns <= 0. The caller |
| 346 | * should pass the value into |SSL_get_error| to determine how to proceed. |
| 347 | * |
| 348 | * TODO(davidben): Ensure 0 is only returned on transport EOF. |
| 349 | * https://crbug.com/466303. */ |
| 350 | OPENSSL_EXPORT int SSL_read(SSL *ssl, void *buf, int num); |
| 351 | |
| 352 | /* SSL_peek behaves like |SSL_read| but does not consume any bytes returned. */ |
| 353 | OPENSSL_EXPORT int SSL_peek(SSL *ssl, void *buf, int num); |
| 354 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 355 | /* SSL_pending returns the number of bytes available in |ssl|. It does not read |
| 356 | * from the transport. */ |
| 357 | OPENSSL_EXPORT int SSL_pending(const SSL *ssl); |
| 358 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 359 | /* SSL_write writes up to |num| bytes from |buf| into |ssl|. It implicitly runs |
| 360 | * any pending handshakes, including renegotiations when enabled. On success, it |
Robert Sloan | 7c50ec5 | 2017-02-27 08:17:21 -0800 | [diff] [blame] | 361 | * returns the number of bytes written. Otherwise, it returns <= 0. The caller |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 362 | * should pass the value into |SSL_get_error| to determine how to proceed. |
| 363 | * |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 364 | * In TLS, a non-blocking |SSL_write| differs from non-blocking |write| in that |
| 365 | * a failed |SSL_write| still commits to the data passed in. When retrying, the |
| 366 | * caller must supply the original write buffer (or a larger one containing the |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 367 | * original as a prefix). By default, retries will fail if they also do not |
| 368 | * reuse the same |buf| pointer. This may be relaxed with |
| 369 | * |SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER|, but the buffer contents still must be |
| 370 | * unchanged. |
| 371 | * |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 372 | * By default, in TLS, |SSL_write| will not return success until all |num| bytes |
| 373 | * are written. This may be relaxed with |SSL_MODE_ENABLE_PARTIAL_WRITE|. It |
| 374 | * allows |SSL_write| to complete with a partial result when only part of the |
| 375 | * input was written in a single record. |
| 376 | * |
| 377 | * In DTLS, neither |SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER| and |
| 378 | * |SSL_MODE_ENABLE_PARTIAL_WRITE| do anything. The caller may retry with a |
| 379 | * different buffer freely. A single call to |SSL_write| only ever writes a |
| 380 | * single record in a single packet, so |num| must be at most |
| 381 | * |SSL3_RT_MAX_PLAIN_LENGTH|. |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 382 | * |
| 383 | * TODO(davidben): Ensure 0 is only returned on transport EOF. |
| 384 | * https://crbug.com/466303. */ |
| 385 | OPENSSL_EXPORT int SSL_write(SSL *ssl, const void *buf, int num); |
| 386 | |
| 387 | /* SSL_shutdown shuts down |ssl|. On success, it completes in two stages. First, |
| 388 | * it returns 0 if |ssl| completed uni-directional shutdown; close_notify has |
| 389 | * been sent, but the peer's close_notify has not been received. Most callers |
| 390 | * may stop at this point. For bi-directional shutdown, call |SSL_shutdown| |
| 391 | * again. It returns 1 if close_notify has been both sent and received. |
| 392 | * |
| 393 | * If the peer's close_notify arrived first, the first stage is skipped. |
| 394 | * |SSL_shutdown| will return 1 once close_notify is sent and skip 0. Callers |
| 395 | * only interested in uni-directional shutdown must therefore allow for the |
| 396 | * first stage returning either 0 or 1. |
| 397 | * |
| 398 | * |SSL_shutdown| returns -1 on failure. The caller should pass the return value |
| 399 | * into |SSL_get_error| to determine how to proceed. If the underlying |BIO| is |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 400 | * non-blocking, both stages may require retry. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 401 | OPENSSL_EXPORT int SSL_shutdown(SSL *ssl); |
| 402 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 403 | /* SSL_CTX_set_quiet_shutdown sets quiet shutdown on |ctx| to |mode|. If |
| 404 | * enabled, |SSL_shutdown| will not send a close_notify alert or wait for one |
| 405 | * from the peer. It will instead synchronously return one. */ |
| 406 | OPENSSL_EXPORT void SSL_CTX_set_quiet_shutdown(SSL_CTX *ctx, int mode); |
| 407 | |
| 408 | /* SSL_CTX_get_quiet_shutdown returns whether quiet shutdown is enabled for |
| 409 | * |ctx|. */ |
| 410 | OPENSSL_EXPORT int SSL_CTX_get_quiet_shutdown(const SSL_CTX *ctx); |
| 411 | |
| 412 | /* SSL_set_quiet_shutdown sets quiet shutdown on |ssl| to |mode|. If enabled, |
| 413 | * |SSL_shutdown| will not send a close_notify alert or wait for one from the |
| 414 | * peer. It will instead synchronously return one. */ |
| 415 | OPENSSL_EXPORT void SSL_set_quiet_shutdown(SSL *ssl, int mode); |
| 416 | |
| 417 | /* SSL_get_quiet_shutdown returns whether quiet shutdown is enabled for |
| 418 | * |ssl|. */ |
| 419 | OPENSSL_EXPORT int SSL_get_quiet_shutdown(const SSL *ssl); |
| 420 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 421 | /* SSL_get_error returns a |SSL_ERROR_*| value for the most recent operation on |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 422 | * |ssl|. It should be called after an operation failed to determine whether the |
| 423 | * error was fatal and, if not, when to retry. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 424 | OPENSSL_EXPORT int SSL_get_error(const SSL *ssl, int ret_code); |
| 425 | |
| 426 | /* SSL_ERROR_NONE indicates the operation succeeded. */ |
| 427 | #define SSL_ERROR_NONE 0 |
| 428 | |
| 429 | /* SSL_ERROR_SSL indicates the operation failed within the library. The caller |
| 430 | * may inspect the error queue for more information. */ |
| 431 | #define SSL_ERROR_SSL 1 |
| 432 | |
| 433 | /* SSL_ERROR_WANT_READ indicates the operation failed attempting to read from |
| 434 | * the transport. The caller may retry the operation when the transport is ready |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 435 | * for reading. |
| 436 | * |
| 437 | * If signaled by a DTLS handshake, the caller must also call |
| 438 | * |DTLSv1_get_timeout| and |DTLSv1_handle_timeout| as appropriate. See |
| 439 | * |SSL_do_handshake|. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 440 | #define SSL_ERROR_WANT_READ 2 |
| 441 | |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 442 | /* SSL_ERROR_WANT_WRITE indicates the operation failed attempting to write to |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 443 | * the transport. The caller may retry the operation when the transport is ready |
| 444 | * for writing. */ |
| 445 | #define SSL_ERROR_WANT_WRITE 3 |
| 446 | |
| 447 | /* SSL_ERROR_WANT_X509_LOOKUP indicates the operation failed in calling the |
| 448 | * |cert_cb| or |client_cert_cb|. The caller may retry the operation when the |
| 449 | * callback is ready to return a certificate or one has been configured |
| 450 | * externally. |
| 451 | * |
| 452 | * See also |SSL_CTX_set_cert_cb| and |SSL_CTX_set_client_cert_cb|. */ |
| 453 | #define SSL_ERROR_WANT_X509_LOOKUP 4 |
| 454 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 455 | /* SSL_ERROR_SYSCALL indicates the operation failed externally to the library. |
| 456 | * The caller should consult the system-specific error mechanism. This is |
| 457 | * typically |errno| but may be something custom if using a custom |BIO|. It |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 458 | * may also be signaled if the transport returned EOF, in which case the |
| 459 | * operation's return value will be zero. */ |
| 460 | #define SSL_ERROR_SYSCALL 5 |
| 461 | |
| 462 | /* SSL_ERROR_ZERO_RETURN indicates the operation failed because the connection |
| 463 | * was cleanly shut down with a close_notify alert. */ |
| 464 | #define SSL_ERROR_ZERO_RETURN 6 |
| 465 | |
| 466 | /* SSL_ERROR_WANT_CONNECT indicates the operation failed attempting to connect |
| 467 | * the transport (the |BIO| signaled |BIO_RR_CONNECT|). The caller may retry the |
| 468 | * operation when the transport is ready. */ |
| 469 | #define SSL_ERROR_WANT_CONNECT 7 |
| 470 | |
| 471 | /* SSL_ERROR_WANT_ACCEPT indicates the operation failed attempting to accept a |
| 472 | * connection from the transport (the |BIO| signaled |BIO_RR_ACCEPT|). The |
| 473 | * caller may retry the operation when the transport is ready. |
| 474 | * |
| 475 | * TODO(davidben): Remove this. It's used by accept BIOs which are bizarre. */ |
| 476 | #define SSL_ERROR_WANT_ACCEPT 8 |
| 477 | |
| 478 | /* SSL_ERROR_WANT_CHANNEL_ID_LOOKUP indicates the operation failed looking up |
| 479 | * the Channel ID key. The caller may retry the operation when |channel_id_cb| |
| 480 | * is ready to return a key or one has been configured with |
| 481 | * |SSL_set1_tls_channel_id|. |
| 482 | * |
| 483 | * See also |SSL_CTX_set_channel_id_cb|. */ |
| 484 | #define SSL_ERROR_WANT_CHANNEL_ID_LOOKUP 9 |
| 485 | |
| 486 | /* SSL_ERROR_PENDING_SESSION indicates the operation failed because the session |
| 487 | * lookup callback indicated the session was unavailable. The caller may retry |
| 488 | * the operation when lookup has completed. |
| 489 | * |
| 490 | * See also |SSL_CTX_sess_set_get_cb| and |SSL_magic_pending_session_ptr|. */ |
| 491 | #define SSL_ERROR_PENDING_SESSION 11 |
| 492 | |
| 493 | /* SSL_ERROR_PENDING_CERTIFICATE indicates the operation failed because the |
| 494 | * early callback indicated certificate lookup was incomplete. The caller may |
| 495 | * retry the operation when lookup has completed. Note: when the operation is |
| 496 | * retried, the early callback will not be called a second time. |
| 497 | * |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 498 | * See also |SSL_CTX_set_select_certificate_cb|. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 499 | #define SSL_ERROR_PENDING_CERTIFICATE 12 |
| 500 | |
| 501 | /* SSL_ERROR_WANT_PRIVATE_KEY_OPERATION indicates the operation failed because |
| 502 | * a private key operation was unfinished. The caller may retry the operation |
| 503 | * when the private key operation is complete. |
| 504 | * |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 505 | * See also |SSL_set_private_key_method| and |
| 506 | * |SSL_CTX_set_private_key_method|. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 507 | #define SSL_ERROR_WANT_PRIVATE_KEY_OPERATION 13 |
| 508 | |
Robert Sloan | 1c9db53 | 2017-03-13 08:03:59 -0700 | [diff] [blame] | 509 | /* SSL_ERROR_PENDING_TICKET indicates that a ticket decryption is pending. The |
| 510 | * caller may retry the operation when the decryption is ready. |
| 511 | * |
| 512 | * See also |SSL_CTX_set_ticket_aead_method|. */ |
| 513 | #define SSL_ERROR_PENDING_TICKET 14 |
| 514 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 515 | /* SSL_set_mtu sets the |ssl|'s MTU in DTLS to |mtu|. It returns one on success |
| 516 | * and zero on failure. */ |
| 517 | OPENSSL_EXPORT int SSL_set_mtu(SSL *ssl, unsigned mtu); |
| 518 | |
David Benjamin | d316cba | 2016-06-02 16:17:39 -0400 | [diff] [blame] | 519 | /* DTLSv1_set_initial_timeout_duration sets the initial duration for a DTLS |
| 520 | * handshake timeout. |
| 521 | * |
| 522 | * This duration overrides the default of 1 second, which is the strong |
| 523 | * recommendation of RFC 6347 (see section 4.2.4.1). However, there may exist |
| 524 | * situations where a shorter timeout would be beneficial, such as for |
| 525 | * time-sensitive applications. */ |
| 526 | OPENSSL_EXPORT void DTLSv1_set_initial_timeout_duration(SSL *ssl, |
| 527 | unsigned duration_ms); |
| 528 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 529 | /* DTLSv1_get_timeout queries the next DTLS handshake timeout. If there is a |
| 530 | * timeout in progress, it sets |*out| to the time remaining and returns one. |
| 531 | * Otherwise, it returns zero. |
| 532 | * |
| 533 | * When the timeout expires, call |DTLSv1_handle_timeout| to handle the |
| 534 | * retransmit behavior. |
| 535 | * |
| 536 | * NOTE: This function must be queried again whenever the handshake state |
| 537 | * machine changes, including when |DTLSv1_handle_timeout| is called. */ |
| 538 | OPENSSL_EXPORT int DTLSv1_get_timeout(const SSL *ssl, struct timeval *out); |
| 539 | |
| 540 | /* DTLSv1_handle_timeout is called when a DTLS handshake timeout expires. If no |
| 541 | * timeout had expired, it returns 0. Otherwise, it retransmits the previous |
| 542 | * flight of handshake messages and returns 1. If too many timeouts had expired |
| 543 | * without progress or an error occurs, it returns -1. |
| 544 | * |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 545 | * The caller's external timer should be compatible with the one |ssl| queries |
| 546 | * within some fudge factor. Otherwise, the call will be a no-op, but |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 547 | * |DTLSv1_get_timeout| will return an updated timeout. |
| 548 | * |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 549 | * If the function returns -1, checking if |SSL_get_error| returns |
| 550 | * |SSL_ERROR_WANT_WRITE| may be used to determine if the retransmit failed due |
| 551 | * to a non-fatal error at the write |BIO|. However, the operation may not be |
| 552 | * retried until the next timeout fires. |
| 553 | * |
| 554 | * WARNING: This function breaks the usual return value convention. |
| 555 | * |
| 556 | * TODO(davidben): This |SSL_ERROR_WANT_WRITE| behavior is kind of bizarre. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 557 | OPENSSL_EXPORT int DTLSv1_handle_timeout(SSL *ssl); |
| 558 | |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 559 | |
| 560 | /* Protocol versions. */ |
| 561 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 562 | #define DTLS1_VERSION_MAJOR 0xfe |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 563 | #define SSL3_VERSION_MAJOR 0x03 |
| 564 | |
| 565 | #define SSL3_VERSION 0x0300 |
| 566 | #define TLS1_VERSION 0x0301 |
| 567 | #define TLS1_1_VERSION 0x0302 |
| 568 | #define TLS1_2_VERSION 0x0303 |
David Benjamin | d316cba | 2016-06-02 16:17:39 -0400 | [diff] [blame] | 569 | #define TLS1_3_VERSION 0x0304 |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 570 | |
| 571 | #define DTLS1_VERSION 0xfeff |
| 572 | #define DTLS1_2_VERSION 0xfefd |
| 573 | |
Steven Valdez | 909b19f | 2016-11-21 15:35:44 -0500 | [diff] [blame] | 574 | #define TLS1_3_DRAFT_VERSION 0x7f12 |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 575 | |
David Benjamin | 7c0d06c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 576 | /* SSL_CTX_set_min_proto_version sets the minimum protocol version for |ctx| to |
| 577 | * |version|. If |version| is zero, the default minimum version is used. It |
| 578 | * returns one on success and zero if |version| is invalid. */ |
| 579 | OPENSSL_EXPORT int SSL_CTX_set_min_proto_version(SSL_CTX *ctx, |
| 580 | uint16_t version); |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 581 | |
David Benjamin | 7c0d06c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 582 | /* SSL_CTX_set_max_proto_version sets the maximum protocol version for |ctx| to |
| 583 | * |version|. If |version| is zero, the default maximum version is used. It |
| 584 | * returns one on success and zero if |version| is invalid. */ |
| 585 | OPENSSL_EXPORT int SSL_CTX_set_max_proto_version(SSL_CTX *ctx, |
| 586 | uint16_t version); |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 587 | |
David Benjamin | 7c0d06c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 588 | /* SSL_set_min_proto_version sets the minimum protocol version for |ssl| to |
| 589 | * |version|. If |version| is zero, the default minimum version is used. It |
| 590 | * returns one on success and zero if |version| is invalid. */ |
| 591 | OPENSSL_EXPORT int SSL_set_min_proto_version(SSL *ssl, uint16_t version); |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 592 | |
David Benjamin | 7c0d06c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 593 | /* SSL_set_max_proto_version sets the maximum protocol version for |ssl| to |
| 594 | * |version|. If |version| is zero, the default maximum version is used. It |
| 595 | * returns one on success and zero if |version| is invalid. */ |
| 596 | OPENSSL_EXPORT int SSL_set_max_proto_version(SSL *ssl, uint16_t version); |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 597 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 598 | /* SSL_version returns the TLS or DTLS protocol version used by |ssl|, which is |
| 599 | * one of the |*_VERSION| values. (E.g. |TLS1_2_VERSION|.) Before the version |
| 600 | * is negotiated, the result is undefined. */ |
| 601 | OPENSSL_EXPORT int SSL_version(const SSL *ssl); |
| 602 | |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 603 | |
| 604 | /* Options. |
| 605 | * |
| 606 | * Options configure protocol behavior. */ |
| 607 | |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 608 | /* SSL_OP_NO_QUERY_MTU, in DTLS, disables querying the MTU from the underlying |
| 609 | * |BIO|. Instead, the MTU is configured with |SSL_set_mtu|. */ |
| 610 | #define SSL_OP_NO_QUERY_MTU 0x00001000L |
| 611 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 612 | /* SSL_OP_NO_TICKET disables session ticket support (RFC 5077). */ |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 613 | #define SSL_OP_NO_TICKET 0x00004000L |
| 614 | |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 615 | /* SSL_OP_CIPHER_SERVER_PREFERENCE configures servers to select ciphers and |
| 616 | * ECDHE curves according to the server's preferences instead of the |
| 617 | * client's. */ |
| 618 | #define SSL_OP_CIPHER_SERVER_PREFERENCE 0x00400000L |
| 619 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 620 | /* The following flags toggle individual protocol versions. This is deprecated. |
David Benjamin | 7c0d06c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 621 | * Use |SSL_CTX_set_min_proto_version| and |SSL_CTX_set_max_proto_version| |
| 622 | * instead. */ |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 623 | #define SSL_OP_NO_SSLv3 0x02000000L |
| 624 | #define SSL_OP_NO_TLSv1 0x04000000L |
| 625 | #define SSL_OP_NO_TLSv1_2 0x08000000L |
| 626 | #define SSL_OP_NO_TLSv1_1 0x10000000L |
| 627 | #define SSL_OP_NO_TLSv1_3 0x20000000L |
| 628 | #define SSL_OP_NO_DTLSv1 SSL_OP_NO_TLSv1 |
| 629 | #define SSL_OP_NO_DTLSv1_2 SSL_OP_NO_TLSv1_2 |
| 630 | |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 631 | /* SSL_CTX_set_options enables all options set in |options| (which should be one |
| 632 | * or more of the |SSL_OP_*| values, ORed together) in |ctx|. It returns a |
| 633 | * bitmask representing the resulting enabled options. */ |
| 634 | OPENSSL_EXPORT uint32_t SSL_CTX_set_options(SSL_CTX *ctx, uint32_t options); |
| 635 | |
| 636 | /* SSL_CTX_clear_options disables all options set in |options| (which should be |
| 637 | * one or more of the |SSL_OP_*| values, ORed together) in |ctx|. It returns a |
| 638 | * bitmask representing the resulting enabled options. */ |
| 639 | OPENSSL_EXPORT uint32_t SSL_CTX_clear_options(SSL_CTX *ctx, uint32_t options); |
| 640 | |
| 641 | /* SSL_CTX_get_options returns a bitmask of |SSL_OP_*| values that represent all |
| 642 | * the options enabled for |ctx|. */ |
| 643 | OPENSSL_EXPORT uint32_t SSL_CTX_get_options(const SSL_CTX *ctx); |
| 644 | |
| 645 | /* SSL_set_options enables all options set in |options| (which should be one or |
| 646 | * more of the |SSL_OP_*| values, ORed together) in |ssl|. It returns a bitmask |
| 647 | * representing the resulting enabled options. */ |
| 648 | OPENSSL_EXPORT uint32_t SSL_set_options(SSL *ssl, uint32_t options); |
| 649 | |
| 650 | /* SSL_clear_options disables all options set in |options| (which should be one |
| 651 | * or more of the |SSL_OP_*| values, ORed together) in |ssl|. It returns a |
| 652 | * bitmask representing the resulting enabled options. */ |
| 653 | OPENSSL_EXPORT uint32_t SSL_clear_options(SSL *ssl, uint32_t options); |
| 654 | |
| 655 | /* SSL_get_options returns a bitmask of |SSL_OP_*| values that represent all the |
| 656 | * options enabled for |ssl|. */ |
| 657 | OPENSSL_EXPORT uint32_t SSL_get_options(const SSL *ssl); |
| 658 | |
| 659 | |
| 660 | /* Modes. |
| 661 | * |
| 662 | * Modes configure API behavior. */ |
| 663 | |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 664 | /* SSL_MODE_ENABLE_PARTIAL_WRITE, in TLS, allows |SSL_write| to complete with a |
| 665 | * partial result when the only part of the input was written in a single |
| 666 | * record. In DTLS, it does nothing. */ |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 667 | #define SSL_MODE_ENABLE_PARTIAL_WRITE 0x00000001L |
| 668 | |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 669 | /* SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER, in TLS, allows retrying an incomplete |
| 670 | * |SSL_write| with a different buffer. However, |SSL_write| still assumes the |
| 671 | * buffer contents are unchanged. This is not the default to avoid the |
| 672 | * misconception that non-blocking |SSL_write| behaves like non-blocking |
| 673 | * |write|. In DTLS, it does nothing. */ |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 674 | #define SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER 0x00000002L |
| 675 | |
| 676 | /* SSL_MODE_NO_AUTO_CHAIN disables automatically building a certificate chain |
Steven Valdez | 909b19f | 2016-11-21 15:35:44 -0500 | [diff] [blame] | 677 | * before sending certificates to the peer. This flag is set (and the feature |
| 678 | * disabled) by default. |
| 679 | * TODO(davidben): Remove this behavior. https://crbug.com/boringssl/42. */ |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 680 | #define SSL_MODE_NO_AUTO_CHAIN 0x00000008L |
| 681 | |
| 682 | /* SSL_MODE_ENABLE_FALSE_START allows clients to send application data before |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 683 | * receipt of ChangeCipherSpec and Finished. This mode enables full handshakes |
| 684 | * to 'complete' in one RTT. See RFC 7918. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 685 | * |
| 686 | * When False Start is enabled, |SSL_do_handshake| may succeed before the |
| 687 | * handshake has completely finished. |SSL_write| will function at this point, |
| 688 | * and |SSL_read| will transparently wait for the final handshake leg before |
| 689 | * returning application data. To determine if False Start occurred or when the |
| 690 | * handshake is completely finished, see |SSL_in_false_start|, |SSL_in_init|, |
| 691 | * and |SSL_CB_HANDSHAKE_DONE| from |SSL_CTX_set_info_callback|. */ |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 692 | #define SSL_MODE_ENABLE_FALSE_START 0x00000080L |
| 693 | |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 694 | /* SSL_MODE_CBC_RECORD_SPLITTING causes multi-byte CBC records in SSL 3.0 and |
| 695 | * TLS 1.0 to be split in two: the first record will contain a single byte and |
| 696 | * the second will contain the remainder. This effectively randomises the IV and |
| 697 | * prevents BEAST attacks. */ |
| 698 | #define SSL_MODE_CBC_RECORD_SPLITTING 0x00000100L |
| 699 | |
| 700 | /* SSL_MODE_NO_SESSION_CREATION will cause any attempts to create a session to |
| 701 | * fail with SSL_R_SESSION_MAY_NOT_BE_CREATED. This can be used to enforce that |
| 702 | * session resumption is used for a given SSL*. */ |
| 703 | #define SSL_MODE_NO_SESSION_CREATION 0x00000200L |
| 704 | |
| 705 | /* SSL_MODE_SEND_FALLBACK_SCSV sends TLS_FALLBACK_SCSV in the ClientHello. |
| 706 | * To be set only by applications that reconnect with a downgraded protocol |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 707 | * version; see RFC 7507 for details. |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 708 | * |
| 709 | * DO NOT ENABLE THIS if your application attempts a normal handshake. Only use |
David Benjamin | 7c0d06c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 710 | * this in explicit fallback retries, following the guidance in RFC 7507. */ |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 711 | #define SSL_MODE_SEND_FALLBACK_SCSV 0x00000400L |
| 712 | |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 713 | /* SSL_CTX_set_mode enables all modes set in |mode| (which should be one or more |
| 714 | * of the |SSL_MODE_*| values, ORed together) in |ctx|. It returns a bitmask |
| 715 | * representing the resulting enabled modes. */ |
| 716 | OPENSSL_EXPORT uint32_t SSL_CTX_set_mode(SSL_CTX *ctx, uint32_t mode); |
| 717 | |
| 718 | /* SSL_CTX_clear_mode disables all modes set in |mode| (which should be one or |
| 719 | * more of the |SSL_MODE_*| values, ORed together) in |ctx|. It returns a |
| 720 | * bitmask representing the resulting enabled modes. */ |
| 721 | OPENSSL_EXPORT uint32_t SSL_CTX_clear_mode(SSL_CTX *ctx, uint32_t mode); |
| 722 | |
| 723 | /* SSL_CTX_get_mode returns a bitmask of |SSL_MODE_*| values that represent all |
| 724 | * the modes enabled for |ssl|. */ |
| 725 | OPENSSL_EXPORT uint32_t SSL_CTX_get_mode(const SSL_CTX *ctx); |
| 726 | |
| 727 | /* SSL_set_mode enables all modes set in |mode| (which should be one or more of |
| 728 | * the |SSL_MODE_*| values, ORed together) in |ssl|. It returns a bitmask |
| 729 | * representing the resulting enabled modes. */ |
| 730 | OPENSSL_EXPORT uint32_t SSL_set_mode(SSL *ssl, uint32_t mode); |
| 731 | |
| 732 | /* SSL_clear_mode disables all modes set in |mode| (which should be one or more |
| 733 | * of the |SSL_MODE_*| values, ORed together) in |ssl|. It returns a bitmask |
| 734 | * representing the resulting enabled modes. */ |
| 735 | OPENSSL_EXPORT uint32_t SSL_clear_mode(SSL *ssl, uint32_t mode); |
| 736 | |
| 737 | /* SSL_get_mode returns a bitmask of |SSL_MODE_*| values that represent all the |
| 738 | * modes enabled for |ssl|. */ |
| 739 | OPENSSL_EXPORT uint32_t SSL_get_mode(const SSL *ssl); |
| 740 | |
Steven Valdez | e7531f0 | 2016-12-14 13:29:57 -0500 | [diff] [blame] | 741 | /* SSL_CTX_set0_buffer_pool sets a |CRYPTO_BUFFER_POOL| that will be used to |
| 742 | * store certificates. This can allow multiple connections to share |
| 743 | * certificates and thus save memory. |
| 744 | * |
| 745 | * The SSL_CTX does not take ownership of |pool| and the caller must ensure |
| 746 | * that |pool| outlives |ctx| and all objects linked to it, including |SSL|, |
| 747 | * |X509| and |SSL_SESSION| objects. Basically, don't ever free |pool|. */ |
| 748 | OPENSSL_EXPORT void SSL_CTX_set0_buffer_pool(SSL_CTX *ctx, |
| 749 | CRYPTO_BUFFER_POOL *pool); |
| 750 | |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 751 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 752 | /* Configuring certificates and private keys. |
| 753 | * |
| 754 | * These functions configure the connection's leaf certificate, private key, and |
| 755 | * certificate chain. The certificate chain is ordered leaf to root (as sent on |
| 756 | * the wire) but does not include the leaf. Both client and server certificates |
| 757 | * use these functions. |
| 758 | * |
| 759 | * Certificates and keys may be configured before the handshake or dynamically |
| 760 | * in the early callback and certificate callback. */ |
| 761 | |
| 762 | /* SSL_CTX_use_certificate sets |ctx|'s leaf certificate to |x509|. It returns |
| 763 | * one on success and zero on failure. */ |
| 764 | OPENSSL_EXPORT int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x509); |
| 765 | |
| 766 | /* SSL_use_certificate sets |ssl|'s leaf certificate to |x509|. It returns one |
| 767 | * on success and zero on failure. */ |
| 768 | OPENSSL_EXPORT int SSL_use_certificate(SSL *ssl, X509 *x509); |
| 769 | |
| 770 | /* SSL_CTX_use_PrivateKey sets |ctx|'s private key to |pkey|. It returns one on |
| 771 | * success and zero on failure. */ |
| 772 | OPENSSL_EXPORT int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey); |
| 773 | |
| 774 | /* SSL_use_PrivateKey sets |ssl|'s private key to |pkey|. It returns one on |
| 775 | * success and zero on failure. */ |
| 776 | OPENSSL_EXPORT int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey); |
| 777 | |
| 778 | /* SSL_CTX_set0_chain sets |ctx|'s certificate chain, excluding the leaf, to |
| 779 | * |chain|. On success, it returns one and takes ownership of |chain|. |
| 780 | * Otherwise, it returns zero. */ |
| 781 | OPENSSL_EXPORT int SSL_CTX_set0_chain(SSL_CTX *ctx, STACK_OF(X509) *chain); |
| 782 | |
| 783 | /* SSL_CTX_set1_chain sets |ctx|'s certificate chain, excluding the leaf, to |
| 784 | * |chain|. It returns one on success and zero on failure. The caller retains |
| 785 | * ownership of |chain| and may release it freely. */ |
| 786 | OPENSSL_EXPORT int SSL_CTX_set1_chain(SSL_CTX *ctx, STACK_OF(X509) *chain); |
| 787 | |
| 788 | /* SSL_set0_chain sets |ssl|'s certificate chain, excluding the leaf, to |
| 789 | * |chain|. On success, it returns one and takes ownership of |chain|. |
| 790 | * Otherwise, it returns zero. */ |
| 791 | OPENSSL_EXPORT int SSL_set0_chain(SSL *ssl, STACK_OF(X509) *chain); |
| 792 | |
| 793 | /* SSL_set1_chain sets |ssl|'s certificate chain, excluding the leaf, to |
| 794 | * |chain|. It returns one on success and zero on failure. The caller retains |
| 795 | * ownership of |chain| and may release it freely. */ |
| 796 | OPENSSL_EXPORT int SSL_set1_chain(SSL *ssl, STACK_OF(X509) *chain); |
| 797 | |
| 798 | /* SSL_CTX_add0_chain_cert appends |x509| to |ctx|'s certificate chain. On |
| 799 | * success, it returns one and takes ownership of |x509|. Otherwise, it returns |
| 800 | * zero. */ |
| 801 | OPENSSL_EXPORT int SSL_CTX_add0_chain_cert(SSL_CTX *ctx, X509 *x509); |
| 802 | |
| 803 | /* SSL_CTX_add1_chain_cert appends |x509| to |ctx|'s certificate chain. It |
| 804 | * returns one on success and zero on failure. The caller retains ownership of |
| 805 | * |x509| and may release it freely. */ |
| 806 | OPENSSL_EXPORT int SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *x509); |
| 807 | |
| 808 | /* SSL_add0_chain_cert appends |x509| to |ctx|'s certificate chain. On success, |
| 809 | * it returns one and takes ownership of |x509|. Otherwise, it returns zero. */ |
| 810 | OPENSSL_EXPORT int SSL_add0_chain_cert(SSL *ssl, X509 *x509); |
| 811 | |
| 812 | /* SSL_CTX_add_extra_chain_cert calls |SSL_CTX_add0_chain_cert|. */ |
| 813 | OPENSSL_EXPORT int SSL_CTX_add_extra_chain_cert(SSL_CTX *ctx, X509 *x509); |
| 814 | |
| 815 | /* SSL_add1_chain_cert appends |x509| to |ctx|'s certificate chain. It returns |
| 816 | * one on success and zero on failure. The caller retains ownership of |x509| |
| 817 | * and may release it freely. */ |
| 818 | OPENSSL_EXPORT int SSL_add1_chain_cert(SSL *ssl, X509 *x509); |
| 819 | |
| 820 | /* SSL_CTX_clear_chain_certs clears |ctx|'s certificate chain and returns |
| 821 | * one. */ |
| 822 | OPENSSL_EXPORT int SSL_CTX_clear_chain_certs(SSL_CTX *ctx); |
| 823 | |
| 824 | /* SSL_CTX_clear_extra_chain_certs calls |SSL_CTX_clear_chain_certs|. */ |
| 825 | OPENSSL_EXPORT int SSL_CTX_clear_extra_chain_certs(SSL_CTX *ctx); |
| 826 | |
| 827 | /* SSL_clear_chain_certs clears |ssl|'s certificate chain and returns one. */ |
| 828 | OPENSSL_EXPORT int SSL_clear_chain_certs(SSL *ssl); |
| 829 | |
| 830 | /* SSL_CTX_set_cert_cb sets a callback that is called to select a certificate. |
| 831 | * The callback returns one on success, zero on internal error, and a negative |
| 832 | * number on failure or to pause the handshake. If the handshake is paused, |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 833 | * |SSL_get_error| will return |SSL_ERROR_WANT_X509_LOOKUP|. |
| 834 | * |
| 835 | * On the client, the callback may call |SSL_get0_certificate_types| and |
| 836 | * |SSL_get_client_CA_list| for information on the server's certificate |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 837 | * request. |
| 838 | * |
| 839 | * On the server, the callback will be called on non-resumption handshakes, |
| 840 | * after extensions have been processed. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 841 | OPENSSL_EXPORT void SSL_CTX_set_cert_cb(SSL_CTX *ctx, |
| 842 | int (*cb)(SSL *ssl, void *arg), |
| 843 | void *arg); |
| 844 | |
| 845 | /* SSL_set_cert_cb sets a callback that is called to select a certificate. The |
| 846 | * callback returns one on success, zero on internal error, and a negative |
| 847 | * number on failure or to pause the handshake. If the handshake is paused, |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 848 | * |SSL_get_error| will return |SSL_ERROR_WANT_X509_LOOKUP|. |
| 849 | * |
| 850 | * On the client, the callback may call |SSL_get0_certificate_types| and |
| 851 | * |SSL_get_client_CA_list| for information on the server's certificate |
| 852 | * request. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 853 | OPENSSL_EXPORT void SSL_set_cert_cb(SSL *ssl, int (*cb)(SSL *ssl, void *arg), |
| 854 | void *arg); |
| 855 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 856 | /* SSL_get0_certificate_types, for a client, sets |*out_types| to an array |
| 857 | * containing the client certificate types requested by a server. It returns the |
| 858 | * length of the array. |
| 859 | * |
| 860 | * The behavior of this function is undefined except during the callbacks set by |
| 861 | * by |SSL_CTX_set_cert_cb| and |SSL_CTX_set_client_cert_cb| or when the |
| 862 | * handshake is paused because of them. */ |
| 863 | OPENSSL_EXPORT size_t SSL_get0_certificate_types(SSL *ssl, |
| 864 | const uint8_t **out_types); |
| 865 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 866 | /* SSL_certs_clear resets the private key, leaf certificate, and certificate |
| 867 | * chain of |ssl|. */ |
| 868 | OPENSSL_EXPORT void SSL_certs_clear(SSL *ssl); |
| 869 | |
| 870 | /* SSL_CTX_check_private_key returns one if the certificate and private key |
| 871 | * configured in |ctx| are consistent and zero otherwise. */ |
| 872 | OPENSSL_EXPORT int SSL_CTX_check_private_key(const SSL_CTX *ctx); |
| 873 | |
| 874 | /* SSL_check_private_key returns one if the certificate and private key |
| 875 | * configured in |ssl| are consistent and zero otherwise. */ |
| 876 | OPENSSL_EXPORT int SSL_check_private_key(const SSL *ssl); |
| 877 | |
| 878 | /* SSL_CTX_get0_certificate returns |ctx|'s leaf certificate. */ |
| 879 | OPENSSL_EXPORT X509 *SSL_CTX_get0_certificate(const SSL_CTX *ctx); |
| 880 | |
| 881 | /* SSL_get_certificate returns |ssl|'s leaf certificate. */ |
| 882 | OPENSSL_EXPORT X509 *SSL_get_certificate(const SSL *ssl); |
| 883 | |
| 884 | /* SSL_CTX_get0_privatekey returns |ctx|'s private key. */ |
| 885 | OPENSSL_EXPORT EVP_PKEY *SSL_CTX_get0_privatekey(const SSL_CTX *ctx); |
| 886 | |
| 887 | /* SSL_get_privatekey returns |ssl|'s private key. */ |
| 888 | OPENSSL_EXPORT EVP_PKEY *SSL_get_privatekey(const SSL *ssl); |
| 889 | |
| 890 | /* SSL_CTX_get0_chain_certs sets |*out_chain| to |ctx|'s certificate chain and |
| 891 | * returns one. */ |
| 892 | OPENSSL_EXPORT int SSL_CTX_get0_chain_certs(const SSL_CTX *ctx, |
| 893 | STACK_OF(X509) **out_chain); |
| 894 | |
| 895 | /* SSL_CTX_get_extra_chain_certs calls |SSL_CTX_get0_chain_certs|. */ |
| 896 | OPENSSL_EXPORT int SSL_CTX_get_extra_chain_certs(const SSL_CTX *ctx, |
| 897 | STACK_OF(X509) **out_chain); |
| 898 | |
| 899 | /* SSL_get0_chain_certs sets |*out_chain| to |ssl|'s certificate chain and |
| 900 | * returns one. */ |
| 901 | OPENSSL_EXPORT int SSL_get0_chain_certs(const SSL *ssl, |
| 902 | STACK_OF(X509) **out_chain); |
| 903 | |
| 904 | /* SSL_CTX_set_signed_cert_timestamp_list sets the list of signed certificate |
| 905 | * timestamps that is sent to clients that request it. The |list| argument must |
| 906 | * contain one or more SCT structures serialised as a SignedCertificateTimestamp |
| 907 | * List (see https://tools.ietf.org/html/rfc6962#section-3.3) – i.e. each SCT |
| 908 | * is prefixed by a big-endian, uint16 length and the concatenation of one or |
| 909 | * more such prefixed SCTs are themselves also prefixed by a uint16 length. It |
| 910 | * returns one on success and zero on error. The caller retains ownership of |
| 911 | * |list|. */ |
| 912 | OPENSSL_EXPORT int SSL_CTX_set_signed_cert_timestamp_list(SSL_CTX *ctx, |
| 913 | const uint8_t *list, |
| 914 | size_t list_len); |
| 915 | |
Robert Sloan | 5d62578 | 2017-02-13 09:55:39 -0800 | [diff] [blame] | 916 | /* SSL_set_signed_cert_timestamp_list sets the list of signed certificate |
| 917 | * timestamps that is sent to clients that request is. The same format as the |
| 918 | * one used for |SSL_CTX_set_signed_cert_timestamp_list| applies. The caller |
| 919 | * retains ownership of |list|. */ |
| 920 | OPENSSL_EXPORT int SSL_set_signed_cert_timestamp_list(SSL *ctx, |
| 921 | const uint8_t *list, |
| 922 | size_t list_len); |
| 923 | |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 924 | /* SSL_CTX_set_ocsp_response sets the OCSP response that is sent to clients |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 925 | * which request it. It returns one on success and zero on error. The caller |
| 926 | * retains ownership of |response|. */ |
| 927 | OPENSSL_EXPORT int SSL_CTX_set_ocsp_response(SSL_CTX *ctx, |
| 928 | const uint8_t *response, |
| 929 | size_t response_len); |
| 930 | |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 931 | /* SSL_set_ocsp_response sets the OCSP response that is sent to clients which |
Steven Valdez | e7531f0 | 2016-12-14 13:29:57 -0500 | [diff] [blame] | 932 | * request it. It returns one on success and zero on error. The caller retains |
| 933 | * ownership of |response|. */ |
| 934 | OPENSSL_EXPORT int SSL_set_ocsp_response(SSL *ssl, |
| 935 | const uint8_t *response, |
| 936 | size_t response_len); |
| 937 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 938 | /* SSL_SIGN_* are signature algorithm values as defined in TLS 1.3. */ |
| 939 | #define SSL_SIGN_RSA_PKCS1_SHA1 0x0201 |
| 940 | #define SSL_SIGN_RSA_PKCS1_SHA256 0x0401 |
| 941 | #define SSL_SIGN_RSA_PKCS1_SHA384 0x0501 |
| 942 | #define SSL_SIGN_RSA_PKCS1_SHA512 0x0601 |
| 943 | #define SSL_SIGN_ECDSA_SHA1 0x0203 |
| 944 | #define SSL_SIGN_ECDSA_SECP256R1_SHA256 0x0403 |
| 945 | #define SSL_SIGN_ECDSA_SECP384R1_SHA384 0x0503 |
| 946 | #define SSL_SIGN_ECDSA_SECP521R1_SHA512 0x0603 |
David Benjamin | 7c0d06c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 947 | #define SSL_SIGN_RSA_PSS_SHA256 0x0804 |
| 948 | #define SSL_SIGN_RSA_PSS_SHA384 0x0805 |
| 949 | #define SSL_SIGN_RSA_PSS_SHA512 0x0806 |
Robert Sloan | 572a4e2 | 2017-04-17 10:52:19 -0700 | [diff] [blame] | 950 | #define SSL_SIGN_ED25519 0x0807 |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 951 | |
| 952 | /* SSL_SIGN_RSA_PKCS1_MD5_SHA1 is an internal signature algorithm used to |
| 953 | * specify raw RSASSA-PKCS1-v1_5 with an MD5/SHA-1 concatenation, as used in TLS |
| 954 | * before TLS 1.2. */ |
| 955 | #define SSL_SIGN_RSA_PKCS1_MD5_SHA1 0xff01 |
| 956 | |
David Benjamin | f0c4a6c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 957 | /* SSL_CTX_set_signing_algorithm_prefs configures |ctx| to use |prefs| as the |
| 958 | * preference list when signing with |ctx|'s private key. It returns one on |
| 959 | * success and zero on error. |prefs| should not include the internal-only value |
| 960 | * |SSL_SIGN_RSA_PKCS1_MD5_SHA1|. */ |
| 961 | OPENSSL_EXPORT int SSL_CTX_set_signing_algorithm_prefs(SSL_CTX *ctx, |
| 962 | const uint16_t *prefs, |
| 963 | size_t num_prefs); |
| 964 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 965 | /* SSL_set_signing_algorithm_prefs configures |ssl| to use |prefs| as the |
| 966 | * preference list when signing with |ssl|'s private key. It returns one on |
| 967 | * success and zero on error. |prefs| should not include the internal-only value |
| 968 | * |SSL_SIGN_RSA_PKCS1_MD5_SHA1|. */ |
| 969 | OPENSSL_EXPORT int SSL_set_signing_algorithm_prefs(SSL *ssl, |
| 970 | const uint16_t *prefs, |
David Benjamin | f0c4a6c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 971 | size_t num_prefs); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 972 | |
| 973 | |
| 974 | /* Certificate and private key convenience functions. */ |
| 975 | |
Robert Sloan | 1c9db53 | 2017-03-13 08:03:59 -0700 | [diff] [blame] | 976 | /* SSL_CTX_set_chain_and_key sets the certificate chain and private key for a |
| 977 | * TLS client or server. References to the given |CRYPTO_BUFFER| and |EVP_PKEY| |
| 978 | * objects are added as needed. Exactly one of |privkey| or |privkey_method| |
| 979 | * may be non-NULL. Returns one on success and zero on error. */ |
| 980 | OPENSSL_EXPORT int SSL_CTX_set_chain_and_key( |
| 981 | SSL_CTX *ctx, CRYPTO_BUFFER *const *certs, size_t num_certs, |
| 982 | EVP_PKEY *privkey, const SSL_PRIVATE_KEY_METHOD *privkey_method); |
| 983 | |
| 984 | /* SSL_set_chain_and_key sets the certificate chain and private key for a TLS |
| 985 | * client or server. References to the given |CRYPTO_BUFFER| and |EVP_PKEY| |
| 986 | * objects are added as needed. Exactly one of |privkey| or |privkey_method| |
| 987 | * may be non-NULL. Returns one on success and zero on error. */ |
| 988 | OPENSSL_EXPORT int SSL_set_chain_and_key( |
| 989 | SSL *ssl, CRYPTO_BUFFER *const *certs, size_t num_certs, EVP_PKEY *privkey, |
| 990 | const SSL_PRIVATE_KEY_METHOD *privkey_method); |
| 991 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 992 | /* SSL_CTX_use_RSAPrivateKey sets |ctx|'s private key to |rsa|. It returns one |
| 993 | * on success and zero on failure. */ |
| 994 | OPENSSL_EXPORT int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa); |
| 995 | |
| 996 | /* SSL_use_RSAPrivateKey sets |ctx|'s private key to |rsa|. It returns one on |
| 997 | * success and zero on failure. */ |
| 998 | OPENSSL_EXPORT int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa); |
| 999 | |
| 1000 | /* The following functions configure certificates or private keys but take as |
| 1001 | * input DER-encoded structures. They return one on success and zero on |
| 1002 | * failure. */ |
| 1003 | |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 1004 | OPENSSL_EXPORT int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, size_t der_len, |
| 1005 | const uint8_t *der); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1006 | OPENSSL_EXPORT int SSL_use_certificate_ASN1(SSL *ssl, const uint8_t *der, |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 1007 | size_t der_len); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1008 | |
| 1009 | OPENSSL_EXPORT int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 1010 | const uint8_t *der, |
| 1011 | size_t der_len); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1012 | OPENSSL_EXPORT int SSL_use_PrivateKey_ASN1(int type, SSL *ssl, |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 1013 | const uint8_t *der, size_t der_len); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1014 | |
| 1015 | OPENSSL_EXPORT int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, |
| 1016 | const uint8_t *der, |
| 1017 | size_t der_len); |
| 1018 | OPENSSL_EXPORT int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, const uint8_t *der, |
| 1019 | size_t der_len); |
| 1020 | |
| 1021 | /* The following functions configure certificates or private keys but take as |
| 1022 | * input files to read from. They return one on success and zero on failure. The |
| 1023 | * |type| parameter is one of the |SSL_FILETYPE_*| values and determines whether |
| 1024 | * the file's contents are read as PEM or DER. */ |
| 1025 | |
| 1026 | #define SSL_FILETYPE_ASN1 X509_FILETYPE_ASN1 |
| 1027 | #define SSL_FILETYPE_PEM X509_FILETYPE_PEM |
| 1028 | |
| 1029 | OPENSSL_EXPORT int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, |
| 1030 | const char *file, |
| 1031 | int type); |
| 1032 | OPENSSL_EXPORT int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, |
| 1033 | int type); |
| 1034 | |
| 1035 | OPENSSL_EXPORT int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, |
| 1036 | int type); |
| 1037 | OPENSSL_EXPORT int SSL_use_certificate_file(SSL *ssl, const char *file, |
| 1038 | int type); |
| 1039 | |
| 1040 | OPENSSL_EXPORT int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, |
| 1041 | int type); |
| 1042 | OPENSSL_EXPORT int SSL_use_PrivateKey_file(SSL *ssl, const char *file, |
| 1043 | int type); |
| 1044 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1045 | /* SSL_CTX_use_certificate_chain_file configures certificates for |ctx|. It |
| 1046 | * reads the contents of |file| as a PEM-encoded leaf certificate followed |
| 1047 | * optionally by the certificate chain to send to the peer. It returns one on |
| 1048 | * success and zero on failure. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1049 | OPENSSL_EXPORT int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, |
| 1050 | const char *file); |
| 1051 | |
| 1052 | /* SSL_CTX_set_default_passwd_cb sets the password callback for PEM-based |
| 1053 | * convenience functions called on |ctx|. */ |
| 1054 | OPENSSL_EXPORT void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, |
| 1055 | pem_password_cb *cb); |
| 1056 | |
| 1057 | /* SSL_CTX_set_default_passwd_cb_userdata sets the userdata parameter for |
| 1058 | * |ctx|'s password callback. */ |
| 1059 | OPENSSL_EXPORT void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, |
| 1060 | void *data); |
| 1061 | |
| 1062 | |
| 1063 | /* Custom private keys. */ |
| 1064 | |
| 1065 | enum ssl_private_key_result_t { |
| 1066 | ssl_private_key_success, |
| 1067 | ssl_private_key_retry, |
| 1068 | ssl_private_key_failure, |
| 1069 | }; |
| 1070 | |
Robert Sloan | 1c9db53 | 2017-03-13 08:03:59 -0700 | [diff] [blame] | 1071 | /* ssl_private_key_method_st (aka |SSL_PRIVATE_KEY_METHOD|) describes private |
| 1072 | * key hooks. This is used to off-load signing operations to a custom, |
Robert Sloan | 572a4e2 | 2017-04-17 10:52:19 -0700 | [diff] [blame] | 1073 | * potentially asynchronous, backend. Metadata about the key such as the type |
| 1074 | * and size are parsed out of the certificate. |
| 1075 | * |
| 1076 | * TODO(davidben): This API has a number of legacy hooks. Remove the last |
| 1077 | * consumer of |sign_digest| and trim it. */ |
Robert Sloan | 1c9db53 | 2017-03-13 08:03:59 -0700 | [diff] [blame] | 1078 | struct ssl_private_key_method_st { |
Robert Sloan | 572a4e2 | 2017-04-17 10:52:19 -0700 | [diff] [blame] | 1079 | /* type is ignored and should be NULL. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1080 | int (*type)(SSL *ssl); |
| 1081 | |
Robert Sloan | 572a4e2 | 2017-04-17 10:52:19 -0700 | [diff] [blame] | 1082 | /* max_signature_len is ignored and should be NULL. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1083 | size_t (*max_signature_len)(SSL *ssl); |
| 1084 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 1085 | /* sign signs the message |in| in using the specified signature algorithm. On |
| 1086 | * success, it returns |ssl_private_key_success| and writes at most |max_out| |
| 1087 | * bytes of signature data to |out| and sets |*out_len| to the number of bytes |
| 1088 | * written. On failure, it returns |ssl_private_key_failure|. If the operation |
| 1089 | * has not completed, it returns |ssl_private_key_retry|. |sign| should |
| 1090 | * arrange for the high-level operation on |ssl| to be retried when the |
| 1091 | * operation is completed. This will result in a call to |complete|. |
| 1092 | * |
| 1093 | * |signature_algorithm| is one of the |SSL_SIGN_*| values, as defined in TLS |
| 1094 | * 1.3. Note that, in TLS 1.2, ECDSA algorithms do not require that curve |
| 1095 | * sizes match hash sizes, so the curve portion of |SSL_SIGN_ECDSA_*| values |
| 1096 | * must be ignored. BoringSSL will internally handle the curve matching logic |
| 1097 | * where appropriate. |
| 1098 | * |
| 1099 | * It is an error to call |sign| while another private key operation is in |
| 1100 | * progress on |ssl|. */ |
| 1101 | enum ssl_private_key_result_t (*sign)(SSL *ssl, uint8_t *out, size_t *out_len, |
| 1102 | size_t max_out, |
| 1103 | uint16_t signature_algorithm, |
| 1104 | const uint8_t *in, size_t in_len); |
| 1105 | |
| 1106 | /* sign_digest signs |in_len| bytes of digest from |in|. |md| is the hash |
| 1107 | * function used to calculate |in|. On success, it returns |
| 1108 | * |ssl_private_key_success| and writes at most |max_out| bytes of signature |
| 1109 | * data to |out|. On failure, it returns |ssl_private_key_failure|. If the |
| 1110 | * operation has not completed, it returns |ssl_private_key_retry|. |sign| |
| 1111 | * should arrange for the high-level operation on |ssl| to be retried when the |
| 1112 | * operation is completed. This will result in a call to |complete|. |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1113 | * |
| 1114 | * If the key is an RSA key, implementations must use PKCS#1 padding. |in| is |
| 1115 | * the digest itself, so the DigestInfo prefix, if any, must be prepended by |
| 1116 | * |sign|. If |md| is |EVP_md5_sha1|, there is no prefix. |
| 1117 | * |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 1118 | * It is an error to call |sign_digest| while another private key operation is |
| 1119 | * in progress on |ssl|. |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1120 | * |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 1121 | * This function is deprecated. Implement |sign| instead. |
| 1122 | * |
| 1123 | * TODO(davidben): Remove this function. */ |
| 1124 | enum ssl_private_key_result_t (*sign_digest)(SSL *ssl, uint8_t *out, |
| 1125 | size_t *out_len, size_t max_out, |
| 1126 | const EVP_MD *md, |
| 1127 | const uint8_t *in, |
| 1128 | size_t in_len); |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1129 | |
| 1130 | /* decrypt decrypts |in_len| bytes of encrypted data from |in|. On success it |
| 1131 | * returns |ssl_private_key_success|, writes at most |max_out| bytes of |
| 1132 | * decrypted data to |out| and sets |*out_len| to the actual number of bytes |
| 1133 | * written. On failure it returns |ssl_private_key_failure|. If the operation |
| 1134 | * has not completed, it returns |ssl_private_key_retry|. The caller should |
| 1135 | * arrange for the high-level operation on |ssl| to be retried when the |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 1136 | * operation is completed, which will result in a call to |complete|. This |
| 1137 | * function only works with RSA keys and should perform a raw RSA decryption |
| 1138 | * operation with no padding. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1139 | * |
| 1140 | * It is an error to call |decrypt| while another private key operation is in |
| 1141 | * progress on |ssl|. */ |
| 1142 | enum ssl_private_key_result_t (*decrypt)(SSL *ssl, uint8_t *out, |
| 1143 | size_t *out_len, size_t max_out, |
| 1144 | const uint8_t *in, size_t in_len); |
| 1145 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 1146 | /* complete completes a pending operation. If the operation has completed, it |
| 1147 | * returns |ssl_private_key_success| and writes the result to |out| as in |
| 1148 | * |sign|. Otherwise, it returns |ssl_private_key_failure| on failure and |
| 1149 | * |ssl_private_key_retry| if the operation is still in progress. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1150 | * |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 1151 | * |complete| may be called arbitrarily many times before completion, but it |
| 1152 | * is an error to call |complete| if there is no pending operation in progress |
| 1153 | * on |ssl|. */ |
| 1154 | enum ssl_private_key_result_t (*complete)(SSL *ssl, uint8_t *out, |
| 1155 | size_t *out_len, size_t max_out); |
Robert Sloan | 1c9db53 | 2017-03-13 08:03:59 -0700 | [diff] [blame] | 1156 | }; |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1157 | |
| 1158 | /* SSL_set_private_key_method configures a custom private key on |ssl|. |
| 1159 | * |key_method| must remain valid for the lifetime of |ssl|. */ |
| 1160 | OPENSSL_EXPORT void SSL_set_private_key_method( |
| 1161 | SSL *ssl, const SSL_PRIVATE_KEY_METHOD *key_method); |
| 1162 | |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 1163 | /* SSL_CTX_set_private_key_method configures a custom private key on |ctx|. |
| 1164 | * |key_method| must remain valid for the lifetime of |ctx|. */ |
| 1165 | OPENSSL_EXPORT void SSL_CTX_set_private_key_method( |
| 1166 | SSL_CTX *ctx, const SSL_PRIVATE_KEY_METHOD *key_method); |
| 1167 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1168 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1169 | /* Cipher suites. |
| 1170 | * |
| 1171 | * |SSL_CIPHER| objects represent cipher suites. */ |
| 1172 | |
| 1173 | DECLARE_STACK_OF(SSL_CIPHER) |
| 1174 | |
| 1175 | /* SSL_get_cipher_by_value returns the structure representing a TLS cipher |
| 1176 | * suite based on its assigned number, or NULL if unknown. See |
| 1177 | * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4. */ |
| 1178 | OPENSSL_EXPORT const SSL_CIPHER *SSL_get_cipher_by_value(uint16_t value); |
| 1179 | |
| 1180 | /* SSL_CIPHER_get_id returns |cipher|'s id. It may be cast to a |uint16_t| to |
| 1181 | * get the cipher suite value. */ |
| 1182 | OPENSSL_EXPORT uint32_t SSL_CIPHER_get_id(const SSL_CIPHER *cipher); |
| 1183 | |
| 1184 | /* SSL_CIPHER_is_AES returns one if |cipher| uses AES (either GCM or CBC |
| 1185 | * mode). */ |
| 1186 | OPENSSL_EXPORT int SSL_CIPHER_is_AES(const SSL_CIPHER *cipher); |
| 1187 | |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 1188 | /* SSL_CIPHER_has_SHA1_HMAC returns one if |cipher| uses HMAC-SHA1. */ |
| 1189 | OPENSSL_EXPORT int SSL_CIPHER_has_SHA1_HMAC(const SSL_CIPHER *cipher); |
| 1190 | |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 1191 | /* SSL_CIPHER_has_SHA256_HMAC returns one if |cipher| uses HMAC-SHA256. */ |
| 1192 | OPENSSL_EXPORT int SSL_CIPHER_has_SHA256_HMAC(const SSL_CIPHER *cipher); |
| 1193 | |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 1194 | /* SSL_CIPHER_is_AEAD returns one if |cipher| uses an AEAD cipher. */ |
| 1195 | OPENSSL_EXPORT int SSL_CIPHER_is_AEAD(const SSL_CIPHER *cipher); |
| 1196 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1197 | /* SSL_CIPHER_is_AESGCM returns one if |cipher| uses AES-GCM. */ |
| 1198 | OPENSSL_EXPORT int SSL_CIPHER_is_AESGCM(const SSL_CIPHER *cipher); |
| 1199 | |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 1200 | /* SSL_CIPHER_is_AES128GCM returns one if |cipher| uses 128-bit AES-GCM. */ |
| 1201 | OPENSSL_EXPORT int SSL_CIPHER_is_AES128GCM(const SSL_CIPHER *cipher); |
| 1202 | |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 1203 | /* SSL_CIPHER_is_AES128CBC returns one if |cipher| uses 128-bit AES in CBC |
| 1204 | * mode. */ |
| 1205 | OPENSSL_EXPORT int SSL_CIPHER_is_AES128CBC(const SSL_CIPHER *cipher); |
| 1206 | |
| 1207 | /* SSL_CIPHER_is_AES256CBC returns one if |cipher| uses 256-bit AES in CBC |
| 1208 | * mode. */ |
| 1209 | OPENSSL_EXPORT int SSL_CIPHER_is_AES256CBC(const SSL_CIPHER *cipher); |
| 1210 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1211 | /* SSL_CIPHER_is_CHACHA20POLY1305 returns one if |cipher| uses |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 1212 | * CHACHA20_POLY1305. Note this includes both the RFC 7905 and |
| 1213 | * draft-agl-tls-chacha20poly1305-04 versions. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1214 | OPENSSL_EXPORT int SSL_CIPHER_is_CHACHA20POLY1305(const SSL_CIPHER *cipher); |
| 1215 | |
| 1216 | /* SSL_CIPHER_is_NULL returns one if |cipher| does not encrypt. */ |
| 1217 | OPENSSL_EXPORT int SSL_CIPHER_is_NULL(const SSL_CIPHER *cipher); |
| 1218 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1219 | /* SSL_CIPHER_is_block_cipher returns one if |cipher| is a block cipher. */ |
| 1220 | OPENSSL_EXPORT int SSL_CIPHER_is_block_cipher(const SSL_CIPHER *cipher); |
| 1221 | |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 1222 | /* SSL_CIPHER_is_ECDSA returns one if |cipher| uses ECDSA. */ |
| 1223 | OPENSSL_EXPORT int SSL_CIPHER_is_ECDSA(const SSL_CIPHER *cipher); |
| 1224 | |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 1225 | /* SSL_CIPHER_is_ECDHE returns one if |cipher| uses ECDHE. */ |
| 1226 | OPENSSL_EXPORT int SSL_CIPHER_is_ECDHE(const SSL_CIPHER *cipher); |
| 1227 | |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 1228 | /* SSL_CIPHER_is_static_RSA returns one if |cipher| uses the static RSA key |
| 1229 | * exchange. */ |
| 1230 | OPENSSL_EXPORT int SSL_CIPHER_is_static_RSA(const SSL_CIPHER *cipher); |
| 1231 | |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 1232 | /* SSL_CIPHER_get_min_version returns the minimum protocol version required |
| 1233 | * for |cipher|. */ |
| 1234 | OPENSSL_EXPORT uint16_t SSL_CIPHER_get_min_version(const SSL_CIPHER *cipher); |
| 1235 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 1236 | /* SSL_CIPHER_get_max_version returns the maximum protocol version that |
| 1237 | * supports |cipher|. */ |
| 1238 | OPENSSL_EXPORT uint16_t SSL_CIPHER_get_max_version(const SSL_CIPHER *cipher); |
| 1239 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1240 | /* SSL_CIPHER_get_name returns the OpenSSL name of |cipher|. */ |
| 1241 | OPENSSL_EXPORT const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher); |
| 1242 | |
| 1243 | /* SSL_CIPHER_get_kx_name returns a string that describes the key-exchange |
Steven Valdez | bb1ceac | 2016-10-07 10:34:51 -0400 | [diff] [blame] | 1244 | * method used by |cipher|. For example, "ECDHE_ECDSA". TLS 1.3 AEAD-only |
| 1245 | * ciphers return the string "GENERIC". */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1246 | OPENSSL_EXPORT const char *SSL_CIPHER_get_kx_name(const SSL_CIPHER *cipher); |
| 1247 | |
| 1248 | /* SSL_CIPHER_get_rfc_name returns a newly-allocated string with the standard |
| 1249 | * name for |cipher| or NULL on error. For example, |
| 1250 | * "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256". The caller is responsible for |
| 1251 | * calling |OPENSSL_free| on the result. */ |
| 1252 | OPENSSL_EXPORT char *SSL_CIPHER_get_rfc_name(const SSL_CIPHER *cipher); |
| 1253 | |
| 1254 | /* SSL_CIPHER_get_bits returns the strength, in bits, of |cipher|. If |
| 1255 | * |out_alg_bits| is not NULL, it writes the number of bits consumed by the |
| 1256 | * symmetric algorithm to |*out_alg_bits|. */ |
| 1257 | OPENSSL_EXPORT int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, |
| 1258 | int *out_alg_bits); |
| 1259 | |
| 1260 | |
| 1261 | /* Cipher suite configuration. |
| 1262 | * |
| 1263 | * OpenSSL uses a mini-language to configure cipher suites. The language |
| 1264 | * maintains an ordered list of enabled ciphers, along with an ordered list of |
| 1265 | * disabled but available ciphers. Initially, all ciphers are disabled with a |
| 1266 | * default ordering. The cipher string is then interpreted as a sequence of |
| 1267 | * directives, separated by colons, each of which modifies this state. |
| 1268 | * |
| 1269 | * Most directives consist of a one character or empty opcode followed by a |
| 1270 | * selector which matches a subset of available ciphers. |
| 1271 | * |
| 1272 | * Available opcodes are: |
| 1273 | * |
| 1274 | * The empty opcode enables and appends all matching disabled ciphers to the |
| 1275 | * end of the enabled list. The newly appended ciphers are ordered relative to |
| 1276 | * each other matching their order in the disabled list. |
| 1277 | * |
| 1278 | * |-| disables all matching enabled ciphers and prepends them to the disabled |
| 1279 | * list, with relative order from the enabled list preserved. This means the |
| 1280 | * most recently disabled ciphers get highest preference relative to other |
| 1281 | * disabled ciphers if re-enabled. |
| 1282 | * |
| 1283 | * |+| moves all matching enabled ciphers to the end of the enabled list, with |
| 1284 | * relative order preserved. |
| 1285 | * |
| 1286 | * |!| deletes all matching ciphers, enabled or not, from either list. Deleted |
| 1287 | * ciphers will not matched by future operations. |
| 1288 | * |
| 1289 | * A selector may be a specific cipher (using the OpenSSL name for the cipher) |
| 1290 | * or one or more rules separated by |+|. The final selector matches the |
| 1291 | * intersection of each rule. For instance, |AESGCM+aECDSA| matches |
| 1292 | * ECDSA-authenticated AES-GCM ciphers. |
| 1293 | * |
| 1294 | * Available cipher rules are: |
| 1295 | * |
| 1296 | * |ALL| matches all ciphers. |
| 1297 | * |
| 1298 | * |kRSA|, |kDHE|, |kECDHE|, and |kPSK| match ciphers using plain RSA, DHE, |
| 1299 | * ECDHE, and plain PSK key exchanges, respectively. Note that ECDHE_PSK is |
| 1300 | * matched by |kECDHE| and not |kPSK|. |
| 1301 | * |
| 1302 | * |aRSA|, |aECDSA|, and |aPSK| match ciphers authenticated by RSA, ECDSA, and |
| 1303 | * a pre-shared key, respectively. |
| 1304 | * |
| 1305 | * |RSA|, |DHE|, |ECDHE|, |PSK|, |ECDSA|, and |PSK| are aliases for the |
| 1306 | * corresponding |k*| or |a*| cipher rule. |RSA| is an alias for |kRSA|, not |
| 1307 | * |aRSA|. |
| 1308 | * |
David Benjamin | 7c0d06c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 1309 | * |3DES|, |AES128|, |AES256|, |AES|, |AESGCM|, |CHACHA20| match ciphers |
| 1310 | * whose bulk cipher use the corresponding encryption scheme. Note that |
| 1311 | * |AES|, |AES128|, and |AES256| match both CBC and GCM ciphers. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1312 | * |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 1313 | * |SHA1|, |SHA256|, and |SHA384| match legacy cipher suites using the |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1314 | * corresponding hash function in their MAC. AEADs are matched by none of |
| 1315 | * these. |
| 1316 | * |
| 1317 | * |SHA| is an alias for |SHA1|. |
| 1318 | * |
| 1319 | * Although implemented, authentication-only ciphers match no rules and must be |
| 1320 | * explicitly selected by name. |
| 1321 | * |
| 1322 | * Deprecated cipher rules: |
| 1323 | * |
| 1324 | * |kEDH|, |EDH|, |kEECDH|, and |EECDH| are legacy aliases for |kDHE|, |DHE|, |
| 1325 | * |kECDHE|, and |ECDHE|, respectively. |
| 1326 | * |
David Benjamin | 7c0d06c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 1327 | * |HIGH| is an alias for |ALL|. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1328 | * |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 1329 | * |FIPS| is an alias for |HIGH|. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1330 | * |
| 1331 | * |SSLv3| and |TLSv1| match ciphers available in TLS 1.1 or earlier. |
| 1332 | * |TLSv1_2| matches ciphers new in TLS 1.2. This is confusing and should not |
| 1333 | * be used. |
| 1334 | * |
Robert Sloan | 7c50ec5 | 2017-02-27 08:17:21 -0800 | [diff] [blame] | 1335 | * Unknown rules are silently ignored by legacy APIs, and rejected by APIs with |
| 1336 | * "strict" in the name, which should be preferred. Cipher lists can be long and |
| 1337 | * it's easy to commit typos. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1338 | * |
| 1339 | * The special |@STRENGTH| directive will sort all enabled ciphers by strength. |
| 1340 | * |
| 1341 | * The |DEFAULT| directive, when appearing at the front of the string, expands |
| 1342 | * to the default ordering of available ciphers. |
| 1343 | * |
| 1344 | * If configuring a server, one may also configure equal-preference groups to |
| 1345 | * partially respect the client's preferences when |
| 1346 | * |SSL_OP_CIPHER_SERVER_PREFERENCE| is enabled. Ciphers in an equal-preference |
| 1347 | * group have equal priority and use the client order. This may be used to |
| 1348 | * enforce that AEADs are preferred but select AES-GCM vs. ChaCha20-Poly1305 |
| 1349 | * based on client preferences. An equal-preference is specified with square |
| 1350 | * brackets, combining multiple selectors separated by |. For example: |
| 1351 | * |
| 1352 | * [ECDHE-ECDSA-CHACHA20-POLY1305|ECDHE-ECDSA-AES128-GCM-SHA256] |
| 1353 | * |
| 1354 | * Once an equal-preference group is used, future directives must be |
Steven Valdez | 909b19f | 2016-11-21 15:35:44 -0500 | [diff] [blame] | 1355 | * opcode-less. |
| 1356 | * |
| 1357 | * TLS 1.3 ciphers do not participate in this mechanism and instead have a |
| 1358 | * built-in preference order. Functions to set cipher lists do not affect TLS |
| 1359 | * 1.3, and functions to query the cipher list do not include TLS 1.3 |
| 1360 | * ciphers. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1361 | |
| 1362 | /* SSL_DEFAULT_CIPHER_LIST is the default cipher suite configuration. It is |
| 1363 | * substituted when a cipher string starts with 'DEFAULT'. */ |
| 1364 | #define SSL_DEFAULT_CIPHER_LIST "ALL" |
| 1365 | |
Robert Sloan | 7c50ec5 | 2017-02-27 08:17:21 -0800 | [diff] [blame] | 1366 | /* SSL_CTX_set_strict_cipher_list configures the cipher list for |ctx|, |
| 1367 | * evaluating |str| as a cipher string and returning error if |str| contains |
| 1368 | * anything meaningless. It returns one on success and zero on failure. */ |
| 1369 | OPENSSL_EXPORT int SSL_CTX_set_strict_cipher_list(SSL_CTX *ctx, |
| 1370 | const char *str); |
| 1371 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1372 | /* SSL_CTX_set_cipher_list configures the cipher list for |ctx|, evaluating |
Robert Sloan | 7c50ec5 | 2017-02-27 08:17:21 -0800 | [diff] [blame] | 1373 | * |str| as a cipher string. It returns one on success and zero on failure. |
| 1374 | * |
| 1375 | * Prefer to use |SSL_CTX_set_strict_cipher_list|. This function tolerates |
| 1376 | * garbage inputs, unless an empty cipher list results. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1377 | OPENSSL_EXPORT int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str); |
| 1378 | |
Robert Sloan | 7c50ec5 | 2017-02-27 08:17:21 -0800 | [diff] [blame] | 1379 | /* SSL_set_strict_cipher_list configures the cipher list for |ssl|, evaluating |
| 1380 | * |str| as a cipher string and returning error if |str| contains anything |
| 1381 | * meaningless. It returns one on success and zero on failure. */ |
| 1382 | OPENSSL_EXPORT int SSL_set_strict_cipher_list(SSL *ssl, const char *str); |
| 1383 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1384 | /* SSL_set_cipher_list configures the cipher list for |ssl|, evaluating |str| as |
Robert Sloan | 7c50ec5 | 2017-02-27 08:17:21 -0800 | [diff] [blame] | 1385 | * a cipher string. It returns one on success and zero on failure. |
| 1386 | * |
| 1387 | * Prefer to use |SSL_set_strict_cipher_list|. This function tolerates garbage |
| 1388 | * inputs, unless an empty cipher list results. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1389 | OPENSSL_EXPORT int SSL_set_cipher_list(SSL *ssl, const char *str); |
| 1390 | |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 1391 | /* SSL_CTX_get_ciphers returns the cipher list for |ctx|, in order of |
| 1392 | * preference. */ |
| 1393 | OPENSSL_EXPORT STACK_OF(SSL_CIPHER) *SSL_CTX_get_ciphers(const SSL_CTX *ctx); |
| 1394 | |
Robert Sloan | 69939df | 2017-01-09 10:53:07 -0800 | [diff] [blame] | 1395 | /* SSL_get_ciphers returns the cipher list for |ssl|, in order of preference. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1396 | OPENSSL_EXPORT STACK_OF(SSL_CIPHER) *SSL_get_ciphers(const SSL *ssl); |
| 1397 | |
| 1398 | |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 1399 | /* Connection information. */ |
| 1400 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1401 | /* SSL_is_init_finished returns one if |ssl| has completed its initial handshake |
| 1402 | * and has no pending handshake. It returns zero otherwise. */ |
| 1403 | OPENSSL_EXPORT int SSL_is_init_finished(const SSL *ssl); |
| 1404 | |
| 1405 | /* SSL_in_init returns one if |ssl| has a pending handshake and zero |
| 1406 | * otherwise. */ |
| 1407 | OPENSSL_EXPORT int SSL_in_init(const SSL *ssl); |
| 1408 | |
| 1409 | /* SSL_in_false_start returns one if |ssl| has a pending handshake that is in |
| 1410 | * False Start. |SSL_write| may be called at this point without waiting for the |
| 1411 | * peer, but |SSL_read| will complete the handshake before accepting application |
| 1412 | * data. |
| 1413 | * |
| 1414 | * See also |SSL_MODE_ENABLE_FALSE_START|. */ |
| 1415 | OPENSSL_EXPORT int SSL_in_false_start(const SSL *ssl); |
| 1416 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1417 | /* SSL_get_peer_certificate returns the peer's leaf certificate or NULL if the |
| 1418 | * peer did not use certificates. The caller must call |X509_free| on the |
| 1419 | * result to release it. */ |
| 1420 | OPENSSL_EXPORT X509 *SSL_get_peer_certificate(const SSL *ssl); |
| 1421 | |
| 1422 | /* SSL_get_peer_cert_chain returns the peer's certificate chain or NULL if |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 1423 | * unavailable or the peer did not use certificates. This is the unverified list |
| 1424 | * of certificates as sent by the peer, not the final chain built during |
| 1425 | * verification. The caller does not take ownership of the result. |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1426 | * |
| 1427 | * WARNING: This function behaves differently between client and server. If |
| 1428 | * |ssl| is a server, the returned chain does not include the leaf certificate. |
| 1429 | * If a client, it does. */ |
| 1430 | OPENSSL_EXPORT STACK_OF(X509) *SSL_get_peer_cert_chain(const SSL *ssl); |
| 1431 | |
Steven Valdez | e7531f0 | 2016-12-14 13:29:57 -0500 | [diff] [blame] | 1432 | /* SSL_get_peer_full_cert_chain returns the peer's certificate chain, or NULL if |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 1433 | * unavailable or the peer did not use certificates. This is the unverified list |
| 1434 | * of certificates as sent by the peer, not the final chain built during |
| 1435 | * verification. The caller does not take ownership of the result. |
Steven Valdez | e7531f0 | 2016-12-14 13:29:57 -0500 | [diff] [blame] | 1436 | * |
| 1437 | * This is the same as |SSL_get_peer_cert_chain| except that this function |
| 1438 | * always returns the full chain, i.e. the first element of the return value |
| 1439 | * (if any) will be the leaf certificate. In constrast, |
| 1440 | * |SSL_get_peer_cert_chain| returns only the intermediate certificates if the |
| 1441 | * |ssl| is a server. */ |
| 1442 | OPENSSL_EXPORT STACK_OF(X509) *SSL_get_peer_full_cert_chain(const SSL *ssl); |
| 1443 | |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 1444 | /* SSL_get0_peer_certificates returns the peer's certificate chain, or NULL if |
| 1445 | * unavailable or the peer did not use certificates. This is the unverified list |
| 1446 | * of certificates as sent by the peer, not the final chain built during |
| 1447 | * verification. The caller does not take ownership of the result. |
| 1448 | * |
| 1449 | * This is the |CRYPTO_BUFFER| variant of |SSL_get_peer_full_cert_chain|. */ |
| 1450 | OPENSSL_EXPORT STACK_OF(CRYPTO_BUFFER) * |
| 1451 | SSL_get0_peer_certificates(const SSL *ssl); |
| 1452 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1453 | /* SSL_get0_signed_cert_timestamp_list sets |*out| and |*out_len| to point to |
| 1454 | * |*out_len| bytes of SCT information from the server. This is only valid if |
| 1455 | * |ssl| is a client. The SCT information is a SignedCertificateTimestampList |
| 1456 | * (including the two leading length bytes). |
| 1457 | * See https://tools.ietf.org/html/rfc6962#section-3.3 |
| 1458 | * If no SCT was received then |*out_len| will be zero on return. |
| 1459 | * |
| 1460 | * WARNING: the returned data is not guaranteed to be well formed. */ |
| 1461 | OPENSSL_EXPORT void SSL_get0_signed_cert_timestamp_list(const SSL *ssl, |
| 1462 | const uint8_t **out, |
| 1463 | size_t *out_len); |
| 1464 | |
| 1465 | /* SSL_get0_ocsp_response sets |*out| and |*out_len| to point to |*out_len| |
| 1466 | * bytes of an OCSP response from the server. This is the DER encoding of an |
| 1467 | * OCSPResponse type as defined in RFC 2560. |
| 1468 | * |
| 1469 | * WARNING: the returned data is not guaranteed to be well formed. */ |
| 1470 | OPENSSL_EXPORT void SSL_get0_ocsp_response(const SSL *ssl, const uint8_t **out, |
| 1471 | size_t *out_len); |
| 1472 | |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 1473 | /* SSL_get_tls_unique writes at most |max_out| bytes of the tls-unique value |
| 1474 | * for |ssl| to |out| and sets |*out_len| to the number of bytes written. It |
| 1475 | * returns one on success or zero on error. In general |max_out| should be at |
| 1476 | * least 12. |
| 1477 | * |
| 1478 | * This function will always fail if the initial handshake has not completed. |
| 1479 | * The tls-unique value will change after a renegotiation but, since |
| 1480 | * renegotiations can be initiated by the server at any point, the higher-level |
| 1481 | * protocol must either leave them disabled or define states in which the |
| 1482 | * tls-unique value can be read. |
| 1483 | * |
| 1484 | * The tls-unique value is defined by |
| 1485 | * https://tools.ietf.org/html/rfc5929#section-3.1. Due to a weakness in the |
| 1486 | * TLS protocol, tls-unique is broken for resumed connections unless the |
| 1487 | * Extended Master Secret extension is negotiated. Thus this function will |
| 1488 | * return zero if |ssl| performed session resumption unless EMS was used when |
| 1489 | * negotiating the original session. */ |
| 1490 | OPENSSL_EXPORT int SSL_get_tls_unique(const SSL *ssl, uint8_t *out, |
| 1491 | size_t *out_len, size_t max_out); |
| 1492 | |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 1493 | /* SSL_get_extms_support returns one if the Extended Master Secret extension or |
| 1494 | * TLS 1.3 was negotiated. Otherwise, it returns zero. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1495 | OPENSSL_EXPORT int SSL_get_extms_support(const SSL *ssl); |
| 1496 | |
| 1497 | /* SSL_get_current_cipher returns the cipher used in the current outgoing |
| 1498 | * connection state, or NULL if the null cipher is active. */ |
| 1499 | OPENSSL_EXPORT const SSL_CIPHER *SSL_get_current_cipher(const SSL *ssl); |
| 1500 | |
| 1501 | /* SSL_session_reused returns one if |ssl| performed an abbreviated handshake |
| 1502 | * and zero otherwise. |
| 1503 | * |
| 1504 | * TODO(davidben): Hammer down the semantics of this API while a handshake, |
| 1505 | * initial or renego, is in progress. */ |
| 1506 | OPENSSL_EXPORT int SSL_session_reused(const SSL *ssl); |
| 1507 | |
| 1508 | /* SSL_get_secure_renegotiation_support returns one if the peer supports secure |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 1509 | * renegotiation (RFC 5746) or TLS 1.3. Otherwise, it returns zero. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1510 | OPENSSL_EXPORT int SSL_get_secure_renegotiation_support(const SSL *ssl); |
| 1511 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1512 | /* SSL_export_keying_material exports a value derived from the master secret, as |
| 1513 | * specified in RFC 5705. It writes |out_len| bytes to |out| given a label and |
| 1514 | * optional context. (Since a zero length context is allowed, the |use_context| |
| 1515 | * flag controls whether a context is included.) |
| 1516 | * |
| 1517 | * It returns one on success and zero otherwise. */ |
| 1518 | OPENSSL_EXPORT int SSL_export_keying_material( |
| 1519 | SSL *ssl, uint8_t *out, size_t out_len, const char *label, size_t label_len, |
| 1520 | const uint8_t *context, size_t context_len, int use_context); |
| 1521 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1522 | |
| 1523 | /* Custom extensions. |
| 1524 | * |
| 1525 | * The custom extension functions allow TLS extensions to be added to |
| 1526 | * ClientHello and ServerHello messages. */ |
| 1527 | |
| 1528 | /* SSL_custom_ext_add_cb is a callback function that is called when the |
| 1529 | * ClientHello (for clients) or ServerHello (for servers) is constructed. In |
| 1530 | * the case of a server, this callback will only be called for a given |
| 1531 | * extension if the ClientHello contained that extension – it's not possible to |
| 1532 | * inject extensions into a ServerHello that the client didn't request. |
| 1533 | * |
| 1534 | * When called, |extension_value| will contain the extension number that is |
| 1535 | * being considered for addition (so that a single callback can handle multiple |
| 1536 | * extensions). If the callback wishes to include the extension, it must set |
| 1537 | * |*out| to point to |*out_len| bytes of extension contents and return one. In |
| 1538 | * this case, the corresponding |SSL_custom_ext_free_cb| callback will later be |
| 1539 | * called with the value of |*out| once that data has been copied. |
| 1540 | * |
| 1541 | * If the callback does not wish to add an extension it must return zero. |
| 1542 | * |
| 1543 | * Alternatively, the callback can abort the connection by setting |
| 1544 | * |*out_alert_value| to a TLS alert number and returning -1. */ |
| 1545 | typedef int (*SSL_custom_ext_add_cb)(SSL *ssl, unsigned extension_value, |
| 1546 | const uint8_t **out, size_t *out_len, |
| 1547 | int *out_alert_value, void *add_arg); |
| 1548 | |
| 1549 | /* SSL_custom_ext_free_cb is a callback function that is called by OpenSSL iff |
| 1550 | * an |SSL_custom_ext_add_cb| callback previously returned one. In that case, |
| 1551 | * this callback is called and passed the |out| pointer that was returned by |
| 1552 | * the add callback. This is to free any dynamically allocated data created by |
| 1553 | * the add callback. */ |
| 1554 | typedef void (*SSL_custom_ext_free_cb)(SSL *ssl, unsigned extension_value, |
| 1555 | const uint8_t *out, void *add_arg); |
| 1556 | |
| 1557 | /* SSL_custom_ext_parse_cb is a callback function that is called by OpenSSL to |
| 1558 | * parse an extension from the peer: that is from the ServerHello for a client |
| 1559 | * and from the ClientHello for a server. |
| 1560 | * |
| 1561 | * When called, |extension_value| will contain the extension number and the |
| 1562 | * contents of the extension are |contents_len| bytes at |contents|. |
| 1563 | * |
| 1564 | * The callback must return one to continue the handshake. Otherwise, if it |
| 1565 | * returns zero, a fatal alert with value |*out_alert_value| is sent and the |
| 1566 | * handshake is aborted. */ |
| 1567 | typedef int (*SSL_custom_ext_parse_cb)(SSL *ssl, unsigned extension_value, |
| 1568 | const uint8_t *contents, |
| 1569 | size_t contents_len, |
| 1570 | int *out_alert_value, void *parse_arg); |
| 1571 | |
| 1572 | /* SSL_extension_supported returns one iff OpenSSL internally handles |
| 1573 | * extensions of type |extension_value|. This can be used to avoid registering |
| 1574 | * custom extension handlers for extensions that a future version of OpenSSL |
| 1575 | * may handle internally. */ |
| 1576 | OPENSSL_EXPORT int SSL_extension_supported(unsigned extension_value); |
| 1577 | |
| 1578 | /* SSL_CTX_add_client_custom_ext registers callback functions for handling |
| 1579 | * custom TLS extensions for client connections. |
| 1580 | * |
| 1581 | * If |add_cb| is NULL then an empty extension will be added in each |
| 1582 | * ClientHello. Otherwise, see the comment for |SSL_custom_ext_add_cb| about |
| 1583 | * this callback. |
| 1584 | * |
| 1585 | * The |free_cb| may be NULL if |add_cb| doesn't dynamically allocate data that |
| 1586 | * needs to be freed. |
| 1587 | * |
| 1588 | * It returns one on success or zero on error. It's always an error to register |
| 1589 | * callbacks for the same extension twice, or to register callbacks for an |
| 1590 | * extension that OpenSSL handles internally. See |SSL_extension_supported| to |
| 1591 | * discover, at runtime, which extensions OpenSSL handles internally. */ |
| 1592 | OPENSSL_EXPORT int SSL_CTX_add_client_custom_ext( |
| 1593 | SSL_CTX *ctx, unsigned extension_value, SSL_custom_ext_add_cb add_cb, |
| 1594 | SSL_custom_ext_free_cb free_cb, void *add_arg, |
| 1595 | SSL_custom_ext_parse_cb parse_cb, void *parse_arg); |
| 1596 | |
| 1597 | /* SSL_CTX_add_server_custom_ext is the same as |
| 1598 | * |SSL_CTX_add_client_custom_ext|, but for server connections. |
| 1599 | * |
| 1600 | * Unlike on the client side, if |add_cb| is NULL no extension will be added. |
| 1601 | * The |add_cb|, if any, will only be called if the ClientHello contained a |
| 1602 | * matching extension. */ |
| 1603 | OPENSSL_EXPORT int SSL_CTX_add_server_custom_ext( |
| 1604 | SSL_CTX *ctx, unsigned extension_value, SSL_custom_ext_add_cb add_cb, |
| 1605 | SSL_custom_ext_free_cb free_cb, void *add_arg, |
| 1606 | SSL_custom_ext_parse_cb parse_cb, void *parse_arg); |
| 1607 | |
| 1608 | |
| 1609 | /* Sessions. |
| 1610 | * |
| 1611 | * An |SSL_SESSION| represents an SSL session that may be resumed in an |
| 1612 | * abbreviated handshake. It is reference-counted and immutable. Once |
| 1613 | * established, an |SSL_SESSION| may be shared by multiple |SSL| objects on |
| 1614 | * different threads and must not be modified. */ |
| 1615 | |
| 1616 | DECLARE_LHASH_OF(SSL_SESSION) |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1617 | DECLARE_PEM_rw(SSL_SESSION, SSL_SESSION) |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1618 | |
| 1619 | /* SSL_SESSION_new returns a newly-allocated blank |SSL_SESSION| or NULL on |
Robert Sloan | 5d62578 | 2017-02-13 09:55:39 -0800 | [diff] [blame] | 1620 | * error. This may be useful when writing tests but should otherwise not be |
| 1621 | * used. */ |
| 1622 | OPENSSL_EXPORT SSL_SESSION *SSL_SESSION_new(const SSL_CTX *ctx); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1623 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 1624 | /* SSL_SESSION_up_ref increments the reference count of |session| and returns |
| 1625 | * one. */ |
| 1626 | OPENSSL_EXPORT int SSL_SESSION_up_ref(SSL_SESSION *session); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1627 | |
| 1628 | /* SSL_SESSION_free decrements the reference count of |session|. If it reaches |
| 1629 | * zero, all data referenced by |session| and |session| itself are released. */ |
| 1630 | OPENSSL_EXPORT void SSL_SESSION_free(SSL_SESSION *session); |
| 1631 | |
| 1632 | /* SSL_SESSION_to_bytes serializes |in| into a newly allocated buffer and sets |
| 1633 | * |*out_data| to that buffer and |*out_len| to its length. The caller takes |
| 1634 | * ownership of the buffer and must call |OPENSSL_free| when done. It returns |
| 1635 | * one on success and zero on error. */ |
| 1636 | OPENSSL_EXPORT int SSL_SESSION_to_bytes(const SSL_SESSION *in, |
| 1637 | uint8_t **out_data, size_t *out_len); |
| 1638 | |
| 1639 | /* SSL_SESSION_to_bytes_for_ticket serializes |in|, but excludes the session |
| 1640 | * identification information, namely the session ID and ticket. */ |
| 1641 | OPENSSL_EXPORT int SSL_SESSION_to_bytes_for_ticket(const SSL_SESSION *in, |
| 1642 | uint8_t **out_data, |
| 1643 | size_t *out_len); |
| 1644 | |
| 1645 | /* SSL_SESSION_from_bytes parses |in_len| bytes from |in| as an SSL_SESSION. It |
| 1646 | * returns a newly-allocated |SSL_SESSION| on success or NULL on error. */ |
Robert Sloan | 5d62578 | 2017-02-13 09:55:39 -0800 | [diff] [blame] | 1647 | OPENSSL_EXPORT SSL_SESSION *SSL_SESSION_from_bytes( |
| 1648 | const uint8_t *in, size_t in_len, const SSL_CTX *ctx); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1649 | |
| 1650 | /* SSL_SESSION_get_version returns a string describing the TLS version |session| |
| 1651 | * was established at. For example, "TLSv1.2" or "SSLv3". */ |
| 1652 | OPENSSL_EXPORT const char *SSL_SESSION_get_version(const SSL_SESSION *session); |
| 1653 | |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 1654 | /* SSL_SESSION_get_id returns a pointer to a buffer containing |session|'s |
| 1655 | * session ID and sets |*out_len| to its length. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1656 | OPENSSL_EXPORT const uint8_t *SSL_SESSION_get_id(const SSL_SESSION *session, |
| 1657 | unsigned *out_len); |
| 1658 | |
| 1659 | /* SSL_SESSION_get_time returns the time at which |session| was established in |
| 1660 | * seconds since the UNIX epoch. */ |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 1661 | OPENSSL_EXPORT uint64_t SSL_SESSION_get_time(const SSL_SESSION *session); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1662 | |
| 1663 | /* SSL_SESSION_get_timeout returns the lifetime of |session| in seconds. */ |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 1664 | OPENSSL_EXPORT uint32_t SSL_SESSION_get_timeout(const SSL_SESSION *session); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1665 | |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 1666 | /* SSL_SESSION_get0_peer returns the peer leaf certificate stored in |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1667 | * |session|. |
| 1668 | * |
| 1669 | * TODO(davidben): This should return a const X509 *. */ |
| 1670 | OPENSSL_EXPORT X509 *SSL_SESSION_get0_peer(const SSL_SESSION *session); |
| 1671 | |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 1672 | /* SSL_SESSION_get_master_key writes up to |max_out| bytes of |session|'s master |
| 1673 | * secret to |out| and returns the number of bytes written. If |max_out| is |
| 1674 | * zero, it returns the size of the master secret. */ |
| 1675 | OPENSSL_EXPORT size_t SSL_SESSION_get_master_key(const SSL_SESSION *session, |
| 1676 | uint8_t *out, size_t max_out); |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 1677 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1678 | /* SSL_SESSION_set_time sets |session|'s creation time to |time| and returns |
| 1679 | * |time|. This function may be useful in writing tests but otherwise should not |
| 1680 | * be used. */ |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 1681 | OPENSSL_EXPORT uint64_t SSL_SESSION_set_time(SSL_SESSION *session, |
| 1682 | uint64_t time); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1683 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1684 | /* SSL_SESSION_set_timeout sets |session|'s timeout to |timeout| and returns |
| 1685 | * one. This function may be useful in writing tests but otherwise should not |
| 1686 | * be used. */ |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 1687 | OPENSSL_EXPORT uint32_t SSL_SESSION_set_timeout(SSL_SESSION *session, |
| 1688 | uint32_t timeout); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1689 | |
| 1690 | /* SSL_SESSION_set1_id_context sets |session|'s session ID context (see |
| 1691 | * |SSL_CTX_set_session_id_context|) to |sid_ctx|. It returns one on success and |
| 1692 | * zero on error. This function may be useful in writing tests but otherwise |
| 1693 | * should not be used. */ |
| 1694 | OPENSSL_EXPORT int SSL_SESSION_set1_id_context(SSL_SESSION *session, |
| 1695 | const uint8_t *sid_ctx, |
David Benjamin | 1b24967 | 2016-12-06 18:25:50 -0500 | [diff] [blame] | 1696 | size_t sid_ctx_len); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1697 | |
| 1698 | |
| 1699 | /* Session caching. |
| 1700 | * |
| 1701 | * Session caching allows clients to reconnect to a server based on saved |
| 1702 | * parameters from a previous connection. |
| 1703 | * |
| 1704 | * For a server, the library implements a built-in internal session cache as an |
| 1705 | * in-memory hash table. One may also register callbacks to implement a custom |
| 1706 | * external session cache. An external cache may be used in addition to or |
| 1707 | * instead of the internal one. Use |SSL_CTX_set_session_cache_mode| to toggle |
| 1708 | * the internal cache. |
| 1709 | * |
| 1710 | * For a client, the only option is an external session cache. Prior to |
| 1711 | * handshaking, the consumer should look up a session externally (keyed, for |
| 1712 | * instance, by hostname) and use |SSL_set_session| to configure which session |
| 1713 | * to offer. The callbacks may be used to determine when new sessions are |
| 1714 | * available. |
| 1715 | * |
| 1716 | * Note that offering or accepting a session short-circuits most parameter |
| 1717 | * negotiation. Resuming sessions across different configurations may result in |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 1718 | * surprising behavior. So, for instance, a client implementing a version |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1719 | * fallback should shard its session cache by maximum protocol version. */ |
| 1720 | |
| 1721 | /* SSL_SESS_CACHE_OFF disables all session caching. */ |
| 1722 | #define SSL_SESS_CACHE_OFF 0x0000 |
| 1723 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1724 | /* SSL_SESS_CACHE_CLIENT enables session caching for a client. The internal |
| 1725 | * cache is never used on a client, so this only enables the callbacks. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1726 | #define SSL_SESS_CACHE_CLIENT 0x0001 |
| 1727 | |
| 1728 | /* SSL_SESS_CACHE_SERVER enables session caching for a server. */ |
| 1729 | #define SSL_SESS_CACHE_SERVER 0x0002 |
| 1730 | |
David Benjamin | f0c4a6c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 1731 | /* SSL_SESS_CACHE_BOTH enables session caching for both client and server. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1732 | #define SSL_SESS_CACHE_BOTH (SSL_SESS_CACHE_CLIENT | SSL_SESS_CACHE_SERVER) |
| 1733 | |
| 1734 | /* SSL_SESS_CACHE_NO_AUTO_CLEAR disables automatically calling |
| 1735 | * |SSL_CTX_flush_sessions| every 255 connections. */ |
| 1736 | #define SSL_SESS_CACHE_NO_AUTO_CLEAR 0x0080 |
| 1737 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1738 | /* SSL_SESS_CACHE_NO_INTERNAL_LOOKUP, on a server, disables looking up a session |
| 1739 | * from the internal session cache. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1740 | #define SSL_SESS_CACHE_NO_INTERNAL_LOOKUP 0x0100 |
| 1741 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1742 | /* SSL_SESS_CACHE_NO_INTERNAL_STORE, on a server, disables storing sessions in |
| 1743 | * the internal session cache. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1744 | #define SSL_SESS_CACHE_NO_INTERNAL_STORE 0x0200 |
| 1745 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1746 | /* SSL_SESS_CACHE_NO_INTERNAL, on a server, disables the internal session |
| 1747 | * cache. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1748 | #define SSL_SESS_CACHE_NO_INTERNAL \ |
| 1749 | (SSL_SESS_CACHE_NO_INTERNAL_LOOKUP | SSL_SESS_CACHE_NO_INTERNAL_STORE) |
| 1750 | |
| 1751 | /* SSL_CTX_set_session_cache_mode sets the session cache mode bits for |ctx| to |
| 1752 | * |mode|. It returns the previous value. */ |
| 1753 | OPENSSL_EXPORT int SSL_CTX_set_session_cache_mode(SSL_CTX *ctx, int mode); |
| 1754 | |
| 1755 | /* SSL_CTX_get_session_cache_mode returns the session cache mode bits for |
| 1756 | * |ctx| */ |
| 1757 | OPENSSL_EXPORT int SSL_CTX_get_session_cache_mode(const SSL_CTX *ctx); |
| 1758 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1759 | /* SSL_set_session, for a client, configures |ssl| to offer to resume |session| |
| 1760 | * in the initial handshake and returns one. The caller retains ownership of |
David Benjamin | 7c0d06c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 1761 | * |session|. |
| 1762 | * |
| 1763 | * It is an error to call this function after the handshake has begun. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1764 | OPENSSL_EXPORT int SSL_set_session(SSL *ssl, SSL_SESSION *session); |
| 1765 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 1766 | /* SSL_get_session returns a non-owning pointer to |ssl|'s session. For |
| 1767 | * historical reasons, which session it returns depends on |ssl|'s state. |
| 1768 | * |
| 1769 | * Prior to the start of the initial handshake, it returns the session the |
| 1770 | * caller set with |SSL_set_session|. After the initial handshake has finished |
| 1771 | * and if no additional handshakes are in progress, it returns the currently |
| 1772 | * active session. Its behavior is undefined while a handshake is in progress. |
| 1773 | * |
| 1774 | * Using this function to add new sessions to an external session cache is |
| 1775 | * deprecated. Use |SSL_CTX_sess_set_new_cb| instead. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1776 | OPENSSL_EXPORT SSL_SESSION *SSL_get_session(const SSL *ssl); |
| 1777 | |
| 1778 | /* SSL_get0_session is an alias for |SSL_get_session|. */ |
| 1779 | #define SSL_get0_session SSL_get_session |
| 1780 | |
| 1781 | /* SSL_get1_session acts like |SSL_get_session| but returns a new reference to |
| 1782 | * the session. */ |
| 1783 | OPENSSL_EXPORT SSL_SESSION *SSL_get1_session(SSL *ssl); |
| 1784 | |
| 1785 | /* SSL_DEFAULT_SESSION_TIMEOUT is the default lifetime, in seconds, of a |
Robert Sloan | 4d1ac50 | 2017-02-06 08:36:14 -0800 | [diff] [blame] | 1786 | * session in TLS 1.2 or earlier. This is how long we are willing to use the |
| 1787 | * secret to encrypt traffic without fresh key material. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1788 | #define SSL_DEFAULT_SESSION_TIMEOUT (2 * 60 * 60) |
| 1789 | |
Robert Sloan | 4d1ac50 | 2017-02-06 08:36:14 -0800 | [diff] [blame] | 1790 | /* SSL_DEFAULT_SESSION_PSK_DHE_TIMEOUT is the default lifetime, in seconds, of a |
| 1791 | * session for TLS 1.3 psk_dhe_ke. This is how long we are willing to use the |
| 1792 | * secret as an authenticator. */ |
| 1793 | #define SSL_DEFAULT_SESSION_PSK_DHE_TIMEOUT (2 * 24 * 60 * 60) |
| 1794 | |
| 1795 | /* SSL_DEFAULT_SESSION_AUTH_TIMEOUT is the default non-renewable lifetime, in |
| 1796 | * seconds, of a TLS 1.3 session. This is how long we are willing to trust the |
| 1797 | * signature in the initial handshake. */ |
| 1798 | #define SSL_DEFAULT_SESSION_AUTH_TIMEOUT (7 * 24 * 60 * 60) |
| 1799 | |
| 1800 | /* SSL_CTX_set_timeout sets the lifetime, in seconds, of TLS 1.2 (or earlier) |
| 1801 | * sessions created in |ctx| to |timeout|. */ |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 1802 | OPENSSL_EXPORT uint32_t SSL_CTX_set_timeout(SSL_CTX *ctx, uint32_t timeout); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1803 | |
Robert Sloan | 4d1ac50 | 2017-02-06 08:36:14 -0800 | [diff] [blame] | 1804 | /* SSL_CTX_set_session_psk_dhe_timeout sets the lifetime, in seconds, of TLS 1.3 |
| 1805 | * sessions created in |ctx| to |timeout|. */ |
| 1806 | OPENSSL_EXPORT void SSL_CTX_set_session_psk_dhe_timeout(SSL_CTX *ctx, |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 1807 | uint32_t timeout); |
Robert Sloan | 4d1ac50 | 2017-02-06 08:36:14 -0800 | [diff] [blame] | 1808 | |
| 1809 | /* SSL_CTX_get_timeout returns the lifetime, in seconds, of TLS 1.2 (or earlier) |
| 1810 | * sessions created in |ctx|. */ |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 1811 | OPENSSL_EXPORT uint32_t SSL_CTX_get_timeout(const SSL_CTX *ctx); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1812 | |
| 1813 | /* SSL_CTX_set_session_id_context sets |ctx|'s session ID context to |sid_ctx|. |
| 1814 | * It returns one on success and zero on error. The session ID context is an |
| 1815 | * application-defined opaque byte string. A session will not be used in a |
| 1816 | * connection without a matching session ID context. |
| 1817 | * |
| 1818 | * For a server, if |SSL_VERIFY_PEER| is enabled, it is an error to not set a |
| 1819 | * session ID context. |
| 1820 | * |
| 1821 | * TODO(davidben): Is that check needed? That seems a special case of taking |
| 1822 | * care not to cross-resume across configuration changes, and this is only |
| 1823 | * relevant if a server requires client auth. */ |
| 1824 | OPENSSL_EXPORT int SSL_CTX_set_session_id_context(SSL_CTX *ctx, |
| 1825 | const uint8_t *sid_ctx, |
David Benjamin | 1b24967 | 2016-12-06 18:25:50 -0500 | [diff] [blame] | 1826 | size_t sid_ctx_len); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1827 | |
| 1828 | /* SSL_set_session_id_context sets |ssl|'s session ID context to |sid_ctx|. It |
| 1829 | * returns one on success and zero on error. See also |
| 1830 | * |SSL_CTX_set_session_id_context|. */ |
| 1831 | OPENSSL_EXPORT int SSL_set_session_id_context(SSL *ssl, const uint8_t *sid_ctx, |
David Benjamin | 1b24967 | 2016-12-06 18:25:50 -0500 | [diff] [blame] | 1832 | size_t sid_ctx_len); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1833 | |
David Benjamin | f31229b | 2017-01-25 14:08:15 -0500 | [diff] [blame] | 1834 | /* SSL_get0_session_id_context returns a pointer to |ssl|'s session ID context |
| 1835 | * and sets |*out_len| to its length. */ |
| 1836 | OPENSSL_EXPORT const uint8_t *SSL_get0_session_id_context(const SSL *ssl, |
| 1837 | size_t *out_len); |
| 1838 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1839 | /* SSL_SESSION_CACHE_MAX_SIZE_DEFAULT is the default maximum size of a session |
| 1840 | * cache. */ |
| 1841 | #define SSL_SESSION_CACHE_MAX_SIZE_DEFAULT (1024 * 20) |
| 1842 | |
| 1843 | /* SSL_CTX_sess_set_cache_size sets the maximum size of |ctx|'s internal session |
| 1844 | * cache to |size|. It returns the previous value. */ |
| 1845 | OPENSSL_EXPORT unsigned long SSL_CTX_sess_set_cache_size(SSL_CTX *ctx, |
| 1846 | unsigned long size); |
| 1847 | |
| 1848 | /* SSL_CTX_sess_get_cache_size returns the maximum size of |ctx|'s internal |
| 1849 | * session cache. */ |
| 1850 | OPENSSL_EXPORT unsigned long SSL_CTX_sess_get_cache_size(const SSL_CTX *ctx); |
| 1851 | |
| 1852 | /* SSL_CTX_sessions returns |ctx|'s internal session cache. */ |
| 1853 | OPENSSL_EXPORT LHASH_OF(SSL_SESSION) *SSL_CTX_sessions(SSL_CTX *ctx); |
| 1854 | |
| 1855 | /* SSL_CTX_sess_number returns the number of sessions in |ctx|'s internal |
| 1856 | * session cache. */ |
| 1857 | OPENSSL_EXPORT size_t SSL_CTX_sess_number(const SSL_CTX *ctx); |
| 1858 | |
| 1859 | /* SSL_CTX_add_session inserts |session| into |ctx|'s internal session cache. It |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1860 | * returns one on success and zero on error or if |session| is already in the |
| 1861 | * cache. The caller retains its reference to |session|. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1862 | OPENSSL_EXPORT int SSL_CTX_add_session(SSL_CTX *ctx, SSL_SESSION *session); |
| 1863 | |
| 1864 | /* SSL_CTX_remove_session removes |session| from |ctx|'s internal session cache. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1865 | * It returns one on success and zero if |session| was not in the cache. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1866 | OPENSSL_EXPORT int SSL_CTX_remove_session(SSL_CTX *ctx, SSL_SESSION *session); |
| 1867 | |
| 1868 | /* SSL_CTX_flush_sessions removes all sessions from |ctx| which have expired as |
| 1869 | * of time |time|. If |time| is zero, all sessions are removed. */ |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 1870 | OPENSSL_EXPORT void SSL_CTX_flush_sessions(SSL_CTX *ctx, uint64_t time); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1871 | |
| 1872 | /* SSL_CTX_sess_set_new_cb sets the callback to be called when a new session is |
| 1873 | * established and ready to be cached. If the session cache is disabled (the |
| 1874 | * appropriate one of |SSL_SESS_CACHE_CLIENT| or |SSL_SESS_CACHE_SERVER| is |
| 1875 | * unset), the callback is not called. |
| 1876 | * |
| 1877 | * The callback is passed a reference to |session|. It returns one if it takes |
| 1878 | * ownership and zero otherwise. |
| 1879 | * |
| 1880 | * Note: For a client, the callback may be called on abbreviated handshakes if a |
| 1881 | * ticket is renewed. Further, it may not be called until some time after |
| 1882 | * |SSL_do_handshake| or |SSL_connect| completes if False Start is enabled. Thus |
| 1883 | * it's recommended to use this callback over checking |SSL_session_reused| on |
| 1884 | * handshake completion. |
| 1885 | * |
| 1886 | * TODO(davidben): Conditioning callbacks on |SSL_SESS_CACHE_CLIENT| or |
| 1887 | * |SSL_SESS_CACHE_SERVER| doesn't make any sense when one could just as easily |
| 1888 | * not supply the callbacks. Removing that condition and the client internal |
| 1889 | * cache would simplify things. */ |
| 1890 | OPENSSL_EXPORT void SSL_CTX_sess_set_new_cb( |
| 1891 | SSL_CTX *ctx, int (*new_session_cb)(SSL *ssl, SSL_SESSION *session)); |
| 1892 | |
| 1893 | /* SSL_CTX_sess_get_new_cb returns the callback set by |
| 1894 | * |SSL_CTX_sess_set_new_cb|. */ |
| 1895 | OPENSSL_EXPORT int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))( |
| 1896 | SSL *ssl, SSL_SESSION *session); |
| 1897 | |
| 1898 | /* SSL_CTX_sess_set_remove_cb sets a callback which is called when a session is |
| 1899 | * removed from the internal session cache. |
| 1900 | * |
| 1901 | * TODO(davidben): What is the point of this callback? It seems useless since it |
| 1902 | * only fires on sessions in the internal cache. */ |
| 1903 | OPENSSL_EXPORT void SSL_CTX_sess_set_remove_cb( |
| 1904 | SSL_CTX *ctx, |
| 1905 | void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *session)); |
| 1906 | |
| 1907 | /* SSL_CTX_sess_get_remove_cb returns the callback set by |
| 1908 | * |SSL_CTX_sess_set_remove_cb|. */ |
| 1909 | OPENSSL_EXPORT void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))( |
| 1910 | SSL_CTX *ctx, SSL_SESSION *session); |
| 1911 | |
| 1912 | /* SSL_CTX_sess_set_get_cb sets a callback to look up a session by ID for a |
| 1913 | * server. The callback is passed the session ID and should return a matching |
| 1914 | * |SSL_SESSION| or NULL if not found. It should set |*out_copy| to zero and |
| 1915 | * return a new reference to the session. This callback is not used for a |
| 1916 | * client. |
| 1917 | * |
| 1918 | * For historical reasons, if |*out_copy| is set to one (default), the SSL |
| 1919 | * library will take a new reference to the returned |SSL_SESSION|, expecting |
| 1920 | * the callback to return a non-owning pointer. This is not recommended. If |
| 1921 | * |ctx| and thus the callback is used on multiple threads, the session may be |
| 1922 | * removed and invalidated before the SSL library calls |SSL_SESSION_up_ref|, |
| 1923 | * whereas the callback may synchronize internally. |
| 1924 | * |
| 1925 | * To look up a session asynchronously, the callback may return |
| 1926 | * |SSL_magic_pending_session_ptr|. See the documentation for that function and |
| 1927 | * |SSL_ERROR_PENDING_SESSION|. |
| 1928 | * |
| 1929 | * If the internal session cache is enabled, the callback is only consulted if |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 1930 | * the internal cache does not return a match. |
| 1931 | * |
| 1932 | * The callback's |id| parameter is not const for historical reasons, but the |
| 1933 | * contents may not be modified. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1934 | OPENSSL_EXPORT void SSL_CTX_sess_set_get_cb( |
| 1935 | SSL_CTX *ctx, |
| 1936 | SSL_SESSION *(*get_session_cb)(SSL *ssl, uint8_t *id, int id_len, |
| 1937 | int *out_copy)); |
| 1938 | |
| 1939 | /* SSL_CTX_sess_get_get_cb returns the callback set by |
| 1940 | * |SSL_CTX_sess_set_get_cb|. */ |
| 1941 | OPENSSL_EXPORT SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))( |
| 1942 | SSL *ssl, uint8_t *id, int id_len, int *out_copy); |
| 1943 | |
| 1944 | /* SSL_magic_pending_session_ptr returns a magic |SSL_SESSION|* which indicates |
| 1945 | * that the session isn't currently unavailable. |SSL_get_error| will then |
| 1946 | * return |SSL_ERROR_PENDING_SESSION| and the handshake can be retried later |
| 1947 | * when the lookup has completed. */ |
| 1948 | OPENSSL_EXPORT SSL_SESSION *SSL_magic_pending_session_ptr(void); |
| 1949 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1950 | |
| 1951 | /* Session tickets. |
| 1952 | * |
| 1953 | * Session tickets, from RFC 5077, allow session resumption without server-side |
| 1954 | * state. Session tickets are supported in by default but may be disabled with |
| 1955 | * |SSL_OP_NO_TICKET|. |
| 1956 | * |
| 1957 | * On the client, ticket-based sessions use the same APIs as ID-based tickets. |
| 1958 | * Callers do not need to handle them differently. |
| 1959 | * |
| 1960 | * On the server, tickets are encrypted and authenticated with a secret key. By |
| 1961 | * default, an |SSL_CTX| generates a key on creation. Tickets are minted and |
| 1962 | * processed transparently. The following functions may be used to configure a |
Robert Sloan | 1c9db53 | 2017-03-13 08:03:59 -0700 | [diff] [blame] | 1963 | * persistent key or implement more custom behavior. There are three levels of |
| 1964 | * customisation possible: |
| 1965 | * |
| 1966 | * 1) One can simply set the keys with |SSL_CTX_set_tlsext_ticket_keys|. |
| 1967 | * 2) One can configure an |EVP_CIPHER_CTX| and |HMAC_CTX| directly for |
| 1968 | * encryption and authentication. |
| 1969 | * 3) One can configure an |SSL_TICKET_ENCRYPTION_METHOD| to have more control |
| 1970 | * and the option of asynchronous decryption. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 1971 | |
| 1972 | /* SSL_CTX_get_tlsext_ticket_keys writes |ctx|'s session ticket key material to |
| 1973 | * |len| bytes of |out|. It returns one on success and zero if |len| is not |
| 1974 | * 48. If |out| is NULL, it returns 48 instead. */ |
| 1975 | OPENSSL_EXPORT int SSL_CTX_get_tlsext_ticket_keys(SSL_CTX *ctx, void *out, |
| 1976 | size_t len); |
| 1977 | |
| 1978 | /* SSL_CTX_set_tlsext_ticket_keys sets |ctx|'s session ticket key material to |
| 1979 | * |len| bytes of |in|. It returns one on success and zero if |len| is not |
| 1980 | * 48. If |in| is NULL, it returns 48 instead. */ |
| 1981 | OPENSSL_EXPORT int SSL_CTX_set_tlsext_ticket_keys(SSL_CTX *ctx, const void *in, |
| 1982 | size_t len); |
| 1983 | |
| 1984 | /* SSL_TICKET_KEY_NAME_LEN is the length of the key name prefix of a session |
| 1985 | * ticket. */ |
| 1986 | #define SSL_TICKET_KEY_NAME_LEN 16 |
| 1987 | |
| 1988 | /* SSL_CTX_set_tlsext_ticket_key_cb sets the ticket callback to |callback| and |
| 1989 | * returns one. |callback| will be called when encrypting a new ticket and when |
| 1990 | * decrypting a ticket from the client. |
| 1991 | * |
| 1992 | * In both modes, |ctx| and |hmac_ctx| will already have been initialized with |
| 1993 | * |EVP_CIPHER_CTX_init| and |HMAC_CTX_init|, respectively. |callback| |
| 1994 | * configures |hmac_ctx| with an HMAC digest and key, and configures |ctx| |
| 1995 | * for encryption or decryption, based on the mode. |
| 1996 | * |
| 1997 | * When encrypting a new ticket, |encrypt| will be one. It writes a public |
| 1998 | * 16-byte key name to |key_name| and a fresh IV to |iv|. The output IV length |
| 1999 | * must match |EVP_CIPHER_CTX_iv_length| of the cipher selected. In this mode, |
| 2000 | * |callback| returns 1 on success and -1 on error. |
| 2001 | * |
| 2002 | * When decrypting a ticket, |encrypt| will be zero. |key_name| will point to a |
| 2003 | * 16-byte key name and |iv| points to an IV. The length of the IV consumed must |
| 2004 | * match |EVP_CIPHER_CTX_iv_length| of the cipher selected. In this mode, |
| 2005 | * |callback| returns -1 to abort the handshake, 0 if decrypting the ticket |
| 2006 | * failed, and 1 or 2 on success. If it returns 2, the ticket will be renewed. |
| 2007 | * This may be used to re-key the ticket. |
| 2008 | * |
| 2009 | * WARNING: |callback| wildly breaks the usual return value convention and is |
| 2010 | * called in two different modes. */ |
| 2011 | OPENSSL_EXPORT int SSL_CTX_set_tlsext_ticket_key_cb( |
| 2012 | SSL_CTX *ctx, int (*callback)(SSL *ssl, uint8_t *key_name, uint8_t *iv, |
| 2013 | EVP_CIPHER_CTX *ctx, HMAC_CTX *hmac_ctx, |
| 2014 | int encrypt)); |
| 2015 | |
Robert Sloan | 1c9db53 | 2017-03-13 08:03:59 -0700 | [diff] [blame] | 2016 | /* ssl_ticket_aead_result_t enumerates the possible results from decrypting a |
| 2017 | * ticket with an |SSL_TICKET_AEAD_METHOD|. */ |
| 2018 | enum ssl_ticket_aead_result_t { |
Robert Sloan | 8ecb7cd | 2017-03-21 09:39:01 -0700 | [diff] [blame] | 2019 | /* ssl_ticket_aead_success indicates that the ticket was successfully |
Robert Sloan | 1c9db53 | 2017-03-13 08:03:59 -0700 | [diff] [blame] | 2020 | * decrypted. */ |
| 2021 | ssl_ticket_aead_success, |
| 2022 | /* ssl_ticket_aead_retry indicates that the operation could not be |
| 2023 | * immediately completed and must be reattempted, via |open|, at a later |
| 2024 | * point. */ |
| 2025 | ssl_ticket_aead_retry, |
| 2026 | /* ssl_ticket_aead_ignore_ticket indicates that the ticket should be ignored |
| 2027 | * (i.e. is corrupt or otherwise undecryptable). */ |
| 2028 | ssl_ticket_aead_ignore_ticket, |
| 2029 | /* ssl_ticket_aead_error indicates that a fatal error occured and the |
| 2030 | * handshake should be terminated. */ |
| 2031 | ssl_ticket_aead_error, |
| 2032 | }; |
| 2033 | |
| 2034 | /* ssl_ticket_aead_method_st (aka |SSL_TICKET_ENCRYPTION_METHOD|) contains |
| 2035 | * methods for encrypting and decrypting session tickets. */ |
| 2036 | struct ssl_ticket_aead_method_st { |
| 2037 | /* max_overhead returns the maximum number of bytes of overhead that |seal| |
| 2038 | * may add. */ |
| 2039 | size_t (*max_overhead)(SSL *ssl); |
| 2040 | |
| 2041 | /* seal encrypts and authenticates |in_len| bytes from |in|, writes, at most, |
| 2042 | * |max_out_len| bytes to |out|, and puts the number of bytes written in |
| 2043 | * |*out_len|. The |in| and |out| buffers may be equal but will not otherwise |
| 2044 | * alias. It returns one on success or zero on error. */ |
| 2045 | int (*seal)(SSL *ssl, uint8_t *out, size_t *out_len, size_t max_out_len, |
| 2046 | const uint8_t *in, size_t in_len); |
| 2047 | |
| 2048 | /* open authenticates and decrypts |in_len| bytes from |in|, writes, at most, |
| 2049 | * |max_out_len| bytes of plaintext to |out|, and puts the number of bytes |
| 2050 | * written in |*out_len|. The |in| and |out| buffers may be equal but will |
| 2051 | * not otherwise alias. See |ssl_ticket_aead_result_t| for details of the |
| 2052 | * return values. In the case that a retry is indicated, the caller should |
| 2053 | * arrange for the high-level operation on |ssl| to be retried when the |
| 2054 | * operation is completed, which will result in another call to |open|. */ |
| 2055 | enum ssl_ticket_aead_result_t (*open)(SSL *ssl, uint8_t *out, size_t *out_len, |
| 2056 | size_t max_out_len, const uint8_t *in, |
| 2057 | size_t in_len); |
| 2058 | }; |
| 2059 | |
| 2060 | /* SSL_CTX_set_ticket_aead_method configures a custom ticket AEAD method table |
| 2061 | * on |ctx|. |aead_method| must remain valid for the lifetime of |ctx|. */ |
| 2062 | OPENSSL_EXPORT void SSL_CTX_set_ticket_aead_method( |
| 2063 | SSL_CTX *ctx, const SSL_TICKET_AEAD_METHOD *aead_method); |
| 2064 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2065 | |
| 2066 | /* Elliptic curve Diffie-Hellman. |
| 2067 | * |
| 2068 | * Cipher suites using an ECDHE key exchange perform Diffie-Hellman over an |
| 2069 | * elliptic curve negotiated by both endpoints. See RFC 4492. Only named curves |
| 2070 | * are supported. ECDHE is always enabled, but the curve preferences may be |
| 2071 | * configured with these functions. |
| 2072 | * |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 2073 | * Note that TLS 1.3 renames these from curves to groups. For consistency, we |
| 2074 | * currently use the TLS 1.2 name in the API. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2075 | |
| 2076 | /* SSL_CTX_set1_curves sets the preferred curves for |ctx| to be |curves|. Each |
| 2077 | * element of |curves| should be a curve nid. It returns one on success and |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 2078 | * zero on failure. |
| 2079 | * |
| 2080 | * Note that this API uses nid values from nid.h and not the |SSL_CURVE_*| |
| 2081 | * values defined below. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2082 | OPENSSL_EXPORT int SSL_CTX_set1_curves(SSL_CTX *ctx, const int *curves, |
| 2083 | size_t curves_len); |
| 2084 | |
| 2085 | /* SSL_set1_curves sets the preferred curves for |ssl| to be |curves|. Each |
| 2086 | * element of |curves| should be a curve nid. It returns one on success and |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 2087 | * zero on failure. |
| 2088 | * |
| 2089 | * Note that this API uses nid values from nid.h and not the |SSL_CURVE_*| |
| 2090 | * values defined below. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2091 | OPENSSL_EXPORT int SSL_set1_curves(SSL *ssl, const int *curves, |
| 2092 | size_t curves_len); |
| 2093 | |
Steven Valdez | bb1ceac | 2016-10-07 10:34:51 -0400 | [diff] [blame] | 2094 | /* SSL_CTX_set1_curves_list sets the preferred curves for |ctx| to be the |
| 2095 | * colon-separated list |curves|. Each element of |curves| should be a curve |
| 2096 | * name (e.g. P-256, X25519, ...). It returns one on success and zero on |
| 2097 | * failure. */ |
| 2098 | OPENSSL_EXPORT int SSL_CTX_set1_curves_list(SSL_CTX *ctx, const char *curves); |
| 2099 | |
| 2100 | /* SSL_set1_curves_list sets the preferred curves for |ssl| to be the |
| 2101 | * colon-separated list |curves|. Each element of |curves| should be a curve |
| 2102 | * name (e.g. P-256, X25519, ...). It returns one on success and zero on |
| 2103 | * failure. */ |
| 2104 | OPENSSL_EXPORT int SSL_set1_curves_list(SSL *ssl, const char *curves); |
| 2105 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 2106 | /* SSL_CURVE_* define TLS curve IDs. */ |
Robert Sloan | 6f79a50 | 2017-04-03 09:16:40 -0700 | [diff] [blame] | 2107 | #define SSL_CURVE_SECP224R1 21 |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 2108 | #define SSL_CURVE_SECP256R1 23 |
| 2109 | #define SSL_CURVE_SECP384R1 24 |
| 2110 | #define SSL_CURVE_SECP521R1 25 |
| 2111 | #define SSL_CURVE_X25519 29 |
| 2112 | |
| 2113 | /* SSL_get_curve_id returns the ID of the curve used by |ssl|'s most recently |
| 2114 | * completed handshake or 0 if not applicable. |
| 2115 | * |
| 2116 | * TODO(davidben): This API currently does not work correctly if there is a |
| 2117 | * renegotiation in progress. Fix this. */ |
| 2118 | OPENSSL_EXPORT uint16_t SSL_get_curve_id(const SSL *ssl); |
| 2119 | |
| 2120 | /* SSL_get_curve_name returns a human-readable name for the curve specified by |
| 2121 | * the given TLS curve id, or NULL if the curve is unknown. */ |
| 2122 | OPENSSL_EXPORT const char *SSL_get_curve_name(uint16_t curve_id); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2123 | |
| 2124 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2125 | /* Certificate verification. |
| 2126 | * |
| 2127 | * SSL may authenticate either endpoint with an X.509 certificate. Typically |
| 2128 | * this is used to authenticate the server to the client. These functions |
| 2129 | * configure certificate verification. |
| 2130 | * |
| 2131 | * WARNING: By default, certificate verification errors on a client are not |
| 2132 | * fatal. See |SSL_VERIFY_NONE| This may be configured with |
| 2133 | * |SSL_CTX_set_verify|. |
| 2134 | * |
| 2135 | * By default clients are anonymous but a server may request a certificate from |
| 2136 | * the client by setting |SSL_VERIFY_PEER|. |
| 2137 | * |
| 2138 | * Many of these functions use OpenSSL's legacy X.509 stack which is |
| 2139 | * underdocumented and deprecated, but the replacement isn't ready yet. For |
| 2140 | * now, consumers may use the existing stack or bypass it by performing |
| 2141 | * certificate verification externally. This may be done with |
| 2142 | * |SSL_CTX_set_cert_verify_callback| or by extracting the chain with |
| 2143 | * |SSL_get_peer_cert_chain| after the handshake. In the future, functions will |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 2144 | * be added to use the SSL stack without dependency on any part of the legacy |
| 2145 | * X.509 and ASN.1 stack. |
| 2146 | * |
| 2147 | * To augment certificate verification, a client may also enable OCSP stapling |
| 2148 | * (RFC 6066) and Certificate Transparency (RFC 6962) extensions. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2149 | |
| 2150 | /* SSL_VERIFY_NONE, on a client, verifies the server certificate but does not |
| 2151 | * make errors fatal. The result may be checked with |SSL_get_verify_result|. On |
| 2152 | * a server it does not request a client certificate. This is the default. */ |
| 2153 | #define SSL_VERIFY_NONE 0x00 |
| 2154 | |
| 2155 | /* SSL_VERIFY_PEER, on a client, makes server certificate errors fatal. On a |
| 2156 | * server it requests a client certificate and makes errors fatal. However, |
| 2157 | * anonymous clients are still allowed. See |
| 2158 | * |SSL_VERIFY_FAIL_IF_NO_PEER_CERT|. */ |
| 2159 | #define SSL_VERIFY_PEER 0x01 |
| 2160 | |
| 2161 | /* SSL_VERIFY_FAIL_IF_NO_PEER_CERT configures a server to reject connections if |
| 2162 | * the client declines to send a certificate. Otherwise |SSL_VERIFY_PEER| still |
| 2163 | * allows anonymous clients. */ |
| 2164 | #define SSL_VERIFY_FAIL_IF_NO_PEER_CERT 0x02 |
| 2165 | |
| 2166 | /* SSL_VERIFY_PEER_IF_NO_OBC configures a server to request a client certificate |
| 2167 | * if and only if Channel ID is not negotiated. */ |
| 2168 | #define SSL_VERIFY_PEER_IF_NO_OBC 0x04 |
| 2169 | |
| 2170 | /* SSL_CTX_set_verify configures certificate verification behavior. |mode| is |
| 2171 | * one of the |SSL_VERIFY_*| values defined above. |callback|, if not NULL, is |
| 2172 | * used to customize certificate verification. See the behavior of |
| 2173 | * |X509_STORE_CTX_set_verify_cb|. |
| 2174 | * |
| 2175 | * The callback may use |SSL_get_ex_data_X509_STORE_CTX_idx| with |
| 2176 | * |X509_STORE_CTX_get_ex_data| to look up the |SSL| from |store_ctx|. */ |
| 2177 | OPENSSL_EXPORT void SSL_CTX_set_verify( |
| 2178 | SSL_CTX *ctx, int mode, int (*callback)(int ok, X509_STORE_CTX *store_ctx)); |
| 2179 | |
| 2180 | /* SSL_set_verify configures certificate verification behavior. |mode| is one of |
| 2181 | * the |SSL_VERIFY_*| values defined above. |callback|, if not NULL, is used to |
| 2182 | * customize certificate verification. See the behavior of |
| 2183 | * |X509_STORE_CTX_set_verify_cb|. |
| 2184 | * |
| 2185 | * The callback may use |SSL_get_ex_data_X509_STORE_CTX_idx| with |
| 2186 | * |X509_STORE_CTX_get_ex_data| to look up the |SSL| from |store_ctx|. */ |
| 2187 | OPENSSL_EXPORT void SSL_set_verify(SSL *ssl, int mode, |
| 2188 | int (*callback)(int ok, |
| 2189 | X509_STORE_CTX *store_ctx)); |
| 2190 | |
| 2191 | /* SSL_CTX_get_verify_mode returns |ctx|'s verify mode, set by |
| 2192 | * |SSL_CTX_set_verify|. */ |
| 2193 | OPENSSL_EXPORT int SSL_CTX_get_verify_mode(const SSL_CTX *ctx); |
| 2194 | |
| 2195 | /* SSL_get_verify_mode returns |ssl|'s verify mode, set by |SSL_CTX_set_verify| |
| 2196 | * or |SSL_set_verify|. */ |
| 2197 | OPENSSL_EXPORT int SSL_get_verify_mode(const SSL *ssl); |
| 2198 | |
| 2199 | /* SSL_CTX_get_verify_callback returns the callback set by |
| 2200 | * |SSL_CTX_set_verify|. */ |
| 2201 | OPENSSL_EXPORT int (*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))( |
| 2202 | int ok, X509_STORE_CTX *store_ctx); |
| 2203 | |
| 2204 | /* SSL_get_verify_callback returns the callback set by |SSL_CTX_set_verify| or |
| 2205 | * |SSL_set_verify|. */ |
| 2206 | OPENSSL_EXPORT int (*SSL_get_verify_callback(const SSL *ssl))( |
| 2207 | int ok, X509_STORE_CTX *store_ctx); |
| 2208 | |
| 2209 | /* SSL_CTX_set_verify_depth sets the maximum depth of a certificate chain |
| 2210 | * accepted in verification. This number does not include the leaf, so a depth |
| 2211 | * of 1 allows the leaf and one CA certificate. */ |
| 2212 | OPENSSL_EXPORT void SSL_CTX_set_verify_depth(SSL_CTX *ctx, int depth); |
| 2213 | |
| 2214 | /* SSL_set_verify_depth sets the maximum depth of a certificate chain accepted |
| 2215 | * in verification. This number does not include the leaf, so a depth of 1 |
| 2216 | * allows the leaf and one CA certificate. */ |
| 2217 | OPENSSL_EXPORT void SSL_set_verify_depth(SSL *ssl, int depth); |
| 2218 | |
| 2219 | /* SSL_CTX_get_verify_depth returns the maximum depth of a certificate accepted |
| 2220 | * in verification. */ |
| 2221 | OPENSSL_EXPORT int SSL_CTX_get_verify_depth(const SSL_CTX *ctx); |
| 2222 | |
| 2223 | /* SSL_get_verify_depth returns the maximum depth of a certificate accepted in |
| 2224 | * verification. */ |
| 2225 | OPENSSL_EXPORT int SSL_get_verify_depth(const SSL *ssl); |
| 2226 | |
| 2227 | /* SSL_CTX_set1_param sets verification parameters from |param|. It returns one |
| 2228 | * on success and zero on failure. The caller retains ownership of |param|. */ |
| 2229 | OPENSSL_EXPORT int SSL_CTX_set1_param(SSL_CTX *ctx, |
| 2230 | const X509_VERIFY_PARAM *param); |
| 2231 | |
| 2232 | /* SSL_set1_param sets verification parameters from |param|. It returns one on |
| 2233 | * success and zero on failure. The caller retains ownership of |param|. */ |
| 2234 | OPENSSL_EXPORT int SSL_set1_param(SSL *ssl, |
| 2235 | const X509_VERIFY_PARAM *param); |
| 2236 | |
| 2237 | /* SSL_CTX_get0_param returns |ctx|'s |X509_VERIFY_PARAM| for certificate |
| 2238 | * verification. The caller must not release the returned pointer but may call |
| 2239 | * functions on it to configure it. */ |
| 2240 | OPENSSL_EXPORT X509_VERIFY_PARAM *SSL_CTX_get0_param(SSL_CTX *ctx); |
| 2241 | |
| 2242 | /* SSL_get0_param returns |ssl|'s |X509_VERIFY_PARAM| for certificate |
| 2243 | * verification. The caller must not release the returned pointer but may call |
| 2244 | * functions on it to configure it. */ |
| 2245 | OPENSSL_EXPORT X509_VERIFY_PARAM *SSL_get0_param(SSL *ssl); |
| 2246 | |
| 2247 | /* SSL_CTX_set_purpose sets |ctx|'s |X509_VERIFY_PARAM|'s 'purpose' parameter to |
| 2248 | * |purpose|. It returns one on success and zero on error. */ |
| 2249 | OPENSSL_EXPORT int SSL_CTX_set_purpose(SSL_CTX *ctx, int purpose); |
| 2250 | |
| 2251 | /* SSL_set_purpose sets |ssl|'s |X509_VERIFY_PARAM|'s 'purpose' parameter to |
| 2252 | * |purpose|. It returns one on success and zero on error. */ |
| 2253 | OPENSSL_EXPORT int SSL_set_purpose(SSL *ssl, int purpose); |
| 2254 | |
| 2255 | /* SSL_CTX_set_trust sets |ctx|'s |X509_VERIFY_PARAM|'s 'trust' parameter to |
| 2256 | * |trust|. It returns one on success and zero on error. */ |
| 2257 | OPENSSL_EXPORT int SSL_CTX_set_trust(SSL_CTX *ctx, int trust); |
| 2258 | |
| 2259 | /* SSL_set_trust sets |ssl|'s |X509_VERIFY_PARAM|'s 'trust' parameter to |
| 2260 | * |trust|. It returns one on success and zero on error. */ |
| 2261 | OPENSSL_EXPORT int SSL_set_trust(SSL *ssl, int trust); |
| 2262 | |
| 2263 | /* SSL_CTX_set_cert_store sets |ctx|'s certificate store to |store|. It takes |
| 2264 | * ownership of |store|. The store is used for certificate verification. |
| 2265 | * |
| 2266 | * The store is also used for the auto-chaining feature, but this is deprecated. |
| 2267 | * See also |SSL_MODE_NO_AUTO_CHAIN|. */ |
| 2268 | OPENSSL_EXPORT void SSL_CTX_set_cert_store(SSL_CTX *ctx, X509_STORE *store); |
| 2269 | |
| 2270 | /* SSL_CTX_get_cert_store returns |ctx|'s certificate store. */ |
| 2271 | OPENSSL_EXPORT X509_STORE *SSL_CTX_get_cert_store(const SSL_CTX *ctx); |
| 2272 | |
| 2273 | /* SSL_CTX_set_default_verify_paths loads the OpenSSL system-default trust |
| 2274 | * anchors into |ctx|'s store. It returns one on success and zero on failure. */ |
| 2275 | OPENSSL_EXPORT int SSL_CTX_set_default_verify_paths(SSL_CTX *ctx); |
| 2276 | |
| 2277 | /* SSL_CTX_load_verify_locations loads trust anchors into |ctx|'s store from |
| 2278 | * |ca_file| and |ca_dir|, either of which may be NULL. If |ca_file| is passed, |
| 2279 | * it is opened and PEM-encoded CA certificates are read. If |ca_dir| is passed, |
| 2280 | * it is treated as a directory in OpenSSL's hashed directory format. It returns |
| 2281 | * one on success and zero on failure. |
| 2282 | * |
| 2283 | * See |
| 2284 | * https://www.openssl.org/docs/manmaster/ssl/SSL_CTX_load_verify_locations.html |
| 2285 | * for documentation on the directory format. */ |
| 2286 | OPENSSL_EXPORT int SSL_CTX_load_verify_locations(SSL_CTX *ctx, |
| 2287 | const char *ca_file, |
| 2288 | const char *ca_dir); |
| 2289 | |
| 2290 | /* SSL_get_verify_result returns the result of certificate verification. It is |
| 2291 | * either |X509_V_OK| or a |X509_V_ERR_*| value. */ |
| 2292 | OPENSSL_EXPORT long SSL_get_verify_result(const SSL *ssl); |
| 2293 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2294 | /* SSL_get_ex_data_X509_STORE_CTX_idx returns the ex_data index used to look up |
| 2295 | * the |SSL| associated with an |X509_STORE_CTX| in the verify callback. */ |
| 2296 | OPENSSL_EXPORT int SSL_get_ex_data_X509_STORE_CTX_idx(void); |
| 2297 | |
| 2298 | /* SSL_CTX_set_cert_verify_callback sets a custom callback to be called on |
| 2299 | * certificate verification rather than |X509_verify_cert|. |store_ctx| contains |
| 2300 | * the verification parameters. The callback should return one on success and |
| 2301 | * zero on fatal error. It may use |X509_STORE_CTX_set_error| to set a |
| 2302 | * verification result. |
| 2303 | * |
Robert Sloan | 47f43ed | 2017-02-06 14:55:15 -0800 | [diff] [blame] | 2304 | * The callback may use |SSL_get_ex_data_X509_STORE_CTX_idx| to recover the |
| 2305 | * |SSL| object from |store_ctx|. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2306 | OPENSSL_EXPORT void SSL_CTX_set_cert_verify_callback( |
| 2307 | SSL_CTX *ctx, int (*callback)(X509_STORE_CTX *store_ctx, void *arg), |
| 2308 | void *arg); |
| 2309 | |
Robert Sloan | 1c9db53 | 2017-03-13 08:03:59 -0700 | [diff] [blame] | 2310 | /* SSL_CTX_i_promise_to_verify_certs_after_the_handshake indicates that the |
| 2311 | * caller understands that the |CRYPTO_BUFFER|-based methods currently require |
| 2312 | * post-handshake verification of certificates and thus it's ok to accept any |
| 2313 | * certificates during the handshake. */ |
| 2314 | OPENSSL_EXPORT void SSL_CTX_i_promise_to_verify_certs_after_the_handshake( |
| 2315 | SSL_CTX *ctx); |
| 2316 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 2317 | /* SSL_enable_signed_cert_timestamps causes |ssl| (which must be the client end |
| 2318 | * of a connection) to request SCTs from the server. See |
Robert Sloan | a94fe05 | 2017-02-21 08:49:28 -0800 | [diff] [blame] | 2319 | * https://tools.ietf.org/html/rfc6962. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 2320 | * |
| 2321 | * Call |SSL_get0_signed_cert_timestamp_list| to recover the SCT after the |
| 2322 | * handshake. */ |
Robert Sloan | a94fe05 | 2017-02-21 08:49:28 -0800 | [diff] [blame] | 2323 | OPENSSL_EXPORT void SSL_enable_signed_cert_timestamps(SSL *ssl); |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 2324 | |
| 2325 | /* SSL_CTX_enable_signed_cert_timestamps enables SCT requests on all client SSL |
| 2326 | * objects created from |ctx|. |
| 2327 | * |
| 2328 | * Call |SSL_get0_signed_cert_timestamp_list| to recover the SCT after the |
| 2329 | * handshake. */ |
| 2330 | OPENSSL_EXPORT void SSL_CTX_enable_signed_cert_timestamps(SSL_CTX *ctx); |
| 2331 | |
| 2332 | /* SSL_enable_ocsp_stapling causes |ssl| (which must be the client end of a |
Robert Sloan | a94fe05 | 2017-02-21 08:49:28 -0800 | [diff] [blame] | 2333 | * connection) to request a stapled OCSP response from the server. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 2334 | * |
| 2335 | * Call |SSL_get0_ocsp_response| to recover the OCSP response after the |
| 2336 | * handshake. */ |
Robert Sloan | a94fe05 | 2017-02-21 08:49:28 -0800 | [diff] [blame] | 2337 | OPENSSL_EXPORT void SSL_enable_ocsp_stapling(SSL *ssl); |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 2338 | |
| 2339 | /* SSL_CTX_enable_ocsp_stapling enables OCSP stapling on all client SSL objects |
| 2340 | * created from |ctx|. |
| 2341 | * |
| 2342 | * Call |SSL_get0_ocsp_response| to recover the OCSP response after the |
| 2343 | * handshake. */ |
| 2344 | OPENSSL_EXPORT void SSL_CTX_enable_ocsp_stapling(SSL_CTX *ctx); |
| 2345 | |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 2346 | /* SSL_CTX_set0_verify_cert_store sets an |X509_STORE| that will be used |
| 2347 | * exclusively for certificate verification and returns one. Ownership of |
| 2348 | * |store| is transferred to the |SSL_CTX|. */ |
| 2349 | OPENSSL_EXPORT int SSL_CTX_set0_verify_cert_store(SSL_CTX *ctx, |
| 2350 | X509_STORE *store); |
| 2351 | |
| 2352 | /* SSL_CTX_set1_verify_cert_store sets an |X509_STORE| that will be used |
| 2353 | * exclusively for certificate verification and returns one. An additional |
| 2354 | * reference to |store| will be taken. */ |
| 2355 | OPENSSL_EXPORT int SSL_CTX_set1_verify_cert_store(SSL_CTX *ctx, |
| 2356 | X509_STORE *store); |
| 2357 | |
| 2358 | /* SSL_set0_verify_cert_store sets an |X509_STORE| that will be used |
| 2359 | * exclusively for certificate verification and returns one. Ownership of |
| 2360 | * |store| is transferred to the |SSL|. */ |
| 2361 | OPENSSL_EXPORT int SSL_set0_verify_cert_store(SSL *ssl, X509_STORE *store); |
| 2362 | |
| 2363 | /* SSL_set1_verify_cert_store sets an |X509_STORE| that will be used |
| 2364 | * exclusively for certificate verification and returns one. An additional |
| 2365 | * reference to |store| will be taken. */ |
| 2366 | OPENSSL_EXPORT int SSL_set1_verify_cert_store(SSL *ssl, X509_STORE *store); |
| 2367 | |
Robert Sloan | 572a4e2 | 2017-04-17 10:52:19 -0700 | [diff] [blame] | 2368 | /* SSL_CTX_set_ed25519_enabled configures whether |ctx| advertises support for |
| 2369 | * the Ed25519 signature algorithm when using the default preference list. */ |
| 2370 | OPENSSL_EXPORT void SSL_CTX_set_ed25519_enabled(SSL_CTX *ctx, int enabled); |
| 2371 | |
| 2372 | /* SSL_CTX_set_verify_algorithm_prefs confingures |ctx| to use |prefs| as the |
| 2373 | * preference list when verifying signature's from the peer's long-term key. It |
| 2374 | * returns one on zero on error. |prefs| should not include the internal-only |
| 2375 | * value |SSL_SIGN_RSA_PKCS1_MD5_SHA1|. */ |
| 2376 | OPENSSL_EXPORT int SSL_CTX_set_verify_algorithm_prefs(SSL_CTX *ctx, |
| 2377 | const uint16_t *prefs, |
| 2378 | size_t num_prefs); |
| 2379 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2380 | |
| 2381 | /* Client certificate CA list. |
| 2382 | * |
| 2383 | * When requesting a client certificate, a server may advertise a list of |
| 2384 | * certificate authorities which are accepted. These functions may be used to |
| 2385 | * configure this list. */ |
| 2386 | |
| 2387 | /* SSL_set_client_CA_list sets |ssl|'s client certificate CA list to |
| 2388 | * |name_list|. It takes ownership of |name_list|. */ |
| 2389 | OPENSSL_EXPORT void SSL_set_client_CA_list(SSL *ssl, |
| 2390 | STACK_OF(X509_NAME) *name_list); |
| 2391 | |
| 2392 | /* SSL_CTX_set_client_CA_list sets |ctx|'s client certificate CA list to |
| 2393 | * |name_list|. It takes ownership of |name_list|. */ |
| 2394 | OPENSSL_EXPORT void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, |
| 2395 | STACK_OF(X509_NAME) *name_list); |
| 2396 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 2397 | /* SSL_get_client_CA_list returns |ssl|'s client certificate CA list. If |ssl| |
| 2398 | * has not been configured as a client, this is the list configured by |
| 2399 | * |SSL_CTX_set_client_CA_list|. |
| 2400 | * |
| 2401 | * If configured as a client, it returns the client certificate CA list sent by |
| 2402 | * the server. In this mode, the behavior is undefined except during the |
| 2403 | * callbacks set by |SSL_CTX_set_cert_cb| and |SSL_CTX_set_client_cert_cb| or |
| 2404 | * when the handshake is paused because of them. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2405 | OPENSSL_EXPORT STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *ssl); |
| 2406 | |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 2407 | /* SSL_get0_server_requested_CAs returns the CAs sent by a server to guide a |
| 2408 | * client in certificate selection. They are a series of DER-encoded X.509 |
| 2409 | * names. This function may only be called during a callback set by |
| 2410 | * |SSL_CTX_set_cert_cb| or when the handshake is paused because of it. |
| 2411 | * |
| 2412 | * The returned stack is owned by |ssl|, as are its contents. It should not be |
| 2413 | * used past the point where the handshake is restarted after the callback. */ |
| 2414 | OPENSSL_EXPORT STACK_OF(CRYPTO_BUFFER) *SSL_get0_server_requested_CAs( |
| 2415 | const SSL *ssl); |
| 2416 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2417 | /* SSL_CTX_get_client_CA_list returns |ctx|'s client certificate CA list. */ |
| 2418 | OPENSSL_EXPORT STACK_OF(X509_NAME) * |
| 2419 | SSL_CTX_get_client_CA_list(const SSL_CTX *ctx); |
| 2420 | |
| 2421 | /* SSL_add_client_CA appends |x509|'s subject to the client certificate CA list. |
| 2422 | * It returns one on success or zero on error. The caller retains ownership of |
| 2423 | * |x509|. */ |
| 2424 | OPENSSL_EXPORT int SSL_add_client_CA(SSL *ssl, X509 *x509); |
| 2425 | |
| 2426 | /* SSL_CTX_add_client_CA appends |x509|'s subject to the client certificate CA |
| 2427 | * list. It returns one on success or zero on error. The caller retains |
| 2428 | * ownership of |x509|. */ |
| 2429 | OPENSSL_EXPORT int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *x509); |
| 2430 | |
| 2431 | /* SSL_load_client_CA_file opens |file| and reads PEM-encoded certificates from |
| 2432 | * it. It returns a newly-allocated stack of the certificate subjects or NULL |
| 2433 | * on error. */ |
| 2434 | OPENSSL_EXPORT STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file); |
| 2435 | |
| 2436 | /* SSL_dup_CA_list makes a deep copy of |list|. It returns the new list on |
| 2437 | * success or NULL on allocation error. */ |
| 2438 | OPENSSL_EXPORT STACK_OF(X509_NAME) *SSL_dup_CA_list(STACK_OF(X509_NAME) *list); |
| 2439 | |
| 2440 | /* SSL_add_file_cert_subjects_to_stack behaves like |SSL_load_client_CA_file| |
| 2441 | * but appends the result to |out|. It returns one on success or zero on |
| 2442 | * error. */ |
| 2443 | OPENSSL_EXPORT int SSL_add_file_cert_subjects_to_stack(STACK_OF(X509_NAME) *out, |
| 2444 | const char *file); |
| 2445 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2446 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 2447 | /* Server name indication. |
| 2448 | * |
| 2449 | * The server_name extension (RFC 3546) allows the client to advertise the name |
| 2450 | * of the server it is connecting to. This is used in virtual hosting |
| 2451 | * deployments to select one of a several certificates on a single IP. Only the |
| 2452 | * host_name name type is supported. */ |
| 2453 | |
| 2454 | #define TLSEXT_NAMETYPE_host_name 0 |
| 2455 | |
| 2456 | /* SSL_set_tlsext_host_name, for a client, configures |ssl| to advertise |name| |
| 2457 | * in the server_name extension. It returns one on success and zero on error. */ |
| 2458 | OPENSSL_EXPORT int SSL_set_tlsext_host_name(SSL *ssl, const char *name); |
| 2459 | |
| 2460 | /* SSL_get_servername, for a server, returns the hostname supplied by the |
| 2461 | * client or NULL if there was none. The |type| argument must be |
| 2462 | * |TLSEXT_NAMETYPE_host_name|. */ |
| 2463 | OPENSSL_EXPORT const char *SSL_get_servername(const SSL *ssl, const int type); |
| 2464 | |
| 2465 | /* SSL_get_servername_type, for a server, returns |TLSEXT_NAMETYPE_host_name| |
| 2466 | * if the client sent a hostname and -1 otherwise. */ |
| 2467 | OPENSSL_EXPORT int SSL_get_servername_type(const SSL *ssl); |
| 2468 | |
| 2469 | /* SSL_CTX_set_tlsext_servername_callback configures |callback| to be called on |
| 2470 | * the server after ClientHello extensions have been parsed and returns one. |
Steven Valdez | 909b19f | 2016-11-21 15:35:44 -0500 | [diff] [blame] | 2471 | * The callback may use |SSL_get_servername| to examine the server_name |
| 2472 | * extension and returns a |SSL_TLSEXT_ERR_*| value. The value of |arg| may be |
| 2473 | * set by calling |SSL_CTX_set_tlsext_servername_arg|. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 2474 | * |
| 2475 | * If the callback returns |SSL_TLSEXT_ERR_NOACK|, the server_name extension is |
| 2476 | * not acknowledged in the ServerHello. If the return value is |
David Benjamin | f31229b | 2017-01-25 14:08:15 -0500 | [diff] [blame] | 2477 | * |SSL_TLSEXT_ERR_ALERT_FATAL|, then |*out_alert| is the alert to send, |
| 2478 | * defaulting to |SSL_AD_UNRECOGNIZED_NAME|. |SSL_TLSEXT_ERR_ALERT_WARNING| is |
| 2479 | * ignored and treated as |SSL_TLSEXT_ERR_OK|. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 2480 | OPENSSL_EXPORT int SSL_CTX_set_tlsext_servername_callback( |
| 2481 | SSL_CTX *ctx, int (*callback)(SSL *ssl, int *out_alert, void *arg)); |
| 2482 | |
| 2483 | /* SSL_CTX_set_tlsext_servername_arg sets the argument to the servername |
| 2484 | * callback and returns one. See |SSL_CTX_set_tlsext_servername_callback|. */ |
| 2485 | OPENSSL_EXPORT int SSL_CTX_set_tlsext_servername_arg(SSL_CTX *ctx, void *arg); |
| 2486 | |
| 2487 | /* SSL_TLSEXT_ERR_* are values returned by some extension-related callbacks. */ |
| 2488 | #define SSL_TLSEXT_ERR_OK 0 |
| 2489 | #define SSL_TLSEXT_ERR_ALERT_WARNING 1 |
| 2490 | #define SSL_TLSEXT_ERR_ALERT_FATAL 2 |
| 2491 | #define SSL_TLSEXT_ERR_NOACK 3 |
| 2492 | |
Robert Sloan | 1c9db53 | 2017-03-13 08:03:59 -0700 | [diff] [blame] | 2493 | /* SSL_set_SSL_CTX changes |ssl|'s |SSL_CTX|. |ssl| will use the |
| 2494 | * certificate-related settings from |ctx|, and |SSL_get_SSL_CTX| will report |
| 2495 | * |ctx|. This function may be used during the callbacks registered by |
| 2496 | * |SSL_CTX_set_select_certificate_cb|, |
| 2497 | * |SSL_CTX_set_tlsext_servername_callback|, and |SSL_CTX_set_cert_cb| or when |
| 2498 | * the handshake is paused from them. It is typically used to switch |
| 2499 | * certificates based on SNI. |
| 2500 | * |
| 2501 | * Note the session cache and related settings will continue to use the initial |
| 2502 | * |SSL_CTX|. Callers should use |SSL_CTX_set_session_id_context| to partition |
| 2503 | * the session cache between different domains. |
| 2504 | * |
| 2505 | * TODO(davidben): Should other settings change after this call? */ |
| 2506 | OPENSSL_EXPORT SSL_CTX *SSL_set_SSL_CTX(SSL *ssl, SSL_CTX *ctx); |
| 2507 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 2508 | |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 2509 | /* Application-layer protocol negotiation. |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2510 | * |
| 2511 | * The ALPN extension (RFC 7301) allows negotiating different application-layer |
| 2512 | * protocols over a single port. This is used, for example, to negotiate |
| 2513 | * HTTP/2. */ |
| 2514 | |
| 2515 | /* SSL_CTX_set_alpn_protos sets the client ALPN protocol list on |ctx| to |
| 2516 | * |protos|. |protos| must be in wire-format (i.e. a series of non-empty, 8-bit |
| 2517 | * length-prefixed strings). It returns zero on success and one on failure. |
| 2518 | * Configuring this list enables ALPN on a client. |
| 2519 | * |
| 2520 | * WARNING: this function is dangerous because it breaks the usual return value |
| 2521 | * convention. */ |
| 2522 | OPENSSL_EXPORT int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const uint8_t *protos, |
| 2523 | unsigned protos_len); |
| 2524 | |
| 2525 | /* SSL_set_alpn_protos sets the client ALPN protocol list on |ssl| to |protos|. |
| 2526 | * |protos| must be in wire-format (i.e. a series of non-empty, 8-bit |
| 2527 | * length-prefixed strings). It returns zero on success and one on failure. |
| 2528 | * Configuring this list enables ALPN on a client. |
| 2529 | * |
| 2530 | * WARNING: this function is dangerous because it breaks the usual return value |
| 2531 | * convention. */ |
| 2532 | OPENSSL_EXPORT int SSL_set_alpn_protos(SSL *ssl, const uint8_t *protos, |
| 2533 | unsigned protos_len); |
| 2534 | |
| 2535 | /* SSL_CTX_set_alpn_select_cb sets a callback function on |ctx| that is called |
| 2536 | * during ClientHello processing in order to select an ALPN protocol from the |
| 2537 | * client's list of offered protocols. Configuring this callback enables ALPN on |
| 2538 | * a server. |
| 2539 | * |
| 2540 | * The callback is passed a wire-format (i.e. a series of non-empty, 8-bit |
| 2541 | * length-prefixed strings) ALPN protocol list in |in|. It should set |*out| and |
| 2542 | * |*out_len| to the selected protocol and return |SSL_TLSEXT_ERR_OK| on |
| 2543 | * success. It does not pass ownership of the buffer. Otherwise, it should |
| 2544 | * return |SSL_TLSEXT_ERR_NOACK|. Other |SSL_TLSEXT_ERR_*| values are |
Steven Valdez | 909b19f | 2016-11-21 15:35:44 -0500 | [diff] [blame] | 2545 | * unimplemented and will be treated as |SSL_TLSEXT_ERR_NOACK|. |
| 2546 | * |
| 2547 | * The cipher suite is selected before negotiating ALPN. The callback may use |
| 2548 | * |SSL_get_pending_cipher| to query the cipher suite. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2549 | OPENSSL_EXPORT void SSL_CTX_set_alpn_select_cb( |
| 2550 | SSL_CTX *ctx, int (*cb)(SSL *ssl, const uint8_t **out, uint8_t *out_len, |
| 2551 | const uint8_t *in, unsigned in_len, void *arg), |
| 2552 | void *arg); |
| 2553 | |
| 2554 | /* SSL_get0_alpn_selected gets the selected ALPN protocol (if any) from |ssl|. |
| 2555 | * On return it sets |*out_data| to point to |*out_len| bytes of protocol name |
| 2556 | * (not including the leading length-prefix byte). If the server didn't respond |
| 2557 | * with a negotiated protocol then |*out_len| will be zero. */ |
| 2558 | OPENSSL_EXPORT void SSL_get0_alpn_selected(const SSL *ssl, |
| 2559 | const uint8_t **out_data, |
| 2560 | unsigned *out_len); |
| 2561 | |
Robert Sloan | 572a4e2 | 2017-04-17 10:52:19 -0700 | [diff] [blame] | 2562 | /* SSL_CTX_set_allow_unknown_alpn_protos configures client connections on |ctx| |
| 2563 | * to allow unknown ALPN protocols from the server. Otherwise, by default, the |
| 2564 | * client will require that the protocol be advertised in |
| 2565 | * |SSL_CTX_set_alpn_protos|. */ |
| 2566 | OPENSSL_EXPORT void SSL_CTX_set_allow_unknown_alpn_protos(SSL_CTX *ctx, |
| 2567 | int enabled); |
| 2568 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2569 | |
| 2570 | /* Next protocol negotiation. |
| 2571 | * |
| 2572 | * The NPN extension (draft-agl-tls-nextprotoneg-03) is the predecessor to ALPN |
| 2573 | * and deprecated in favor of it. */ |
| 2574 | |
| 2575 | /* SSL_CTX_set_next_protos_advertised_cb sets a callback that is called when a |
| 2576 | * TLS server needs a list of supported protocols for Next Protocol |
| 2577 | * Negotiation. The returned list must be in wire format. The list is returned |
| 2578 | * by setting |*out| to point to it and |*out_len| to its length. This memory |
| 2579 | * will not be modified, but one should assume that |ssl| keeps a reference to |
| 2580 | * it. |
| 2581 | * |
| 2582 | * The callback should return |SSL_TLSEXT_ERR_OK| if it wishes to advertise. |
| 2583 | * Otherwise, no such extension will be included in the ServerHello. */ |
| 2584 | OPENSSL_EXPORT void SSL_CTX_set_next_protos_advertised_cb( |
| 2585 | SSL_CTX *ctx, |
| 2586 | int (*cb)(SSL *ssl, const uint8_t **out, unsigned *out_len, void *arg), |
| 2587 | void *arg); |
| 2588 | |
| 2589 | /* SSL_CTX_set_next_proto_select_cb sets a callback that is called when a client |
| 2590 | * needs to select a protocol from the server's provided list. |*out| must be |
| 2591 | * set to point to the selected protocol (which may be within |in|). The length |
| 2592 | * of the protocol name must be written into |*out_len|. The server's advertised |
| 2593 | * protocols are provided in |in| and |in_len|. The callback can assume that |
| 2594 | * |in| is syntactically valid. |
| 2595 | * |
| 2596 | * The client must select a protocol. It is fatal to the connection if this |
| 2597 | * callback returns a value other than |SSL_TLSEXT_ERR_OK|. |
| 2598 | * |
| 2599 | * Configuring this callback enables NPN on a client. */ |
| 2600 | OPENSSL_EXPORT void SSL_CTX_set_next_proto_select_cb( |
| 2601 | SSL_CTX *ctx, int (*cb)(SSL *ssl, uint8_t **out, uint8_t *out_len, |
| 2602 | const uint8_t *in, unsigned in_len, void *arg), |
| 2603 | void *arg); |
| 2604 | |
| 2605 | /* SSL_get0_next_proto_negotiated sets |*out_data| and |*out_len| to point to |
| 2606 | * the client's requested protocol for this connection. If the client didn't |
| 2607 | * request any protocol, then |*out_data| is set to NULL. |
| 2608 | * |
| 2609 | * Note that the client can request any protocol it chooses. The value returned |
| 2610 | * from this function need not be a member of the list of supported protocols |
| 2611 | * provided by the server. */ |
| 2612 | OPENSSL_EXPORT void SSL_get0_next_proto_negotiated(const SSL *ssl, |
| 2613 | const uint8_t **out_data, |
| 2614 | unsigned *out_len); |
| 2615 | |
| 2616 | /* SSL_select_next_proto implements the standard protocol selection. It is |
| 2617 | * expected that this function is called from the callback set by |
| 2618 | * |SSL_CTX_set_next_proto_select_cb|. |
| 2619 | * |
| 2620 | * The protocol data is assumed to be a vector of 8-bit, length prefixed byte |
| 2621 | * strings. The length byte itself is not included in the length. A byte |
| 2622 | * string of length 0 is invalid. No byte string may be truncated. |
| 2623 | * |
| 2624 | * The current, but experimental algorithm for selecting the protocol is: |
| 2625 | * |
| 2626 | * 1) If the server doesn't support NPN then this is indicated to the |
| 2627 | * callback. In this case, the client application has to abort the connection |
| 2628 | * or have a default application level protocol. |
| 2629 | * |
| 2630 | * 2) If the server supports NPN, but advertises an empty list then the |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 2631 | * client selects the first protocol in its list, but indicates via the |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2632 | * API that this fallback case was enacted. |
| 2633 | * |
| 2634 | * 3) Otherwise, the client finds the first protocol in the server's list |
| 2635 | * that it supports and selects this protocol. This is because it's |
| 2636 | * assumed that the server has better information about which protocol |
| 2637 | * a client should use. |
| 2638 | * |
| 2639 | * 4) If the client doesn't support any of the server's advertised |
| 2640 | * protocols, then this is treated the same as case 2. |
| 2641 | * |
| 2642 | * It returns either |OPENSSL_NPN_NEGOTIATED| if a common protocol was found, or |
| 2643 | * |OPENSSL_NPN_NO_OVERLAP| if the fallback case was reached. */ |
| 2644 | OPENSSL_EXPORT int SSL_select_next_proto(uint8_t **out, uint8_t *out_len, |
| 2645 | const uint8_t *server, |
| 2646 | unsigned server_len, |
| 2647 | const uint8_t *client, |
| 2648 | unsigned client_len); |
| 2649 | |
| 2650 | #define OPENSSL_NPN_UNSUPPORTED 0 |
| 2651 | #define OPENSSL_NPN_NEGOTIATED 1 |
| 2652 | #define OPENSSL_NPN_NO_OVERLAP 2 |
| 2653 | |
| 2654 | |
| 2655 | /* Channel ID. |
| 2656 | * |
| 2657 | * See draft-balfanz-tls-channelid-01. */ |
| 2658 | |
David Benjamin | 1b24967 | 2016-12-06 18:25:50 -0500 | [diff] [blame] | 2659 | /* SSL_CTX_set_tls_channel_id_enabled configures whether connections associated |
| 2660 | * with |ctx| should enable Channel ID. */ |
| 2661 | OPENSSL_EXPORT void SSL_CTX_set_tls_channel_id_enabled(SSL_CTX *ctx, |
| 2662 | int enabled); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2663 | |
David Benjamin | 1b24967 | 2016-12-06 18:25:50 -0500 | [diff] [blame] | 2664 | /* SSL_set_tls_channel_id_enabled configures whether |ssl| should enable Channel |
| 2665 | * ID. */ |
| 2666 | OPENSSL_EXPORT void SSL_set_tls_channel_id_enabled(SSL *ssl, int enabled); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2667 | |
| 2668 | /* SSL_CTX_set1_tls_channel_id configures a TLS client to send a TLS Channel ID |
| 2669 | * to compatible servers. |private_key| must be a P-256 EC key. It returns one |
| 2670 | * on success and zero on error. */ |
| 2671 | OPENSSL_EXPORT int SSL_CTX_set1_tls_channel_id(SSL_CTX *ctx, |
| 2672 | EVP_PKEY *private_key); |
| 2673 | |
| 2674 | /* SSL_set1_tls_channel_id configures a TLS client to send a TLS Channel ID to |
| 2675 | * compatible servers. |private_key| must be a P-256 EC key. It returns one on |
| 2676 | * success and zero on error. */ |
| 2677 | OPENSSL_EXPORT int SSL_set1_tls_channel_id(SSL *ssl, EVP_PKEY *private_key); |
| 2678 | |
| 2679 | /* SSL_get_tls_channel_id gets the client's TLS Channel ID from a server |SSL*| |
| 2680 | * and copies up to the first |max_out| bytes into |out|. The Channel ID |
| 2681 | * consists of the client's P-256 public key as an (x,y) pair where each is a |
| 2682 | * 32-byte, big-endian field element. It returns 0 if the client didn't offer a |
| 2683 | * Channel ID and the length of the complete Channel ID otherwise. */ |
| 2684 | OPENSSL_EXPORT size_t SSL_get_tls_channel_id(SSL *ssl, uint8_t *out, |
| 2685 | size_t max_out); |
| 2686 | |
| 2687 | /* SSL_CTX_set_channel_id_cb sets a callback to be called when a TLS Channel ID |
| 2688 | * is requested. The callback may set |*out_pkey| to a key, passing a reference |
| 2689 | * to the caller. If none is returned, the handshake will pause and |
| 2690 | * |SSL_get_error| will return |SSL_ERROR_WANT_CHANNEL_ID_LOOKUP|. |
| 2691 | * |
| 2692 | * See also |SSL_ERROR_WANT_CHANNEL_ID_LOOKUP|. */ |
| 2693 | OPENSSL_EXPORT void SSL_CTX_set_channel_id_cb( |
| 2694 | SSL_CTX *ctx, void (*channel_id_cb)(SSL *ssl, EVP_PKEY **out_pkey)); |
| 2695 | |
| 2696 | /* SSL_CTX_get_channel_id_cb returns the callback set by |
| 2697 | * |SSL_CTX_set_channel_id_cb|. */ |
| 2698 | OPENSSL_EXPORT void (*SSL_CTX_get_channel_id_cb(SSL_CTX *ctx))( |
| 2699 | SSL *ssl, EVP_PKEY **out_pkey); |
| 2700 | |
| 2701 | |
| 2702 | /* DTLS-SRTP. |
| 2703 | * |
| 2704 | * See RFC 5764. */ |
| 2705 | |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 2706 | /* srtp_protection_profile_st (aka |SRTP_PROTECTION_PROFILE|) is an SRTP |
| 2707 | * profile for use with the use_srtp extension. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2708 | struct srtp_protection_profile_st { |
| 2709 | const char *name; |
| 2710 | unsigned long id; |
| 2711 | } /* SRTP_PROTECTION_PROFILE */; |
| 2712 | |
| 2713 | DECLARE_STACK_OF(SRTP_PROTECTION_PROFILE) |
| 2714 | |
| 2715 | /* SRTP_* define constants for SRTP profiles. */ |
| 2716 | #define SRTP_AES128_CM_SHA1_80 0x0001 |
| 2717 | #define SRTP_AES128_CM_SHA1_32 0x0002 |
| 2718 | #define SRTP_AES128_F8_SHA1_80 0x0003 |
| 2719 | #define SRTP_AES128_F8_SHA1_32 0x0004 |
| 2720 | #define SRTP_NULL_SHA1_80 0x0005 |
| 2721 | #define SRTP_NULL_SHA1_32 0x0006 |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 2722 | #define SRTP_AEAD_AES_128_GCM 0x0007 |
| 2723 | #define SRTP_AEAD_AES_256_GCM 0x0008 |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2724 | |
| 2725 | /* SSL_CTX_set_srtp_profiles enables SRTP for all SSL objects created from |
| 2726 | * |ctx|. |profile| contains a colon-separated list of profile names. It returns |
| 2727 | * one on success and zero on failure. */ |
| 2728 | OPENSSL_EXPORT int SSL_CTX_set_srtp_profiles(SSL_CTX *ctx, |
| 2729 | const char *profiles); |
| 2730 | |
| 2731 | /* SSL_set_srtp_profiles enables SRTP for |ssl|. |profile| contains a |
| 2732 | * colon-separated list of profile names. It returns one on success and zero on |
| 2733 | * failure. */ |
| 2734 | OPENSSL_EXPORT int SSL_set_srtp_profiles(SSL *ssl, const char *profiles); |
| 2735 | |
| 2736 | /* SSL_get_srtp_profiles returns the SRTP profiles supported by |ssl|. */ |
| 2737 | OPENSSL_EXPORT STACK_OF(SRTP_PROTECTION_PROFILE) *SSL_get_srtp_profiles( |
| 2738 | SSL *ssl); |
| 2739 | |
| 2740 | /* SSL_get_selected_srtp_profile returns the selected SRTP profile, or NULL if |
| 2741 | * SRTP was not negotiated. */ |
| 2742 | OPENSSL_EXPORT const SRTP_PROTECTION_PROFILE *SSL_get_selected_srtp_profile( |
| 2743 | SSL *ssl); |
| 2744 | |
| 2745 | |
| 2746 | /* Pre-shared keys. |
| 2747 | * |
| 2748 | * Connections may be configured with PSK (Pre-Shared Key) cipher suites. These |
| 2749 | * authenticate using out-of-band pre-shared keys rather than certificates. See |
| 2750 | * RFC 4279. |
| 2751 | * |
| 2752 | * This implementation uses NUL-terminated C strings for identities and identity |
| 2753 | * hints, so values with a NUL character are not supported. (RFC 4279 does not |
| 2754 | * specify the format of an identity.) */ |
| 2755 | |
| 2756 | /* PSK_MAX_IDENTITY_LEN is the maximum supported length of a PSK identity, |
| 2757 | * excluding the NUL terminator. */ |
| 2758 | #define PSK_MAX_IDENTITY_LEN 128 |
| 2759 | |
| 2760 | /* PSK_MAX_PSK_LEN is the maximum supported length of a pre-shared key. */ |
| 2761 | #define PSK_MAX_PSK_LEN 256 |
| 2762 | |
| 2763 | /* SSL_CTX_set_psk_client_callback sets the callback to be called when PSK is |
| 2764 | * negotiated on the client. This callback must be set to enable PSK cipher |
| 2765 | * suites on the client. |
| 2766 | * |
| 2767 | * The callback is passed the identity hint in |hint| or NULL if none was |
| 2768 | * provided. It should select a PSK identity and write the identity and the |
| 2769 | * corresponding PSK to |identity| and |psk|, respectively. The identity is |
| 2770 | * written as a NUL-terminated C string of length (excluding the NUL terminator) |
| 2771 | * at most |max_identity_len|. The PSK's length must be at most |max_psk_len|. |
| 2772 | * The callback returns the length of the PSK or 0 if no suitable identity was |
| 2773 | * found. */ |
| 2774 | OPENSSL_EXPORT void SSL_CTX_set_psk_client_callback( |
| 2775 | SSL_CTX *ctx, |
| 2776 | unsigned (*psk_client_callback)( |
| 2777 | SSL *ssl, const char *hint, char *identity, |
| 2778 | unsigned max_identity_len, uint8_t *psk, unsigned max_psk_len)); |
| 2779 | |
| 2780 | /* SSL_set_psk_client_callback sets the callback to be called when PSK is |
| 2781 | * negotiated on the client. This callback must be set to enable PSK cipher |
| 2782 | * suites on the client. See also |SSL_CTX_set_psk_client_callback|. */ |
| 2783 | OPENSSL_EXPORT void SSL_set_psk_client_callback( |
| 2784 | SSL *ssl, unsigned (*psk_client_callback)(SSL *ssl, const char *hint, |
| 2785 | char *identity, |
| 2786 | unsigned max_identity_len, |
| 2787 | uint8_t *psk, |
| 2788 | unsigned max_psk_len)); |
| 2789 | |
| 2790 | /* SSL_CTX_set_psk_server_callback sets the callback to be called when PSK is |
| 2791 | * negotiated on the server. This callback must be set to enable PSK cipher |
| 2792 | * suites on the server. |
| 2793 | * |
| 2794 | * The callback is passed the identity in |identity|. It should write a PSK of |
| 2795 | * length at most |max_psk_len| to |psk| and return the number of bytes written |
| 2796 | * or zero if the PSK identity is unknown. */ |
| 2797 | OPENSSL_EXPORT void SSL_CTX_set_psk_server_callback( |
| 2798 | SSL_CTX *ctx, |
| 2799 | unsigned (*psk_server_callback)(SSL *ssl, const char *identity, |
| 2800 | uint8_t *psk, |
| 2801 | unsigned max_psk_len)); |
| 2802 | |
| 2803 | /* SSL_set_psk_server_callback sets the callback to be called when PSK is |
| 2804 | * negotiated on the server. This callback must be set to enable PSK cipher |
| 2805 | * suites on the server. See also |SSL_CTX_set_psk_server_callback|. */ |
| 2806 | OPENSSL_EXPORT void SSL_set_psk_server_callback( |
| 2807 | SSL *ssl, |
| 2808 | unsigned (*psk_server_callback)(SSL *ssl, const char *identity, |
| 2809 | uint8_t *psk, |
| 2810 | unsigned max_psk_len)); |
| 2811 | |
| 2812 | /* SSL_CTX_use_psk_identity_hint configures server connections to advertise an |
| 2813 | * identity hint of |identity_hint|. It returns one on success and zero on |
| 2814 | * error. */ |
| 2815 | OPENSSL_EXPORT int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, |
| 2816 | const char *identity_hint); |
| 2817 | |
| 2818 | /* SSL_use_psk_identity_hint configures server connections to advertise an |
| 2819 | * identity hint of |identity_hint|. It returns one on success and zero on |
| 2820 | * error. */ |
| 2821 | OPENSSL_EXPORT int SSL_use_psk_identity_hint(SSL *ssl, |
| 2822 | const char *identity_hint); |
| 2823 | |
| 2824 | /* SSL_get_psk_identity_hint returns the PSK identity hint advertised for |ssl| |
| 2825 | * or NULL if there is none. */ |
| 2826 | OPENSSL_EXPORT const char *SSL_get_psk_identity_hint(const SSL *ssl); |
| 2827 | |
| 2828 | /* SSL_get_psk_identity, after the handshake completes, returns the PSK identity |
| 2829 | * that was negotiated by |ssl| or NULL if PSK was not used. */ |
| 2830 | OPENSSL_EXPORT const char *SSL_get_psk_identity(const SSL *ssl); |
| 2831 | |
| 2832 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 2833 | /* Alerts. |
| 2834 | * |
| 2835 | * TLS and SSL 3.0 use alerts to signal error conditions. Alerts have a type |
| 2836 | * (warning or fatal) and description. OpenSSL internally handles fatal alerts |
| 2837 | * with dedicated error codes (see |SSL_AD_REASON_OFFSET|). Except for |
| 2838 | * close_notify, warning alerts are silently ignored and may only be surfaced |
| 2839 | * with |SSL_CTX_set_info_callback|. */ |
| 2840 | |
| 2841 | /* SSL_AD_REASON_OFFSET is the offset between error reasons and |SSL_AD_*| |
| 2842 | * values. Any error code under |ERR_LIB_SSL| with an error reason above this |
| 2843 | * value corresponds to an alert description. Consumers may add or subtract |
| 2844 | * |SSL_AD_REASON_OFFSET| to convert between them. |
| 2845 | * |
| 2846 | * make_errors.go reserves error codes above 1000 for manually-assigned errors. |
| 2847 | * This value must be kept in sync with reservedReasonCode in make_errors.h */ |
| 2848 | #define SSL_AD_REASON_OFFSET 1000 |
| 2849 | |
| 2850 | /* SSL_AD_* are alert descriptions for SSL 3.0 and TLS. */ |
| 2851 | #define SSL_AD_CLOSE_NOTIFY SSL3_AD_CLOSE_NOTIFY |
| 2852 | #define SSL_AD_UNEXPECTED_MESSAGE SSL3_AD_UNEXPECTED_MESSAGE |
| 2853 | #define SSL_AD_BAD_RECORD_MAC SSL3_AD_BAD_RECORD_MAC |
| 2854 | #define SSL_AD_DECRYPTION_FAILED TLS1_AD_DECRYPTION_FAILED |
| 2855 | #define SSL_AD_RECORD_OVERFLOW TLS1_AD_RECORD_OVERFLOW |
| 2856 | #define SSL_AD_DECOMPRESSION_FAILURE SSL3_AD_DECOMPRESSION_FAILURE |
| 2857 | #define SSL_AD_HANDSHAKE_FAILURE SSL3_AD_HANDSHAKE_FAILURE |
| 2858 | #define SSL_AD_NO_CERTIFICATE SSL3_AD_NO_CERTIFICATE /* Not used in TLS */ |
| 2859 | #define SSL_AD_BAD_CERTIFICATE SSL3_AD_BAD_CERTIFICATE |
| 2860 | #define SSL_AD_UNSUPPORTED_CERTIFICATE SSL3_AD_UNSUPPORTED_CERTIFICATE |
| 2861 | #define SSL_AD_CERTIFICATE_REVOKED SSL3_AD_CERTIFICATE_REVOKED |
| 2862 | #define SSL_AD_CERTIFICATE_EXPIRED SSL3_AD_CERTIFICATE_EXPIRED |
| 2863 | #define SSL_AD_CERTIFICATE_UNKNOWN SSL3_AD_CERTIFICATE_UNKNOWN |
| 2864 | #define SSL_AD_ILLEGAL_PARAMETER SSL3_AD_ILLEGAL_PARAMETER |
| 2865 | #define SSL_AD_UNKNOWN_CA TLS1_AD_UNKNOWN_CA |
| 2866 | #define SSL_AD_ACCESS_DENIED TLS1_AD_ACCESS_DENIED |
| 2867 | #define SSL_AD_DECODE_ERROR TLS1_AD_DECODE_ERROR |
| 2868 | #define SSL_AD_DECRYPT_ERROR TLS1_AD_DECRYPT_ERROR |
| 2869 | #define SSL_AD_EXPORT_RESTRICTION TLS1_AD_EXPORT_RESTRICTION |
| 2870 | #define SSL_AD_PROTOCOL_VERSION TLS1_AD_PROTOCOL_VERSION |
| 2871 | #define SSL_AD_INSUFFICIENT_SECURITY TLS1_AD_INSUFFICIENT_SECURITY |
| 2872 | #define SSL_AD_INTERNAL_ERROR TLS1_AD_INTERNAL_ERROR |
David Benjamin | 95add82 | 2016-10-19 01:09:12 -0400 | [diff] [blame] | 2873 | #define SSL_AD_INAPPROPRIATE_FALLBACK SSL3_AD_INAPPROPRIATE_FALLBACK |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 2874 | #define SSL_AD_USER_CANCELLED TLS1_AD_USER_CANCELLED |
| 2875 | #define SSL_AD_NO_RENEGOTIATION TLS1_AD_NO_RENEGOTIATION |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 2876 | #define SSL_AD_MISSING_EXTENSION TLS1_AD_MISSING_EXTENSION |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 2877 | #define SSL_AD_UNSUPPORTED_EXTENSION TLS1_AD_UNSUPPORTED_EXTENSION |
| 2878 | #define SSL_AD_CERTIFICATE_UNOBTAINABLE TLS1_AD_CERTIFICATE_UNOBTAINABLE |
| 2879 | #define SSL_AD_UNRECOGNIZED_NAME TLS1_AD_UNRECOGNIZED_NAME |
| 2880 | #define SSL_AD_BAD_CERTIFICATE_STATUS_RESPONSE \ |
| 2881 | TLS1_AD_BAD_CERTIFICATE_STATUS_RESPONSE |
| 2882 | #define SSL_AD_BAD_CERTIFICATE_HASH_VALUE TLS1_AD_BAD_CERTIFICATE_HASH_VALUE |
| 2883 | #define SSL_AD_UNKNOWN_PSK_IDENTITY TLS1_AD_UNKNOWN_PSK_IDENTITY |
David Benjamin | 95add82 | 2016-10-19 01:09:12 -0400 | [diff] [blame] | 2884 | #define SSL_AD_CERTIFICATE_REQUIRED TLS1_AD_CERTIFICATE_REQUIRED |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 2885 | |
| 2886 | /* SSL_alert_type_string_long returns a string description of |value| as an |
| 2887 | * alert type (warning or fatal). */ |
| 2888 | OPENSSL_EXPORT const char *SSL_alert_type_string_long(int value); |
| 2889 | |
| 2890 | /* SSL_alert_desc_string_long returns a string description of |value| as an |
| 2891 | * alert description or "unknown" if unknown. */ |
| 2892 | OPENSSL_EXPORT const char *SSL_alert_desc_string_long(int value); |
| 2893 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 2894 | /* SSL_send_fatal_alert sends a fatal alert over |ssl| of the specified type, |
| 2895 | * which should be one of the |SSL_AD_*| constants. It returns one on success |
| 2896 | * and <= 0 on error. The caller should pass the return value into |
| 2897 | * |SSL_get_error| to determine how to proceed. Once this function has been |
| 2898 | * called, future calls to |SSL_write| will fail. |
| 2899 | * |
| 2900 | * If retrying a failed operation due to |SSL_ERROR_WANT_WRITE|, subsequent |
| 2901 | * calls must use the same |alert| parameter. */ |
| 2902 | OPENSSL_EXPORT int SSL_send_fatal_alert(SSL *ssl, uint8_t alert); |
| 2903 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 2904 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2905 | /* ex_data functions. |
| 2906 | * |
| 2907 | * See |ex_data.h| for details. */ |
| 2908 | |
| 2909 | OPENSSL_EXPORT int SSL_set_ex_data(SSL *ssl, int idx, void *data); |
| 2910 | OPENSSL_EXPORT void *SSL_get_ex_data(const SSL *ssl, int idx); |
| 2911 | OPENSSL_EXPORT int SSL_get_ex_new_index(long argl, void *argp, |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 2912 | CRYPTO_EX_unused *unused, |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2913 | CRYPTO_EX_dup *dup_func, |
| 2914 | CRYPTO_EX_free *free_func); |
| 2915 | |
| 2916 | OPENSSL_EXPORT int SSL_SESSION_set_ex_data(SSL_SESSION *session, int idx, |
| 2917 | void *data); |
| 2918 | OPENSSL_EXPORT void *SSL_SESSION_get_ex_data(const SSL_SESSION *session, |
| 2919 | int idx); |
| 2920 | OPENSSL_EXPORT int SSL_SESSION_get_ex_new_index(long argl, void *argp, |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 2921 | CRYPTO_EX_unused *unused, |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2922 | CRYPTO_EX_dup *dup_func, |
| 2923 | CRYPTO_EX_free *free_func); |
| 2924 | |
| 2925 | OPENSSL_EXPORT int SSL_CTX_set_ex_data(SSL_CTX *ctx, int idx, void *data); |
| 2926 | OPENSSL_EXPORT void *SSL_CTX_get_ex_data(const SSL_CTX *ctx, int idx); |
| 2927 | OPENSSL_EXPORT int SSL_CTX_get_ex_new_index(long argl, void *argp, |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 2928 | CRYPTO_EX_unused *unused, |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2929 | CRYPTO_EX_dup *dup_func, |
| 2930 | CRYPTO_EX_free *free_func); |
| 2931 | |
| 2932 | |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 2933 | /* Low-level record-layer state. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2934 | |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 2935 | /* SSL_get_ivs sets |*out_iv_len| to the length of the IVs for the ciphers |
| 2936 | * underlying |ssl| and sets |*out_read_iv| and |*out_write_iv| to point to the |
| 2937 | * current IVs for the read and write directions. This is only meaningful for |
| 2938 | * connections with implicit IVs (i.e. CBC mode with SSLv3 or TLS 1.0). |
| 2939 | * |
| 2940 | * It returns one on success or zero on error. */ |
| 2941 | OPENSSL_EXPORT int SSL_get_ivs(const SSL *ssl, const uint8_t **out_read_iv, |
| 2942 | const uint8_t **out_write_iv, |
| 2943 | size_t *out_iv_len); |
| 2944 | |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 2945 | /* SSL_get_key_block_len returns the length of |ssl|'s key block. */ |
| 2946 | OPENSSL_EXPORT size_t SSL_get_key_block_len(const SSL *ssl); |
| 2947 | |
| 2948 | /* SSL_generate_key_block generates |out_len| bytes of key material for |ssl|'s |
| 2949 | * current connection state. */ |
| 2950 | OPENSSL_EXPORT int SSL_generate_key_block(const SSL *ssl, uint8_t *out, |
| 2951 | size_t out_len); |
| 2952 | |
| 2953 | /* SSL_get_read_sequence returns, in TLS, the expected sequence number of the |
| 2954 | * next incoming record in the current epoch. In DTLS, it returns the maximum |
| 2955 | * sequence number received in the current epoch and includes the epoch number |
| 2956 | * in the two most significant bytes. */ |
| 2957 | OPENSSL_EXPORT uint64_t SSL_get_read_sequence(const SSL *ssl); |
| 2958 | |
| 2959 | /* SSL_get_write_sequence returns the sequence number of the next outgoing |
| 2960 | * record in the current epoch. In DTLS, it includes the epoch number in the |
| 2961 | * two most significant bytes. */ |
| 2962 | OPENSSL_EXPORT uint64_t SSL_get_write_sequence(const SSL *ssl); |
| 2963 | |
| 2964 | |
| 2965 | /* Obscure functions. */ |
| 2966 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 2967 | /* SSL_get_structure_sizes returns the sizes of the SSL, SSL_CTX and |
| 2968 | * SSL_SESSION structures so that a test can ensure that outside code agrees on |
| 2969 | * these values. */ |
| 2970 | OPENSSL_EXPORT void SSL_get_structure_sizes(size_t *ssl_size, |
| 2971 | size_t *ssl_ctx_size, |
| 2972 | size_t *ssl_session_size); |
Adam Langley | 56d2503 | 2015-06-23 16:20:13 -0700 | [diff] [blame] | 2973 | |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 2974 | /* SSL_CTX_set_msg_callback installs |cb| as the message callback for |ctx|. |
| 2975 | * This callback will be called when sending or receiving low-level record |
| 2976 | * headers, complete handshake messages, ChangeCipherSpec, and alerts. |
| 2977 | * |write_p| is one for outgoing messages and zero for incoming messages. |
| 2978 | * |
| 2979 | * For each record header, |cb| is called with |version| = 0 and |content_type| |
| 2980 | * = |SSL3_RT_HEADER|. The |len| bytes from |buf| contain the header. Note that |
| 2981 | * this does not include the record body. If the record is sealed, the length |
| 2982 | * in the header is the length of the ciphertext. |
| 2983 | * |
| 2984 | * For each handshake message, ChangeCipherSpec, and alert, |version| is the |
| 2985 | * protocol version and |content_type| is the corresponding record type. The |
| 2986 | * |len| bytes from |buf| contain the handshake message, one-byte |
David Benjamin | 7c0d06c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 2987 | * ChangeCipherSpec body, and two-byte alert, respectively. |
| 2988 | * |
| 2989 | * For a V2ClientHello, |version| is |SSL2_VERSION|, |content_type| is zero, and |
| 2990 | * the |len| bytes from |buf| contain the V2ClientHello structure. */ |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 2991 | OPENSSL_EXPORT void SSL_CTX_set_msg_callback( |
| 2992 | SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, |
| 2993 | const void *buf, size_t len, SSL *ssl, void *arg)); |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 2994 | |
| 2995 | /* SSL_CTX_set_msg_callback_arg sets the |arg| parameter of the message |
| 2996 | * callback. */ |
| 2997 | OPENSSL_EXPORT void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg); |
| 2998 | |
| 2999 | /* SSL_set_msg_callback installs |cb| as the message callback of |ssl|. See |
| 3000 | * |SSL_CTX_set_msg_callback| for when this callback is called. */ |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 3001 | OPENSSL_EXPORT void SSL_set_msg_callback( |
| 3002 | SSL *ssl, void (*cb)(int write_p, int version, int content_type, |
| 3003 | const void *buf, size_t len, SSL *ssl, void *arg)); |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3004 | |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 3005 | /* SSL_set_msg_callback_arg sets the |arg| parameter of the message callback. */ |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3006 | OPENSSL_EXPORT void SSL_set_msg_callback_arg(SSL *ssl, void *arg); |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 3007 | |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 3008 | /* SSL_CTX_set_keylog_callback configures a callback to log key material. This |
| 3009 | * is intended for debugging use with tools like Wireshark. The |cb| function |
| 3010 | * should log |line| followed by a newline, synchronizing with any concurrent |
| 3011 | * access to the log. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 3012 | * |
| 3013 | * The format is described in |
| 3014 | * https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format. */ |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 3015 | OPENSSL_EXPORT void SSL_CTX_set_keylog_callback( |
| 3016 | SSL_CTX *ctx, void (*cb)(const SSL *ssl, const char *line)); |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 3017 | |
David Benjamin | 7c0d06c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3018 | /* SSL_CTX_get_keylog_callback returns the callback configured by |
| 3019 | * |SSL_CTX_set_keylog_callback|. */ |
| 3020 | OPENSSL_EXPORT void (*SSL_CTX_get_keylog_callback(const SSL_CTX *ctx))( |
| 3021 | const SSL *ssl, const char *line); |
| 3022 | |
David Benjamin | 6e899c7 | 2016-06-09 18:02:18 -0400 | [diff] [blame] | 3023 | /* SSL_CTX_set_current_time_cb configures a callback to retrieve the current |
| 3024 | * time, which should be set in |*out_clock|. This can be used for testing |
| 3025 | * purposes; for example, a callback can be configured that returns a time |
| 3026 | * set explicitly by the test. */ |
| 3027 | OPENSSL_EXPORT void SSL_CTX_set_current_time_cb( |
| 3028 | SSL_CTX *ctx, void (*cb)(const SSL *ssl, struct timeval *out_clock)); |
| 3029 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3030 | enum ssl_renegotiate_mode_t { |
| 3031 | ssl_renegotiate_never = 0, |
| 3032 | ssl_renegotiate_once, |
| 3033 | ssl_renegotiate_freely, |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3034 | ssl_renegotiate_ignore, |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 3035 | }; |
| 3036 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3037 | /* SSL_set_renegotiate_mode configures how |ssl|, a client, reacts to |
| 3038 | * renegotiation attempts by a server. If |ssl| is a server, peer-initiated |
| 3039 | * renegotiations are *always* rejected and this function does nothing. |
Kenny Root | 03bcf61 | 2015-11-05 20:20:27 +0000 | [diff] [blame] | 3040 | * |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3041 | * The renegotiation mode defaults to |ssl_renegotiate_never|, but may be set |
| 3042 | * at any point in a connection's lifetime. Set it to |ssl_renegotiate_once| to |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3043 | * allow one renegotiation, |ssl_renegotiate_freely| to allow all |
| 3044 | * renegotiations or |ssl_renegotiate_ignore| to ignore HelloRequest messages. |
| 3045 | * Note that ignoring HelloRequest messages may cause the connection to stall |
| 3046 | * if the server waits for the renegotiation to complete. |
Kenny Root | 03bcf61 | 2015-11-05 20:20:27 +0000 | [diff] [blame] | 3047 | * |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3048 | * There is no support in BoringSSL for initiating renegotiations as a client |
| 3049 | * or server. */ |
| 3050 | OPENSSL_EXPORT void SSL_set_renegotiate_mode(SSL *ssl, |
| 3051 | enum ssl_renegotiate_mode_t mode); |
Kenny Root | 03bcf61 | 2015-11-05 20:20:27 +0000 | [diff] [blame] | 3052 | |
| 3053 | /* SSL_renegotiate_pending returns one if |ssl| is in the middle of a |
| 3054 | * renegotiation. */ |
| 3055 | OPENSSL_EXPORT int SSL_renegotiate_pending(SSL *ssl); |
| 3056 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3057 | /* SSL_total_renegotiations returns the total number of renegotiation handshakes |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 3058 | * performed by |ssl|. This includes the pending renegotiation, if any. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3059 | OPENSSL_EXPORT int SSL_total_renegotiations(const SSL *ssl); |
Kenny Root | 03bcf61 | 2015-11-05 20:20:27 +0000 | [diff] [blame] | 3060 | |
Robert Sloan | 69939df | 2017-01-09 10:53:07 -0800 | [diff] [blame] | 3061 | /* SSL_CTX_set_early_data_enabled sets whether early data is allowed to be used |
Robert Sloan | 6d0d00e | 2017-03-27 07:13:07 -0700 | [diff] [blame] | 3062 | * with resumptions using |ctx|. |
| 3063 | * |
| 3064 | * As a server, if the client's early data is accepted, |SSL_do_handshake| will |
| 3065 | * complete as soon as the ClientHello is processed and server flight sent. |
| 3066 | * |SSL_write| may be used to send half-RTT data. |SSL_read| will consume early |
| 3067 | * data and transition to 1-RTT data as appropriate. |
| 3068 | * |
| 3069 | * Note early data is replayable by a network attacker. |SSL_in_init| and |
| 3070 | * |SSL_is_init_finished| will report the handshake is still in progress until |
| 3071 | * the client's Finished message is received. Callers may use these functions |
| 3072 | * to defer some processing if desired. |
| 3073 | * |
| 3074 | * WARNING: This is experimental and may cause interoperability failures until |
| 3075 | * fully implemented. */ |
Robert Sloan | 69939df | 2017-01-09 10:53:07 -0800 | [diff] [blame] | 3076 | OPENSSL_EXPORT void SSL_CTX_set_early_data_enabled(SSL_CTX *ctx, int enabled); |
| 3077 | |
Robert Sloan | 572a4e2 | 2017-04-17 10:52:19 -0700 | [diff] [blame] | 3078 | /* SSL_set_early_data_enabled sets whether early data is allowed to be used |
| 3079 | * with resumptions using |ssl|. See |SSL_CTX_set_early_data_enabled| for more |
| 3080 | * information. */ |
| 3081 | OPENSSL_EXPORT void SSL_set_early_data_enabled(SSL *ssl, int enabled); |
| 3082 | |
Robert Sloan | 6d0d00e | 2017-03-27 07:13:07 -0700 | [diff] [blame] | 3083 | /* SSL_early_data_accepted returns whether early data was accepted on the |
| 3084 | * handshake performed by |ssl|. */ |
| 3085 | OPENSSL_EXPORT int SSL_early_data_accepted(const SSL *ssl); |
| 3086 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3087 | /* SSL_MAX_CERT_LIST_DEFAULT is the default maximum length, in bytes, of a peer |
| 3088 | * certificate chain. */ |
David Benjamin | 95add82 | 2016-10-19 01:09:12 -0400 | [diff] [blame] | 3089 | #define SSL_MAX_CERT_LIST_DEFAULT (1024 * 100) |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 3090 | |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3091 | /* SSL_CTX_get_max_cert_list returns the maximum length, in bytes, of a peer |
| 3092 | * certificate chain accepted by |ctx|. */ |
| 3093 | OPENSSL_EXPORT size_t SSL_CTX_get_max_cert_list(const SSL_CTX *ctx); |
| 3094 | |
| 3095 | /* SSL_CTX_set_max_cert_list sets the maximum length, in bytes, of a peer |
| 3096 | * certificate chain to |max_cert_list|. This affects how much memory may be |
| 3097 | * consumed during the handshake. */ |
| 3098 | OPENSSL_EXPORT void SSL_CTX_set_max_cert_list(SSL_CTX *ctx, |
| 3099 | size_t max_cert_list); |
| 3100 | |
| 3101 | /* SSL_get_max_cert_list returns the maximum length, in bytes, of a peer |
| 3102 | * certificate chain accepted by |ssl|. */ |
| 3103 | OPENSSL_EXPORT size_t SSL_get_max_cert_list(const SSL *ssl); |
| 3104 | |
| 3105 | /* SSL_set_max_cert_list sets the maximum length, in bytes, of a peer |
| 3106 | * certificate chain to |max_cert_list|. This affects how much memory may be |
| 3107 | * consumed during the handshake. */ |
| 3108 | OPENSSL_EXPORT void SSL_set_max_cert_list(SSL *ssl, size_t max_cert_list); |
| 3109 | |
| 3110 | /* SSL_CTX_set_max_send_fragment sets the maximum length, in bytes, of records |
| 3111 | * sent by |ctx|. Beyond this length, handshake messages and application data |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 3112 | * will be split into multiple records. It returns one on success or zero on |
| 3113 | * error. */ |
| 3114 | OPENSSL_EXPORT int SSL_CTX_set_max_send_fragment(SSL_CTX *ctx, |
| 3115 | size_t max_send_fragment); |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3116 | |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 3117 | /* SSL_set_max_send_fragment sets the maximum length, in bytes, of records sent |
| 3118 | * by |ssl|. Beyond this length, handshake messages and application data will |
| 3119 | * be split into multiple records. It returns one on success or zero on |
| 3120 | * error. */ |
| 3121 | OPENSSL_EXPORT int SSL_set_max_send_fragment(SSL *ssl, |
| 3122 | size_t max_send_fragment); |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3123 | |
Robert Sloan | 4d1ac50 | 2017-02-06 08:36:14 -0800 | [diff] [blame] | 3124 | /* SSL_get_v2clienthello_count returns the total number of V2ClientHellos that |
| 3125 | * are accepted. */ |
| 3126 | OPENSSL_EXPORT uint64_t SSL_get_v2clienthello_count(void); |
| 3127 | |
David Benjamin | 1b24967 | 2016-12-06 18:25:50 -0500 | [diff] [blame] | 3128 | /* ssl_early_callback_ctx (aka |SSL_CLIENT_HELLO|) is passed to certain |
| 3129 | * callbacks that are called very early on during the server handshake. At this |
| 3130 | * point, much of the SSL* hasn't been filled out and only the ClientHello can |
| 3131 | * be depended on. */ |
| 3132 | typedef struct ssl_early_callback_ctx { |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3133 | SSL *ssl; |
| 3134 | const uint8_t *client_hello; |
| 3135 | size_t client_hello_len; |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3136 | uint16_t version; |
| 3137 | const uint8_t *random; |
| 3138 | size_t random_len; |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3139 | const uint8_t *session_id; |
| 3140 | size_t session_id_len; |
| 3141 | const uint8_t *cipher_suites; |
| 3142 | size_t cipher_suites_len; |
| 3143 | const uint8_t *compression_methods; |
| 3144 | size_t compression_methods_len; |
| 3145 | const uint8_t *extensions; |
| 3146 | size_t extensions_len; |
David Benjamin | 1b24967 | 2016-12-06 18:25:50 -0500 | [diff] [blame] | 3147 | } SSL_CLIENT_HELLO; |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3148 | |
Robert Sloan | 6d0d00e | 2017-03-27 07:13:07 -0700 | [diff] [blame] | 3149 | /* ssl_select_cert_result_t enumerates the possible results from selecting a |
| 3150 | * certificate with |select_certificate_cb|. */ |
| 3151 | enum ssl_select_cert_result_t { |
| 3152 | /* ssl_select_cert_success indicates that the certificate selection was |
| 3153 | * successful. */ |
| 3154 | ssl_select_cert_success = 1, |
| 3155 | /* ssl_select_cert_retry indicates that the operation could not be |
| 3156 | * immediately completed and must be reattempted at a later point. */ |
| 3157 | ssl_select_cert_retry = 0, |
| 3158 | /* ssl_select_cert_error indicates that a fatal error occured and the |
| 3159 | * handshake should be terminated. */ |
| 3160 | ssl_select_cert_error = -1, |
| 3161 | }; |
| 3162 | |
David Benjamin | 1b24967 | 2016-12-06 18:25:50 -0500 | [diff] [blame] | 3163 | /* SSL_early_callback_ctx_extension_get searches the extensions in |
| 3164 | * |client_hello| for an extension of the given type. If not found, it returns |
| 3165 | * zero. Otherwise it sets |out_data| to point to the extension contents (not |
| 3166 | * including the type and length bytes), sets |out_len| to the length of the |
| 3167 | * extension contents and returns one. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3168 | OPENSSL_EXPORT int SSL_early_callback_ctx_extension_get( |
David Benjamin | 1b24967 | 2016-12-06 18:25:50 -0500 | [diff] [blame] | 3169 | const SSL_CLIENT_HELLO *client_hello, uint16_t extension_type, |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3170 | const uint8_t **out_data, size_t *out_len); |
| 3171 | |
| 3172 | /* SSL_CTX_set_select_certificate_cb sets a callback that is called before most |
| 3173 | * ClientHello processing and before the decision whether to resume a session |
| 3174 | * is made. The callback may inspect the ClientHello and configure the |
Robert Sloan | 6d0d00e | 2017-03-27 07:13:07 -0700 | [diff] [blame] | 3175 | * connection. See |ssl_select_cert_result_t| for details of the return values. |
| 3176 | * |
| 3177 | * In the case that a retry is indicated, |SSL_get_error| will return |
| 3178 | * |SSL_ERROR_PENDING_CERTIFICATE| and the caller should arrange for the |
| 3179 | * high-level operation on |ssl| to be retried at a later time, which will |
| 3180 | * result in another call to |cb|. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3181 | * |
David Benjamin | 1b24967 | 2016-12-06 18:25:50 -0500 | [diff] [blame] | 3182 | * Note: The |SSL_CLIENT_HELLO| is only valid for the duration of the callback |
David Benjamin | f31229b | 2017-01-25 14:08:15 -0500 | [diff] [blame] | 3183 | * and is not valid while the handshake is paused. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3184 | OPENSSL_EXPORT void SSL_CTX_set_select_certificate_cb( |
Robert Sloan | 6d0d00e | 2017-03-27 07:13:07 -0700 | [diff] [blame] | 3185 | SSL_CTX *ctx, |
| 3186 | enum ssl_select_cert_result_t (*cb)(const SSL_CLIENT_HELLO *)); |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3187 | |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3188 | /* SSL_CTX_set_dos_protection_cb sets a callback that is called once the |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3189 | * resumption decision for a ClientHello has been made. It can return one to |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3190 | * allow the handshake to continue or zero to cause the handshake to abort. */ |
| 3191 | OPENSSL_EXPORT void SSL_CTX_set_dos_protection_cb( |
David Benjamin | 1b24967 | 2016-12-06 18:25:50 -0500 | [diff] [blame] | 3192 | SSL_CTX *ctx, int (*cb)(const SSL_CLIENT_HELLO *)); |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3193 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3194 | /* SSL_ST_* are possible values for |SSL_state| and the bitmasks that make them |
| 3195 | * up. */ |
| 3196 | #define SSL_ST_CONNECT 0x1000 |
| 3197 | #define SSL_ST_ACCEPT 0x2000 |
| 3198 | #define SSL_ST_MASK 0x0FFF |
| 3199 | #define SSL_ST_INIT (SSL_ST_CONNECT | SSL_ST_ACCEPT) |
| 3200 | #define SSL_ST_OK 0x03 |
| 3201 | #define SSL_ST_RENEGOTIATE (0x04 | SSL_ST_INIT) |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3202 | #define SSL_ST_TLS13 (0x05 | SSL_ST_INIT) |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3203 | |
| 3204 | /* SSL_CB_* are possible values for the |type| parameter in the info |
| 3205 | * callback and the bitmasks that make them up. */ |
| 3206 | #define SSL_CB_LOOP 0x01 |
| 3207 | #define SSL_CB_EXIT 0x02 |
| 3208 | #define SSL_CB_READ 0x04 |
| 3209 | #define SSL_CB_WRITE 0x08 |
| 3210 | #define SSL_CB_ALERT 0x4000 |
| 3211 | #define SSL_CB_READ_ALERT (SSL_CB_ALERT | SSL_CB_READ) |
| 3212 | #define SSL_CB_WRITE_ALERT (SSL_CB_ALERT | SSL_CB_WRITE) |
| 3213 | #define SSL_CB_ACCEPT_LOOP (SSL_ST_ACCEPT | SSL_CB_LOOP) |
| 3214 | #define SSL_CB_ACCEPT_EXIT (SSL_ST_ACCEPT | SSL_CB_EXIT) |
| 3215 | #define SSL_CB_CONNECT_LOOP (SSL_ST_CONNECT | SSL_CB_LOOP) |
| 3216 | #define SSL_CB_CONNECT_EXIT (SSL_ST_CONNECT | SSL_CB_EXIT) |
| 3217 | #define SSL_CB_HANDSHAKE_START 0x10 |
| 3218 | #define SSL_CB_HANDSHAKE_DONE 0x20 |
| 3219 | |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3220 | /* SSL_CTX_set_info_callback configures a callback to be run when various |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 3221 | * events occur during a connection's lifetime. The |type| argument determines |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3222 | * the type of event and the meaning of the |value| argument. Callbacks must |
| 3223 | * ignore unexpected |type| values. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3224 | * |
| 3225 | * |SSL_CB_READ_ALERT| is signaled for each alert received, warning or fatal. |
| 3226 | * The |value| argument is a 16-bit value where the alert level (either |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 3227 | * |SSL3_AL_WARNING| or |SSL3_AL_FATAL|) is in the most-significant eight bits |
| 3228 | * and the alert type (one of |SSL_AD_*|) is in the least-significant eight. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3229 | * |
| 3230 | * |SSL_CB_WRITE_ALERT| is signaled for each alert sent. The |value| argument |
| 3231 | * is constructed as with |SSL_CB_READ_ALERT|. |
| 3232 | * |
| 3233 | * |SSL_CB_HANDSHAKE_START| is signaled when a handshake begins. The |value| |
| 3234 | * argument is always one. |
| 3235 | * |
| 3236 | * |SSL_CB_HANDSHAKE_DONE| is signaled when a handshake completes successfully. |
| 3237 | * The |value| argument is always one. If a handshake False Starts, this event |
| 3238 | * may be used to determine when the Finished message is received. |
| 3239 | * |
| 3240 | * The following event types expose implementation details of the handshake |
| 3241 | * state machine. Consuming them is deprecated. |
| 3242 | * |
| 3243 | * |SSL_CB_ACCEPT_LOOP| (respectively, |SSL_CB_CONNECT_LOOP|) is signaled when |
| 3244 | * a server (respectively, client) handshake progresses. The |value| argument |
Robert Sloan | a94fe05 | 2017-02-21 08:49:28 -0800 | [diff] [blame] | 3245 | * is always one. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3246 | * |
| 3247 | * |SSL_CB_ACCEPT_EXIT| (respectively, |SSL_CB_CONNECT_EXIT|) is signaled when |
| 3248 | * a server (respectively, client) handshake completes, fails, or is paused. |
| 3249 | * The |value| argument is one if the handshake succeeded and <= 0 |
| 3250 | * otherwise. */ |
| 3251 | OPENSSL_EXPORT void SSL_CTX_set_info_callback( |
| 3252 | SSL_CTX *ctx, void (*cb)(const SSL *ssl, int type, int value)); |
| 3253 | |
| 3254 | /* SSL_CTX_get_info_callback returns the callback set by |
| 3255 | * |SSL_CTX_set_info_callback|. */ |
| 3256 | OPENSSL_EXPORT void (*SSL_CTX_get_info_callback(SSL_CTX *ctx))(const SSL *ssl, |
| 3257 | int type, |
| 3258 | int value); |
| 3259 | |
| 3260 | /* SSL_set_info_callback configures a callback to be run at various events |
| 3261 | * during a connection's lifetime. See |SSL_CTX_set_info_callback|. */ |
| 3262 | OPENSSL_EXPORT void SSL_set_info_callback( |
| 3263 | SSL *ssl, void (*cb)(const SSL *ssl, int type, int value)); |
| 3264 | |
| 3265 | /* SSL_get_info_callback returns the callback set by |SSL_set_info_callback|. */ |
| 3266 | OPENSSL_EXPORT void (*SSL_get_info_callback(const SSL *ssl))(const SSL *ssl, |
| 3267 | int type, |
| 3268 | int value); |
| 3269 | |
| 3270 | /* SSL_state_string_long returns the current state of the handshake state |
| 3271 | * machine as a string. This may be useful for debugging and logging. */ |
| 3272 | OPENSSL_EXPORT const char *SSL_state_string_long(const SSL *ssl); |
| 3273 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3274 | #define SSL_SENT_SHUTDOWN 1 |
| 3275 | #define SSL_RECEIVED_SHUTDOWN 2 |
| 3276 | |
| 3277 | /* SSL_get_shutdown returns a bitmask with a subset of |SSL_SENT_SHUTDOWN| and |
| 3278 | * |SSL_RECEIVED_SHUTDOWN| to query whether close_notify was sent or received, |
| 3279 | * respectively. */ |
| 3280 | OPENSSL_EXPORT int SSL_get_shutdown(const SSL *ssl); |
| 3281 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3282 | /* SSL_get_peer_signature_algorithm returns the signature algorithm used by the |
| 3283 | * peer. If not applicable, it returns zero. */ |
| 3284 | OPENSSL_EXPORT uint16_t SSL_get_peer_signature_algorithm(const SSL *ssl); |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3285 | |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 3286 | /* SSL_get_client_random writes up to |max_out| bytes of the most recent |
| 3287 | * handshake's client_random to |out| and returns the number of bytes written. |
| 3288 | * If |max_out| is zero, it returns the size of the client_random. */ |
| 3289 | OPENSSL_EXPORT size_t SSL_get_client_random(const SSL *ssl, uint8_t *out, |
| 3290 | size_t max_out); |
| 3291 | |
| 3292 | /* SSL_get_server_random writes up to |max_out| bytes of the most recent |
| 3293 | * handshake's server_random to |out| and returns the number of bytes written. |
| 3294 | * If |max_out| is zero, it returns the size of the server_random. */ |
| 3295 | OPENSSL_EXPORT size_t SSL_get_server_random(const SSL *ssl, uint8_t *out, |
| 3296 | size_t max_out); |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 3297 | |
| 3298 | /* SSL_get_pending_cipher returns the cipher suite for the current handshake or |
| 3299 | * NULL if one has not been negotiated yet or there is no pending handshake. */ |
| 3300 | OPENSSL_EXPORT const SSL_CIPHER *SSL_get_pending_cipher(const SSL *ssl); |
| 3301 | |
Steven Valdez | 909b19f | 2016-11-21 15:35:44 -0500 | [diff] [blame] | 3302 | /* SSL_set_retain_only_sha256_of_client_certs, on a server, sets whether only |
| 3303 | * the SHA-256 hash of peer's certificate should be saved in memory and in the |
| 3304 | * session. This can save memory, ticket size and session cache space. If |
| 3305 | * enabled, |SSL_get_peer_certificate| will return NULL after the handshake |
| 3306 | * completes. See the |peer_sha256| field of |SSL_SESSION| for the hash. */ |
| 3307 | OPENSSL_EXPORT void SSL_set_retain_only_sha256_of_client_certs(SSL *ssl, |
| 3308 | int enable); |
| 3309 | |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 3310 | /* SSL_CTX_set_retain_only_sha256_of_client_certs, on a server, sets whether |
| 3311 | * only the SHA-256 hash of peer's certificate should be saved in memory and in |
| 3312 | * the session. This can save memory, ticket size and session cache space. If |
| 3313 | * enabled, |SSL_get_peer_certificate| will return NULL after the handshake |
| 3314 | * completes. See the |peer_sha256| field of |SSL_SESSION| for the hash. */ |
| 3315 | OPENSSL_EXPORT void SSL_CTX_set_retain_only_sha256_of_client_certs(SSL_CTX *ctx, |
| 3316 | int enable); |
| 3317 | |
David Benjamin | 95add82 | 2016-10-19 01:09:12 -0400 | [diff] [blame] | 3318 | /* SSL_CTX_set_grease_enabled configures whether sockets on |ctx| should enable |
| 3319 | * GREASE. See draft-davidben-tls-grease-01. */ |
Steven Valdez | bb1ceac | 2016-10-07 10:34:51 -0400 | [diff] [blame] | 3320 | OPENSSL_EXPORT void SSL_CTX_set_grease_enabled(SSL_CTX *ctx, int enabled); |
| 3321 | |
Steven Valdez | 909b19f | 2016-11-21 15:35:44 -0500 | [diff] [blame] | 3322 | /* SSL_max_seal_overhead returns the maximum overhead, in bytes, of sealing a |
| 3323 | * record with |ssl|. */ |
| 3324 | OPENSSL_EXPORT size_t SSL_max_seal_overhead(const SSL *ssl); |
| 3325 | |
Robert Sloan | 1c9db53 | 2017-03-13 08:03:59 -0700 | [diff] [blame] | 3326 | /* SSL_get_ticket_age_skew returns the difference, in seconds, between the |
| 3327 | * client-sent ticket age and the server-computed value in TLS 1.3 server |
| 3328 | * connections which resumed a session. */ |
| 3329 | OPENSSL_EXPORT int32_t SSL_get_ticket_age_skew(const SSL *ssl); |
| 3330 | |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3331 | |
| 3332 | /* Deprecated functions. */ |
| 3333 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3334 | /* SSL_library_init calls |CRYPTO_library_init| and returns one. */ |
| 3335 | OPENSSL_EXPORT int SSL_library_init(void); |
| 3336 | |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3337 | /* SSL_CIPHER_description writes a description of |cipher| into |buf| and |
| 3338 | * returns |buf|. If |buf| is NULL, it returns a newly allocated string, to be |
| 3339 | * freed with |OPENSSL_free|, or NULL on error. |
| 3340 | * |
| 3341 | * The description includes a trailing newline and has the form: |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 3342 | * AES128-SHA Kx=RSA Au=RSA Enc=AES(128) Mac=SHA1 |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3343 | * |
| 3344 | * Consider |SSL_CIPHER_get_name| or |SSL_CIPHER_get_rfc_name| instead. */ |
| 3345 | OPENSSL_EXPORT const char *SSL_CIPHER_description(const SSL_CIPHER *cipher, |
| 3346 | char *buf, int len); |
| 3347 | |
| 3348 | /* SSL_CIPHER_get_version returns the string "TLSv1/SSLv3". */ |
| 3349 | OPENSSL_EXPORT const char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher); |
| 3350 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3351 | typedef void COMP_METHOD; |
| 3352 | |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3353 | /* SSL_COMP_get_compression_methods returns NULL. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3354 | OPENSSL_EXPORT COMP_METHOD *SSL_COMP_get_compression_methods(void); |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3355 | |
| 3356 | /* SSL_COMP_add_compression_method returns one. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3357 | OPENSSL_EXPORT int SSL_COMP_add_compression_method(int id, COMP_METHOD *cm); |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3358 | |
| 3359 | /* SSL_COMP_get_name returns NULL. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3360 | OPENSSL_EXPORT const char *SSL_COMP_get_name(const COMP_METHOD *comp); |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3361 | |
Steven Valdez | bb1ceac | 2016-10-07 10:34:51 -0400 | [diff] [blame] | 3362 | /* SSL_COMP_free_compression_methods does nothing. */ |
| 3363 | OPENSSL_EXPORT void SSL_COMP_free_compression_methods(void); |
| 3364 | |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3365 | /* SSLv23_method calls |TLS_method|. */ |
| 3366 | OPENSSL_EXPORT const SSL_METHOD *SSLv23_method(void); |
| 3367 | |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3368 | /* These version-specific methods behave exactly like |TLS_method| and |
David Benjamin | 7c0d06c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3369 | * |DTLS_method| except they also call |SSL_CTX_set_min_proto_version| and |
| 3370 | * |SSL_CTX_set_max_proto_version| to lock connections to that protocol |
| 3371 | * version. */ |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3372 | OPENSSL_EXPORT const SSL_METHOD *TLSv1_method(void); |
| 3373 | OPENSSL_EXPORT const SSL_METHOD *TLSv1_1_method(void); |
| 3374 | OPENSSL_EXPORT const SSL_METHOD *TLSv1_2_method(void); |
| 3375 | OPENSSL_EXPORT const SSL_METHOD *DTLSv1_method(void); |
| 3376 | OPENSSL_EXPORT const SSL_METHOD *DTLSv1_2_method(void); |
| 3377 | |
Robert Sloan | 572a4e2 | 2017-04-17 10:52:19 -0700 | [diff] [blame] | 3378 | /* SSLv3_method returns an |SSL_METHOD| with no versions enabled. */ |
| 3379 | OPENSSL_EXPORT const SSL_METHOD *SSLv3_method(void); |
| 3380 | |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3381 | /* These client- and server-specific methods call their corresponding generic |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3382 | * methods. */ |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3383 | OPENSSL_EXPORT const SSL_METHOD *TLS_server_method(void); |
| 3384 | OPENSSL_EXPORT const SSL_METHOD *TLS_client_method(void); |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3385 | OPENSSL_EXPORT const SSL_METHOD *SSLv23_server_method(void); |
| 3386 | OPENSSL_EXPORT const SSL_METHOD *SSLv23_client_method(void); |
| 3387 | OPENSSL_EXPORT const SSL_METHOD *SSLv3_server_method(void); |
| 3388 | OPENSSL_EXPORT const SSL_METHOD *SSLv3_client_method(void); |
| 3389 | OPENSSL_EXPORT const SSL_METHOD *TLSv1_server_method(void); |
| 3390 | OPENSSL_EXPORT const SSL_METHOD *TLSv1_client_method(void); |
| 3391 | OPENSSL_EXPORT const SSL_METHOD *TLSv1_1_server_method(void); |
| 3392 | OPENSSL_EXPORT const SSL_METHOD *TLSv1_1_client_method(void); |
| 3393 | OPENSSL_EXPORT const SSL_METHOD *TLSv1_2_server_method(void); |
| 3394 | OPENSSL_EXPORT const SSL_METHOD *TLSv1_2_client_method(void); |
| 3395 | OPENSSL_EXPORT const SSL_METHOD *DTLS_server_method(void); |
| 3396 | OPENSSL_EXPORT const SSL_METHOD *DTLS_client_method(void); |
| 3397 | OPENSSL_EXPORT const SSL_METHOD *DTLSv1_server_method(void); |
| 3398 | OPENSSL_EXPORT const SSL_METHOD *DTLSv1_client_method(void); |
| 3399 | OPENSSL_EXPORT const SSL_METHOD *DTLSv1_2_server_method(void); |
| 3400 | OPENSSL_EXPORT const SSL_METHOD *DTLSv1_2_client_method(void); |
| 3401 | |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 3402 | /* SSL_clear resets |ssl| to allow another connection and returns one on success |
| 3403 | * or zero on failure. It returns most configuration state but releases memory |
| 3404 | * associated with the current connection. |
| 3405 | * |
| 3406 | * Free |ssl| and create a new one instead. */ |
| 3407 | OPENSSL_EXPORT int SSL_clear(SSL *ssl); |
| 3408 | |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 3409 | /* SSL_CTX_set_tmp_rsa_callback does nothing. */ |
| 3410 | OPENSSL_EXPORT void SSL_CTX_set_tmp_rsa_callback( |
| 3411 | SSL_CTX *ctx, RSA *(*cb)(SSL *ssl, int is_export, int keylength)); |
| 3412 | |
| 3413 | /* SSL_set_tmp_rsa_callback does nothing. */ |
| 3414 | OPENSSL_EXPORT void SSL_set_tmp_rsa_callback(SSL *ssl, |
| 3415 | RSA *(*cb)(SSL *ssl, int is_export, |
| 3416 | int keylength)); |
| 3417 | |
| 3418 | /* SSL_CTX_sess_connect returns zero. */ |
| 3419 | OPENSSL_EXPORT int SSL_CTX_sess_connect(const SSL_CTX *ctx); |
| 3420 | |
| 3421 | /* SSL_CTX_sess_connect_good returns zero. */ |
| 3422 | OPENSSL_EXPORT int SSL_CTX_sess_connect_good(const SSL_CTX *ctx); |
| 3423 | |
| 3424 | /* SSL_CTX_sess_connect_renegotiate returns zero. */ |
| 3425 | OPENSSL_EXPORT int SSL_CTX_sess_connect_renegotiate(const SSL_CTX *ctx); |
| 3426 | |
| 3427 | /* SSL_CTX_sess_accept returns zero. */ |
| 3428 | OPENSSL_EXPORT int SSL_CTX_sess_accept(const SSL_CTX *ctx); |
| 3429 | |
| 3430 | /* SSL_CTX_sess_accept_renegotiate returns zero. */ |
| 3431 | OPENSSL_EXPORT int SSL_CTX_sess_accept_renegotiate(const SSL_CTX *ctx); |
| 3432 | |
| 3433 | /* SSL_CTX_sess_accept_good returns zero. */ |
| 3434 | OPENSSL_EXPORT int SSL_CTX_sess_accept_good(const SSL_CTX *ctx); |
| 3435 | |
| 3436 | /* SSL_CTX_sess_hits returns zero. */ |
| 3437 | OPENSSL_EXPORT int SSL_CTX_sess_hits(const SSL_CTX *ctx); |
| 3438 | |
| 3439 | /* SSL_CTX_sess_cb_hits returns zero. */ |
| 3440 | OPENSSL_EXPORT int SSL_CTX_sess_cb_hits(const SSL_CTX *ctx); |
| 3441 | |
| 3442 | /* SSL_CTX_sess_misses returns zero. */ |
| 3443 | OPENSSL_EXPORT int SSL_CTX_sess_misses(const SSL_CTX *ctx); |
| 3444 | |
| 3445 | /* SSL_CTX_sess_timeouts returns zero. */ |
| 3446 | OPENSSL_EXPORT int SSL_CTX_sess_timeouts(const SSL_CTX *ctx); |
| 3447 | |
| 3448 | /* SSL_CTX_sess_cache_full returns zero. */ |
| 3449 | OPENSSL_EXPORT int SSL_CTX_sess_cache_full(const SSL_CTX *ctx); |
| 3450 | |
| 3451 | /* SSL_cutthrough_complete calls |SSL_in_false_start|. */ |
| 3452 | OPENSSL_EXPORT int SSL_cutthrough_complete(const SSL *s); |
| 3453 | |
| 3454 | /* SSL_num_renegotiations calls |SSL_total_renegotiations|. */ |
| 3455 | OPENSSL_EXPORT int SSL_num_renegotiations(const SSL *ssl); |
| 3456 | |
| 3457 | /* SSL_CTX_need_tmp_RSA returns zero. */ |
| 3458 | OPENSSL_EXPORT int SSL_CTX_need_tmp_RSA(const SSL_CTX *ctx); |
| 3459 | |
| 3460 | /* SSL_need_tmp_RSA returns zero. */ |
| 3461 | OPENSSL_EXPORT int SSL_need_tmp_RSA(const SSL *ssl); |
| 3462 | |
| 3463 | /* SSL_CTX_set_tmp_rsa returns one. */ |
| 3464 | OPENSSL_EXPORT int SSL_CTX_set_tmp_rsa(SSL_CTX *ctx, const RSA *rsa); |
| 3465 | |
| 3466 | /* SSL_set_tmp_rsa returns one. */ |
| 3467 | OPENSSL_EXPORT int SSL_set_tmp_rsa(SSL *ssl, const RSA *rsa); |
| 3468 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3469 | /* SSL_CTX_get_read_ahead returns zero. */ |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 3470 | OPENSSL_EXPORT int SSL_CTX_get_read_ahead(const SSL_CTX *ctx); |
| 3471 | |
| 3472 | /* SSL_CTX_set_read_ahead does nothing. */ |
| 3473 | OPENSSL_EXPORT void SSL_CTX_set_read_ahead(SSL_CTX *ctx, int yes); |
| 3474 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3475 | /* SSL_get_read_ahead returns zero. */ |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 3476 | OPENSSL_EXPORT int SSL_get_read_ahead(const SSL *s); |
| 3477 | |
| 3478 | /* SSL_set_read_ahead does nothing. */ |
| 3479 | OPENSSL_EXPORT void SSL_set_read_ahead(SSL *s, int yes); |
| 3480 | |
| 3481 | /* SSL_renegotiate put an error on the error queue and returns zero. */ |
| 3482 | OPENSSL_EXPORT int SSL_renegotiate(SSL *ssl); |
| 3483 | |
| 3484 | /* SSL_set_state does nothing. */ |
| 3485 | OPENSSL_EXPORT void SSL_set_state(SSL *ssl, int state); |
| 3486 | |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 3487 | /* SSL_get_shared_ciphers writes an empty string to |buf| and returns a |
| 3488 | * pointer to |buf|, or NULL if |len| is less than or equal to zero. */ |
| 3489 | OPENSSL_EXPORT char *SSL_get_shared_ciphers(const SSL *ssl, char *buf, int len); |
| 3490 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3491 | /* SSL_MODE_HANDSHAKE_CUTTHROUGH is the same as SSL_MODE_ENABLE_FALSE_START. */ |
| 3492 | #define SSL_MODE_HANDSHAKE_CUTTHROUGH SSL_MODE_ENABLE_FALSE_START |
| 3493 | |
| 3494 | /* i2d_SSL_SESSION serializes |in| to the bytes pointed to by |*pp|. On success, |
| 3495 | * it returns the number of bytes written and advances |*pp| by that many bytes. |
| 3496 | * On failure, it returns -1. If |pp| is NULL, no bytes are written and only the |
| 3497 | * length is returned. |
| 3498 | * |
| 3499 | * Use |SSL_SESSION_to_bytes| instead. */ |
| 3500 | OPENSSL_EXPORT int i2d_SSL_SESSION(SSL_SESSION *in, uint8_t **pp); |
| 3501 | |
| 3502 | /* d2i_SSL_SESSION parses a serialized session from the |length| bytes pointed |
| 3503 | * to by |*pp|. It returns the new |SSL_SESSION| and advances |*pp| by the |
| 3504 | * number of bytes consumed on success and NULL on failure. The caller takes |
| 3505 | * ownership of the new session and must call |SSL_SESSION_free| when done. |
| 3506 | * |
| 3507 | * If |a| is non-NULL, |*a| is released and set the new |SSL_SESSION|. |
| 3508 | * |
| 3509 | * Use |SSL_SESSION_from_bytes| instead. */ |
| 3510 | OPENSSL_EXPORT SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a, const uint8_t **pp, |
| 3511 | long length); |
| 3512 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3513 | /* i2d_SSL_SESSION_bio serializes |session| and writes the result to |bio|. It |
| 3514 | * returns the number of bytes written on success and <= 0 on error. */ |
| 3515 | OPENSSL_EXPORT int i2d_SSL_SESSION_bio(BIO *bio, const SSL_SESSION *session); |
| 3516 | |
| 3517 | /* d2i_SSL_SESSION_bio reads a serialized |SSL_SESSION| from |bio| and returns a |
| 3518 | * newly-allocated |SSL_SESSION| or NULL on error. If |out| is not NULL, it also |
| 3519 | * frees |*out| and sets |*out| to the new |SSL_SESSION|. */ |
| 3520 | OPENSSL_EXPORT SSL_SESSION *d2i_SSL_SESSION_bio(BIO *bio, SSL_SESSION **out); |
| 3521 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3522 | /* ERR_load_SSL_strings does nothing. */ |
| 3523 | OPENSSL_EXPORT void ERR_load_SSL_strings(void); |
| 3524 | |
| 3525 | /* SSL_load_error_strings does nothing. */ |
| 3526 | OPENSSL_EXPORT void SSL_load_error_strings(void); |
| 3527 | |
| 3528 | /* SSL_CTX_set_tlsext_use_srtp calls |SSL_CTX_set_srtp_profiles|. It returns |
| 3529 | * zero on success and one on failure. |
| 3530 | * |
| 3531 | * WARNING: this function is dangerous because it breaks the usual return value |
| 3532 | * convention. Use |SSL_CTX_set_srtp_profiles| instead. */ |
| 3533 | OPENSSL_EXPORT int SSL_CTX_set_tlsext_use_srtp(SSL_CTX *ctx, |
| 3534 | const char *profiles); |
| 3535 | |
| 3536 | /* SSL_set_tlsext_use_srtp calls |SSL_set_srtp_profiles|. It returns zero on |
| 3537 | * success and one on failure. |
| 3538 | * |
| 3539 | * WARNING: this function is dangerous because it breaks the usual return value |
| 3540 | * convention. Use |SSL_set_srtp_profiles| instead. */ |
| 3541 | OPENSSL_EXPORT int SSL_set_tlsext_use_srtp(SSL *ssl, const char *profiles); |
| 3542 | |
| 3543 | /* SSL_get_current_compression returns NULL. */ |
| 3544 | OPENSSL_EXPORT const COMP_METHOD *SSL_get_current_compression(SSL *s); |
| 3545 | |
| 3546 | /* SSL_get_current_expansion returns NULL. */ |
| 3547 | OPENSSL_EXPORT const COMP_METHOD *SSL_get_current_expansion(SSL *s); |
| 3548 | |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 3549 | /* SSL_get_server_tmp_key returns zero. */ |
| 3550 | OPENSSL_EXPORT int *SSL_get_server_tmp_key(SSL *ssl, EVP_PKEY **out_key); |
| 3551 | |
Robert Sloan | 572a4e2 | 2017-04-17 10:52:19 -0700 | [diff] [blame] | 3552 | /* SSL_CTX_set_tmp_dh returns 1. */ |
| 3553 | OPENSSL_EXPORT int SSL_CTX_set_tmp_dh(SSL_CTX *ctx, const DH *dh); |
| 3554 | |
| 3555 | /* SSL_set_tmp_dh returns 1. */ |
| 3556 | OPENSSL_EXPORT int SSL_set_tmp_dh(SSL *ssl, const DH *dh); |
| 3557 | |
| 3558 | /* SSL_CTX_set_tmp_dh_callback does nothing. */ |
| 3559 | OPENSSL_EXPORT void SSL_CTX_set_tmp_dh_callback( |
| 3560 | SSL_CTX *ctx, DH *(*callback)(SSL *ssl, int is_export, int keylength)); |
| 3561 | |
| 3562 | /* SSL_set_tmp_dh_callback does nothing. */ |
| 3563 | OPENSSL_EXPORT void SSL_set_tmp_dh_callback(SSL *ssl, |
| 3564 | DH *(*dh)(SSL *ssl, int is_export, |
| 3565 | int keylength)); |
| 3566 | |
| 3567 | |
David Benjamin | 95add82 | 2016-10-19 01:09:12 -0400 | [diff] [blame] | 3568 | #define SSL_set_app_data(s, arg) (SSL_set_ex_data(s, 0, (char *)(arg))) |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3569 | #define SSL_get_app_data(s) (SSL_get_ex_data(s, 0)) |
| 3570 | #define SSL_SESSION_set_app_data(s, a) \ |
David Benjamin | 95add82 | 2016-10-19 01:09:12 -0400 | [diff] [blame] | 3571 | (SSL_SESSION_set_ex_data(s, 0, (char *)(a))) |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3572 | #define SSL_SESSION_get_app_data(s) (SSL_SESSION_get_ex_data(s, 0)) |
| 3573 | #define SSL_CTX_get_app_data(ctx) (SSL_CTX_get_ex_data(ctx, 0)) |
| 3574 | #define SSL_CTX_set_app_data(ctx, arg) \ |
David Benjamin | 95add82 | 2016-10-19 01:09:12 -0400 | [diff] [blame] | 3575 | (SSL_CTX_set_ex_data(ctx, 0, (char *)(arg))) |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3576 | |
| 3577 | #define OpenSSL_add_ssl_algorithms() SSL_library_init() |
| 3578 | #define SSLeay_add_ssl_algorithms() SSL_library_init() |
| 3579 | |
| 3580 | #define SSL_get_cipher(ssl) SSL_CIPHER_get_name(SSL_get_current_cipher(ssl)) |
| 3581 | #define SSL_get_cipher_bits(ssl, out_alg_bits) \ |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3582 | SSL_CIPHER_get_bits(SSL_get_current_cipher(ssl), out_alg_bits) |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3583 | #define SSL_get_cipher_version(ssl) \ |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3584 | SSL_CIPHER_get_version(SSL_get_current_cipher(ssl)) |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3585 | #define SSL_get_cipher_name(ssl) \ |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3586 | SSL_CIPHER_get_name(SSL_get_current_cipher(ssl)) |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3587 | #define SSL_get_time(session) SSL_SESSION_get_time(session) |
| 3588 | #define SSL_set_time(session, time) SSL_SESSION_set_time((session), (time)) |
| 3589 | #define SSL_get_timeout(session) SSL_SESSION_get_timeout(session) |
| 3590 | #define SSL_set_timeout(session, timeout) \ |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3591 | SSL_SESSION_set_timeout((session), (timeout)) |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3592 | |
| 3593 | typedef struct ssl_comp_st SSL_COMP; |
| 3594 | |
| 3595 | struct ssl_comp_st { |
| 3596 | int id; |
| 3597 | const char *name; |
| 3598 | char *method; |
| 3599 | }; |
| 3600 | |
| 3601 | DECLARE_STACK_OF(SSL_COMP) |
| 3602 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3603 | /* The following flags do nothing and are included only to make it easier to |
| 3604 | * compile code with BoringSSL. */ |
| 3605 | #define SSL_MODE_AUTO_RETRY 0 |
| 3606 | #define SSL_MODE_RELEASE_BUFFERS 0 |
| 3607 | #define SSL_MODE_SEND_CLIENTHELLO_TIME 0 |
| 3608 | #define SSL_MODE_SEND_SERVERHELLO_TIME 0 |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 3609 | #define SSL_OP_ALL 0 |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3610 | #define SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION 0 |
| 3611 | #define SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS 0 |
| 3612 | #define SSL_OP_EPHEMERAL_RSA 0 |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 3613 | #define SSL_OP_LEGACY_SERVER_CONNECT 0 |
| 3614 | #define SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER 0 |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3615 | #define SSL_OP_MICROSOFT_SESS_ID_BUG 0 |
| 3616 | #define SSL_OP_MSIE_SSLV2_RSA_PADDING 0 |
| 3617 | #define SSL_OP_NETSCAPE_CA_DN_BUG 0 |
| 3618 | #define SSL_OP_NETSCAPE_CHALLENGE_BUG 0 |
| 3619 | #define SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG 0 |
| 3620 | #define SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG 0 |
| 3621 | #define SSL_OP_NO_COMPRESSION 0 |
| 3622 | #define SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION 0 |
| 3623 | #define SSL_OP_NO_SSLv2 0 |
| 3624 | #define SSL_OP_PKCS1_CHECK_1 0 |
| 3625 | #define SSL_OP_PKCS1_CHECK_2 0 |
| 3626 | #define SSL_OP_SINGLE_DH_USE 0 |
| 3627 | #define SSL_OP_SINGLE_ECDH_USE 0 |
| 3628 | #define SSL_OP_SSLEAY_080_CLIENT_DH_BUG 0 |
| 3629 | #define SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG 0 |
| 3630 | #define SSL_OP_TLS_BLOCK_PADDING_BUG 0 |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 3631 | #define SSL_OP_TLS_D5_BUG 0 |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3632 | #define SSL_OP_TLS_ROLLBACK_BUG 0 |
| 3633 | #define SSL_VERIFY_CLIENT_ONCE 0 |
| 3634 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3635 | /* SSL_cache_hit calls |SSL_session_reused|. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3636 | OPENSSL_EXPORT int SSL_cache_hit(SSL *ssl); |
| 3637 | |
| 3638 | /* SSL_get_default_timeout returns |SSL_DEFAULT_SESSION_TIMEOUT|. */ |
| 3639 | OPENSSL_EXPORT long SSL_get_default_timeout(const SSL *ssl); |
| 3640 | |
| 3641 | /* SSL_get_version returns a string describing the TLS version used by |ssl|. |
| 3642 | * For example, "TLSv1.2" or "SSLv3". */ |
| 3643 | OPENSSL_EXPORT const char *SSL_get_version(const SSL *ssl); |
| 3644 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3645 | /* SSL_get_cipher_list returns the name of the |n|th cipher in the output of |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 3646 | * |SSL_get_ciphers| or NULL if out of range. Use |SSL_get_ciphers| instead. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3647 | OPENSSL_EXPORT const char *SSL_get_cipher_list(const SSL *ssl, int n); |
| 3648 | |
| 3649 | /* SSL_CTX_set_client_cert_cb sets a callback which is called on the client if |
| 3650 | * the server requests a client certificate and none is configured. On success, |
| 3651 | * the callback should return one and set |*out_x509| to |*out_pkey| to a leaf |
| 3652 | * certificate and private key, respectively, passing ownership. It should |
| 3653 | * return zero to send no certificate and -1 to fail or pause the handshake. If |
| 3654 | * the handshake is paused, |SSL_get_error| will return |
| 3655 | * |SSL_ERROR_WANT_X509_LOOKUP|. |
| 3656 | * |
| 3657 | * The callback may call |SSL_get0_certificate_types| and |
| 3658 | * |SSL_get_client_CA_list| for information on the server's certificate request. |
| 3659 | * |
| 3660 | * Use |SSL_CTX_set_cert_cb| instead. Configuring intermediate certificates with |
Steven Valdez | e7531f0 | 2016-12-14 13:29:57 -0500 | [diff] [blame] | 3661 | * this function is confusing. This callback may not be registered concurrently |
| 3662 | * with |SSL_CTX_set_cert_cb| or |SSL_set_cert_cb|. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3663 | OPENSSL_EXPORT void SSL_CTX_set_client_cert_cb( |
| 3664 | SSL_CTX *ctx, |
| 3665 | int (*client_cert_cb)(SSL *ssl, X509 **out_x509, EVP_PKEY **out_pkey)); |
| 3666 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3667 | #define SSL_NOTHING 1 |
| 3668 | #define SSL_WRITING 2 |
| 3669 | #define SSL_READING 3 |
| 3670 | #define SSL_X509_LOOKUP 4 |
| 3671 | #define SSL_CHANNEL_ID_LOOKUP 5 |
| 3672 | #define SSL_PENDING_SESSION 7 |
| 3673 | #define SSL_CERTIFICATE_SELECTION_PENDING 8 |
| 3674 | #define SSL_PRIVATE_KEY_OPERATION 9 |
Robert Sloan | 1c9db53 | 2017-03-13 08:03:59 -0700 | [diff] [blame] | 3675 | #define SSL_PENDING_TICKET 10 |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3676 | |
| 3677 | /* SSL_want returns one of the above values to determine what the most recent |
| 3678 | * operation on |ssl| was blocked on. Use |SSL_get_error| instead. */ |
| 3679 | OPENSSL_EXPORT int SSL_want(const SSL *ssl); |
| 3680 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3681 | #define SSL_want_read(ssl) (SSL_want(ssl) == SSL_READING) |
| 3682 | #define SSL_want_write(ssl) (SSL_want(ssl) == SSL_WRITING) |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3683 | |
| 3684 | /* SSL_get_finished writes up to |count| bytes of the Finished message sent by |
| 3685 | * |ssl| to |buf|. It returns the total untruncated length or zero if none has |
David Benjamin | 95add82 | 2016-10-19 01:09:12 -0400 | [diff] [blame] | 3686 | * been sent yet. At SSL 3.0 or TLS 1.3 and later, it returns zero. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3687 | * |
| 3688 | * Use |SSL_get_tls_unique| instead. */ |
| 3689 | OPENSSL_EXPORT size_t SSL_get_finished(const SSL *ssl, void *buf, size_t count); |
| 3690 | |
| 3691 | /* SSL_get_peer_finished writes up to |count| bytes of the Finished message |
| 3692 | * received from |ssl|'s peer to |buf|. It returns the total untruncated length |
David Benjamin | 95add82 | 2016-10-19 01:09:12 -0400 | [diff] [blame] | 3693 | * or zero if none has been received yet. At SSL 3.0 or TLS 1.3 and later, it |
| 3694 | * returns zero. |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3695 | * |
| 3696 | * Use |SSL_get_tls_unique| instead. */ |
| 3697 | OPENSSL_EXPORT size_t SSL_get_peer_finished(const SSL *ssl, void *buf, |
| 3698 | size_t count); |
| 3699 | |
| 3700 | /* SSL_alert_type_string returns "!". Use |SSL_alert_type_string_long| |
| 3701 | * instead. */ |
| 3702 | OPENSSL_EXPORT const char *SSL_alert_type_string(int value); |
| 3703 | |
| 3704 | /* SSL_alert_desc_string returns "!!". Use |SSL_alert_desc_string_long| |
| 3705 | * instead. */ |
| 3706 | OPENSSL_EXPORT const char *SSL_alert_desc_string(int value); |
| 3707 | |
| 3708 | /* SSL_TXT_* expand to strings. */ |
| 3709 | #define SSL_TXT_MEDIUM "MEDIUM" |
| 3710 | #define SSL_TXT_HIGH "HIGH" |
| 3711 | #define SSL_TXT_FIPS "FIPS" |
| 3712 | #define SSL_TXT_kRSA "kRSA" |
| 3713 | #define SSL_TXT_kDHE "kDHE" |
| 3714 | #define SSL_TXT_kEDH "kEDH" |
| 3715 | #define SSL_TXT_kECDHE "kECDHE" |
| 3716 | #define SSL_TXT_kEECDH "kEECDH" |
| 3717 | #define SSL_TXT_kPSK "kPSK" |
| 3718 | #define SSL_TXT_aRSA "aRSA" |
| 3719 | #define SSL_TXT_aECDSA "aECDSA" |
| 3720 | #define SSL_TXT_aPSK "aPSK" |
| 3721 | #define SSL_TXT_DH "DH" |
| 3722 | #define SSL_TXT_DHE "DHE" |
| 3723 | #define SSL_TXT_EDH "EDH" |
| 3724 | #define SSL_TXT_RSA "RSA" |
| 3725 | #define SSL_TXT_ECDH "ECDH" |
| 3726 | #define SSL_TXT_ECDHE "ECDHE" |
| 3727 | #define SSL_TXT_EECDH "EECDH" |
| 3728 | #define SSL_TXT_ECDSA "ECDSA" |
| 3729 | #define SSL_TXT_PSK "PSK" |
| 3730 | #define SSL_TXT_3DES "3DES" |
| 3731 | #define SSL_TXT_RC4 "RC4" |
| 3732 | #define SSL_TXT_AES128 "AES128" |
| 3733 | #define SSL_TXT_AES256 "AES256" |
| 3734 | #define SSL_TXT_AES "AES" |
| 3735 | #define SSL_TXT_AES_GCM "AESGCM" |
| 3736 | #define SSL_TXT_CHACHA20 "CHACHA20" |
| 3737 | #define SSL_TXT_MD5 "MD5" |
| 3738 | #define SSL_TXT_SHA1 "SHA1" |
| 3739 | #define SSL_TXT_SHA "SHA" |
| 3740 | #define SSL_TXT_SHA256 "SHA256" |
| 3741 | #define SSL_TXT_SHA384 "SHA384" |
| 3742 | #define SSL_TXT_SSLV3 "SSLv3" |
| 3743 | #define SSL_TXT_TLSV1 "TLSv1" |
| 3744 | #define SSL_TXT_TLSV1_1 "TLSv1.1" |
| 3745 | #define SSL_TXT_TLSV1_2 "TLSv1.2" |
David Benjamin | d316cba | 2016-06-02 16:17:39 -0400 | [diff] [blame] | 3746 | #define SSL_TXT_TLSV1_3 "TLSv1.3" |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3747 | #define SSL_TXT_ALL "ALL" |
| 3748 | #define SSL_TXT_CMPDEF "COMPLEMENTOFDEFAULT" |
| 3749 | |
| 3750 | typedef struct ssl_conf_ctx_st SSL_CONF_CTX; |
| 3751 | |
Robert Sloan | a94fe05 | 2017-02-21 08:49:28 -0800 | [diff] [blame] | 3752 | /* SSL_state returns |SSL_ST_INIT| if a handshake is in progress and |SSL_ST_OK| |
| 3753 | * otherwise. |
| 3754 | * |
| 3755 | * Use |SSL_is_init| instead. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3756 | OPENSSL_EXPORT int SSL_state(const SSL *ssl); |
| 3757 | |
| 3758 | #define SSL_get_state(ssl) SSL_state(ssl) |
| 3759 | |
| 3760 | /* SSL_state_string returns the current state of the handshake state machine as |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3761 | * a six-letter string. Use |SSL_state_string_long| for a more intelligible |
| 3762 | * string. */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3763 | OPENSSL_EXPORT const char *SSL_state_string(const SSL *ssl); |
| 3764 | |
| 3765 | /* SSL_set_shutdown causes |ssl| to behave as if the shutdown bitmask (see |
| 3766 | * |SSL_get_shutdown|) were |mode|. This may be used to skip sending or |
| 3767 | * receiving close_notify in |SSL_shutdown| by causing the implementation to |
| 3768 | * believe the events already happened. |
| 3769 | * |
| 3770 | * It is an error to use |SSL_set_shutdown| to unset a bit that has already been |
| 3771 | * set. Doing so will trigger an |assert| in debug builds and otherwise be |
| 3772 | * ignored. |
| 3773 | * |
| 3774 | * Use |SSL_CTX_set_quiet_shutdown| instead. */ |
| 3775 | OPENSSL_EXPORT void SSL_set_shutdown(SSL *ssl, int mode); |
| 3776 | |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 3777 | /* SSL_CTX_set_tmp_ecdh calls |SSL_CTX_set1_curves| with a one-element list |
| 3778 | * containing |ec_key|'s curve. */ |
| 3779 | OPENSSL_EXPORT int SSL_CTX_set_tmp_ecdh(SSL_CTX *ctx, const EC_KEY *ec_key); |
| 3780 | |
| 3781 | /* SSL_set_tmp_ecdh calls |SSL_set1_curves| with a one-element list containing |
| 3782 | * |ec_key|'s curve. */ |
| 3783 | OPENSSL_EXPORT int SSL_set_tmp_ecdh(SSL *ssl, const EC_KEY *ec_key); |
| 3784 | |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 3785 | /* SSL_add_dir_cert_subjects_to_stack lists files in directory |dir|. It calls |
| 3786 | * |SSL_add_file_cert_subjects_to_stack| on each file and returns one on success |
| 3787 | * or zero on error. This function is only available from the libdecrepit |
| 3788 | * library. */ |
| 3789 | OPENSSL_EXPORT int SSL_add_dir_cert_subjects_to_stack(STACK_OF(X509_NAME) *out, |
| 3790 | const char *dir); |
| 3791 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3792 | /* SSL_set_private_key_digest_prefs copies |num_digests| NIDs from |digest_nids| |
| 3793 | * into |ssl|. These digests will be used, in decreasing order of preference, |
| 3794 | * when signing with |ssl|'s private key. It returns one on success and zero on |
| 3795 | * error. |
| 3796 | * |
| 3797 | * Use |SSL_set_signing_algorithm_prefs| instead. |
| 3798 | * |
| 3799 | * TODO(davidben): Remove this API when callers have been updated. */ |
| 3800 | OPENSSL_EXPORT int SSL_set_private_key_digest_prefs(SSL *ssl, |
| 3801 | const int *digest_nids, |
| 3802 | size_t num_digests); |
| 3803 | |
David Benjamin | f0c4a6c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3804 | /* SSL_set_verify_result calls |abort| unless |result| is |X509_V_OK|. |
| 3805 | * |
| 3806 | * TODO(davidben): Remove this function once it has been removed from |
| 3807 | * netty-tcnative. */ |
| 3808 | OPENSSL_EXPORT void SSL_set_verify_result(SSL *ssl, long result); |
| 3809 | |
David Benjamin | 7c0d06c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3810 | /* SSL_CTX_set_min_version calls |SSL_CTX_set_min_proto_version|. */ |
| 3811 | OPENSSL_EXPORT int SSL_CTX_set_min_version(SSL_CTX *ctx, uint16_t version); |
| 3812 | |
| 3813 | /* SSL_CTX_set_max_version calls |SSL_CTX_set_max_proto_version|. */ |
| 3814 | OPENSSL_EXPORT int SSL_CTX_set_max_version(SSL_CTX *ctx, uint16_t version); |
| 3815 | |
| 3816 | /* SSL_set_min_version calls |SSL_set_min_proto_version|. */ |
| 3817 | OPENSSL_EXPORT int SSL_set_min_version(SSL *ssl, uint16_t version); |
| 3818 | |
| 3819 | /* SSL_set_max_version calls |SSL_set_max_proto_version|. */ |
| 3820 | OPENSSL_EXPORT int SSL_set_max_version(SSL *ssl, uint16_t version); |
| 3821 | |
David Benjamin | 1b24967 | 2016-12-06 18:25:50 -0500 | [diff] [blame] | 3822 | /* SSL_CTX_enable_tls_channel_id calls |SSL_CTX_set_tls_channel_id_enabled|. */ |
| 3823 | OPENSSL_EXPORT int SSL_CTX_enable_tls_channel_id(SSL_CTX *ctx); |
| 3824 | |
| 3825 | /* SSL_enable_tls_channel_id calls |SSL_set_tls_channel_id_enabled|. */ |
| 3826 | OPENSSL_EXPORT int SSL_enable_tls_channel_id(SSL *ssl); |
| 3827 | |
Steven Valdez | e7531f0 | 2016-12-14 13:29:57 -0500 | [diff] [blame] | 3828 | /* BIO_f_ssl returns a |BIO_METHOD| that can wrap an |SSL*| in a |BIO*|. Note |
| 3829 | * that this has quite different behaviour from the version in OpenSSL (notably |
Robert Sloan | 4d1ac50 | 2017-02-06 08:36:14 -0800 | [diff] [blame] | 3830 | * that it doesn't try to auto renegotiate). |
| 3831 | * |
| 3832 | * IMPORTANT: if you are not curl, don't use this. */ |
Steven Valdez | e7531f0 | 2016-12-14 13:29:57 -0500 | [diff] [blame] | 3833 | OPENSSL_EXPORT const BIO_METHOD *BIO_f_ssl(void); |
| 3834 | |
| 3835 | /* BIO_set_ssl sets |ssl| as the underlying connection for |bio|, which must |
| 3836 | * have been created using |BIO_f_ssl|. If |take_owership| is true, |bio| will |
| 3837 | * call |SSL_free| on |ssl| when closed. It returns one on success or something |
| 3838 | * other than one on error. */ |
| 3839 | OPENSSL_EXPORT long BIO_set_ssl(BIO *bio, SSL *ssl, int take_owership); |
| 3840 | |
Robert Sloan | 8ecb7cd | 2017-03-21 09:39:01 -0700 | [diff] [blame] | 3841 | /* SSL_CTX_set_ecdh_auto returns one. */ |
| 3842 | #define SSL_CTX_set_ecdh_auto(ctx, onoff) 1 |
| 3843 | |
| 3844 | /* SSL_set_ecdh_auto returns one. */ |
| 3845 | #define SSL_set_ecdh_auto(ssl, onoff) 1 |
| 3846 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3847 | |
| 3848 | /* Private structures. |
| 3849 | * |
| 3850 | * This structures are exposed for historical reasons, but access to them is |
| 3851 | * deprecated. */ |
| 3852 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3853 | typedef struct ssl_protocol_method_st SSL_PROTOCOL_METHOD; |
Robert Sloan | 5d62578 | 2017-02-13 09:55:39 -0800 | [diff] [blame] | 3854 | typedef struct ssl_x509_method_st SSL_X509_METHOD; |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3855 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3856 | struct ssl_cipher_st { |
| 3857 | /* name is the OpenSSL name for the cipher. */ |
| 3858 | const char *name; |
| 3859 | /* id is the cipher suite value bitwise OR-d with 0x03000000. */ |
| 3860 | uint32_t id; |
| 3861 | |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 3862 | /* algorithm_* are internal fields. See ssl/internal.h for their values. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3863 | uint32_t algorithm_mkey; |
| 3864 | uint32_t algorithm_auth; |
| 3865 | uint32_t algorithm_enc; |
| 3866 | uint32_t algorithm_mac; |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3867 | uint32_t algorithm_prf; |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3868 | }; |
| 3869 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 3870 | #define SSL_MAX_SSL_SESSION_ID_LENGTH 32 |
| 3871 | #define SSL_MAX_SID_CTX_LENGTH 32 |
| 3872 | #define SSL_MAX_MASTER_KEY_LENGTH 48 |
| 3873 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3874 | struct ssl_session_st { |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3875 | CRYPTO_refcount_t references; |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3876 | int ssl_version; /* what ssl version session info is being kept in here? */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3877 | |
Steven Valdez | e7531f0 | 2016-12-14 13:29:57 -0500 | [diff] [blame] | 3878 | /* group_id is the ID of the ECDH group used to establish this session or zero |
| 3879 | * if not applicable or unknown. */ |
| 3880 | uint16_t group_id; |
| 3881 | |
| 3882 | /* peer_signature_algorithm is the signature algorithm used to authenticate |
| 3883 | * the peer, or zero if not applicable or unknown. */ |
| 3884 | uint16_t peer_signature_algorithm; |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3885 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3886 | /* master_key, in TLS 1.2 and below, is the master secret associated with the |
| 3887 | * session. In TLS 1.3 and up, it is the resumption secret. */ |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3888 | int master_key_length; |
| 3889 | uint8_t master_key[SSL_MAX_MASTER_KEY_LENGTH]; |
| 3890 | |
| 3891 | /* session_id - valid? */ |
| 3892 | unsigned int session_id_length; |
| 3893 | uint8_t session_id[SSL_MAX_SSL_SESSION_ID_LENGTH]; |
| 3894 | /* this is used to determine whether the session is being reused in |
| 3895 | * the appropriate context. It is up to the application to set this, |
| 3896 | * via SSL_new */ |
David Benjamin | 1b24967 | 2016-12-06 18:25:50 -0500 | [diff] [blame] | 3897 | uint8_t sid_ctx_length; |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3898 | uint8_t sid_ctx[SSL_MAX_SID_CTX_LENGTH]; |
| 3899 | |
| 3900 | char *psk_identity; |
Steven Valdez | e7531f0 | 2016-12-14 13:29:57 -0500 | [diff] [blame] | 3901 | |
| 3902 | /* certs contains the certificate chain from the peer, starting with the leaf |
| 3903 | * certificate. */ |
| 3904 | STACK_OF(CRYPTO_BUFFER) *certs; |
| 3905 | |
Robert Sloan | 5d62578 | 2017-02-13 09:55:39 -0800 | [diff] [blame] | 3906 | const SSL_X509_METHOD *x509_method; |
| 3907 | |
Steven Valdez | 909b19f | 2016-11-21 15:35:44 -0500 | [diff] [blame] | 3908 | /* x509_peer is the peer's certificate. */ |
| 3909 | X509 *x509_peer; |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3910 | |
Steven Valdez | 909b19f | 2016-11-21 15:35:44 -0500 | [diff] [blame] | 3911 | /* x509_chain is the certificate chain sent by the peer. NOTE: for historical |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3912 | * reasons, when a client (so the peer is a server), the chain includes |
| 3913 | * |peer|, but when a server it does not. */ |
Steven Valdez | 909b19f | 2016-11-21 15:35:44 -0500 | [diff] [blame] | 3914 | STACK_OF(X509) *x509_chain; |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3915 | |
Steven Valdez | e7531f0 | 2016-12-14 13:29:57 -0500 | [diff] [blame] | 3916 | /* x509_chain_without_leaf is a lazily constructed copy of |x509_chain| that |
| 3917 | * omits the leaf certificate. This exists because OpenSSL, historically, |
| 3918 | * didn't include the leaf certificate in the chain for a server, but did for |
| 3919 | * a client. The |x509_chain| always includes it and, if an API call requires |
| 3920 | * a chain without, it is stored here. */ |
| 3921 | STACK_OF(X509) *x509_chain_without_leaf; |
| 3922 | |
David Benjamin | f0c4a6c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3923 | /* verify_result is the result of certificate verification in the case of |
| 3924 | * non-fatal certificate errors. */ |
| 3925 | long verify_result; |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3926 | |
Robert Sloan | 4d1ac50 | 2017-02-06 08:36:14 -0800 | [diff] [blame] | 3927 | /* timeout is the lifetime of the session in seconds, measured from |time|. |
| 3928 | * This is renewable up to |auth_timeout|. */ |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 3929 | uint32_t timeout; |
Steven Valdez | 909b19f | 2016-11-21 15:35:44 -0500 | [diff] [blame] | 3930 | |
Robert Sloan | 4d1ac50 | 2017-02-06 08:36:14 -0800 | [diff] [blame] | 3931 | /* auth_timeout is the non-renewable lifetime of the session in seconds, |
| 3932 | * measured from |time|. */ |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 3933 | uint32_t auth_timeout; |
Robert Sloan | 4d1ac50 | 2017-02-06 08:36:14 -0800 | [diff] [blame] | 3934 | |
Steven Valdez | 909b19f | 2016-11-21 15:35:44 -0500 | [diff] [blame] | 3935 | /* time is the time the session was issued, measured in seconds from the UNIX |
| 3936 | * epoch. */ |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 3937 | uint64_t time; |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3938 | |
| 3939 | const SSL_CIPHER *cipher; |
| 3940 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3941 | CRYPTO_EX_DATA ex_data; /* application specific data */ |
| 3942 | |
| 3943 | /* These are used to make removal of session-ids more efficient and to |
| 3944 | * implement a maximum cache size. */ |
| 3945 | SSL_SESSION *prev, *next; |
| 3946 | char *tlsext_hostname; |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3947 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3948 | /* RFC4507 info */ |
| 3949 | uint8_t *tlsext_tick; /* Session ticket */ |
| 3950 | size_t tlsext_ticklen; /* Session ticket length */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3951 | |
| 3952 | size_t tlsext_signed_cert_timestamp_list_length; |
| 3953 | uint8_t *tlsext_signed_cert_timestamp_list; /* Server's list. */ |
| 3954 | |
| 3955 | /* The OCSP response that came with the session. */ |
| 3956 | size_t ocsp_response_length; |
| 3957 | uint8_t *ocsp_response; |
| 3958 | |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3959 | /* peer_sha256 contains the SHA-256 hash of the peer's certificate if |
| 3960 | * |peer_sha256_valid| is true. */ |
| 3961 | uint8_t peer_sha256[SHA256_DIGEST_LENGTH]; |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3962 | |
| 3963 | /* original_handshake_hash contains the handshake hash (either SHA-1+MD5 or |
| 3964 | * SHA-2, depending on TLS version) for the original, full handshake that |
| 3965 | * created a session. This is used by Channel IDs during resumption. */ |
| 3966 | uint8_t original_handshake_hash[EVP_MAX_MD_SIZE]; |
David Benjamin | 1b24967 | 2016-12-06 18:25:50 -0500 | [diff] [blame] | 3967 | uint8_t original_handshake_hash_len; |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3968 | |
| 3969 | uint32_t tlsext_tick_lifetime_hint; /* Session lifetime hint in seconds */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3970 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3971 | uint32_t ticket_age_add; |
| 3972 | |
Robert Sloan | 69939df | 2017-01-09 10:53:07 -0800 | [diff] [blame] | 3973 | /* ticket_max_early_data is the maximum amount of data allowed to be sent as |
| 3974 | * early data. If zero, 0-RTT is disallowed. */ |
| 3975 | uint32_t ticket_max_early_data; |
| 3976 | |
Robert Sloan | a94fe05 | 2017-02-21 08:49:28 -0800 | [diff] [blame] | 3977 | /* early_alpn is the ALPN protocol from the initial handshake. This is only |
| 3978 | * stored for TLS 1.3 and above in order to enforce ALPN matching for 0-RTT |
| 3979 | * resumptions. */ |
| 3980 | uint8_t *early_alpn; |
| 3981 | size_t early_alpn_len; |
| 3982 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3983 | /* extended_master_secret is true if the master secret in this session was |
| 3984 | * generated using EMS and thus isn't vulnerable to the Triple Handshake |
| 3985 | * attack. */ |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3986 | unsigned extended_master_secret:1; |
| 3987 | |
| 3988 | /* peer_sha256_valid is non-zero if |peer_sha256| is valid. */ |
| 3989 | unsigned peer_sha256_valid:1; /* Non-zero if peer_sha256 is valid */ |
| 3990 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3991 | /* not_resumable is used to indicate that session resumption is disallowed. */ |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 3992 | unsigned not_resumable:1; |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 3993 | |
| 3994 | /* ticket_age_add_valid is non-zero if |ticket_age_add| is valid. */ |
| 3995 | unsigned ticket_age_add_valid:1; |
Steven Valdez | e7531f0 | 2016-12-14 13:29:57 -0500 | [diff] [blame] | 3996 | |
| 3997 | /* is_server is true if this session was created by a server. */ |
| 3998 | unsigned is_server:1; |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 3999 | }; |
| 4000 | |
| 4001 | /* ssl_cipher_preference_list_st contains a list of SSL_CIPHERs with |
| 4002 | * equal-preference groups. For TLS clients, the groups are moot because the |
| 4003 | * server picks the cipher and groups cannot be expressed on the wire. However, |
| 4004 | * for servers, the equal-preference groups allow the client's preferences to |
| 4005 | * be partially respected. (This only has an effect with |
| 4006 | * SSL_OP_CIPHER_SERVER_PREFERENCE). |
| 4007 | * |
| 4008 | * The equal-preference groups are expressed by grouping SSL_CIPHERs together. |
| 4009 | * All elements of a group have the same priority: no ordering is expressed |
| 4010 | * within a group. |
| 4011 | * |
| 4012 | * The values in |ciphers| are in one-to-one correspondence with |
| 4013 | * |in_group_flags|. (That is, sk_SSL_CIPHER_num(ciphers) is the number of |
| 4014 | * bytes in |in_group_flags|.) The bytes in |in_group_flags| are either 1, to |
| 4015 | * indicate that the corresponding SSL_CIPHER is not the last element of a |
| 4016 | * group, or 0 to indicate that it is. |
| 4017 | * |
| 4018 | * For example, if |in_group_flags| contains all zeros then that indicates a |
| 4019 | * traditional, fully-ordered preference. Every SSL_CIPHER is the last element |
| 4020 | * of the group (i.e. they are all in a one-element group). |
| 4021 | * |
| 4022 | * For a more complex example, consider: |
| 4023 | * ciphers: A B C D E F |
| 4024 | * in_group_flags: 1 1 0 0 1 0 |
| 4025 | * |
| 4026 | * That would express the following, order: |
| 4027 | * |
| 4028 | * A E |
| 4029 | * B -> D -> F |
| 4030 | * C |
| 4031 | */ |
| 4032 | struct ssl_cipher_preference_list_st { |
| 4033 | STACK_OF(SSL_CIPHER) *ciphers; |
| 4034 | uint8_t *in_group_flags; |
| 4035 | }; |
| 4036 | |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 4037 | /* ssl_ctx_st (aka |SSL_CTX|) contains configuration common to several SSL |
| 4038 | * connections. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4039 | struct ssl_ctx_st { |
| 4040 | const SSL_PROTOCOL_METHOD *method; |
Robert Sloan | 5d62578 | 2017-02-13 09:55:39 -0800 | [diff] [blame] | 4041 | const SSL_X509_METHOD *x509_method; |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4042 | |
| 4043 | /* lock is used to protect various operations on this object. */ |
| 4044 | CRYPTO_MUTEX lock; |
| 4045 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 4046 | /* max_version is the maximum acceptable protocol version. Note this version |
| 4047 | * is normalized in DTLS. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4048 | uint16_t max_version; |
| 4049 | |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 4050 | /* min_version is the minimum acceptable protocol version. Note this version |
| 4051 | * is normalized in DTLS. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4052 | uint16_t min_version; |
| 4053 | |
| 4054 | struct ssl_cipher_preference_list_st *cipher_list; |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4055 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4056 | X509_STORE *cert_store; |
| 4057 | LHASH_OF(SSL_SESSION) *sessions; |
| 4058 | /* Most session-ids that will be cached, default is |
| 4059 | * SSL_SESSION_CACHE_MAX_SIZE_DEFAULT. 0 is unlimited. */ |
| 4060 | unsigned long session_cache_size; |
| 4061 | SSL_SESSION *session_cache_head; |
| 4062 | SSL_SESSION *session_cache_tail; |
| 4063 | |
| 4064 | /* handshakes_since_cache_flush is the number of successful handshakes since |
| 4065 | * the last cache flush. */ |
| 4066 | int handshakes_since_cache_flush; |
| 4067 | |
| 4068 | /* This can have one of 2 values, ored together, |
| 4069 | * SSL_SESS_CACHE_CLIENT, |
| 4070 | * SSL_SESS_CACHE_SERVER, |
| 4071 | * Default is SSL_SESSION_CACHE_SERVER, which means only |
| 4072 | * SSL_accept which cache SSL_SESSIONS. */ |
| 4073 | int session_cache_mode; |
| 4074 | |
Robert Sloan | 4d1ac50 | 2017-02-06 08:36:14 -0800 | [diff] [blame] | 4075 | /* session_timeout is the default lifetime for new sessions in TLS 1.2 and |
| 4076 | * earlier, in seconds. */ |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 4077 | uint32_t session_timeout; |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4078 | |
Robert Sloan | 4d1ac50 | 2017-02-06 08:36:14 -0800 | [diff] [blame] | 4079 | /* session_psk_dhe_timeout is the default lifetime for new sessions in TLS |
| 4080 | * 1.3, in seconds. */ |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 4081 | uint32_t session_psk_dhe_timeout; |
Robert Sloan | 4d1ac50 | 2017-02-06 08:36:14 -0800 | [diff] [blame] | 4082 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4083 | /* If this callback is not null, it will be called each time a session id is |
| 4084 | * added to the cache. If this function returns 1, it means that the |
| 4085 | * callback will do a SSL_SESSION_free() when it has finished using it. |
| 4086 | * Otherwise, on 0, it means the callback has finished with it. If |
| 4087 | * remove_session_cb is not null, it will be called when a session-id is |
| 4088 | * removed from the cache. After the call, OpenSSL will SSL_SESSION_free() |
| 4089 | * it. */ |
| 4090 | int (*new_session_cb)(SSL *ssl, SSL_SESSION *sess); |
| 4091 | void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *sess); |
| 4092 | SSL_SESSION *(*get_session_cb)(SSL *ssl, uint8_t *data, int len, |
| 4093 | int *copy); |
| 4094 | |
| 4095 | CRYPTO_refcount_t references; |
| 4096 | |
| 4097 | /* if defined, these override the X509_verify_cert() calls */ |
| 4098 | int (*app_verify_callback)(X509_STORE_CTX *store_ctx, void *arg); |
| 4099 | void *app_verify_arg; |
| 4100 | |
| 4101 | /* Default password callback. */ |
| 4102 | pem_password_cb *default_passwd_callback; |
| 4103 | |
| 4104 | /* Default password callback user data. */ |
| 4105 | void *default_passwd_callback_userdata; |
| 4106 | |
| 4107 | /* get client cert callback */ |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 4108 | int (*client_cert_cb)(SSL *ssl, X509 **out_x509, EVP_PKEY **out_pkey); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4109 | |
| 4110 | /* get channel id callback */ |
| 4111 | void (*channel_id_cb)(SSL *ssl, EVP_PKEY **out_pkey); |
| 4112 | |
| 4113 | CRYPTO_EX_DATA ex_data; |
| 4114 | |
| 4115 | /* custom_*_extensions stores any callback sets for custom extensions. Note |
| 4116 | * that these pointers will be NULL if the stack would otherwise be empty. */ |
| 4117 | STACK_OF(SSL_CUSTOM_EXTENSION) *client_custom_extensions; |
| 4118 | STACK_OF(SSL_CUSTOM_EXTENSION) *server_custom_extensions; |
| 4119 | |
| 4120 | /* Default values used when no per-SSL value is defined follow */ |
| 4121 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 4122 | void (*info_callback)(const SSL *ssl, int type, int value); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4123 | |
| 4124 | /* what we put in client cert requests */ |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 4125 | STACK_OF(CRYPTO_BUFFER) *client_CA; |
| 4126 | |
| 4127 | /* cached_x509_client_CA is a cache of parsed versions of the elements of |
| 4128 | * |client_CA|. */ |
| 4129 | STACK_OF(X509_NAME) *cached_x509_client_CA; |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4130 | |
| 4131 | |
| 4132 | /* Default values to use in SSL structures follow (these are copied by |
| 4133 | * SSL_new) */ |
| 4134 | |
| 4135 | uint32_t options; |
| 4136 | uint32_t mode; |
| 4137 | uint32_t max_cert_list; |
| 4138 | |
| 4139 | struct cert_st /* CERT */ *cert; |
| 4140 | |
| 4141 | /* callback that allows applications to peek at protocol messages */ |
| 4142 | void (*msg_callback)(int write_p, int version, int content_type, |
| 4143 | const void *buf, size_t len, SSL *ssl, void *arg); |
| 4144 | void *msg_callback_arg; |
| 4145 | |
| 4146 | int verify_mode; |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4147 | int (*default_verify_callback)( |
| 4148 | int ok, X509_STORE_CTX *ctx); /* called 'verify_callback' in the SSL */ |
| 4149 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4150 | X509_VERIFY_PARAM *param; |
| 4151 | |
| 4152 | /* select_certificate_cb is called before most ClientHello processing and |
Robert Sloan | 6d0d00e | 2017-03-27 07:13:07 -0700 | [diff] [blame] | 4153 | * before the decision whether to resume a session is made. See |
| 4154 | * |ssl_select_cert_result_t| for details of the return values. */ |
| 4155 | enum ssl_select_cert_result_t (*select_certificate_cb)( |
| 4156 | const SSL_CLIENT_HELLO *); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4157 | |
| 4158 | /* dos_protection_cb is called once the resumption decision for a ClientHello |
| 4159 | * has been made. It returns one to continue the handshake or zero to |
| 4160 | * abort. */ |
David Benjamin | 1b24967 | 2016-12-06 18:25:50 -0500 | [diff] [blame] | 4161 | int (*dos_protection_cb) (const SSL_CLIENT_HELLO *); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4162 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4163 | /* Maximum amount of data to send in one fragment. actual record size can be |
| 4164 | * more than this due to padding and MAC overheads. */ |
| 4165 | uint16_t max_send_fragment; |
| 4166 | |
| 4167 | /* TLS extensions servername callback */ |
| 4168 | int (*tlsext_servername_callback)(SSL *, int *, void *); |
| 4169 | void *tlsext_servername_arg; |
| 4170 | /* RFC 4507 session ticket keys */ |
| 4171 | uint8_t tlsext_tick_key_name[SSL_TICKET_KEY_NAME_LEN]; |
| 4172 | uint8_t tlsext_tick_hmac_key[16]; |
| 4173 | uint8_t tlsext_tick_aes_key[16]; |
| 4174 | /* Callback to support customisation of ticket key setting */ |
| 4175 | int (*tlsext_ticket_key_cb)(SSL *ssl, uint8_t *name, uint8_t *iv, |
| 4176 | EVP_CIPHER_CTX *ectx, HMAC_CTX *hctx, int enc); |
| 4177 | |
| 4178 | /* Server-only: psk_identity_hint is the default identity hint to send in |
| 4179 | * PSK-based key exchanges. */ |
| 4180 | char *psk_identity_hint; |
| 4181 | |
| 4182 | unsigned int (*psk_client_callback)(SSL *ssl, const char *hint, |
| 4183 | char *identity, |
| 4184 | unsigned int max_identity_len, |
| 4185 | uint8_t *psk, unsigned int max_psk_len); |
| 4186 | unsigned int (*psk_server_callback)(SSL *ssl, const char *identity, |
| 4187 | uint8_t *psk, unsigned int max_psk_len); |
| 4188 | |
| 4189 | |
| 4190 | /* retain_only_sha256_of_client_certs is true if we should compute the SHA256 |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 4191 | * hash of the peer's certificate and then discard it to save memory and |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4192 | * session space. Only effective on the server side. */ |
| 4193 | char retain_only_sha256_of_client_certs; |
| 4194 | |
| 4195 | /* Next protocol negotiation information */ |
| 4196 | /* (for experimental NPN extension). */ |
| 4197 | |
| 4198 | /* For a server, this contains a callback function by which the set of |
| 4199 | * advertised protocols can be provided. */ |
| 4200 | int (*next_protos_advertised_cb)(SSL *ssl, const uint8_t **out, |
| 4201 | unsigned *out_len, void *arg); |
| 4202 | void *next_protos_advertised_cb_arg; |
| 4203 | /* For a client, this contains a callback function that selects the |
| 4204 | * next protocol from the list provided by the server. */ |
| 4205 | int (*next_proto_select_cb)(SSL *ssl, uint8_t **out, uint8_t *out_len, |
| 4206 | const uint8_t *in, unsigned in_len, void *arg); |
| 4207 | void *next_proto_select_cb_arg; |
| 4208 | |
| 4209 | /* ALPN information |
| 4210 | * (we are in the process of transitioning from NPN to ALPN.) */ |
| 4211 | |
| 4212 | /* For a server, this contains a callback function that allows the |
| 4213 | * server to select the protocol for the connection. |
| 4214 | * out: on successful return, this must point to the raw protocol |
| 4215 | * name (without the length prefix). |
| 4216 | * outlen: on successful return, this contains the length of |*out|. |
| 4217 | * in: points to the client's list of supported protocols in |
| 4218 | * wire-format. |
| 4219 | * inlen: the length of |in|. */ |
| 4220 | int (*alpn_select_cb)(SSL *s, const uint8_t **out, uint8_t *out_len, |
| 4221 | const uint8_t *in, unsigned in_len, void *arg); |
| 4222 | void *alpn_select_cb_arg; |
| 4223 | |
| 4224 | /* For a client, this contains the list of supported protocols in wire |
| 4225 | * format. */ |
| 4226 | uint8_t *alpn_client_proto_list; |
| 4227 | unsigned alpn_client_proto_list_len; |
| 4228 | |
| 4229 | /* SRTP profiles we are willing to do from RFC 5764 */ |
| 4230 | STACK_OF(SRTP_PROTECTION_PROFILE) *srtp_profiles; |
| 4231 | |
David Benjamin | d316cba | 2016-06-02 16:17:39 -0400 | [diff] [blame] | 4232 | /* Supported group values inherited by SSL structure */ |
| 4233 | size_t supported_group_list_len; |
| 4234 | uint16_t *supported_group_list; |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4235 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4236 | /* The client's Channel ID private key. */ |
| 4237 | EVP_PKEY *tlsext_channel_id_private; |
| 4238 | |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 4239 | /* keylog_callback, if not NULL, is the key logging callback. See |
| 4240 | * |SSL_CTX_set_keylog_callback|. */ |
| 4241 | void (*keylog_callback)(const SSL *ssl, const char *line); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4242 | |
| 4243 | /* current_time_cb, if not NULL, is the function to use to get the current |
David Benjamin | 6e899c7 | 2016-06-09 18:02:18 -0400 | [diff] [blame] | 4244 | * time. It sets |*out_clock| to the current time. See |
| 4245 | * |SSL_CTX_set_current_time_cb|. */ |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4246 | void (*current_time_cb)(const SSL *ssl, struct timeval *out_clock); |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 4247 | |
Steven Valdez | e7531f0 | 2016-12-14 13:29:57 -0500 | [diff] [blame] | 4248 | /* pool is used for all |CRYPTO_BUFFER|s in case we wish to share certificate |
| 4249 | * memory. */ |
| 4250 | CRYPTO_BUFFER_POOL *pool; |
| 4251 | |
Robert Sloan | 1c9db53 | 2017-03-13 08:03:59 -0700 | [diff] [blame] | 4252 | /* ticket_aead_method contains function pointers for opening and sealing |
| 4253 | * session tickets. */ |
| 4254 | const SSL_TICKET_AEAD_METHOD *ticket_aead_method; |
| 4255 | |
Robert Sloan | 572a4e2 | 2017-04-17 10:52:19 -0700 | [diff] [blame] | 4256 | /* verify_sigalgs, if not empty, is the set of signature algorithms |
| 4257 | * accepted from the peer in decreasing order of preference. */ |
| 4258 | uint16_t *verify_sigalgs; |
| 4259 | size_t num_verify_sigalgs; |
| 4260 | |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 4261 | /* quiet_shutdown is true if the connection should not send a close_notify on |
| 4262 | * shutdown. */ |
| 4263 | unsigned quiet_shutdown:1; |
| 4264 | |
| 4265 | /* ocsp_stapling_enabled is only used by client connections and indicates |
| 4266 | * whether OCSP stapling will be requested. */ |
| 4267 | unsigned ocsp_stapling_enabled:1; |
| 4268 | |
| 4269 | /* If true, a client will request certificate timestamps. */ |
| 4270 | unsigned signed_cert_timestamps_enabled:1; |
| 4271 | |
Steven Valdez | bb1ceac | 2016-10-07 10:34:51 -0400 | [diff] [blame] | 4272 | /* tlsext_channel_id_enabled is one if Channel ID is enabled and zero |
| 4273 | * otherwise. For a server, means that we'll accept Channel IDs from clients. |
| 4274 | * For a client, means that we'll advertise support. */ |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 4275 | unsigned tlsext_channel_id_enabled:1; |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 4276 | |
Steven Valdez | bb1ceac | 2016-10-07 10:34:51 -0400 | [diff] [blame] | 4277 | /* grease_enabled is one if draft-davidben-tls-grease-01 is enabled and zero |
| 4278 | * otherwise. */ |
| 4279 | unsigned grease_enabled:1; |
Robert Sloan | 1c9db53 | 2017-03-13 08:03:59 -0700 | [diff] [blame] | 4280 | |
| 4281 | /* i_promise_to_verify_certs_after_the_handshake indicates that the |
| 4282 | * application is using the |CRYPTO_BUFFER|-based methods and understands |
| 4283 | * that this currently requires post-handshake verification of |
| 4284 | * certificates. */ |
| 4285 | unsigned i_promise_to_verify_certs_after_the_handshake:1; |
Robert Sloan | 572a4e2 | 2017-04-17 10:52:19 -0700 | [diff] [blame] | 4286 | |
| 4287 | /* allow_unknown_alpn_protos is one if the client allows unsolicited ALPN |
| 4288 | * protocols from the peer. */ |
| 4289 | unsigned allow_unknown_alpn_protos:1; |
| 4290 | |
| 4291 | /* ed25519_enabled is one if Ed25519 is advertised in the handshake. */ |
| 4292 | unsigned ed25519_enabled:1; |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4293 | }; |
| 4294 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 4295 | |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 4296 | /* Nodejs compatibility section (hidden). |
| 4297 | * |
| 4298 | * These defines exist for node.js, with the hope that we can eliminate the |
| 4299 | * need for them over time. */ |
| 4300 | #define SSLerr(function, reason) \ |
| 4301 | ERR_put_error(ERR_LIB_SSL, 0, reason, __FILE__, __LINE__) |
| 4302 | |
| 4303 | |
Kenny Root | e99801b | 2015-11-06 15:31:15 -0800 | [diff] [blame] | 4304 | /* Preprocessor compatibility section (hidden). |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 4305 | * |
| 4306 | * Historically, a number of APIs were implemented in OpenSSL as macros and |
| 4307 | * constants to 'ctrl' functions. To avoid breaking #ifdefs in consumers, this |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4308 | * section defines a number of legacy macros. |
| 4309 | * |
| 4310 | * Although using either the CTRL values or their wrapper macros in #ifdefs is |
| 4311 | * still supported, the CTRL values may not be passed to |SSL_ctrl| and |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 4312 | * |SSL_CTX_ctrl|. Call the functions (previously wrapper macros) instead. |
| 4313 | * |
| 4314 | * See PORTING.md in the BoringSSL source tree for a table of corresponding |
| 4315 | * functions. |
| 4316 | * https://boringssl.googlesource.com/boringssl/+/master/PORTING.md#Replacements-for-values |
| 4317 | */ |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 4318 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4319 | #define DTLS_CTRL_GET_TIMEOUT doesnt_exist |
| 4320 | #define DTLS_CTRL_HANDLE_TIMEOUT doesnt_exist |
| 4321 | #define SSL_CTRL_CHAIN doesnt_exist |
| 4322 | #define SSL_CTRL_CHAIN_CERT doesnt_exist |
| 4323 | #define SSL_CTRL_CHANNEL_ID doesnt_exist |
| 4324 | #define SSL_CTRL_CLEAR_EXTRA_CHAIN_CERTS doesnt_exist |
| 4325 | #define SSL_CTRL_CLEAR_MODE doesnt_exist |
| 4326 | #define SSL_CTRL_CLEAR_OPTIONS doesnt_exist |
| 4327 | #define SSL_CTRL_EXTRA_CHAIN_CERT doesnt_exist |
| 4328 | #define SSL_CTRL_GET_CHAIN_CERTS doesnt_exist |
| 4329 | #define SSL_CTRL_GET_CHANNEL_ID doesnt_exist |
| 4330 | #define SSL_CTRL_GET_CLIENT_CERT_TYPES doesnt_exist |
| 4331 | #define SSL_CTRL_GET_EXTRA_CHAIN_CERTS doesnt_exist |
| 4332 | #define SSL_CTRL_GET_MAX_CERT_LIST doesnt_exist |
Kenny Root | a04d78d | 2015-09-25 00:26:37 +0000 | [diff] [blame] | 4333 | #define SSL_CTRL_GET_NUM_RENEGOTIATIONS doesnt_exist |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4334 | #define SSL_CTRL_GET_READ_AHEAD doesnt_exist |
| 4335 | #define SSL_CTRL_GET_RI_SUPPORT doesnt_exist |
| 4336 | #define SSL_CTRL_GET_SESSION_REUSED doesnt_exist |
| 4337 | #define SSL_CTRL_GET_SESS_CACHE_MODE doesnt_exist |
| 4338 | #define SSL_CTRL_GET_SESS_CACHE_SIZE doesnt_exist |
| 4339 | #define SSL_CTRL_GET_TLSEXT_TICKET_KEYS doesnt_exist |
Kenny Root | a04d78d | 2015-09-25 00:26:37 +0000 | [diff] [blame] | 4340 | #define SSL_CTRL_GET_TOTAL_RENEGOTIATIONS doesnt_exist |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4341 | #define SSL_CTRL_MODE doesnt_exist |
| 4342 | #define SSL_CTRL_NEED_TMP_RSA doesnt_exist |
| 4343 | #define SSL_CTRL_OPTIONS doesnt_exist |
| 4344 | #define SSL_CTRL_SESS_NUMBER doesnt_exist |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4345 | #define SSL_CTRL_SET_CURVES doesnt_exist |
Steven Valdez | bb1ceac | 2016-10-07 10:34:51 -0400 | [diff] [blame] | 4346 | #define SSL_CTRL_SET_CURVES_LIST doesnt_exist |
Robert Sloan | 8ecb7cd | 2017-03-21 09:39:01 -0700 | [diff] [blame] | 4347 | #define SSL_CTRL_SET_ECDH_AUTO doesnt_exist |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4348 | #define SSL_CTRL_SET_MAX_CERT_LIST doesnt_exist |
| 4349 | #define SSL_CTRL_SET_MAX_SEND_FRAGMENT doesnt_exist |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 4350 | #define SSL_CTRL_SET_MSG_CALLBACK doesnt_exist |
| 4351 | #define SSL_CTRL_SET_MSG_CALLBACK_ARG doesnt_exist |
| 4352 | #define SSL_CTRL_SET_MTU doesnt_exist |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 4353 | #define SSL_CTRL_SET_READ_AHEAD doesnt_exist |
Kenny Root | a04d78d | 2015-09-25 00:26:37 +0000 | [diff] [blame] | 4354 | #define SSL_CTRL_SET_SESS_CACHE_MODE doesnt_exist |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4355 | #define SSL_CTRL_SET_SESS_CACHE_SIZE doesnt_exist |
Kenny Root | a04d78d | 2015-09-25 00:26:37 +0000 | [diff] [blame] | 4356 | #define SSL_CTRL_SET_TLSEXT_HOSTNAME doesnt_exist |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4357 | #define SSL_CTRL_SET_TLSEXT_SERVERNAME_ARG doesnt_exist |
| 4358 | #define SSL_CTRL_SET_TLSEXT_SERVERNAME_CB doesnt_exist |
| 4359 | #define SSL_CTRL_SET_TLSEXT_TICKET_KEYS doesnt_exist |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 4360 | #define SSL_CTRL_SET_TLSEXT_TICKET_KEY_CB doesnt_exist |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4361 | #define SSL_CTRL_SET_TMP_DH doesnt_exist |
| 4362 | #define SSL_CTRL_SET_TMP_DH_CB doesnt_exist |
| 4363 | #define SSL_CTRL_SET_TMP_ECDH doesnt_exist |
| 4364 | #define SSL_CTRL_SET_TMP_ECDH_CB doesnt_exist |
| 4365 | #define SSL_CTRL_SET_TMP_RSA doesnt_exist |
| 4366 | #define SSL_CTRL_SET_TMP_RSA_CB doesnt_exist |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 4367 | |
Kenny Root | a04d78d | 2015-09-25 00:26:37 +0000 | [diff] [blame] | 4368 | #define DTLSv1_get_timeout DTLSv1_get_timeout |
| 4369 | #define DTLSv1_handle_timeout DTLSv1_handle_timeout |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4370 | #define SSL_CTX_add0_chain_cert SSL_CTX_add0_chain_cert |
| 4371 | #define SSL_CTX_add1_chain_cert SSL_CTX_add1_chain_cert |
| 4372 | #define SSL_CTX_add_extra_chain_cert SSL_CTX_add_extra_chain_cert |
| 4373 | #define SSL_CTX_clear_extra_chain_certs SSL_CTX_clear_extra_chain_certs |
| 4374 | #define SSL_CTX_clear_chain_certs SSL_CTX_clear_chain_certs |
| 4375 | #define SSL_CTX_clear_mode SSL_CTX_clear_mode |
| 4376 | #define SSL_CTX_clear_options SSL_CTX_clear_options |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4377 | #define SSL_CTX_get0_chain_certs SSL_CTX_get0_chain_certs |
| 4378 | #define SSL_CTX_get_extra_chain_certs SSL_CTX_get_extra_chain_certs |
| 4379 | #define SSL_CTX_get_max_cert_list SSL_CTX_get_max_cert_list |
| 4380 | #define SSL_CTX_get_mode SSL_CTX_get_mode |
| 4381 | #define SSL_CTX_get_options SSL_CTX_get_options |
| 4382 | #define SSL_CTX_get_read_ahead SSL_CTX_get_read_ahead |
| 4383 | #define SSL_CTX_get_session_cache_mode SSL_CTX_get_session_cache_mode |
| 4384 | #define SSL_CTX_get_tlsext_ticket_keys SSL_CTX_get_tlsext_ticket_keys |
| 4385 | #define SSL_CTX_need_tmp_RSA SSL_CTX_need_tmp_RSA |
| 4386 | #define SSL_CTX_sess_get_cache_size SSL_CTX_sess_get_cache_size |
| 4387 | #define SSL_CTX_sess_number SSL_CTX_sess_number |
| 4388 | #define SSL_CTX_sess_set_cache_size SSL_CTX_sess_set_cache_size |
| 4389 | #define SSL_CTX_set0_chain SSL_CTX_set0_chain |
| 4390 | #define SSL_CTX_set1_chain SSL_CTX_set1_chain |
| 4391 | #define SSL_CTX_set1_curves SSL_CTX_set1_curves |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4392 | #define SSL_CTX_set_max_cert_list SSL_CTX_set_max_cert_list |
| 4393 | #define SSL_CTX_set_max_send_fragment SSL_CTX_set_max_send_fragment |
| 4394 | #define SSL_CTX_set_mode SSL_CTX_set_mode |
| 4395 | #define SSL_CTX_set_msg_callback_arg SSL_CTX_set_msg_callback_arg |
| 4396 | #define SSL_CTX_set_options SSL_CTX_set_options |
| 4397 | #define SSL_CTX_set_read_ahead SSL_CTX_set_read_ahead |
| 4398 | #define SSL_CTX_set_session_cache_mode SSL_CTX_set_session_cache_mode |
| 4399 | #define SSL_CTX_set_tlsext_servername_arg SSL_CTX_set_tlsext_servername_arg |
| 4400 | #define SSL_CTX_set_tlsext_servername_callback \ |
| 4401 | SSL_CTX_set_tlsext_servername_callback |
| 4402 | #define SSL_CTX_set_tlsext_ticket_key_cb SSL_CTX_set_tlsext_ticket_key_cb |
| 4403 | #define SSL_CTX_set_tlsext_ticket_keys SSL_CTX_set_tlsext_ticket_keys |
| 4404 | #define SSL_CTX_set_tmp_dh SSL_CTX_set_tmp_dh |
| 4405 | #define SSL_CTX_set_tmp_ecdh SSL_CTX_set_tmp_ecdh |
| 4406 | #define SSL_CTX_set_tmp_rsa SSL_CTX_set_tmp_rsa |
| 4407 | #define SSL_add0_chain_cert SSL_add0_chain_cert |
| 4408 | #define SSL_add1_chain_cert SSL_add1_chain_cert |
| 4409 | #define SSL_clear_chain_certs SSL_clear_chain_certs |
| 4410 | #define SSL_clear_mode SSL_clear_mode |
| 4411 | #define SSL_clear_options SSL_clear_options |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4412 | #define SSL_get0_certificate_types SSL_get0_certificate_types |
| 4413 | #define SSL_get0_chain_certs SSL_get0_chain_certs |
| 4414 | #define SSL_get_max_cert_list SSL_get_max_cert_list |
| 4415 | #define SSL_get_mode SSL_get_mode |
| 4416 | #define SSL_get_options SSL_get_options |
Kenny Root | a04d78d | 2015-09-25 00:26:37 +0000 | [diff] [blame] | 4417 | #define SSL_get_secure_renegotiation_support \ |
| 4418 | SSL_get_secure_renegotiation_support |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4419 | #define SSL_need_tmp_RSA SSL_need_tmp_RSA |
| 4420 | #define SSL_num_renegotiations SSL_num_renegotiations |
| 4421 | #define SSL_session_reused SSL_session_reused |
| 4422 | #define SSL_set0_chain SSL_set0_chain |
| 4423 | #define SSL_set1_chain SSL_set1_chain |
| 4424 | #define SSL_set1_curves SSL_set1_curves |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 4425 | #define SSL_set_max_cert_list SSL_set_max_cert_list |
| 4426 | #define SSL_set_max_send_fragment SSL_set_max_send_fragment |
| 4427 | #define SSL_set_mode SSL_set_mode |
| 4428 | #define SSL_set_msg_callback_arg SSL_set_msg_callback_arg |
| 4429 | #define SSL_set_mtu SSL_set_mtu |
| 4430 | #define SSL_set_options SSL_set_options |
| 4431 | #define SSL_set_tlsext_host_name SSL_set_tlsext_host_name |
| 4432 | #define SSL_set_tmp_dh SSL_set_tmp_dh |
| 4433 | #define SSL_set_tmp_ecdh SSL_set_tmp_ecdh |
| 4434 | #define SSL_set_tmp_rsa SSL_set_tmp_rsa |
| 4435 | #define SSL_total_renegotiations SSL_total_renegotiations |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 4436 | |
| 4437 | |
| 4438 | #if defined(__cplusplus) |
| 4439 | } /* extern C */ |
David Benjamin | f0c4a6c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 4440 | |
| 4441 | extern "C++" { |
| 4442 | |
| 4443 | namespace bssl { |
| 4444 | |
| 4445 | BORINGSSL_MAKE_DELETER(SSL, SSL_free) |
| 4446 | BORINGSSL_MAKE_DELETER(SSL_CTX, SSL_CTX_free) |
| 4447 | BORINGSSL_MAKE_DELETER(SSL_SESSION, SSL_SESSION_free) |
| 4448 | |
| 4449 | } // namespace bssl |
| 4450 | |
| 4451 | } /* extern C++ */ |
| 4452 | |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 4453 | #endif |
| 4454 | |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 4455 | #define SSL_R_APP_DATA_IN_HANDSHAKE 100 |
| 4456 | #define SSL_R_ATTEMPT_TO_REUSE_SESSION_IN_DIFFERENT_CONTEXT 101 |
| 4457 | #define SSL_R_BAD_ALERT 102 |
| 4458 | #define SSL_R_BAD_CHANGE_CIPHER_SPEC 103 |
| 4459 | #define SSL_R_BAD_DATA_RETURNED_BY_CALLBACK 104 |
| 4460 | #define SSL_R_BAD_DH_P_LENGTH 105 |
| 4461 | #define SSL_R_BAD_DIGEST_LENGTH 106 |
| 4462 | #define SSL_R_BAD_ECC_CERT 107 |
| 4463 | #define SSL_R_BAD_ECPOINT 108 |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 4464 | #define SSL_R_BAD_HANDSHAKE_RECORD 109 |
| 4465 | #define SSL_R_BAD_HELLO_REQUEST 110 |
| 4466 | #define SSL_R_BAD_LENGTH 111 |
| 4467 | #define SSL_R_BAD_PACKET_LENGTH 112 |
| 4468 | #define SSL_R_BAD_RSA_ENCRYPT 113 |
| 4469 | #define SSL_R_BAD_SIGNATURE 114 |
| 4470 | #define SSL_R_BAD_SRTP_MKI_VALUE 115 |
| 4471 | #define SSL_R_BAD_SRTP_PROTECTION_PROFILE_LIST 116 |
| 4472 | #define SSL_R_BAD_SSL_FILETYPE 117 |
| 4473 | #define SSL_R_BAD_WRITE_RETRY 118 |
| 4474 | #define SSL_R_BIO_NOT_SET 119 |
| 4475 | #define SSL_R_BN_LIB 120 |
| 4476 | #define SSL_R_BUFFER_TOO_SMALL 121 |
| 4477 | #define SSL_R_CA_DN_LENGTH_MISMATCH 122 |
| 4478 | #define SSL_R_CA_DN_TOO_LONG 123 |
| 4479 | #define SSL_R_CCS_RECEIVED_EARLY 124 |
| 4480 | #define SSL_R_CERTIFICATE_VERIFY_FAILED 125 |
| 4481 | #define SSL_R_CERT_CB_ERROR 126 |
| 4482 | #define SSL_R_CERT_LENGTH_MISMATCH 127 |
| 4483 | #define SSL_R_CHANNEL_ID_NOT_P256 128 |
| 4484 | #define SSL_R_CHANNEL_ID_SIGNATURE_INVALID 129 |
| 4485 | #define SSL_R_CIPHER_OR_HASH_UNAVAILABLE 130 |
| 4486 | #define SSL_R_CLIENTHELLO_PARSE_FAILED 131 |
| 4487 | #define SSL_R_CLIENTHELLO_TLSEXT 132 |
| 4488 | #define SSL_R_CONNECTION_REJECTED 133 |
| 4489 | #define SSL_R_CONNECTION_TYPE_NOT_SET 134 |
| 4490 | #define SSL_R_CUSTOM_EXTENSION_ERROR 135 |
| 4491 | #define SSL_R_DATA_LENGTH_TOO_LONG 136 |
| 4492 | #define SSL_R_DECODE_ERROR 137 |
| 4493 | #define SSL_R_DECRYPTION_FAILED 138 |
| 4494 | #define SSL_R_DECRYPTION_FAILED_OR_BAD_RECORD_MAC 139 |
| 4495 | #define SSL_R_DH_PUBLIC_VALUE_LENGTH_IS_WRONG 140 |
| 4496 | #define SSL_R_DH_P_TOO_LONG 141 |
| 4497 | #define SSL_R_DIGEST_CHECK_FAILED 142 |
| 4498 | #define SSL_R_DTLS_MESSAGE_TOO_BIG 143 |
| 4499 | #define SSL_R_ECC_CERT_NOT_FOR_SIGNING 144 |
| 4500 | #define SSL_R_EMS_STATE_INCONSISTENT 145 |
| 4501 | #define SSL_R_ENCRYPTED_LENGTH_TOO_LONG 146 |
| 4502 | #define SSL_R_ERROR_ADDING_EXTENSION 147 |
| 4503 | #define SSL_R_ERROR_IN_RECEIVED_CIPHER_LIST 148 |
| 4504 | #define SSL_R_ERROR_PARSING_EXTENSION 149 |
| 4505 | #define SSL_R_EXCESSIVE_MESSAGE_SIZE 150 |
| 4506 | #define SSL_R_EXTRA_DATA_IN_MESSAGE 151 |
| 4507 | #define SSL_R_FRAGMENT_MISMATCH 152 |
| 4508 | #define SSL_R_GOT_NEXT_PROTO_WITHOUT_EXTENSION 153 |
| 4509 | #define SSL_R_HANDSHAKE_FAILURE_ON_CLIENT_HELLO 154 |
| 4510 | #define SSL_R_HTTPS_PROXY_REQUEST 155 |
| 4511 | #define SSL_R_HTTP_REQUEST 156 |
| 4512 | #define SSL_R_INAPPROPRIATE_FALLBACK 157 |
| 4513 | #define SSL_R_INVALID_COMMAND 158 |
| 4514 | #define SSL_R_INVALID_MESSAGE 159 |
| 4515 | #define SSL_R_INVALID_SSL_SESSION 160 |
| 4516 | #define SSL_R_INVALID_TICKET_KEYS_LENGTH 161 |
| 4517 | #define SSL_R_LENGTH_MISMATCH 162 |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 4518 | #define SSL_R_MISSING_EXTENSION 164 |
| 4519 | #define SSL_R_MISSING_RSA_CERTIFICATE 165 |
| 4520 | #define SSL_R_MISSING_TMP_DH_KEY 166 |
| 4521 | #define SSL_R_MISSING_TMP_ECDH_KEY 167 |
| 4522 | #define SSL_R_MIXED_SPECIAL_OPERATOR_WITH_GROUPS 168 |
| 4523 | #define SSL_R_MTU_TOO_SMALL 169 |
| 4524 | #define SSL_R_NEGOTIATED_BOTH_NPN_AND_ALPN 170 |
| 4525 | #define SSL_R_NESTED_GROUP 171 |
| 4526 | #define SSL_R_NO_CERTIFICATES_RETURNED 172 |
| 4527 | #define SSL_R_NO_CERTIFICATE_ASSIGNED 173 |
| 4528 | #define SSL_R_NO_CERTIFICATE_SET 174 |
| 4529 | #define SSL_R_NO_CIPHERS_AVAILABLE 175 |
| 4530 | #define SSL_R_NO_CIPHERS_PASSED 176 |
| 4531 | #define SSL_R_NO_CIPHER_MATCH 177 |
| 4532 | #define SSL_R_NO_COMPRESSION_SPECIFIED 178 |
| 4533 | #define SSL_R_NO_METHOD_SPECIFIED 179 |
| 4534 | #define SSL_R_NO_P256_SUPPORT 180 |
| 4535 | #define SSL_R_NO_PRIVATE_KEY_ASSIGNED 181 |
| 4536 | #define SSL_R_NO_RENEGOTIATION 182 |
| 4537 | #define SSL_R_NO_REQUIRED_DIGEST 183 |
| 4538 | #define SSL_R_NO_SHARED_CIPHER 184 |
| 4539 | #define SSL_R_NULL_SSL_CTX 185 |
| 4540 | #define SSL_R_NULL_SSL_METHOD_PASSED 186 |
| 4541 | #define SSL_R_OLD_SESSION_CIPHER_NOT_RETURNED 187 |
| 4542 | #define SSL_R_OLD_SESSION_VERSION_NOT_RETURNED 188 |
| 4543 | #define SSL_R_OUTPUT_ALIASES_INPUT 189 |
| 4544 | #define SSL_R_PARSE_TLSEXT 190 |
| 4545 | #define SSL_R_PATH_TOO_LONG 191 |
| 4546 | #define SSL_R_PEER_DID_NOT_RETURN_A_CERTIFICATE 192 |
| 4547 | #define SSL_R_PEER_ERROR_UNSUPPORTED_CERTIFICATE_TYPE 193 |
| 4548 | #define SSL_R_PROTOCOL_IS_SHUTDOWN 194 |
| 4549 | #define SSL_R_PSK_IDENTITY_NOT_FOUND 195 |
| 4550 | #define SSL_R_PSK_NO_CLIENT_CB 196 |
| 4551 | #define SSL_R_PSK_NO_SERVER_CB 197 |
| 4552 | #define SSL_R_READ_TIMEOUT_EXPIRED 198 |
| 4553 | #define SSL_R_RECORD_LENGTH_MISMATCH 199 |
| 4554 | #define SSL_R_RECORD_TOO_LARGE 200 |
| 4555 | #define SSL_R_RENEGOTIATION_ENCODING_ERR 201 |
| 4556 | #define SSL_R_RENEGOTIATION_MISMATCH 202 |
| 4557 | #define SSL_R_REQUIRED_CIPHER_MISSING 203 |
| 4558 | #define SSL_R_RESUMED_EMS_SESSION_WITHOUT_EMS_EXTENSION 204 |
| 4559 | #define SSL_R_RESUMED_NON_EMS_SESSION_WITH_EMS_EXTENSION 205 |
| 4560 | #define SSL_R_SCSV_RECEIVED_WHEN_RENEGOTIATING 206 |
| 4561 | #define SSL_R_SERVERHELLO_TLSEXT 207 |
| 4562 | #define SSL_R_SESSION_ID_CONTEXT_UNINITIALIZED 208 |
| 4563 | #define SSL_R_SESSION_MAY_NOT_BE_CREATED 209 |
| 4564 | #define SSL_R_SIGNATURE_ALGORITHMS_EXTENSION_SENT_BY_SERVER 210 |
| 4565 | #define SSL_R_SRTP_COULD_NOT_ALLOCATE_PROFILES 211 |
| 4566 | #define SSL_R_SRTP_UNKNOWN_PROTECTION_PROFILE 212 |
| 4567 | #define SSL_R_SSL3_EXT_INVALID_SERVERNAME 213 |
| 4568 | #define SSL_R_SSL_CTX_HAS_NO_DEFAULT_SSL_VERSION 214 |
| 4569 | #define SSL_R_SSL_HANDSHAKE_FAILURE 215 |
| 4570 | #define SSL_R_SSL_SESSION_ID_CONTEXT_TOO_LONG 216 |
| 4571 | #define SSL_R_TLS_PEER_DID_NOT_RESPOND_WITH_CERTIFICATE_LIST 217 |
| 4572 | #define SSL_R_TLS_RSA_ENCRYPTED_VALUE_LENGTH_IS_WRONG 218 |
| 4573 | #define SSL_R_TOO_MANY_EMPTY_FRAGMENTS 219 |
| 4574 | #define SSL_R_TOO_MANY_WARNING_ALERTS 220 |
| 4575 | #define SSL_R_UNABLE_TO_FIND_ECDH_PARAMETERS 221 |
| 4576 | #define SSL_R_UNEXPECTED_EXTENSION 222 |
| 4577 | #define SSL_R_UNEXPECTED_MESSAGE 223 |
| 4578 | #define SSL_R_UNEXPECTED_OPERATOR_IN_GROUP 224 |
| 4579 | #define SSL_R_UNEXPECTED_RECORD 225 |
| 4580 | #define SSL_R_UNINITIALIZED 226 |
| 4581 | #define SSL_R_UNKNOWN_ALERT_TYPE 227 |
| 4582 | #define SSL_R_UNKNOWN_CERTIFICATE_TYPE 228 |
| 4583 | #define SSL_R_UNKNOWN_CIPHER_RETURNED 229 |
| 4584 | #define SSL_R_UNKNOWN_CIPHER_TYPE 230 |
| 4585 | #define SSL_R_UNKNOWN_DIGEST 231 |
| 4586 | #define SSL_R_UNKNOWN_KEY_EXCHANGE_TYPE 232 |
| 4587 | #define SSL_R_UNKNOWN_PROTOCOL 233 |
| 4588 | #define SSL_R_UNKNOWN_SSL_VERSION 234 |
| 4589 | #define SSL_R_UNKNOWN_STATE 235 |
| 4590 | #define SSL_R_UNSAFE_LEGACY_RENEGOTIATION_DISABLED 236 |
| 4591 | #define SSL_R_UNSUPPORTED_CIPHER 237 |
| 4592 | #define SSL_R_UNSUPPORTED_COMPRESSION_ALGORITHM 238 |
| 4593 | #define SSL_R_UNSUPPORTED_ELLIPTIC_CURVE 239 |
| 4594 | #define SSL_R_UNSUPPORTED_PROTOCOL 240 |
| 4595 | #define SSL_R_WRONG_CERTIFICATE_TYPE 241 |
| 4596 | #define SSL_R_WRONG_CIPHER_RETURNED 242 |
| 4597 | #define SSL_R_WRONG_CURVE 243 |
| 4598 | #define SSL_R_WRONG_MESSAGE_TYPE 244 |
| 4599 | #define SSL_R_WRONG_SIGNATURE_TYPE 245 |
| 4600 | #define SSL_R_WRONG_SSL_VERSION 246 |
| 4601 | #define SSL_R_WRONG_VERSION_NUMBER 247 |
| 4602 | #define SSL_R_X509_LIB 248 |
| 4603 | #define SSL_R_X509_VERIFICATION_SETUP_PROBLEMS 249 |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 4604 | #define SSL_R_SHUTDOWN_WHILE_IN_INIT 250 |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 4605 | #define SSL_R_INVALID_OUTER_RECORD_TYPE 251 |
| 4606 | #define SSL_R_UNSUPPORTED_PROTOCOL_FOR_CUSTOM_KEY 252 |
| 4607 | #define SSL_R_NO_COMMON_SIGNATURE_ALGORITHMS 253 |
| 4608 | #define SSL_R_DOWNGRADE_DETECTED 254 |
| 4609 | #define SSL_R_BUFFERED_MESSAGES_ON_CIPHER_CHANGE 255 |
| 4610 | #define SSL_R_INVALID_COMPRESSION_LIST 256 |
| 4611 | #define SSL_R_DUPLICATE_EXTENSION 257 |
| 4612 | #define SSL_R_MISSING_KEY_SHARE 258 |
| 4613 | #define SSL_R_INVALID_ALPN_PROTOCOL 259 |
David Benjamin | f0c4a6c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 4614 | #define SSL_R_TOO_MANY_KEY_UPDATES 260 |
| 4615 | #define SSL_R_BLOCK_CIPHER_PAD_IS_WRONG 261 |
| 4616 | #define SSL_R_NO_CIPHERS_SPECIFIED 262 |
| 4617 | #define SSL_R_RENEGOTIATION_EMS_MISMATCH 263 |
David Benjamin | 7c0d06c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 4618 | #define SSL_R_DUPLICATE_KEY_SHARE 264 |
| 4619 | #define SSL_R_NO_GROUPS_SPECIFIED 265 |
Steven Valdez | bb1ceac | 2016-10-07 10:34:51 -0400 | [diff] [blame] | 4620 | #define SSL_R_NO_SHARED_GROUP 266 |
Steven Valdez | 909b19f | 2016-11-21 15:35:44 -0500 | [diff] [blame] | 4621 | #define SSL_R_PRE_SHARED_KEY_MUST_BE_LAST 267 |
| 4622 | #define SSL_R_OLD_SESSION_PRF_HASH_MISMATCH 268 |
| 4623 | #define SSL_R_INVALID_SCT_LIST 269 |
David Benjamin | 1b24967 | 2016-12-06 18:25:50 -0500 | [diff] [blame] | 4624 | #define SSL_R_TOO_MUCH_SKIPPED_EARLY_DATA 270 |
| 4625 | #define SSL_R_PSK_IDENTITY_BINDER_COUNT_MISMATCH 271 |
Steven Valdez | e7531f0 | 2016-12-14 13:29:57 -0500 | [diff] [blame] | 4626 | #define SSL_R_CANNOT_PARSE_LEAF_CERT 272 |
Robert Sloan | 7d422bc | 2017-03-06 10:04:29 -0800 | [diff] [blame] | 4627 | #define SSL_R_SERVER_CERT_CHANGED 273 |
Robert Sloan | 1c9db53 | 2017-03-13 08:03:59 -0700 | [diff] [blame] | 4628 | #define SSL_R_CERTIFICATE_AND_PRIVATE_KEY_MISMATCH 274 |
| 4629 | #define SSL_R_CANNOT_HAVE_BOTH_PRIVKEY_AND_METHOD 275 |
| 4630 | #define SSL_R_TICKET_ENCRYPTION_FAILED 276 |
Robert Sloan | 6d0d00e | 2017-03-27 07:13:07 -0700 | [diff] [blame] | 4631 | #define SSL_R_ALPN_MISMATCH_ON_EARLY_DATA 277 |
| 4632 | #define SSL_R_WRONG_VERSION_ON_EARLY_DATA 278 |
| 4633 | #define SSL_R_CHANNEL_ID_ON_EARLY_DATA 279 |
Robert Sloan | 572a4e2 | 2017-04-17 10:52:19 -0700 | [diff] [blame] | 4634 | #define SSL_R_NO_SUPPORTED_VERSIONS_ENABLED 280 |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 4635 | #define SSL_R_SSLV3_ALERT_CLOSE_NOTIFY 1000 |
| 4636 | #define SSL_R_SSLV3_ALERT_UNEXPECTED_MESSAGE 1010 |
| 4637 | #define SSL_R_SSLV3_ALERT_BAD_RECORD_MAC 1020 |
| 4638 | #define SSL_R_TLSV1_ALERT_DECRYPTION_FAILED 1021 |
| 4639 | #define SSL_R_TLSV1_ALERT_RECORD_OVERFLOW 1022 |
| 4640 | #define SSL_R_SSLV3_ALERT_DECOMPRESSION_FAILURE 1030 |
| 4641 | #define SSL_R_SSLV3_ALERT_HANDSHAKE_FAILURE 1040 |
| 4642 | #define SSL_R_SSLV3_ALERT_NO_CERTIFICATE 1041 |
| 4643 | #define SSL_R_SSLV3_ALERT_BAD_CERTIFICATE 1042 |
| 4644 | #define SSL_R_SSLV3_ALERT_UNSUPPORTED_CERTIFICATE 1043 |
| 4645 | #define SSL_R_SSLV3_ALERT_CERTIFICATE_REVOKED 1044 |
| 4646 | #define SSL_R_SSLV3_ALERT_CERTIFICATE_EXPIRED 1045 |
| 4647 | #define SSL_R_SSLV3_ALERT_CERTIFICATE_UNKNOWN 1046 |
| 4648 | #define SSL_R_SSLV3_ALERT_ILLEGAL_PARAMETER 1047 |
| 4649 | #define SSL_R_TLSV1_ALERT_UNKNOWN_CA 1048 |
| 4650 | #define SSL_R_TLSV1_ALERT_ACCESS_DENIED 1049 |
| 4651 | #define SSL_R_TLSV1_ALERT_DECODE_ERROR 1050 |
| 4652 | #define SSL_R_TLSV1_ALERT_DECRYPT_ERROR 1051 |
| 4653 | #define SSL_R_TLSV1_ALERT_EXPORT_RESTRICTION 1060 |
| 4654 | #define SSL_R_TLSV1_ALERT_PROTOCOL_VERSION 1070 |
| 4655 | #define SSL_R_TLSV1_ALERT_INSUFFICIENT_SECURITY 1071 |
| 4656 | #define SSL_R_TLSV1_ALERT_INTERNAL_ERROR 1080 |
| 4657 | #define SSL_R_TLSV1_ALERT_INAPPROPRIATE_FALLBACK 1086 |
| 4658 | #define SSL_R_TLSV1_ALERT_USER_CANCELLED 1090 |
| 4659 | #define SSL_R_TLSV1_ALERT_NO_RENEGOTIATION 1100 |
| 4660 | #define SSL_R_TLSV1_UNSUPPORTED_EXTENSION 1110 |
| 4661 | #define SSL_R_TLSV1_CERTIFICATE_UNOBTAINABLE 1111 |
| 4662 | #define SSL_R_TLSV1_UNRECOGNIZED_NAME 1112 |
| 4663 | #define SSL_R_TLSV1_BAD_CERTIFICATE_STATUS_RESPONSE 1113 |
| 4664 | #define SSL_R_TLSV1_BAD_CERTIFICATE_HASH_VALUE 1114 |
David Benjamin | 95add82 | 2016-10-19 01:09:12 -0400 | [diff] [blame] | 4665 | #define SSL_R_TLSV1_UNKNOWN_PSK_IDENTITY 1115 |
| 4666 | #define SSL_R_TLSV1_CERTIFICATE_REQUIRED 1116 |
Robert Sloan | 9254e68 | 2017-04-24 09:42:06 -0700 | [diff] [blame] | 4667 | #define SSL_R_TOO_MUCH_READ_EARLY_DATA 1117 |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 4668 | |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 4669 | #endif /* OPENSSL_HEADER_SSL_H */ |