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