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