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