1.\" $OpenBSD: ssl.3,v 1.20 2020/09/21 08:53:56 schwarze Exp $ 2.\" full merge up to: OpenSSL e330f55d Nov 11 00:51:04 2016 +0100 3.\" selective merge up to: OpenSSL 322755cc Sep 1 08:40:51 2018 +0800 4.\" 5.\" This file was written by Ralf S. Engelschall <rse@openssl.org>, 6.\" Ben Laurie <ben@openssl.org>, and Ulf Moeller <ulf@openssl.org>. 7.\" Copyright (c) 1998-2002, 2005, 2013, 2015 The OpenSSL Project. 8.\" All rights reserved. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 17.\" 2. Redistributions in binary form must reproduce the above copyright 18.\" notice, this list of conditions and the following disclaimer in 19.\" the documentation and/or other materials provided with the 20.\" distribution. 21.\" 22.\" 3. All advertising materials mentioning features or use of this 23.\" software must display the following acknowledgment: 24.\" "This product includes software developed by the OpenSSL Project 25.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 26.\" 27.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 28.\" endorse or promote products derived from this software without 29.\" prior written permission. For written permission, please contact 30.\" openssl-core@openssl.org. 31.\" 32.\" 5. Products derived from this software may not be called "OpenSSL" 33.\" nor may "OpenSSL" appear in their names without prior written 34.\" permission of the OpenSSL Project. 35.\" 36.\" 6. Redistributions of any form whatsoever must retain the following 37.\" acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 40.\" 41.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 42.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 43.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 44.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 45.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 46.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 47.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 48.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 49.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 50.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 51.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 52.\" OF THE POSSIBILITY OF SUCH DAMAGE. 53.\" 54.Dd $Mdocdate: September 21 2020 $ 55.Dt SSL 3 56.Os 57.Sh NAME 58.Nm ssl 59.Nd OpenSSL SSL/TLS library 60.Sh DESCRIPTION 61The OpenSSL 62.Nm ssl 63library implements the Transport Layer Security (TLS v1) protocols. 64.Pp 65An 66.Vt SSL_CTX 67object is created as a framework to establish TLS/SSL enabled connections (see 68.Xr SSL_CTX_new 3 ) . 69Various options regarding certificates, algorithms, etc., can be set in this 70object. 71.Pp 72When a network connection has been created, it can be assigned to an 73.Vt SSL 74object. 75After the 76.Vt SSL 77object has been created using 78.Xr SSL_new 3 , 79.Xr SSL_set_fd 3 80or 81.Xr SSL_set_bio 3 82can be used to associate the network connection with the object. 83.Pp 84Then the TLS/SSL handshake is performed using 85.Xr SSL_accept 3 86or 87.Xr SSL_connect 3 88respectively. 89.Xr SSL_read 3 90and 91.Xr SSL_write 3 92are used to read and write data on the TLS/SSL connection. 93.Xr SSL_shutdown 3 94can be used to shut down the TLS/SSL connection. 95.Sh DATA STRUCTURES 96Currently the OpenSSL 97.Nm ssl 98library functions deal with the following data structures: 99.Bl -tag -width Ds 100.It Vt SSL_METHOD No (SSL Method) 101That's a dispatch structure describing the internal 102.Nm ssl 103library methods/functions which implement the various protocol versions. 104It's needed to create an 105.Vt SSL_CTX . 106See 107.Xr TLS_method 3 108for constructors. 109.It Vt SSL_CIPHER No (SSL Cipher) 110This structure holds the algorithm information for a particular cipher which 111is a core part of the SSL/TLS protocol. 112The available ciphers are configured on an 113.Vt SSL_CTX 114basis and the actually used ones are then part of the 115.Vt SSL_SESSION . 116.It Vt SSL_CTX No (SSL Context) 117That's the global context structure which is created by a server or client 118once per program lifetime and which holds mainly default values for the 119.Vt SSL 120structures which are later created for the connections. 121.It Vt SSL_SESSION No (SSL Session) 122This is a structure containing the current TLS/SSL session details for a 123connection: 124.Vt SSL_CIPHER Ns s , 125client and server certificates, keys, etc. 126.It Vt SSL No (SSL Connection) 127That's the main SSL/TLS structure which is created by a server or client per 128established connection. 129This actually is the core structure in the SSL API. 130At run-time the application usually deals with this structure which has 131links to mostly all other structures. 132.El 133.Sh HEADER FILES 134Currently the OpenSSL 135.Nm ssl 136library provides the following C header files containing the prototypes for the 137data structures and functions: 138.Bl -tag -width Ds 139.It Pa ssl.h 140That's the common header file for the SSL/TLS API. 141Include it into your program to make the API of the 142.Nm ssl 143library available. 144It internally includes both more private SSL headers and headers from the 145.Em crypto 146library. 147Whenever you need hardcore details on the internals of the SSL API, look inside 148this header file. 149.It Pa ssl2.h 150That's the sub header file dealing with the SSLv2 protocol only. 151.Bf Em 152 Usually you don't have to include it explicitly because it's already included 153by 154.Pa ssl.h . 155.Ef 156.It Pa ssl3.h 157That's the sub header file dealing with the SSLv3 protocol only. 158.Bf Em 159Usually you don't have to include it explicitly because it's already included 160by 161.Pa ssl.h . 162.Ef 163.It Pa ssl23.h 164That's the sub header file dealing with the combined use of the SSLv2 and SSLv3 165protocols. 166.Bf Em 167Usually you don't have to include it explicitly because it's already included 168by 169.Pa ssl.h . 170.Ef 171.It Pa tls1.h 172That's the sub header file dealing with the TLSv1 protocol only. 173.Bf Em 174Usually you don't have to include it explicitly because it's already included 175by 176.Pa ssl.h . 177.Ef 178.El 179.Sh API FUNCTIONS 180.Ss Ciphers 181The following pages describe functions acting on 182.Vt SSL_CIPHER 183objects: 184.Xr SSL_get_ciphers 3 , 185.Xr SSL_get_current_cipher 3 , 186.Xr SSL_CIPHER_get_name 3 187.Ss Protocol contexts 188The following pages describe functions acting on 189.Vt SSL_CTX 190objects. 191.Pp 192Constructors and destructors: 193.Xr SSL_CTX_new 3 , 194.Xr SSL_CTX_set_ssl_version 3 , 195.Xr SSL_CTX_free 3 196.Pp 197Certificate configuration: 198.Xr SSL_CTX_add_extra_chain_cert 3 , 199.Xr SSL_CTX_get0_certificate 3 , 200.Xr SSL_CTX_load_verify_locations 3 , 201.Xr SSL_CTX_set_cert_store 3 , 202.Xr SSL_CTX_set_cert_verify_callback 3 , 203.Xr SSL_CTX_set_client_cert_cb 3 , 204.Xr SSL_CTX_set_default_passwd_cb 3 , 205.Xr SSL_CTX_set_tlsext_status_cb 3 206.Pp 207Session configuration: 208.Xr SSL_CTX_add_session 3 , 209.Xr SSL_CTX_flush_sessions 3 , 210.Xr SSL_CTX_sess_number 3 , 211.Xr SSL_CTX_sess_set_cache_size 3 , 212.Xr SSL_CTX_sess_set_get_cb 3 , 213.Xr SSL_CTX_sessions 3 , 214.Xr SSL_CTX_set_session_cache_mode 3 , 215.Xr SSL_CTX_set_timeout 3 , 216.Xr SSL_CTX_set_tlsext_ticket_key_cb 3 217.Pp 218Various configuration: 219.Xr SSL_CTX_get_ex_new_index 3 , 220.Xr SSL_CTX_set_tlsext_servername_callback 3 221.Ss Common configuration of contexts and connections 222The functions on the following pages each come in two variants: 223one to directly configure a single 224.Vt SSL 225connection and another to be called on an 226.Vt SSL_CTX 227object, to set up defaults for all future 228.Vt SSL 229connections created from that context. 230.Pp 231Protocol and algorithm configuration: 232.Xr SSL_CTX_set_alpn_select_cb 3 , 233.Xr SSL_CTX_set_cipher_list 3 , 234.Xr SSL_CTX_set_min_proto_version 3 , 235.Xr SSL_CTX_set_options 3 , 236.Xr SSL_CTX_set_tlsext_use_srtp 3 , 237.Xr SSL_CTX_set_tmp_dh_callback 3 , 238.Xr SSL_CTX_set1_groups 3 239.Pp 240Certificate configuration: 241.Xr SSL_CTX_add1_chain_cert 3 , 242.Xr SSL_CTX_get_verify_mode 3 , 243.Xr SSL_CTX_set_client_CA_list 3 , 244.Xr SSL_CTX_set_max_cert_list 3 , 245.Xr SSL_CTX_set_verify 3 , 246.Xr SSL_CTX_use_certificate 3 , 247.Xr SSL_get_client_CA_list 3 248.Xr SSL_set1_param 3 249.Pp 250Session configuration: 251.Xr SSL_CTX_set_generate_session_id 3 , 252.Xr SSL_CTX_set_session_id_context 3 253.Pp 254Various configuration: 255.Xr SSL_CTX_ctrl 3 , 256.Xr SSL_CTX_set_info_callback 3 , 257.Xr SSL_CTX_set_mode 3 , 258.Xr SSL_CTX_set_msg_callback 3 , 259.Xr SSL_CTX_set_quiet_shutdown 3 , 260.Xr SSL_CTX_set_read_ahead 3 , 261.Xr SSL_set_max_send_fragment 3 262.Ss Sessions 263The following pages describe functions acting on 264.Vt SSL_SESSION 265objects. 266.Pp 267Constructors and destructors: 268.Xr SSL_SESSION_new 3 , 269.Xr SSL_SESSION_free 3 270.Pp 271Accessors: 272.Xr SSL_SESSION_get_compress_id 3 , 273.Xr SSL_SESSION_get_ex_new_index 3 , 274.Xr SSL_SESSION_get_id 3 , 275.Xr SSL_SESSION_get_protocol_version 3 , 276.Xr SSL_SESSION_get_time 3 , 277.Xr SSL_SESSION_get0_peer 3 , 278.Xr SSL_SESSION_has_ticket 3 , 279.Xr SSL_SESSION_set1_id_context 3 280.Pp 281Encoding and decoding: 282.Xr d2i_SSL_SESSION 3 , 283.Xr PEM_read_SSL_SESSION 3 , 284.Xr SSL_SESSION_print 3 285.Ss Connections 286The following pages describe functions acting on 287.Vt SSL 288connection objects: 289.Pp 290Constructors and destructors: 291.Xr SSL_new 3 , 292.Xr SSL_dup 3 , 293.Xr SSL_free 3 , 294.Xr BIO_f_ssl 3 295.Pp 296To change the configuration: 297.Xr SSL_clear 3 , 298.Xr SSL_set_SSL_CTX 3 , 299.Xr SSL_copy_session_id 3 , 300.Xr SSL_set_bio 3 , 301.Xr SSL_set_connect_state 3 , 302.Xr SSL_set_fd 3 , 303.Xr SSL_set_session 3 , 304.Xr SSL_set1_host 3 , 305.Xr SSL_set_verify_result 3 306.Pp 307To inspect the configuration: 308.Xr SSL_get_certificate 3 , 309.Xr SSL_get_default_timeout 3 , 310.Xr SSL_get_ex_new_index 3 , 311.Xr SSL_get_fd 3 , 312.Xr SSL_get_rbio 3 , 313.Xr SSL_get_SSL_CTX 3 314.Pp 315To transmit data: 316.Xr DTLSv1_listen 3 , 317.Xr SSL_accept 3 , 318.Xr SSL_connect 3 , 319.Xr SSL_do_handshake 3 , 320.Xr SSL_read 3 , 321.\" XXX enable after the 6.8 release: Xr SSL_read_early_data 3 , 322.Xr SSL_renegotiate 3 , 323.Xr SSL_shutdown 3 , 324.Xr SSL_write 3 325.Pp 326To inspect the state after a connection is established: 327.Xr SSL_export_keying_material 3 , 328.Xr SSL_get_client_random 3 , 329.Xr SSL_get_ex_data_X509_STORE_CTX_idx 3 , 330.Xr SSL_get_peer_cert_chain 3 , 331.Xr SSL_get_peer_certificate 3 , 332.Xr SSL_get_server_tmp_key 3 , 333.Xr SSL_get_servername 3 , 334.Xr SSL_get_session 3 , 335.Xr SSL_get_shared_ciphers 3 , 336.Xr SSL_get_verify_result 3 , 337.Xr SSL_get_version 3 , 338.Xr SSL_session_reused 3 339.Pp 340To inspect the state during ongoing communication: 341.Xr SSL_get_error 3 , 342.Xr SSL_get_shutdown 3 , 343.Xr SSL_get_state 3 , 344.Xr SSL_num_renegotiations 3 , 345.Xr SSL_pending 3 , 346.Xr SSL_rstate_string 3 , 347.Xr SSL_state_string 3 , 348.Xr SSL_want 3 349.Ss Utility functions 350.Xr SSL_alert_type_string 3 , 351.Xr SSL_dup_CA_list 3 , 352.Xr SSL_load_client_CA_file 3 353.Ss Obsolete functions 354.Xr OPENSSL_init_ssl 3 , 355.Xr SSL_COMP_add_compression_method 3 , 356.Xr SSL_CTX_set_tmp_rsa_callback 3 , 357.Xr SSL_library_init 3 , 358.Xr SSL_set_tmp_ecdh 3 359.Sh SEE ALSO 360.Xr openssl 1 , 361.Xr crypto 3 , 362.Xr tls_init 3 363.Sh HISTORY 364The 365.Nm 366document appeared in OpenSSL 0.9.2. 367