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