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