1.\" $OpenBSD: ssl.3,v 1.15 2019/04/05 18:29:43 schwarze Exp $ 2.\" full merge up to: OpenSSL e330f55d Nov 11 00:51:04 2016 +0100 3.\" selective merge up to: OpenSSL cbade361 Dec 12 13:14:45 2017 +0100 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: April 5 2019 $ 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 65At first the library must be initialized; see 66.Xr SSL_library_init 3 . 67.Pp 68Then an 69.Vt SSL_CTX 70object is created as a framework to establish TLS/SSL enabled connections (see 71.Xr SSL_CTX_new 3 ) . 72Various options regarding certificates, algorithms, etc., can be set in this 73object. 74.Pp 75When a network connection has been created, it can be assigned to an 76.Vt SSL 77object. 78After the 79.Vt SSL 80object has been created using 81.Xr SSL_new 3 , 82.Xr SSL_set_fd 3 83or 84.Xr SSL_set_bio 3 85can be used to associate the network connection with the object. 86.Pp 87Then the TLS/SSL handshake is performed using 88.Xr SSL_accept 3 89or 90.Xr SSL_connect 3 91respectively. 92.Xr SSL_read 3 93and 94.Xr SSL_write 3 95are used to read and write data on the TLS/SSL connection. 96.Xr SSL_shutdown 3 97can be used to shut down the TLS/SSL connection. 98.Sh DATA STRUCTURES 99Currently the OpenSSL 100.Nm ssl 101library functions deal with the following data structures: 102.Bl -tag -width Ds 103.It Vt SSL_METHOD No (SSL Method) 104That's a dispatch structure describing the internal 105.Nm ssl 106library methods/functions which implement the various protocol versions. 107It's needed to create an 108.Vt SSL_CTX . 109See 110.Xr TLS_method 3 111for constructors. 112.It Vt SSL_CIPHER No (SSL Cipher) 113This structure holds the algorithm information for a particular cipher which 114is a core part of the SSL/TLS protocol. 115The available ciphers are configured on an 116.Vt SSL_CTX 117basis and the actually used ones are then part of the 118.Vt SSL_SESSION . 119.It Vt SSL_CTX No (SSL Context) 120That's the global context structure which is created by a server or client 121once per program lifetime and which holds mainly default values for the 122.Vt SSL 123structures which are later created for the connections. 124.It Vt SSL_SESSION No (SSL Session) 125This is a structure containing the current TLS/SSL session details for a 126connection: 127.Vt SSL_CIPHER Ns s , 128client and server certificates, keys, etc. 129.It Vt SSL No (SSL Connection) 130That's the main SSL/TLS structure which is created by a server or client per 131established connection. 132This actually is the core structure in the SSL API. 133At run-time the application usually deals with this structure which has 134links to mostly all other structures. 135.El 136.Sh HEADER FILES 137Currently the OpenSSL 138.Nm ssl 139library provides the following C header files containing the prototypes for the 140data structures and functions: 141.Bl -tag -width Ds 142.It Pa ssl.h 143That's the common header file for the SSL/TLS API. 144Include it into your program to make the API of the 145.Nm ssl 146library available. 147It internally includes both more private SSL headers and headers from the 148.Em crypto 149library. 150Whenever you need hardcore details on the internals of the SSL API, look inside 151this header file. 152.It Pa ssl2.h 153That's the sub header file dealing with the SSLv2 protocol only. 154.Bf Em 155 Usually you don't have to include it explicitly because it's already included 156by 157.Pa ssl.h . 158.Ef 159.It Pa ssl3.h 160That's the sub header file dealing with the SSLv3 protocol only. 161.Bf Em 162Usually you don't have to include it explicitly because it's already included 163by 164.Pa ssl.h . 165.Ef 166.It Pa ssl23.h 167That's the sub header file dealing with the combined use of the SSLv2 and SSLv3 168protocols. 169.Bf Em 170Usually you don't have to include it explicitly because it's already included 171by 172.Pa ssl.h . 173.Ef 174.It Pa tls1.h 175That's the sub header file dealing with the TLSv1 protocol only. 176.Bf Em 177Usually you don't have to include it explicitly because it's already included 178by 179.Pa ssl.h . 180.Ef 181.El 182.Sh API FUNCTIONS 183.Ss Ciphers 184The following pages describe functions acting on 185.Vt SSL_CIPHER 186objects: 187.Xr SSL_get_ciphers 3 , 188.Xr SSL_get_current_cipher 3 , 189.Xr SSL_CIPHER_get_name 3 190.Ss Protocol contexts 191The following pages describe functions acting on 192.Vt SSL_CTX 193objects. 194Many of these pages also document variants providing similar 195functionality for individual connection objects. 196.Pp 197Constructors and destructors: 198.Xr SSL_CTX_new 3 , 199.Xr SSL_CTX_set_ssl_version 3 , 200.Xr SSL_CTX_free 3 201.Pp 202Configuration functions: 203.Xr SSL_CTX_add1_chain_cert 3 , 204.Xr SSL_CTX_add_extra_chain_cert 3 , 205.Xr SSL_CTX_ctrl 3 , 206.Xr SSL_CTX_flush_sessions 3 , 207.Xr SSL_CTX_get_verify_mode 3 , 208.Xr SSL_CTX_load_verify_locations 3 , 209.Xr SSL_CTX_sess_set_get_cb 3 , 210.Xr SSL_CTX_set_alpn_select_cb 3 , 211.Xr SSL_CTX_set_cert_store 3 , 212.Xr SSL_CTX_set_cert_verify_callback 3 , 213.Xr SSL_CTX_set_cipher_list 3 , 214.Xr SSL_CTX_set_client_CA_list 3 , 215.Xr SSL_CTX_set_client_cert_cb 3 , 216.Xr SSL_CTX_set_default_passwd_cb 3 , 217.Xr SSL_CTX_set_generate_session_id 3 , 218.Xr SSL_CTX_set_info_callback 3 , 219.Xr SSL_CTX_set_min_proto_version 3 , 220.Xr SSL_CTX_set_msg_callback 3 , 221.Xr SSL_CTX_set_options 3 , 222.Xr SSL_CTX_set_quiet_shutdown 3 , 223.Xr SSL_CTX_set_read_ahead 3 , 224.Xr SSL_CTX_set_session_id_context 3 , 225.Xr SSL_CTX_set_timeout 3 , 226.Xr SSL_CTX_set_tmp_dh_callback 3 , 227.Xr SSL_CTX_set_tmp_rsa_callback 3 , 228.Xr SSL_CTX_set_verify 3 , 229.Xr SSL_CTX_set1_groups 3 , 230.Xr SSL_CTX_use_certificate 3 , 231.Xr SSL_set_tmp_ecdh 3 , 232.Xr SSL_set1_param 3 233.Pp 234Accessors: 235.Xr SSL_CTX_get_ex_new_index 3 , 236.Xr SSL_CTX_sessions 3 , 237.Xr SSL_get_client_CA_list 3 238.Ss Sessions 239The following pages describe functions acting on 240.Vt SSL_SESSION 241objects. 242.Pp 243Constructors and destructors: 244.Xr SSL_SESSION_new 3 , 245.Xr SSL_SESSION_free 3 246.Pp 247Accessors: 248.Xr SSL_SESSION_get_compress_id 3 , 249.Xr SSL_SESSION_get_ex_new_index 3 , 250.Xr SSL_SESSION_get_id 3 , 251.Xr SSL_SESSION_get_protocol_version 3 , 252.Xr SSL_SESSION_get_time 3 , 253.Xr SSL_SESSION_get0_peer 3 , 254.Xr SSL_SESSION_has_ticket 3 , 255.Xr SSL_SESSION_set1_id_context 3 256.Pp 257Encoding and decoding: 258.Xr d2i_SSL_SESSION 3 , 259.Xr PEM_read_SSL_SESSION 3 , 260.Xr SSL_SESSION_print 3 261.Pp 262Use by other objects: 263.Xr SSL_CTX_add_session 3 , 264.Xr SSL_set_session 3 , 265.Xr SSL_get_session 3 266.Ss Connections 267The following pages describe functions acting on 268.Vt SSL 269connection objects: 270.Pp 271Constructors and destructors: 272.Xr SSL_new 3 , 273.Xr SSL_set_connect_state 3 , 274.Xr SSL_dup 3 , 275.Xr SSL_set_bio 3 , 276.Xr SSL_set_fd 3 , 277.Xr BIO_f_ssl 3 , 278.Xr SSL_clear 3 , 279.Xr SSL_free 3 280.Pp 281I/O: 282.Xr DTLSv1_listen 3 , 283.Xr SSL_accept 3 , 284.Xr SSL_connect 3 , 285.Xr SSL_do_handshake 3 , 286.Xr SSL_read 3 , 287.Xr SSL_renegotiate 3 , 288.Xr SSL_shutdown 3 , 289.Xr SSL_write 3 290.Pp 291Accessors: 292.Xr SSL_copy_session_id 3 , 293.Xr SSL_export_keying_material 3 , 294.Xr SSL_get_SSL_CTX 3 , 295.Xr SSL_get_certificate 3 , 296.Xr SSL_get_client_random 3 , 297.Xr SSL_get_default_timeout 3 , 298.Xr SSL_get_error 3 , 299.Xr SSL_get_ex_data_X509_STORE_CTX_idx 3 , 300.Xr SSL_get_ex_new_index 3 , 301.Xr SSL_get_fd 3 , 302.Xr SSL_get_peer_cert_chain 3 , 303.Xr SSL_get_peer_certificate 3 , 304.Xr SSL_get_rbio 3 , 305.Xr SSL_get_shared_ciphers 3 , 306.Xr SSL_get_state 3 , 307.Xr SSL_get_verify_result 3 , 308.Xr SSL_get_version 3 , 309.Xr SSL_pending 3 , 310.Xr SSL_rstate_string 3 , 311.Xr SSL_set_shutdown 3 , 312.Xr SSL_set_verify_result 3 , 313.Xr SSL_state_string 3 , 314.Xr SSL_want 3 315.Pp 316Utility functions: 317.Xr SSL_alert_type_string 3 , 318.Xr SSL_dup_CA_list 3 , 319.Xr SSL_load_client_CA_file 3 320.Sh SEE ALSO 321.Xr openssl 1 , 322.Xr crypto 3 , 323.Xr SSL_load_error_strings 3 324.Sh HISTORY 325The 326.Nm 327document appeared in OpenSSL 0.9.2. 328