1.\" $OpenBSD: ssl.3,v 1.26 2024/08/31 10:51:48 tb 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: August 31 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 ssl3.h 151That's the sub header file dealing with the SSLv3 protocol only. 152.Bf Em 153Usually you don't have to include it explicitly because it's already included 154by 155.Pa ssl.h . 156.Ef 157.It Pa tls1.h 158That's the sub header file dealing with the TLSv1 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.El 165.Sh API FUNCTIONS 166.Ss Ciphers 167The following pages describe functions acting on 168.Vt SSL_CIPHER 169objects: 170.Xr SSL_get_ciphers 3 , 171.Xr SSL_get_current_cipher 3 , 172.Xr SSL_CIPHER_get_name 3 173.Ss Protocol contexts 174The following pages describe functions acting on 175.Vt SSL_CTX 176objects. 177.Pp 178Constructors and destructors: 179.Xr SSL_CTX_new 3 , 180.Xr SSL_CTX_set_ssl_version 3 , 181.Xr SSL_CTX_free 3 182.Pp 183Certificate configuration: 184.Xr SSL_CTX_add_extra_chain_cert 3 , 185.Xr SSL_CTX_get0_certificate 3 , 186.Xr SSL_CTX_load_verify_locations 3 , 187.Xr SSL_CTX_set_cert_store 3 , 188.Xr SSL_CTX_set_cert_verify_callback 3 , 189.Xr SSL_CTX_set_client_cert_cb 3 , 190.Xr SSL_CTX_set_default_passwd_cb 3 , 191.Xr SSL_CTX_set_tlsext_status_cb 3 192.Pp 193Session configuration: 194.Xr SSL_CTX_add_session 3 , 195.Xr SSL_CTX_flush_sessions 3 , 196.Xr SSL_CTX_sess_number 3 , 197.Xr SSL_CTX_sess_set_cache_size 3 , 198.Xr SSL_CTX_sess_set_get_cb 3 , 199.Xr SSL_CTX_sessions 3 , 200.Xr SSL_CTX_set_session_cache_mode 3 , 201.Xr SSL_CTX_set_timeout 3 , 202.Xr SSL_CTX_set_tlsext_ticket_key_cb 3 203.Pp 204Various configuration: 205.Xr SSL_CTX_get_ex_new_index 3 , 206.Xr SSL_CTX_set_tlsext_servername_callback 3 207.Ss Common configuration of contexts and connections 208The functions on the following pages each come in two variants: 209one to directly configure a single 210.Vt SSL 211connection and another to be called on an 212.Vt SSL_CTX 213object, to set up defaults for all future 214.Vt SSL 215connections created from that context. 216.Pp 217Protocol and algorithm configuration: 218.Xr SSL_CTX_set_alpn_select_cb 3 , 219.Xr SSL_CTX_set_cipher_list 3 , 220.Xr SSL_CTX_set_min_proto_version 3 , 221.Xr SSL_CTX_set_options 3 , 222.Xr SSL_CTX_set_security_level 3 , 223.Xr SSL_CTX_set_tlsext_use_srtp 3 , 224.Xr SSL_CTX_set_tmp_dh_callback 3 , 225.Xr SSL_CTX_set1_groups 3 226.Pp 227Certificate configuration: 228.Xr SSL_CTX_add1_chain_cert 3 , 229.Xr SSL_CTX_get_verify_mode 3 , 230.Xr SSL_CTX_set_client_CA_list 3 , 231.Xr SSL_CTX_set_max_cert_list 3 , 232.Xr SSL_CTX_set_verify 3 , 233.Xr SSL_CTX_use_certificate 3 , 234.Xr SSL_get_client_CA_list 3 235.Xr SSL_set1_param 3 236.Pp 237Session configuration: 238.Xr SSL_CTX_set_generate_session_id 3 , 239.Xr SSL_CTX_set_session_id_context 3 240.Pp 241Various configuration: 242.Xr SSL_CTX_ctrl 3 , 243.Xr SSL_CTX_set_info_callback 3 , 244.Xr SSL_CTX_set_mode 3 , 245.Xr SSL_CTX_set_msg_callback 3 , 246.Xr SSL_CTX_set_quiet_shutdown 3 , 247.Xr SSL_CTX_set_read_ahead 3 , 248.Xr SSL_set_max_send_fragment 3 249.Ss Sessions 250The following pages describe functions acting on 251.Vt SSL_SESSION 252objects. 253.Pp 254Constructors and destructors: 255.Xr SSL_SESSION_new 3 , 256.Xr SSL_SESSION_free 3 257.Pp 258Accessors: 259.Xr SSL_SESSION_get_compress_id 3 , 260.Xr SSL_SESSION_get_ex_new_index 3 , 261.Xr SSL_SESSION_get_id 3 , 262.Xr SSL_SESSION_get_protocol_version 3 , 263.Xr SSL_SESSION_get_time 3 , 264.Xr SSL_SESSION_get0_peer 3 , 265.Xr SSL_SESSION_has_ticket 3 , 266.Xr SSL_SESSION_set1_id_context 3 267.Pp 268Encoding and decoding: 269.Xr d2i_SSL_SESSION 3 , 270.Xr PEM_read_SSL_SESSION 3 , 271.Xr SSL_SESSION_print 3 272.Ss Connections 273The following pages describe functions acting on 274.Vt SSL 275connection objects: 276.Pp 277Constructors and destructors: 278.Xr SSL_new 3 , 279.Xr SSL_dup 3 , 280.Xr SSL_free 3 , 281.Xr BIO_f_ssl 3 282.Pp 283To change the configuration: 284.Xr SSL_clear 3 , 285.Xr SSL_set_SSL_CTX 3 , 286.Xr SSL_copy_session_id 3 , 287.Xr SSL_set_bio 3 , 288.Xr SSL_set_connect_state 3 , 289.Xr SSL_set_fd 3 , 290.Xr SSL_set_session 3 , 291.Xr SSL_set1_host 3 , 292.Xr SSL_set_verify_result 3 293.Pp 294To inspect the configuration: 295.Xr SSL_get_certificate 3 , 296.Xr SSL_get_default_timeout 3 , 297.Xr SSL_get_ex_new_index 3 , 298.Xr SSL_get_fd 3 , 299.Xr SSL_get_rbio 3 , 300.Xr SSL_get_SSL_CTX 3 301.Pp 302To transmit data: 303.Xr DTLSv1_listen 3 , 304.Xr SSL_accept 3 , 305.Xr SSL_connect 3 , 306.Xr SSL_do_handshake 3 , 307.Xr SSL_read 3 , 308.Xr SSL_read_early_data 3 , 309.Xr SSL_renegotiate 3 , 310.Xr SSL_shutdown 3 , 311.Xr SSL_write 3 312.Pp 313To inspect the state after a connection is established: 314.Xr SSL_export_keying_material 3 , 315.Xr SSL_get_client_random 3 , 316.Xr SSL_get_ex_data_X509_STORE_CTX_idx 3 , 317.Xr SSL_get_peer_cert_chain 3 , 318.Xr SSL_get_peer_certificate 3 , 319.Xr SSL_get_server_tmp_key 3 , 320.Xr SSL_get_servername 3 , 321.Xr SSL_get_session 3 , 322.Xr SSL_get_shared_ciphers 3 , 323.Xr SSL_get_verify_result 3 , 324.Xr SSL_get_version 3 , 325.Xr SSL_session_reused 3 326.Pp 327To inspect the state during ongoing communication: 328.Xr SSL_get_error 3 , 329.Xr SSL_get_shutdown 3 , 330.Xr SSL_get_state 3 , 331.Xr SSL_num_renegotiations 3 , 332.Xr SSL_pending 3 , 333.Xr SSL_rstate_string 3 , 334.Xr SSL_state_string 3 , 335.Xr SSL_want 3 336.Ss Utility functions 337.Xr SSL_alert_type_string 3 , 338.Xr SSL_dup_CA_list 3 , 339.Xr SSL_load_client_CA_file 3 340.Ss Obsolete functions 341.Xr OPENSSL_init_ssl 3 , 342.Xr SSL_COMP_get_compression_methods 3 , 343.Xr SSL_CTX_set_tmp_rsa_callback 3 , 344.Xr SSL_library_init 3 , 345.Xr SSL_set_tmp_ecdh 3 346.Sh SEE ALSO 347.Xr openssl 1 , 348.Xr crypto 3 , 349.Xr tls_init 3 350.Sh HISTORY 351The 352.Nm 353document appeared in OpenSSL 0.9.2. 354