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