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