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.3353
1 files changed, 0 insertions, 353 deletions
diff --git a/src/lib/libssl/man/ssl.3 b/src/lib/libssl/man/ssl.3
deleted file mode 100644
index 314a1b0a94..0000000000
--- a/src/lib/libssl/man/ssl.3
+++ /dev/null
@@ -1,353 +0,0 @@
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.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-04-28 22:40:06 +0000