1.\" $OpenBSD: ssl.3,v 1.24 2024/05/09 17:57:36 jmc 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: May 9 2024 $ 55.Dt SSL 3 56.Os 57.Sh NAME 58.Nm ssl 59.Nd OpenSSL TLS library 60.Sh DESCRIPTION 61The 62.Nm ssl 63library implements the Transport Layer Security (TLS) protocol, 64the successor to the Secure Sockets Layer (SSL) protocol. 65.Pp 66An 67.Vt SSL_CTX 68object is created as a framework to establish TLS/SSL enabled connections (see 69.Xr SSL_CTX_new 3 ) . 70Various options regarding certificates, algorithms, etc., can be set in this 71object. 72.Pp 73When a network connection has been created, it can be assigned to an 74.Vt SSL 75object. 76After the 77.Vt SSL 78object has been created using 79.Xr SSL_new 3 , 80.Xr SSL_set_fd 3 81or 82.Xr SSL_set_bio 3 83can be used to associate the network connection with the object. 84.Pp 85Then the TLS/SSL handshake is performed using 86.Xr SSL_accept 3 87or 88.Xr SSL_connect 3 89respectively. 90.Xr SSL_read 3 91and 92.Xr SSL_write 3 93are used to read and write data on the TLS/SSL connection. 94.Xr SSL_shutdown 3 95can be used to shut down the TLS/SSL connection. 96.Sh DATA STRUCTURES 97Currently the 98.Nm ssl 99library functions deal with the following data structures: 100.Bl -tag -width Ds 101.It Vt SSL_METHOD No (SSL Method) 102That's a dispatch structure describing the internal 103.Nm ssl 104library methods/functions which implement the various protocol versions. 105It's needed to create an 106.Vt SSL_CTX . 107See 108.Xr TLS_method 3 109for constructors. 110.It Vt SSL_CIPHER No (SSL Cipher) 111This structure holds the algorithm information for a particular cipher which 112is a core part of the SSL/TLS protocol. 113The available ciphers are configured on an 114.Vt SSL_CTX 115basis and the actually used ones are then part of the 116.Vt SSL_SESSION . 117.It Vt SSL_CTX No (SSL Context) 118That's the global context structure which is created by a server or client 119once per program lifetime and which holds mainly default values for the 120.Vt SSL 121structures which are later created for the connections. 122.It Vt SSL_SESSION No (SSL Session) 123This is a structure containing the current TLS/SSL session details for a 124connection: 125.Vt SSL_CIPHER Ns s , 126client and server certificates, keys, etc. 127.It Vt SSL No (SSL Connection) 128That's the main SSL/TLS structure which is created by a server or client per 129established connection. 130This actually is the core structure in the SSL API. 131At run-time the application usually deals with this structure which has 132links to mostly all other structures. 133.El 134.Sh HEADER FILES 135Currently the 136.Nm ssl 137library provides the following C header files containing the prototypes for the 138data structures and functions: 139.Bl -tag -width Ds 140.It Pa ssl.h 141That's the common header file for the SSL/TLS API. 142Include it into your program to make the API of the 143.Nm ssl 144library available. 145It internally includes both more private SSL headers and headers from the 146.Em crypto 147library. 148Whenever you need hardcore details on the internals of the SSL API, look inside 149this header file. 150.It Pa ssl2.h 151That's the sub header file dealing with the SSLv2 protocol only. 152.Bf Em 153 Usually you don't have to include it explicitly because it's already included 154by 155.Pa ssl.h . 156.Ef 157.It Pa ssl3.h 158That's the sub header file dealing with the SSLv3 protocol only. 159.Bf Em 160Usually you don't have to include it explicitly because it's already included 161by 162.Pa ssl.h . 163.Ef 164.It Pa ssl23.h 165That's the sub header file dealing with the combined use of the SSLv2 and SSLv3 166protocols. 167.Bf Em 168Usually you don't have to include it explicitly because it's already included 169by 170.Pa ssl.h . 171.Ef 172.It Pa tls1.h 173That's the sub header file dealing with the TLSv1 protocol only. 174.Bf Em 175Usually you don't have to include it explicitly because it's already included 176by 177.Pa ssl.h . 178.Ef 179.El 180.Sh API FUNCTIONS 181.Ss Ciphers 182The following pages describe functions acting on 183.Vt SSL_CIPHER 184objects: 185.Xr SSL_get_ciphers 3 , 186.Xr SSL_get_current_cipher 3 , 187.Xr SSL_CIPHER_get_name 3 188.Ss Protocol contexts 189The following pages describe functions acting on 190.Vt SSL_CTX 191objects. 192.Pp 193Constructors and destructors: 194.Xr SSL_CTX_new 3 , 195.Xr SSL_CTX_set_ssl_version 3 , 196.Xr SSL_CTX_free 3 197.Pp 198Certificate configuration: 199.Xr SSL_CTX_add_extra_chain_cert 3 , 200.Xr SSL_CTX_get0_certificate 3 , 201.Xr SSL_CTX_load_verify_locations 3 , 202.Xr SSL_CTX_set_cert_store 3 , 203.Xr SSL_CTX_set_cert_verify_callback 3 , 204.Xr SSL_CTX_set_client_cert_cb 3 , 205.Xr SSL_CTX_set_default_passwd_cb 3 , 206.Xr SSL_CTX_set_tlsext_status_cb 3 207.Pp 208Session configuration: 209.Xr SSL_CTX_add_session 3 , 210.Xr SSL_CTX_flush_sessions 3 , 211.Xr SSL_CTX_sess_number 3 , 212.Xr SSL_CTX_sess_set_cache_size 3 , 213.Xr SSL_CTX_sess_set_get_cb 3 , 214.Xr SSL_CTX_sessions 3 , 215.Xr SSL_CTX_set_session_cache_mode 3 , 216.Xr SSL_CTX_set_timeout 3 , 217.Xr SSL_CTX_set_tlsext_ticket_key_cb 3 218.Pp 219Various configuration: 220.Xr SSL_CTX_get_ex_new_index 3 , 221.Xr SSL_CTX_set_tlsext_servername_callback 3 222.Ss Common configuration of contexts and connections 223The functions on the following pages each come in two variants: 224one to directly configure a single 225.Vt SSL 226connection and another to be called on an 227.Vt SSL_CTX 228object, to set up defaults for all future 229.Vt SSL 230connections created from that context. 231.Pp 232Protocol and algorithm configuration: 233.Xr SSL_CTX_set_alpn_select_cb 3 , 234.Xr SSL_CTX_set_cipher_list 3 , 235.Xr SSL_CTX_set_min_proto_version 3 , 236.Xr SSL_CTX_set_options 3 , 237.Xr SSL_CTX_set_security_level 3 , 238.Xr SSL_CTX_set_tlsext_use_srtp 3 , 239.Xr SSL_CTX_set_tmp_dh_callback 3 , 240.Xr SSL_CTX_set1_groups 3 241.Pp 242Certificate configuration: 243.Xr SSL_CTX_add1_chain_cert 3 , 244.Xr SSL_CTX_get_verify_mode 3 , 245.Xr SSL_CTX_set_client_CA_list 3 , 246.Xr SSL_CTX_set_max_cert_list 3 , 247.Xr SSL_CTX_set_verify 3 , 248.Xr SSL_CTX_use_certificate 3 , 249.Xr SSL_get_client_CA_list 3 250.Xr SSL_set1_param 3 251.Pp 252Session configuration: 253.Xr SSL_CTX_set_generate_session_id 3 , 254.Xr SSL_CTX_set_session_id_context 3 255.Pp 256Various configuration: 257.Xr SSL_CTX_ctrl 3 , 258.Xr SSL_CTX_set_info_callback 3 , 259.Xr SSL_CTX_set_mode 3 , 260.Xr SSL_CTX_set_msg_callback 3 , 261.Xr SSL_CTX_set_quiet_shutdown 3 , 262.Xr SSL_CTX_set_read_ahead 3 , 263.Xr SSL_set_max_send_fragment 3 264.Ss Sessions 265The following pages describe functions acting on 266.Vt SSL_SESSION 267objects. 268.Pp 269Constructors and destructors: 270.Xr SSL_SESSION_new 3 , 271.Xr SSL_SESSION_free 3 272.Pp 273Accessors: 274.Xr SSL_SESSION_get_compress_id 3 , 275.Xr SSL_SESSION_get_ex_new_index 3 , 276.Xr SSL_SESSION_get_id 3 , 277.Xr SSL_SESSION_get_protocol_version 3 , 278.Xr SSL_SESSION_get_time 3 , 279.Xr SSL_SESSION_get0_peer 3 , 280.Xr SSL_SESSION_has_ticket 3 , 281.Xr SSL_SESSION_set1_id_context 3 282.Pp 283Encoding and decoding: 284.Xr d2i_SSL_SESSION 3 , 285.Xr PEM_read_SSL_SESSION 3 , 286.Xr SSL_SESSION_print 3 287.Ss Connections 288The following pages describe functions acting on 289.Vt SSL 290connection objects: 291.Pp 292Constructors and destructors: 293.Xr SSL_new 3 , 294.Xr SSL_dup 3 , 295.Xr SSL_free 3 , 296.Xr BIO_f_ssl 3 297.Pp 298To change the configuration: 299.Xr SSL_clear 3 , 300.Xr SSL_set_SSL_CTX 3 , 301.Xr SSL_copy_session_id 3 , 302.Xr SSL_set_bio 3 , 303.Xr SSL_set_connect_state 3 , 304.Xr SSL_set_fd 3 , 305.Xr SSL_set_session 3 , 306.Xr SSL_set1_host 3 , 307.Xr SSL_set_verify_result 3 308.Pp 309To inspect the configuration: 310.Xr SSL_get_certificate 3 , 311.Xr SSL_get_default_timeout 3 , 312.Xr SSL_get_ex_new_index 3 , 313.Xr SSL_get_fd 3 , 314.Xr SSL_get_rbio 3 , 315.Xr SSL_get_SSL_CTX 3 316.Pp 317To transmit data: 318.Xr DTLSv1_listen 3 , 319.Xr SSL_accept 3 , 320.Xr SSL_connect 3 , 321.Xr SSL_do_handshake 3 , 322.Xr SSL_read 3 , 323.Xr SSL_read_early_data 3 , 324.Xr SSL_renegotiate 3 , 325.Xr SSL_shutdown 3 , 326.Xr SSL_write 3 327.Pp 328To inspect the state after a connection is established: 329.Xr SSL_export_keying_material 3 , 330.Xr SSL_get_client_random 3 , 331.Xr SSL_get_ex_data_X509_STORE_CTX_idx 3 , 332.Xr SSL_get_peer_cert_chain 3 , 333.Xr SSL_get_peer_certificate 3 , 334.Xr SSL_get_server_tmp_key 3 , 335.Xr SSL_get_servername 3 , 336.Xr SSL_get_session 3 , 337.Xr SSL_get_shared_ciphers 3 , 338.Xr SSL_get_verify_result 3 , 339.Xr SSL_get_version 3 , 340.Xr SSL_session_reused 3 341.Pp 342To inspect the state during ongoing communication: 343.Xr SSL_get_error 3 , 344.Xr SSL_get_shutdown 3 , 345.Xr SSL_get_state 3 , 346.Xr SSL_num_renegotiations 3 , 347.Xr SSL_pending 3 , 348.Xr SSL_rstate_string 3 , 349.Xr SSL_state_string 3 , 350.Xr SSL_want 3 351.Ss Utility functions 352.Xr SSL_alert_type_string 3 , 353.Xr SSL_dup_CA_list 3 , 354.Xr SSL_load_client_CA_file 3 355.Ss Obsolete functions 356.Xr OPENSSL_init_ssl 3 , 357.Xr SSL_COMP_add_compression_method 3 , 358.Xr SSL_CTX_set_tmp_rsa_callback 3 , 359.Xr SSL_library_init 3 , 360.Xr SSL_set_tmp_ecdh 3 361.Sh SEE ALSO 362.Xr openssl 1 , 363.Xr crypto 3 , 364.Xr tls_init 3 365.Sh HISTORY 366The 367.Nm 368document appeared in OpenSSL 0.9.2. 369