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