summaryrefslogtreecommitdiff
path: root/src/lib/libtls/man
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libtls/man')
-rw-r--r--src/lib/libtls/man/Makefile23
-rw-r--r--src/lib/libtls/man/tls_accept_socket.3107
-rw-r--r--src/lib/libtls/man/tls_client.3110
-rw-r--r--src/lib/libtls/man/tls_config_ocsp_require_stapling.340
-rw-r--r--src/lib/libtls/man/tls_config_set_protocols.3229
-rw-r--r--src/lib/libtls/man/tls_config_set_session_id.3105
-rw-r--r--src/lib/libtls/man/tls_config_verify.379
-rw-r--r--src/lib/libtls/man/tls_conn_version.3225
-rw-r--r--src/lib/libtls/man/tls_connect.3144
-rw-r--r--src/lib/libtls/man/tls_init.3180
-rw-r--r--src/lib/libtls/man/tls_load_file.3369
-rw-r--r--src/lib/libtls/man/tls_ocsp_process_response.3167
-rw-r--r--src/lib/libtls/man/tls_read.3240
13 files changed, 0 insertions, 2018 deletions
diff --git a/src/lib/libtls/man/Makefile b/src/lib/libtls/man/Makefile
deleted file mode 100644
index 4883377669..0000000000
--- a/src/lib/libtls/man/Makefile
+++ /dev/null
@@ -1,23 +0,0 @@
1# $OpenBSD: Makefile,v 1.1 2017/01/25 23:53:18 schwarze Exp $
2
3.include <bsd.own.mk>
4
5MAN = \
6 tls_accept_socket.3 \
7 tls_client.3 \
8 tls_config_ocsp_require_stapling.3 \
9 tls_config_set_protocols.3 \
10 tls_config_set_session_id.3 \
11 tls_config_verify.3 \
12 tls_conn_version.3 \
13 tls_connect.3 \
14 tls_init.3 \
15 tls_load_file.3 \
16 tls_ocsp_process_response.3 \
17 tls_read.3 \
18
19all clean cleandir depend includes obj tags:
20
21install: maninstall
22
23.include <bsd.man.mk>
diff --git a/src/lib/libtls/man/tls_accept_socket.3 b/src/lib/libtls/man/tls_accept_socket.3
deleted file mode 100644
index 931b9346ec..0000000000
--- a/src/lib/libtls/man/tls_accept_socket.3
+++ /dev/null
@@ -1,107 +0,0 @@
1.\" $OpenBSD: tls_accept_socket.3,v 1.4 2018/05/26 12:35:26 schwarze Exp $
2.\"
3.\" Copyright (c) 2015 Ted Unangst <tedu@openbsd.org>
4.\" Copyright (c) 2015 Joel Sing <jsing@openbsd.org>
5.\" Copyright (c) 2016 Brent Cook <bcook@openbsd.org>
6.\"
7.\" Permission to use, copy, modify, and distribute this software for any
8.\" purpose with or without fee is hereby granted, provided that the above
9.\" copyright notice and this permission notice appear in all copies.
10.\"
11.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
12.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
13.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
14.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
15.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
16.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
17.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18.\"
19.Dd $Mdocdate: May 26 2018 $
20.Dt TLS_ACCEPT_SOCKET 3
21.Os
22.Sh NAME
23.Nm tls_accept_socket ,
24.Nm tls_accept_fds ,
25.Nm tls_accept_cbs
26.Nd accept an incoming client connection in a TLS server
27.Sh SYNOPSIS
28.In tls.h
29.Ft int
30.Fo tls_accept_socket
31.Fa "struct tls *tls"
32.Fa "struct tls **cctx"
33.Fa "int socket"
34.Fc
35.Ft int
36.Fo tls_accept_fds
37.Fa "struct tls *tls"
38.Fa "struct tls **cctx"
39.Fa "int fd_read"
40.Fa "int fd_write"
41.Fc
42.Ft int
43.Fo tls_accept_cbs
44.Fa "struct tls *tls"
45.Fa "struct tls **cctx"
46.Fa "ssize_t (*tls_read_cb)(struct tls *ctx,\
47 void *buf, size_t buflen, void *cb_arg)"
48.Fa "ssize_t (*tls_write_cb)(struct tls *ctx,\
49 const void *buf, size_t buflen, void *cb_arg)"
50.Fa "void *cb_arg"
51.Fc
52.Sh DESCRIPTION
53After creating a TLS server context
54.Fa tls
55with
56.Xr tls_server 3
57and configuring it with
58.Xr tls_configure 3 ,
59a server can accept a new client connection by calling
60.Fn tls_accept_socket
61on an already established socket connection.
62.Pp
63Alternatively, a new client connection can be accepted over a pair of existing
64file descriptors by calling
65.Fn tls_accept_fds .
66.Pp
67Calling
68.Fn tls_accept_cbs
69allows read and write callback functions to handle data transfers.
70The specified
71.Fa cb_arg
72parameter is passed back to the functions,
73and can contain a pointer to any caller-specified data.
74.Pp
75All these functions create a new context suitable for reading and writing
76and return it in
77.Pf * Fa cctx .
78.Sh RETURN VALUES
79These functions return 0 on success or -1 on error.
80.Sh SEE ALSO
81.Xr tls_close 3 ,
82.Xr tls_config_set_session_id 3 ,
83.Xr tls_configure 3 ,
84.Xr tls_connect 3 ,
85.Xr tls_init 3 ,
86.Xr tls_server 3
87.Sh HISTORY
88.Fn tls_accept_socket
89appeared in
90.Ox 5.6
91and got its final name in
92.Ox 5.7 .
93.Pp
94.Fn tls_accept_fds
95appeared in
96.Ox 5.8
97and
98.Fn tls_accept_cbs
99in
100.Ox 6.1 .
101.Sh AUTHORS
102.An Joel Sing Aq Mt jsing@openbsd.org
103.Pp
104.An -nosplit
105.Fn tls_accept_cbs
106was written by
107.An Tobias Pape Aq Mt tobias@netshed.de .
diff --git a/src/lib/libtls/man/tls_client.3 b/src/lib/libtls/man/tls_client.3
deleted file mode 100644
index 98f58d4c20..0000000000
--- a/src/lib/libtls/man/tls_client.3
+++ /dev/null
@@ -1,110 +0,0 @@
1.\" $OpenBSD: tls_client.3,v 1.4 2017/08/12 03:41:48 jsing Exp $
2.\"
3.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: August 12 2017 $
18.Dt TLS_CLIENT 3
19.Os
20.Sh NAME
21.Nm tls_client ,
22.Nm tls_server ,
23.Nm tls_configure ,
24.Nm tls_reset ,
25.Nm tls_free
26.Nd configure a TLS connection
27.Sh SYNOPSIS
28.In tls.h
29.Ft struct tls *
30.Fn tls_client void
31.Ft struct tls *
32.Fn tls_server void
33.Ft int
34.Fo tls_configure
35.Fa "struct tls *ctx"
36.Fa "struct tls_config *config"
37.Fc
38.Ft void
39.Fn tls_free "struct tls *ctx"
40.Ft void
41.Fn tls_reset "struct tls *ctx"
42.Sh DESCRIPTION
43A TLS connection is represented as a
44.Vt struct tls
45object called a
46.Dq context .
47A new context is created by either the
48.Fn tls_client
49or
50.Fn tls_server
51functions.
52.Fn tls_client
53is used in TLS client programs,
54.Fn tls_server
55in TLS server programs.
56.Pp
57The context can then be configured with the function
58.Fn tls_configure .
59The same
60.Vt tls_config
61object can be used to configure multiple contexts.
62.Pp
63After configuration,
64.Xr tls_connect 3
65can be called on objects created with
66.Fn tls_client ,
67and
68.Xr tls_accept_socket 3
69on objects created with
70.Fn tls_server .
71.Pp
72After use, a TLS context should be closed with
73.Xr tls_close 3 ,
74and then freed by calling
75.Fn tls_free .
76If
77.Fn tls_free
78is called with an argument of
79.Dv NULL ,
80no action occurs.
81.Pp
82A TLS context can be reset by calling
83.Fn tls_reset ,
84allowing for it to be reused.
85This is essentially equivalent to calling
86.Fn tls_free ,
87followed by a call to the same function that was used to originally allocate
88the TLS context.
89.Sh RETURN VALUES
90.Fn tls_client
91and
92.Fn tls_server
93return
94.Dv NULL
95on error or an out of memory condition.
96.Pp
97.Fn tls_configure
98returns 0 on success or -1 on error.
99.Sh SEE ALSO
100.Xr tls_accept_socket 3 ,
101.Xr tls_config_new 3 ,
102.Xr tls_connect 3 ,
103.Xr tls_init 3
104.Sh HISTORY
105These functions appeared in
106.Ox 5.6
107and got their final names in
108.Ox 5.7 .
109.Sh AUTHORS
110.An Joel Sing Aq Mt jsing@openbsd.org
diff --git a/src/lib/libtls/man/tls_config_ocsp_require_stapling.3 b/src/lib/libtls/man/tls_config_ocsp_require_stapling.3
deleted file mode 100644
index a0694d304f..0000000000
--- a/src/lib/libtls/man/tls_config_ocsp_require_stapling.3
+++ /dev/null
@@ -1,40 +0,0 @@
1.\" $OpenBSD: tls_config_ocsp_require_stapling.3,v 1.5 2017/01/31 20:53:50 jmc Exp $
2.\"
3.\" Copyright (c) 2016 Bob Beck <beck@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: January 31 2017 $
18.Dt TLS_CONFIG_OCSP_REQUIRE_STAPLING 3
19.Os
20.Sh NAME
21.Nm tls_config_ocsp_require_stapling
22.Nd OCSP configuration for libtls
23.Sh SYNOPSIS
24.In tls.h
25.Ft void
26.Fn tls_config_ocsp_require_stapling "struct tls_config *config"
27.Sh DESCRIPTION
28.Fn tls_config_ocsp_require_stapling
29requires that a valid stapled OCSP response be provided
30during the TLS handshake.
31.Sh SEE ALSO
32.Xr tls_config_add_keypair_file 3 ,
33.Xr tls_handshake 3 ,
34.Xr tls_init 3 ,
35.Xr tls_ocsp_process_response 3
36.Sh HISTORY
37These functions appeared in
38.Ox 6.1 .
39.Sh AUTHORS
40.An Bob Beck Aq Mt beck@openbsd.org
diff --git a/src/lib/libtls/man/tls_config_set_protocols.3 b/src/lib/libtls/man/tls_config_set_protocols.3
deleted file mode 100644
index 32b8cce757..0000000000
--- a/src/lib/libtls/man/tls_config_set_protocols.3
+++ /dev/null
@@ -1,229 +0,0 @@
1.\" $OpenBSD: tls_config_set_protocols.3,v 1.12 2023/07/02 06:37:27 beck Exp $
2.\"
3.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org>
4.\" Copyright (c) 2015, 2016 Joel Sing <jsing@openbsd.org>
5.\" Copyright (c) 2015 Bob Beck <beck@openbsd.org>
6.\"
7.\" Permission to use, copy, modify, and distribute this software for any
8.\" purpose with or without fee is hereby granted, provided that the above
9.\" copyright notice and this permission notice appear in all copies.
10.\"
11.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
12.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
13.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
14.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
15.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
16.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
17.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18.\"
19.Dd $Mdocdate: July 2 2023 $
20.Dt TLS_CONFIG_SET_PROTOCOLS 3
21.Os
22.Sh NAME
23.Nm tls_config_set_protocols ,
24.Nm tls_config_parse_protocols ,
25.Nm tls_config_set_alpn ,
26.Nm tls_config_set_ciphers ,
27.Nm tls_config_set_dheparams ,
28.Nm tls_config_set_ecdhecurves ,
29.Nm tls_config_prefer_ciphers_client ,
30.Nm tls_config_prefer_ciphers_server
31.Nd TLS protocol and cipher selection
32.Sh SYNOPSIS
33.In tls.h
34.Ft int
35.Fo tls_config_set_protocols
36.Fa "struct tls_config *config"
37.Fa "uint32_t protocols"
38.Fc
39.Ft int
40.Fo tls_config_parse_protocols
41.Fa "uint32_t *protocols"
42.Fa "const char *protostr"
43.Fc
44.Ft int
45.Fo tls_config_set_alpn
46.Fa "struct tls_config *config"
47.Fa "const char *alpn"
48.Fc
49.Ft int
50.Fo tls_config_set_ciphers
51.Fa "struct tls_config *config"
52.Fa "const char *ciphers"
53.Fc
54.Ft int
55.Fo tls_config_set_dheparams
56.Fa "struct tls_config *config"
57.Fa "const char *params"
58.Fc
59.Ft int
60.Fo tls_config_set_ecdhecurves
61.Fa "struct tls_config *config"
62.Fa "const char *curves"
63.Fc
64.Ft void
65.Fn tls_config_prefer_ciphers_client "struct tls_config *config"
66.Ft void
67.Fn tls_config_prefer_ciphers_server "struct tls_config *config"
68.Sh DESCRIPTION
69These functions modify a configuration by setting parameters.
70The configuration options apply to both clients and servers, unless noted
71otherwise.
72.Pp
73.Fn tls_config_set_protocols
74specifies which versions of the TLS protocol may be used.
75Possible values are the bitwise OR of:
76.Pp
77.Bl -item -offset indent -compact
78.It
79.Dv TLS_PROTOCOL_TLSv1_2
80.It
81.Dv TLS_PROTOCOL_TLSv1_3
82.El
83.Pp
84Additionally, the values
85.Dv TLS_PROTOCOL_TLSv1
86(TLSv1.2, TLSv1.3),
87.Dv TLS_PROTOCOLS_ALL
88(all supported protocols) and
89.Dv TLS_PROTOCOLS_DEFAULT
90(TLSv1.2 and TLSv1.3) may be used.
91.Pp
92The
93.Fn tls_config_parse_protocols
94utility function parses a protocol string and returns the corresponding
95value via the
96.Ar protocols
97argument.
98This value can then be passed to the
99.Fn tls_config_set_protocols
100function.
101The protocol string is a comma or colon separated list of keywords.
102Valid keywords are:
103.Pp
104.Bl -tag -width "tlsv1.3" -offset indent -compact
105.It Dv tlsv1.2
106.It Dv tlsv1.3
107.It Dv all
108.Pq all supported protocols
109.It Dv default
110.Pq an alias for Dv secure
111.It Dv legacy
112.Pq an alias for Dv all
113.It Dv secure
114.Pq currently TLSv1.2 and TLSv1.3
115.El
116.Pp
117If a value has a negative prefix (in the form of a leading exclamation mark)
118then it is removed from the list of available protocols, rather than being
119added to it.
120.Pp
121.Fn tls_config_set_alpn
122sets the ALPN protocols that are supported.
123The alpn string is a comma separated list of protocols, in order of preference.
124.Pp
125.Fn tls_config_set_ciphers
126sets the list of ciphers that may be used.
127Lists of ciphers are specified by name, and the
128permitted names are:
129.Pp
130.Bl -item -offset indent -compact
131.It
132.Dv secure Pq or alias Dv default
133.It
134.Dv compat
135.It
136.Dv legacy
137.It
138.Dv insecure Pq or alias Dv all
139.El
140.Pp
141Alternatively, libssl cipher strings can be specified.
142See the CIPHERS section of
143.Xr openssl 1
144for further information.
145.Pp
146.Fn tls_config_set_dheparams
147specifies the parameters that will be used during Diffie-Hellman Ephemeral
148(DHE) key exchange.
149Possible values are:
150.Pp
151.Bl -item -offset indent -compact
152.It
153.Dv none
154.It
155.Dv auto
156.It
157.Dv legacy
158.El
159.Pp
160In
161.Dv auto
162mode, the key size for the ephemeral key is automatically selected
163based on the size of the private key being used for signing.
164In
165.Dv legacy
166mode, 1024 bit ephemeral keys are used.
167The default value is
168.Dv none ,
169which disables DHE key exchange.
170.Pp
171.Fn tls_config_set_ecdhecurves
172specifies the names of the elliptic curves that may be used during Elliptic
173Curve Diffie-Hellman Ephemeral (ECDHE) key exchange.
174This is a comma separated list, given in order of preference.
175The special value of "default" will use the default curves (currently X25519,
176P-256 and P-384).
177This function replaces
178.Fn tls_config_set_ecdhecurve ,
179which is deprecated.
180.Pp
181.Fn tls_config_prefer_ciphers_client
182prefers ciphers in the client's cipher list when selecting a cipher suite
183(server only).
184This is considered to be less secure than preferring the server's list.
185.Pp
186.Fn tls_config_prefer_ciphers_server
187prefers ciphers in the server's cipher list when selecting a cipher suite
188(server only).
189This is considered to be more secure than preferring the client's list and is
190the default.
191.Sh RETURN VALUES
192These functions return 0 on success or -1 on error.
193.Sh SEE ALSO
194.Xr tls_config_ocsp_require_stapling 3 ,
195.Xr tls_config_set_session_id 3 ,
196.Xr tls_config_verify 3 ,
197.Xr tls_init 3 ,
198.Xr tls_load_file 3
199.Sh HISTORY
200.Fn tls_config_set_ciphers
201appeared in
202.Ox 5.6
203and got its final name in
204.Ox 5.7 .
205.Pp
206.Fn tls_config_set_protocols ,
207.Fn tls_config_parse_protocols ,
208.Fn tls_config_set_dheparams ,
209and
210.Fn tls_config_set_ecdhecurve
211appeared in
212.Ox 5.7 ,
213.Fn tls_config_prefer_ciphers_client
214and
215.Fn tls_config_prefer_ciphers_server
216in
217.Ox 5.9 ,
218and
219.Fn tls_config_set_alpn
220in
221.Ox 6.1 .
222.Sh AUTHORS
223.An Joel Sing Aq Mt jsing@openbsd.org
224with contributions from
225.An Ted Unangst Aq Mt tedu@openbsd.org
226.Pq Fn tls_config_set_ciphers
227and
228.An Reyk Floeter Aq Mt reyk@openbsd.org
229.Pq Fn tls_config_set_ecdhecurve
diff --git a/src/lib/libtls/man/tls_config_set_session_id.3 b/src/lib/libtls/man/tls_config_set_session_id.3
deleted file mode 100644
index d969e01e33..0000000000
--- a/src/lib/libtls/man/tls_config_set_session_id.3
+++ /dev/null
@@ -1,105 +0,0 @@
1.\" $OpenBSD: tls_config_set_session_id.3,v 1.5 2018/02/10 06:07:43 jsing Exp $
2.\"
3.\" Copyright (c) 2017 Claudio Jeker <claudio@openbsd.org>
4.\" Copyright (c) 2018 Joel Sing <jsing@openbsd.org>
5.\"
6.\" Permission to use, copy, modify, and distribute this software for any
7.\" purpose with or without fee is hereby granted, provided that the above
8.\" copyright notice and this permission notice appear in all copies.
9.\"
10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17.\"
18.Dd $Mdocdate: February 10 2018 $
19.Dt TLS_CONFIG_SET_SESSION_ID 3
20.Os
21.Sh NAME
22.Nm tls_config_set_session_fd ,
23.Nm tls_config_set_session_id ,
24.Nm tls_config_set_session_lifetime ,
25.Nm tls_config_add_ticket_key
26.Nd configure resuming of TLS handshakes
27.Sh SYNOPSIS
28.In tls.h
29.Ft int
30.Fo tls_config_set_session_fd
31.Fa "struct tls_config *config"
32.Fa "int session_fd"
33.Fc
34.Ft int
35.Fo tls_config_set_session_id
36.Fa "struct tls_config *config"
37.Fa "const unsigned char *session_id"
38.Fa "size_t len"
39.Fc
40.Ft int
41.Fo tls_config_set_session_lifetime
42.Fa "struct tls_config *config"
43.Fa "int lifetime"
44.Fc
45.Ft int
46.Fo tls_config_add_ticket_key
47.Fa "struct tls_config *config"
48.Fa "uint32_t keyrev"
49.Fa "unsigned char *key"
50.Fa "size_t keylen"
51.Fc
52.Sh DESCRIPTION
53.Fn tls_config_set_session_fd
54sets a file descriptor to be used to manage data for TLS sessions (client only).
55The given file descriptor must be a regular file and be owned by the current
56user, with permissions being restricted to only allow the owner to read and
57write the file (0600).
58If the file has a non-zero length, the client will attempt to read session
59data from this file and resume the previous TLS session with the server.
60Upon a successful handshake the file will be updated with current session
61data, if available.
62The caller is responsible for closing this file descriptor, after all TLS
63contexts that have been configured to use it have been freed via
64.Fn tls_free .
65.Pp
66.Fn tls_config_set_session_id
67sets the session identifier that will be used by the TLS server when
68sessions are enabled (server only).
69By default a random value is used.
70.Pp
71.Fn tls_config_set_session_lifetime
72sets the lifetime to be used for TLS sessions (server only).
73Session support is disabled if a lifetime of zero is specified, which is the
74default.
75.Pp
76.Fn tls_config_add_ticket_key
77adds a key used for the encryption and authentication of TLS tickets
78(server only).
79By default keys are generated and rotated automatically based on their lifetime.
80This function should only be used to synchronise ticket encryption key across
81multiple processes.
82Re-adding a known key will result in an error, unless it is the most recently
83added key.
84.Sh RETURN VALUES
85These functions return 0 on success or -1 on error.
86.Sh SEE ALSO
87.Xr tls_accept_socket 3 ,
88.Xr tls_config_set_protocols 3 ,
89.Xr tls_init 3 ,
90.Xr tls_load_file 3 ,
91.Xr tls_server 3
92.Sh HISTORY
93.Fn tls_config_set_session_id ,
94.Fn tls_config_set_session_lifetime
95and
96.Fn tls_config_add_ticket_key
97appeared in
98.Ox 6.1 .
99.Pp
100.Fn tls_config_set_session_fd
101appeared in
102.Ox 6.3 .
103.Sh AUTHORS
104.An Claudio Jeker Aq Mt claudio@openbsd.org
105.An Joel Sing Aq Mt jsing@openbsd.org
diff --git a/src/lib/libtls/man/tls_config_verify.3 b/src/lib/libtls/man/tls_config_verify.3
deleted file mode 100644
index 4a43c834d7..0000000000
--- a/src/lib/libtls/man/tls_config_verify.3
+++ /dev/null
@@ -1,79 +0,0 @@
1.\" $OpenBSD: tls_config_verify.3,v 1.4 2017/03/02 11:05:50 jmc Exp $
2.\"
3.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org>
4.\" Copyright (c) 2015 Joel Sing <jsing@openbsd.org>
5.\"
6.\" Permission to use, copy, modify, and distribute this software for any
7.\" purpose with or without fee is hereby granted, provided that the above
8.\" copyright notice and this permission notice appear in all copies.
9.\"
10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17.\"
18.Dd $Mdocdate: March 2 2017 $
19.Dt TLS_CONFIG_VERIFY 3
20.Os
21.Sh NAME
22.Nm tls_config_verify ,
23.Nm tls_config_insecure_noverifycert ,
24.Nm tls_config_insecure_noverifyname ,
25.Nm tls_config_insecure_noverifytime
26.Nd insecure TLS configuration
27.Sh SYNOPSIS
28.In tls.h
29.Ft void
30.Fn tls_config_verify "struct tls_config *config"
31.Ft void
32.Fn tls_config_insecure_noverifycert "struct tls_config *config"
33.Ft void
34.Fn tls_config_insecure_noverifyname "struct tls_config *config"
35.Ft void
36.Fn tls_config_insecure_noverifytime "struct tls_config *config"
37.Sh DESCRIPTION
38These functions disable parts of the normal certificate verification
39process, resulting in insecure configurations.
40Be very careful when using them.
41.Pp
42.Fn tls_config_insecure_noverifycert
43disables certificate verification and OCSP validation.
44.Pp
45.Fn tls_config_insecure_noverifyname
46disables server name verification (client only).
47.Pp
48.Fn tls_config_insecure_noverifytime
49disables validity checking of certificates and OCSP validation.
50.Pp
51.Fn tls_config_verify
52reenables server name and certificate verification.
53.Sh SEE ALSO
54.Xr tls_client 3 ,
55.Xr tls_config_ocsp_require_stapling 3 ,
56.Xr tls_config_set_protocols 3 ,
57.Xr tls_conn_version 3 ,
58.Xr tls_connect 3 ,
59.Xr tls_handshake 3 ,
60.Xr tls_init 3
61.Sh HISTORY
62.Fn tls_config_verify
63appeared in
64.Ox 5.6
65and got its final name in
66.Ox 5.7 .
67.Pp
68.Fn tls_config_insecure_noverifycert
69and
70.Fn tls_config_insecure_noverifyname
71appeared in
72.Ox 5.7
73and
74.Nm tls_config_insecure_noverifytime
75in
76.Ox 5.9 .
77.Sh AUTHORS
78.An Joel Sing Aq Mt jsing@openbsd.org
79.An Ted Unangst Aq Mt tedu@openbsd.org
diff --git a/src/lib/libtls/man/tls_conn_version.3 b/src/lib/libtls/man/tls_conn_version.3
deleted file mode 100644
index 8fb30624d7..0000000000
--- a/src/lib/libtls/man/tls_conn_version.3
+++ /dev/null
@@ -1,225 +0,0 @@
1.\" $OpenBSD: tls_conn_version.3,v 1.11 2024/12/10 08:42:12 tb Exp $
2.\"
3.\" Copyright (c) 2015 Bob Beck <beck@openbsd.org>
4.\" Copyright (c) 2016, 2018 Joel Sing <jsing@openbsd.org>
5.\"
6.\" Permission to use, copy, modify, and distribute this software for any
7.\" purpose with or without fee is hereby granted, provided that the above
8.\" copyright notice and this permission notice appear in all copies.
9.\"
10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17.\"
18.Dd $Mdocdate: December 10 2024 $
19.Dt TLS_CONN_VERSION 3
20.Os
21.Sh NAME
22.Nm tls_conn_version ,
23.Nm tls_conn_cipher ,
24.Nm tls_conn_cipher_strength ,
25.Nm tls_conn_alpn_selected ,
26.Nm tls_conn_servername ,
27.Nm tls_conn_session_resumed ,
28.Nm tls_peer_cert_provided ,
29.Nm tls_peer_cert_contains_name ,
30.Nm tls_peer_cert_chain_pem ,
31.Nm tls_peer_cert_issuer ,
32.Nm tls_peer_cert_subject ,
33.Nm tls_peer_cert_common_name ,
34.Nm tls_peer_cert_hash ,
35.Nm tls_peer_cert_notbefore ,
36.Nm tls_peer_cert_notafter
37.Nd inspect an established TLS connection
38.Sh SYNOPSIS
39.In tls.h
40.Ft const char *
41.Fn tls_conn_version "struct tls *ctx"
42.Ft const char *
43.Fn tls_conn_cipher "struct tls *ctx"
44.Ft int
45.Fn tls_conn_cipher_strength "struct tls *ctx"
46.Ft const char *
47.Fn tls_conn_alpn_selected "struct tls *ctx"
48.Ft const char *
49.Fn tls_conn_servername "struct tls *ctx"
50.Ft int
51.Fn tls_conn_session_resumed "struct tls *ctx"
52.Ft int
53.Fn tls_peer_cert_provided "struct tls *ctx"
54.Ft int
55.Fo tls_peer_cert_contains_name
56.Fa "struct tls *ctx"
57.Fa "const char *name"
58.Fc
59.Ft const uint8_t *
60.Fo tls_peer_cert_chain_pem
61.Fa "struct tls *ctx"
62.Fa "size_t *size"
63.Fc
64.Ft const char *
65.Fn tls_peer_cert_issuer "struct tls *ctx"
66.Ft const char *
67.Fn tls_peer_cert_subject "struct tls *ctx"
68.Ft const char *
69.Fn tls_peer_cert_common_name "struct tls *ctx"
70.Ft const char *
71.Fn tls_peer_cert_hash "struct tls *ctx"
72.Ft time_t
73.Fn tls_peer_cert_notbefore "struct tls *ctx"
74.Ft time_t
75.Fn tls_peer_cert_notafter "struct tls *ctx"
76.Sh DESCRIPTION
77These functions return information about a TLS connection and will only
78succeed after the handshake is complete (the connection information applies
79to both clients and servers, unless noted otherwise):
80.Pp
81.Fn tls_conn_version
82returns a string corresponding to a TLS version negotiated with the peer
83connected to
84.Ar ctx .
85.Pp
86.Fn tls_conn_cipher
87returns a string corresponding to the cipher suite negotiated with the peer
88connected to
89.Ar ctx .
90.Pp
91.Fn tls_conn_cipher_strength
92returns the strength in bits for the symmetric cipher that is being
93used with the peer connected to
94.Ar ctx .
95.Pp
96.Fn tls_conn_alpn_selected
97returns a string that specifies the ALPN protocol selected for use with the peer
98connected to
99.Ar ctx .
100If no protocol was selected then NULL is returned.
101.Pp
102.Fn tls_conn_servername
103returns a string corresponding to the servername that the client connected to
104.Ar ctx
105requested by sending a TLS Server Name Indication extension (server only).
106.Pp
107.Fn tls_conn_session_resumed
108indicates whether a TLS session has been resumed during the handshake with
109the server connected to
110.Ar ctx
111(client only).
112.Pp
113.Fn tls_peer_cert_provided
114checks if the peer of
115.Ar ctx
116has provided a certificate.
117.Pp
118.Fn tls_peer_cert_contains_name
119checks if the peer of a TLS
120.Ar ctx
121has provided a certificate that contains a
122SAN or CN that matches
123.Ar name .
124.Pp
125.Fn tls_peer_cert_chain_pem
126returns a pointer to memory containing a PEM-encoded certificate chain for the
127peer certificate from
128.Ar ctx .
129.Pp
130.Fn tls_peer_cert_subject
131returns a string
132corresponding to the subject of the peer certificate from
133.Ar ctx .
134.Pp
135.Fn tls_peer_cert_issuer
136returns a string
137corresponding to the issuer of the peer certificate from
138.Ar ctx .
139.Fn tls_peer_cert_common_name
140returns a string
141corresponding to the common name of the peer certificate from
142.Ar ctx
143or the empty string if no common name is present.
144.Pp
145.Fn tls_peer_cert_hash
146returns a string
147corresponding to a hash of the raw peer certificate from
148.Ar ctx
149prefixed by a hash name followed by a colon.
150The hash currently used is SHA256, though this
151could change in the future.
152The hash string for a certificate in file
153.Ar mycert.crt
154can be generated using the commands:
155.Bd -literal -offset indent
156h=$(openssl x509 -outform der -in mycert.crt | sha256)
157printf "SHA256:${h}\\n"
158.Ed
159.Pp
160.Fn tls_peer_cert_notbefore
161returns the time corresponding to the start of the validity period of
162the peer certificate from
163.Ar ctx .
164.Pp
165.Fn tls_peer_cert_notafter
166returns the time corresponding to the end of the validity period of
167the peer certificate from
168.Ar ctx .
169.Sh RETURN VALUES
170The
171.Fn tls_conn_session_resumed
172function returns 1 if a TLS session was resumed or 0 if it was not.
173.Pp
174The
175.Fn tls_peer_cert_provided
176and
177.Fn tls_peer_cert_contains_name
178functions return 1 if the check succeeds or 0 if it does not.
179.Pp
180.Fn tls_peer_cert_notbefore
181and
182.Fn tls_peer_cert_notafter
183return a time in epoch-seconds on success or -1 on error.
184.Pp
185The functions that return a pointer return
186.Dv NULL
187on error or an out of memory condition.
188.Sh SEE ALSO
189.Xr tls_configure 3 ,
190.Xr tls_handshake 3 ,
191.Xr tls_init 3 ,
192.Xr tls_ocsp_process_response 3
193.Sh HISTORY
194.Fn tls_conn_version ,
195.Fn tls_conn_cipher ,
196.Fn tls_peer_cert_provided ,
197.Fn tls_peer_cert_contains_name ,
198.Fn tls_peer_cert_issuer ,
199.Fn tls_peer_cert_subject ,
200.Fn tls_peer_cert_hash ,
201.Fn tls_peer_cert_notbefore ,
202and
203.Fn tls_peer_cert_notafter
204appeared in
205.Ox 5.9 .
206.Pp
207.Fn tls_conn_servername
208and
209.Fn tls_conn_alpn_selected
210appeared in
211.Ox 6.1 .
212.Pp
213.Fn tls_conn_session_resumed
214appeared in
215.Ox 6.3 .
216.Pp
217.Fn tls_conn_cipher_strength
218appeared in
219.Ox 6.7 .
220.Fn tls_peer_cert_common_name
221appeared in
222.Ox 7.7 .
223.Sh AUTHORS
224.An Bob Beck Aq Mt beck@openbsd.org
225.An Joel Sing Aq Mt jsing@openbsd.org
diff --git a/src/lib/libtls/man/tls_connect.3 b/src/lib/libtls/man/tls_connect.3
deleted file mode 100644
index 4c4f01c256..0000000000
--- a/src/lib/libtls/man/tls_connect.3
+++ /dev/null
@@ -1,144 +0,0 @@
1.\" $OpenBSD: tls_connect.3,v 1.4 2018/07/09 19:51:18 tb Exp $
2.\"
3.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org>
4.\" Copyright (c) 2014, 2015 Joel Sing <jsing@openbsd.org>
5.\" Copyright (c) 2016 Brent Cook <bcook@openbsd.org>
6.\"
7.\" Permission to use, copy, modify, and distribute this software for any
8.\" purpose with or without fee is hereby granted, provided that the above
9.\" copyright notice and this permission notice appear in all copies.
10.\"
11.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
12.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
13.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
14.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
15.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
16.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
17.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18.\"
19.Dd $Mdocdate: July 9 2018 $
20.Dt TLS_CONNECT 3
21.Os
22.Sh NAME
23.Nm tls_connect ,
24.Nm tls_connect_fds ,
25.Nm tls_connect_servername ,
26.Nm tls_connect_socket ,
27.Nm tls_connect_cbs
28.Nd instruct a TLS client to establish a connection
29.Sh SYNOPSIS
30.In tls.h
31.Ft int
32.Fo tls_connect
33.Fa "struct tls *ctx"
34.Fa "const char *host"
35.Fa "const char *port"
36.Fc
37.Ft int
38.Fo tls_connect_fds
39.Fa "struct tls *ctx"
40.Fa "int fd_read"
41.Fa "int fd_write"
42.Fa "const char *servername"
43.Fc
44.Ft int
45.Fo tls_connect_servername
46.Fa "struct tls *ctx"
47.Fa "const char *host"
48.Fa "const char *port"
49.Fa "const char *servername"
50.Fc
51.Ft int
52.Fo tls_connect_socket
53.Fa "struct tls *ctx"
54.Fa "int s"
55.Fa "const char *servername"
56.Fc
57.Ft int
58.Fo tls_connect_cbs
59.Fa "struct tls *ctx"
60.Fa "ssize_t (*tls_read_cb)(struct tls *ctx,\
61 void *buf, size_t buflen, void *cb_arg)"
62.Fa "ssize_t (*tls_write_cb)(struct tls *ctx,\
63 const void *buf, size_t buflen, void *cb_arg)"
64.Fa "void *cb_arg"
65.Fa "const char *servername"
66.Fc
67.Sh DESCRIPTION
68After creating a TLS client context with
69.Xr tls_client 3
70and configuring it with
71.Xr tls_configure 3 ,
72a client connection is initiated by calling
73.Fn tls_connect .
74This function will create a new socket, connect to the specified
75.Fa host
76and
77.Fa port ,
78and then establish a secure connection.
79The
80.Fa port
81may be numeric or a service name.
82If it is
83.Dv NULL ,
84then a
85.Fa host
86of the format "hostname:port" is permitted.
87The name to use for verification is inferred from the
88.Ar host
89value.
90.Pp
91The
92.Fn tls_connect_servername
93function has the same behaviour, however the name to use for verification is
94explicitly provided, for the case where the TLS server name differs from the
95DNS name.
96.Pp
97An already existing socket can be upgraded to a secure connection by calling
98.Fn tls_connect_socket .
99.Pp
100Alternatively, a secure connection can be established over a pair of existing
101file descriptors by calling
102.Fn tls_connect_fds .
103.Pp
104Calling
105.Fn tls_connect_cbs
106allows read and write callback functions to handle data transfers.
107The specified cb_arg parameter is passed back to the functions,
108and can contain a pointer to any caller-specified data.
109.Sh RETURN VALUES
110These functions return 0 on success or -1 on error.
111.Sh SEE ALSO
112.Xr tls_accept_socket 3 ,
113.Xr tls_client 3 ,
114.Xr tls_close 3 ,
115.Xr tls_config_ocsp_require_stapling 3 ,
116.Xr tls_configure 3 ,
117.Xr tls_handshake 3 ,
118.Xr tls_init 3
119.Sh HISTORY
120.Fn tls_connect
121and
122.Fn tls_connect_socket
123appeared in
124.Ox 5.6
125and got their final names in
126.Ox 5.7 .
127.Pp
128.Fn tls_connect_fds
129and
130.Fn tls_connect_servername
131appeared in
132.Ox 5.7
133and
134.Fn tls_connect_cbs
135in
136.Ox 6.1 .
137.Sh AUTHORS
138.An Joel Sing Aq Mt jsing@openbsd.org
139.An Reyk Floeter Aq Mt reyk@openbsd.org
140.Pp
141.An -nosplit
142.Fn tls_connect_cbs
143was written by
144.An Tobias Pape Aq Mt tobias@netshed.de .
diff --git a/src/lib/libtls/man/tls_init.3 b/src/lib/libtls/man/tls_init.3
deleted file mode 100644
index 557998107c..0000000000
--- a/src/lib/libtls/man/tls_init.3
+++ /dev/null
@@ -1,180 +0,0 @@
1.\" $OpenBSD: tls_init.3,v 1.13 2018/07/09 19:47:20 tb Exp $
2.\"
3.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org>
4.\" Copyright (c) 2016 Joel Sing <jsing@openbsd.org>
5.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
6.\"
7.\" Permission to use, copy, modify, and distribute this software for any
8.\" purpose with or without fee is hereby granted, provided that the above
9.\" copyright notice and this permission notice appear in all copies.
10.\"
11.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
12.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
13.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
14.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
15.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
16.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
17.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18.\"
19.Dd $Mdocdate: July 9 2018 $
20.Dt TLS_INIT 3
21.Os
22.Sh NAME
23.Nm tls_init ,
24.Nm tls_config_new ,
25.Nm tls_config_free ,
26.Nm tls_config_error
27.Nd initialize TLS client and server API
28.Sh SYNOPSIS
29.In tls.h
30.Ft int
31.Fn tls_init void
32.Ft struct tls_config *
33.Fn tls_config_new void
34.Ft void
35.Fn tls_config_free "struct tls_config *config"
36.Ft const char *
37.Fn tls_config_error "struct tls_config *config"
38.Sh DESCRIPTION
39The
40.Nm tls
41family of functions establishes a secure communications channel
42using the TLS socket protocol.
43Both clients and servers are supported.
44.Pp
45The
46.Fn tls_init
47function initializes global data structures.
48It is no longer necessary to call this function directly,
49since it is invoked internally when needed.
50It may be called more than once, and may be called concurrently.
51.Pp
52Before a connection is created, a configuration must be created.
53The
54.Fn tls_config_new
55function allocates, initializes, and returns a new default configuration
56object that can be used for future connections.
57Several functions exist to change the options of the configuration; see
58.Xr tls_config_set_protocols 3 ,
59.Xr tls_load_file 3 ,
60.Xr tls_config_ocsp_require_stapling 3 ,
61and
62.Xr tls_config_verify 3 .
63.Pp
64The
65.Fn tls_config_error
66function may be used to retrieve a string containing more information
67about the most recent error relating to a configuration.
68.Pp
69A TLS connection object is created by
70.Xr tls_client 3
71or
72.Xr tls_server 3
73and configured with
74.Xr tls_configure 3 .
75.Pp
76A client connection is initiated after configuration by calling
77.Xr tls_connect 3 .
78A server can accept a new client connection by calling
79.Xr tls_accept_socket 3
80on an already established socket connection.
81.Pp
82Two functions are provided for input and output,
83.Xr tls_read 3
84and
85.Xr tls_write 3 .
86Both automatically perform the
87.Xr tls_handshake 3
88when needed.
89.Pp
90The properties of established TLS connections
91can be inspected with the functions described in
92.Xr tls_conn_version 3
93and
94.Xr tls_ocsp_process_response 3 .
95.Pp
96After use, a TLS connection should be closed with
97.Xr tls_close 3
98and then freed by calling
99.Xr tls_free 3 .
100.Pp
101When no more contexts are to be configured,
102the configuration object should be freed by calling
103.Fn tls_config_free .
104It is safe to call
105.Fn tls_config_free
106as soon as the final call to
107.Fn tls_configure
108has been made.
109If
110.Fa config
111is
112.Dv NULL ,
113no action occurs.
114.Sh RETURN VALUES
115.Fn tls_init
116returns 0 on success or -1 on error.
117.Pp
118.Fn tls_config_new
119returns
120.Dv NULL
121on error or an out of memory condition.
122.Pp
123.Fn tls_config_error
124returns
125.Dv NULL
126if no error occurred with
127.Fa config
128at all, or if memory allocation failed while trying to assemble the
129string describing the most recent error related to
130.Fa config .
131.Sh SEE ALSO
132.Xr tls_accept_socket 3 ,
133.Xr tls_client 3 ,
134.Xr tls_config_ocsp_require_stapling 3 ,
135.Xr tls_config_set_protocols 3 ,
136.Xr tls_config_verify 3 ,
137.Xr tls_conn_version 3 ,
138.Xr tls_connect 3 ,
139.Xr tls_load_file 3 ,
140.Xr tls_ocsp_process_response 3 ,
141.Xr tls_read 3
142.Sh HISTORY
143The
144.Nm tls
145API first appeared in
146.Ox 5.6
147as a response to the unnecessary challenges other APIs present in
148order to use them safely.
149.Pp
150All functions were renamed from
151.Fn ressl_*
152to
153.Fn tls_*
154for
155.Ox 5.7 .
156.Pp
157.Fn tls_config_error
158appeared in
159.Ox 6.0 .
160.Sh AUTHORS
161.An Joel Sing Aq Mt jsing@openbsd.org
162.An Ted Unangst Aq Mt tedu@openbsd.org
163.Pp
164Many others contributed to various parts of the library; see the
165individual manual pages for more information.
166.Sh CAVEATS
167The function
168.Fn tls_config_error
169returns an internal pointer.
170It must not be freed by the application, or a double free error
171will occur.
172The pointer will become invalid when the next error occurs with
173.Fa config .
174Consequently, if the application may need the message at a later
175time, it has to copy the string before calling the next
176.Sy libtls
177function involving
178.Fa config ,
179or a segmentation fault or read access to unintended data is the
180likely result.
diff --git a/src/lib/libtls/man/tls_load_file.3 b/src/lib/libtls/man/tls_load_file.3
deleted file mode 100644
index cf33b575ef..0000000000
--- a/src/lib/libtls/man/tls_load_file.3
+++ /dev/null
@@ -1,369 +0,0 @@
1.\" $OpenBSD: tls_load_file.3,v 1.14 2022/01/01 02:18:28 jsg Exp $
2.\"
3.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org>
4.\" Copyright (c) 2015 Reyk Floeter <reyk@openbsd.org>
5.\" Copyright (c) 2015 Bob Beck <beck@openbsd.org>
6.\" Copyright (c) 2016, 2017 Joel Sing <jsing@openbsd.org>
7.\"
8.\" Permission to use, copy, modify, and distribute this software for any
9.\" purpose with or without fee is hereby granted, provided that the above
10.\" copyright notice and this permission notice appear in all copies.
11.\"
12.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
13.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
14.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
15.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
16.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
17.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
18.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
19.\"
20.Dd $Mdocdate: January 1 2022 $
21.Dt TLS_LOAD_FILE 3
22.Os
23.Sh NAME
24.Nm tls_load_file ,
25.Nm tls_unload_file ,
26.Nm tls_config_set_ca_file ,
27.Nm tls_config_set_ca_path ,
28.Nm tls_config_set_ca_mem ,
29.Nm tls_config_set_cert_file ,
30.Nm tls_config_set_cert_mem ,
31.Nm tls_config_set_crl_file ,
32.Nm tls_config_set_crl_mem ,
33.Nm tls_config_set_key_file ,
34.Nm tls_config_set_key_mem ,
35.Nm tls_config_set_ocsp_staple_mem ,
36.Nm tls_config_set_ocsp_staple_file ,
37.Nm tls_config_set_keypair_file ,
38.Nm tls_config_set_keypair_mem ,
39.Nm tls_config_set_keypair_ocsp_file ,
40.Nm tls_config_set_keypair_ocsp_mem ,
41.Nm tls_config_add_keypair_file ,
42.Nm tls_config_add_keypair_ocsp_mem ,
43.Nm tls_config_add_keypair_ocsp_file ,
44.Nm tls_config_add_keypair_mem ,
45.Nm tls_config_clear_keys ,
46.Nm tls_config_set_verify_depth ,
47.Nm tls_config_verify_client ,
48.Nm tls_config_verify_client_optional ,
49.Nm tls_default_ca_cert_file
50.Nd TLS certificate and key configuration
51.Sh SYNOPSIS
52.In tls.h
53.Ft uint8_t *
54.Fo tls_load_file
55.Fa "const char *file"
56.Fa "size_t *len"
57.Fa "char *password"
58.Fc
59.Ft void
60.Fo tls_unload_file
61.Fa "uint8_t *buf"
62.Fa "size_t len"
63.Fc
64.Ft int
65.Fo tls_config_set_ca_file
66.Fa "struct tls_config *config"
67.Fa "const char *ca_file"
68.Fc
69.Ft int
70.Fo tls_config_set_ca_path
71.Fa "struct tls_config *config"
72.Fa "const char *ca_path"
73.Fc
74.Ft int
75.Fo tls_config_set_ca_mem
76.Fa "struct tls_config *config"
77.Fa "const uint8_t *cert"
78.Fa "size_t len"
79.Fc
80.Ft int
81.Fo tls_config_set_cert_file
82.Fa "struct tls_config *config"
83.Fa "const char *cert_file"
84.Fc
85.Ft int
86.Fo tls_config_set_cert_mem
87.Fa "struct tls_config *config"
88.Fa "const uint8_t *cert"
89.Fa "size_t len"
90.Fc
91.Ft int
92.Fo tls_config_set_crl_file
93.Fa "struct tls_config *config"
94.Fa "const char *crl_file"
95.Fc
96.Ft int
97.Fo tls_config_set_crl_mem
98.Fa "struct tls_config *config"
99.Fa "const uint8_t *crl"
100.Fa "size_t len"
101.Fc
102.Ft int
103.Fo tls_config_set_key_file
104.Fa "struct tls_config *config"
105.Fa "const char *key_file"
106.Fc
107.Ft int
108.Fo tls_config_set_key_mem
109.Fa "struct tls_config *config"
110.Fa "const uint8_t *key"
111.Fa "size_t len"
112.Fc
113.Ft int
114.Fo tls_config_set_ocsp_staple_mem
115.Fa "struct tls_config *config"
116.Fa "const uint8_t *staple"
117.Fa "size_t len"
118.Fc
119.Ft int
120.Fo tls_config_set_ocsp_staple_file
121.Fa "struct tls_config *config"
122.Fa "const char *staple_file"
123.Fc
124.Ft int
125.Fo tls_config_set_keypair_file
126.Fa "struct tls_config *config"
127.Fa "const char *cert_file"
128.Fa "const char *key_file"
129.Fc
130.Ft int
131.Fo tls_config_set_keypair_mem
132.Fa "struct tls_config *config"
133.Fa "const uint8_t *cert"
134.Fa "size_t cert_len"
135.Fa "const uint8_t *key"
136.Fa "size_t key_len"
137.Fc
138.Ft int
139.Fo tls_config_set_keypair_ocsp_file
140.Fa "struct tls_config *config"
141.Fa "const char *cert_file"
142.Fa "const char *key_file"
143.Fa "const char *staple_file"
144.Fc
145.Ft int
146.Fo tls_config_set_keypair_ocsp_mem
147.Fa "struct tls_config *config"
148.Fa "const uint8_t *cert"
149.Fa "size_t cert_len"
150.Fa "const uint8_t *key"
151.Fa "size_t key_len"
152.Fa "const uint8_t *staple"
153.Fa "size_t staple_len"
154.Fc
155.Ft int
156.Fo tls_config_add_keypair_file
157.Fa "struct tls_config *config"
158.Fa "const char *cert_file"
159.Fa "const char *key_file"
160.Fc
161.Ft int
162.Fo tls_config_add_keypair_mem
163.Fa "struct tls_config *config"
164.Fa "const uint8_t *cert"
165.Fa "size_t cert_len"
166.Fa "const uint8_t *key"
167.Fa "size_t key_len"
168.Fc
169.Ft int
170.Fo tls_config_add_keypair_ocsp_file
171.Fa "struct tls_config *config"
172.Fa "const char *cert_file"
173.Fa "const char *key_file"
174.Fa "const char *staple_file"
175.Fc
176.Ft int
177.Fo tls_config_add_keypair_ocsp_mem
178.Fa "struct tls_config *config"
179.Fa "const uint8_t *cert"
180.Fa "size_t cert_len"
181.Fa "const uint8_t *key"
182.Fa "size_t key_len"
183.Fa "const uint8_t *staple"
184.Fa "size_t staple_len"
185.Fc
186.Ft void
187.Fn tls_config_clear_keys "struct tls_config *config"
188.Ft int
189.Fo tls_config_set_verify_depth
190.Fa "struct tls_config *config"
191.Fa "int verify_depth"
192.Fc
193.Ft void
194.Fn tls_config_verify_client "struct tls_config *config"
195.Ft void
196.Fn tls_config_verify_client_optional "struct tls_config *config"
197.Ft const char *
198.Fn tls_default_ca_cert_file "void"
199.Sh DESCRIPTION
200.Fn tls_load_file
201loads a certificate or key from disk into memory to be used with
202.Fn tls_config_set_ca_mem ,
203.Fn tls_config_set_cert_mem ,
204.Fn tls_config_set_crl_mem
205or
206.Fn tls_config_set_key_mem .
207A private key will be decrypted if the optional
208.Ar password
209argument is specified.
210.Pp
211.Fn tls_unload_file
212unloads the memory that was returned from an earlier
213.Fn tls_load_file
214call, ensuring that the memory contents is discarded.
215.Pp
216.Fn tls_default_ca_cert_file
217returns the path of the file that contains the default root certificates.
218.Pp
219.Fn tls_config_set_ca_file
220loads a file containing the root certificates.
221.Pp
222.Fn tls_config_set_ca_path
223sets the path (directory) which should be searched for root
224certificates.
225.Pp
226.Fn tls_config_set_ca_mem
227sets the root certificates directly from memory.
228.Pp
229.Fn tls_config_set_cert_file
230loads a file containing the public certificate.
231.Pp
232.Fn tls_config_set_cert_mem
233sets the public certificate directly from memory.
234.Pp
235.Fn tls_config_set_crl_file
236loads a file containing the Certificate Revocation List (CRL).
237.Pp
238.Fn tls_config_set_crl_mem
239sets the CRL directly from memory.
240.Pp
241.Fn tls_config_set_key_file
242loads a file containing the private key.
243.Pp
244.Fn tls_config_set_key_mem
245directly sets the private key from memory.
246.Pp
247.Fn tls_config_set_ocsp_staple_file
248loads a file containing a DER-encoded OCSP response to be stapled
249during the TLS handshake.
250.Pp
251.Fn tls_config_set_ocsp_staple_mem
252sets a DER-encoded OCSP response to be stapled during the TLS handshake from
253memory.
254.Pp
255.Fn tls_config_set_keypair_file
256loads two files from which the public certificate and private key will be read.
257.Pp
258.Fn tls_config_set_keypair_mem
259directly sets the public certificate and private key from memory.
260.Pp
261.Fn tls_config_set_keypair_ocsp_file
262loads three files containing the public certificate, private key,
263and DER-encoded OCSP staple.
264.Pp
265.Fn tls_config_set_keypair_ocsp_mem
266directly sets the public certificate, private key, and DER-encoded OCSP staple
267from memory.
268.Pp
269.Fn tls_config_add_keypair_file
270adds an additional public certificate and private key from the specified files,
271used as an alternative certificate for Server Name Indication (server only).
272.Pp
273.Fn tls_config_add_keypair_mem
274adds an additional public certificate and private key from memory, used as an
275alternative certificate for Server Name Indication (server only).
276.Pp
277.Fn tls_config_add_keypair_ocsp_file
278adds an additional public certificate, private key, and DER-encoded OCSP staple
279from the specified files, used as an alternative certificate for Server Name
280Indication (server only).
281.Pp
282.Fn tls_config_add_keypair_ocsp_mem
283adds an additional public certificate, private key, and DER-encoded OCSP staple
284from memory, used as an alternative certificate for Server Name Indication
285(server only).
286.Pp
287.Fn tls_config_clear_keys
288clears any secret keys from memory.
289.Pp
290.Fn tls_config_set_verify_depth
291limits the number of intermediate certificates that will be followed during
292certificate validation.
293.Pp
294.Fn tls_config_verify_client
295enables client certificate verification, requiring the client to send
296a certificate (server only).
297.Pp
298.Fn tls_config_verify_client_optional
299enables client certificate verification, without requiring the client
300to send a certificate (server only).
301.Sh RETURN VALUES
302.Fn tls_load_file
303returns
304.Dv NULL
305on error or an out of memory condition.
306.Pp
307The other functions return 0 on success or -1 on error.
308.Sh SEE ALSO
309.Xr tls_config_ocsp_require_stapling 3 ,
310.Xr tls_config_set_protocols 3 ,
311.Xr tls_config_set_session_id 3 ,
312.Xr tls_configure 3 ,
313.Xr tls_init 3
314.Sh HISTORY
315.Fn tls_config_set_ca_file ,
316.Fn tls_config_set_ca_path ,
317.Fn tls_config_set_cert_file ,
318.Fn tls_config_set_cert_mem ,
319.Fn tls_config_set_key_file ,
320.Fn tls_config_set_key_mem ,
321and
322.Fn tls_config_set_verify_depth
323appeared in
324.Ox 5.6
325and got their final names in
326.Ox 5.7 .
327.Pp
328.Fn tls_load_file ,
329.Fn tls_config_set_ca_mem ,
330and
331.Fn tls_config_clear_keys
332appeared in
333.Ox 5.7 .
334.Pp
335.Fn tls_config_verify_client
336and
337.Fn tls_config_verify_client_optional
338appeared in
339.Ox 5.9 .
340.Pp
341.Fn tls_config_set_keypair_file
342and
343.Fn tls_config_set_keypair_mem
344appeared in
345.Ox 6.0 ,
346and
347.Fn tls_config_add_keypair_file
348and
349.Fn tls_config_add_keypair_mem
350in
351.Ox 6.1 .
352.Pp
353.Fn tls_config_set_crl_file
354and
355.Fn tls_config_set_crl_mem
356appeared in
357.Ox 6.2 .
358.Sh AUTHORS
359.An Joel Sing Aq Mt jsing@openbsd.org
360with contributions from
361.An Ted Unangst Aq Mt tedu@openbsd.org
362and
363.An Bob Beck Aq Mt beck@openbsd.org .
364.Pp
365.Fn tls_load_file
366and
367.Fn tls_config_set_ca_mem
368were written by
369.An Reyk Floeter Aq Mt reyk@openbsd.org .
diff --git a/src/lib/libtls/man/tls_ocsp_process_response.3 b/src/lib/libtls/man/tls_ocsp_process_response.3
deleted file mode 100644
index 6e3aa4aecc..0000000000
--- a/src/lib/libtls/man/tls_ocsp_process_response.3
+++ /dev/null
@@ -1,167 +0,0 @@
1.\" $OpenBSD: tls_ocsp_process_response.3,v 1.6 2018/07/24 02:01:34 tb Exp $
2.\"
3.\" Copyright (c) 2016 Bob Beck <beck@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: July 24 2018 $
18.Dt TLS_OCSP_PROCESS_RESPONSE 3
19.Os
20.Sh NAME
21.Nm tls_ocsp_process_response ,
22.Nm tls_peer_ocsp_url ,
23.Nm tls_peer_ocsp_response_status ,
24.Nm tls_peer_ocsp_cert_status ,
25.Nm tls_peer_ocsp_crl_reason ,
26.Nm tls_peer_ocsp_result ,
27.Nm tls_peer_ocsp_revocation_time ,
28.Nm tls_peer_ocsp_this_update ,
29.Nm tls_peer_ocsp_next_update
30.Nd inspect an OCSP response
31.Sh SYNOPSIS
32.In tls.h
33.Ft int
34.Fo tls_ocsp_process_response
35.Fa "struct tls *ctx"
36.Fa "const unsigned char *response"
37.Fa "size_t size"
38.Fc
39.Ft const char *
40.Fn tls_peer_ocsp_url "struct tls *ctx"
41.Ft int
42.Fn tls_peer_ocsp_response_status "struct tls *ctx"
43.Ft int
44.Fn tls_peer_ocsp_cert_status "struct tls *ctx"
45.Ft int
46.Fn tls_peer_ocsp_crl_reason "struct tls *ctx"
47.Ft const char *
48.Fn tls_peer_ocsp_result "struct tls *ctx"
49.Ft time_t
50.Fn tls_peer_ocsp_revocation_time "struct tls *ctx"
51.Ft time_t
52.Fn tls_peer_ocsp_this_update "struct tls *ctx"
53.Ft time_t
54.Fn tls_peer_ocsp_next_update "struct tls *ctx"
55.Sh DESCRIPTION
56.Fn tls_ocsp_process_response
57processes a raw OCSP response in
58.Ar response
59of size
60.Ar size
61to check the revocation status of the peer certificate from
62.Ar ctx .
63A successful return code of 0 indicates that the certificate
64has not been revoked.
65.Pp
66.Fn tls_peer_ocsp_url
67returns the URL for OCSP validation of the peer certificate from
68.Ar ctx .
69.Pp
70The following functions return information about the peer certificate from
71.Ar ctx
72that was obtained by validating a stapled OCSP response during the handshake,
73or via a previous call to
74.Fn tls_ocsp_process_response .
75.Pp
76.Fn tls_peer_ocsp_response_status
77returns the OCSP response status as per RFC 6960 section 2.3.
78.Pp
79.Fn tls_peer_ocsp_cert_status
80returns the OCSP certificate status code as per RFC 6960 section 2.2.
81.Pp
82.Fn tls_peer_ocsp_crl_reason
83returns the OCSP certificate revocation reason status code as per RFC 5280
84section 5.3.1.
85.Pp
86.Fn tls_peer_ocsp_result
87returns a textual representation of the OCSP status code
88returned by one of the previous three functions.
89If the OCSP response was valid and the certificate was not
90revoked, the string indicates the OCSP certificate status.
91Otherwise, the string indicates
92the OCSP certificate revocation reason or the OCSP error.
93.Pp
94.Fn tls_peer_ocsp_revocation_time
95returns the OCSP revocation time.
96.Pp
97.Fn tls_peer_ocsp_this_update
98returns the OCSP this update time.
99.Pp
100.Fn tls_peer_ocsp_next_update
101returns the OCSP next update time.
102.Sh RETURN VALUES
103.Fn tls_ocsp_process_response
104returns 0 on success or -1 on error.
105.Pp
106.Fn tls_peer_ocsp_url
107and
108.Fn tls_peer_ocsp_result
109return
110.Dv NULL
111on error or an out of memory condition.
112.Pp
113The
114.Fn tls_peer_ocsp_response_status
115function returns one of
116.Dv TLS_OCSP_RESPONSE_SUCCESSFUL ,
117.Dv TLS_OCSP_RESPONSE_MALFORMED ,
118.Dv TLS_OCSP_RESPONSE_INTERNALERROR ,
119.Dv TLS_OCSP_RESPONSE_TRYLATER ,
120.Dv TLS_OCSP_RESPONSE_SIGREQUIRED ,
121or
122.Dv TLS_OCSP_RESPONSE_UNAUTHORIZED
123on success or -1 on error.
124.Pp
125The
126.Fn tls_peer_ocsp_cert_status
127function returns one of
128.Dv TLS_OCSP_CERT_GOOD ,
129.Dv TLS_OCSP_CERT_REVOKED ,
130or
131.Dv TLS_OCSP_CERT_UNKNOWN
132on success, and -1 on error.
133.Pp
134The
135.Fn tls_peer_ocsp_crl_reason
136function returns one of
137.Dv TLS_CRL_REASON_UNSPECIFIED ,
138.Dv TLS_CRL_REASON_KEY_COMPROMISE ,
139.Dv TLS_CRL_REASON_CA_COMPROMISE ,
140.Dv TLS_CRL_REASON_AFFILIATION_CHANGED ,
141.Dv TLS_CRL_REASON_SUPERSEDED ,
142.Dv TLS_CRL_REASON_CESSATION_OF_OPERATION ,
143.Dv TLS_CRL_REASON_CERTIFICATE_HOLD ,
144.Dv TLS_CRL_REASON_REMOVE_FROM_CRL ,
145.Dv TLS_CRL_REASON_PRIVILEGE_WITHDRAWN ,
146or
147.Dv TLS_CRL_REASON_AA_COMPROMISE
148on success or -1 on error.
149.Pp
150.Fn tls_peer_ocsp_revocation_time ,
151.Fn tls_peer_ocsp_this_update ,
152and
153.Fn tls_peer_ocsp_next_update
154return a time in epoch-seconds on success or -1 on error.
155.Sh SEE ALSO
156.Xr tls_client 3 ,
157.Xr tls_config_ocsp_require_stapling 3 ,
158.Xr tls_conn_version 3 ,
159.Xr tls_connect 3 ,
160.Xr tls_handshake 3 ,
161.Xr tls_init 3
162.Sh HISTORY
163These functions appeared in
164.Ox 6.1 .
165.Sh AUTHORS
166.An Bob Beck Aq Mt beck@openbsd.org
167.An Marko Kreen Aq Mt markokr@gmail.com
diff --git a/src/lib/libtls/man/tls_read.3 b/src/lib/libtls/man/tls_read.3
deleted file mode 100644
index f9d949eef5..0000000000
--- a/src/lib/libtls/man/tls_read.3
+++ /dev/null
@@ -1,240 +0,0 @@
1.\" $OpenBSD: tls_read.3,v 1.8 2023/09/18 17:25:15 schwarze Exp $
2.\"
3.\" Copyright (c) 2014, 2015 Ted Unangst <tedu@openbsd.org>
4.\" Copyright (c) 2015 Doug Hogan <doug@openbsd.org>
5.\" Copyright (c) 2015 Joel Sing <jsing@openbsd.org>
6.\" Copyright (c) 2015 Bob Beck <beck@openbsd.org>
7.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
8.\"
9.\" Permission to use, copy, modify, and distribute this software for any
10.\" purpose with or without fee is hereby granted, provided that the above
11.\" copyright notice and this permission notice appear in all copies.
12.\"
13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20.\"
21.Dd $Mdocdate: September 18 2023 $
22.Dt TLS_READ 3
23.Os
24.Sh NAME
25.Nm tls_read ,
26.Nm tls_write ,
27.Nm tls_handshake ,
28.Nm tls_error ,
29.Nm tls_close
30.Nd use a TLS connection
31.Sh SYNOPSIS
32.In tls.h
33.Ft ssize_t
34.Fo tls_read
35.Fa "struct tls *ctx"
36.Fa "void *buf"
37.Fa "size_t buflen"
38.Fc
39.Ft ssize_t
40.Fo tls_write
41.Fa "struct tls *ctx"
42.Fa "const void *buf"
43.Fa "size_t buflen"
44.Fc
45.Ft int
46.Fn tls_handshake "struct tls *ctx"
47.Ft const char *
48.Fn tls_error "struct tls *ctx"
49.Ft int
50.Fn tls_close "struct tls *ctx"
51.Sh DESCRIPTION
52.Fn tls_read
53reads
54.Fa buflen
55bytes of data from the socket into
56.Fa buf .
57It returns the amount of data read.
58.Pp
59.Fn tls_write
60writes
61.Fa buflen
62bytes of data from
63.Fa buf
64to the socket.
65It returns the amount of data written.
66.Pp
67.Fn tls_handshake
68explicitly performs the TLS handshake.
69It is only necessary to call this function if you need to guarantee that the
70handshake has completed, as both
71.Fn tls_read
72and
73.Fn tls_write
74automatically perform the TLS handshake when necessary.
75.Pp
76The
77.Fn tls_error
78function may be used to retrieve a string containing more information
79about the most recent error relating to a context.
80.Pp
81.Fn tls_close
82closes a connection after use.
83Only the TLS layer will be shut down and the caller is responsible for closing
84the file descriptors, unless the connection was established using
85.Xr tls_connect 3
86or
87.Xr tls_connect_servername 3 .
88After closing the connection,
89.Fa ctx
90can be passed to
91.Xr tls_free 3 .
92.Sh RETURN VALUES
93.Fn tls_read
94and
95.Fn tls_write
96return a size on success or -1 on error.
97.Pp
98.Fn tls_handshake
99and
100.Fn tls_close
101return 0 on success or -1 on error.
102.Pp
103The
104.Fn tls_read ,
105.Fn tls_write ,
106.Fn tls_handshake ,
107and
108.Fn tls_close
109functions also have two special return values:
110.Pp
111.Bl -tag -width "TLS_WANT_POLLOUT" -offset indent -compact
112.It Dv TLS_WANT_POLLIN
113The underlying read file descriptor needs to be readable in order to continue.
114.It Dv TLS_WANT_POLLOUT
115The underlying write file descriptor needs to be writeable in order to continue.
116.El
117.Pp
118In the case of blocking file descriptors, the same function call should be
119repeated immediately.
120In the case of non-blocking file descriptors, the same function call should be
121repeated when the required condition has been met.
122.Pp
123Callers of these functions cannot rely on the value of the global
124.Ar errno .
125To prevent mishandling of error conditions,
126.Fn tls_read ,
127.Fn tls_write ,
128.Fn tls_handshake ,
129and
130.Fn tls_close
131all explicitly clear
132.Ar errno .
133.Pp
134.Fn tls_error
135returns
136.Dv NULL
137if no error occurred with
138.Fa ctx
139during or since the last call to
140.Fn tls_handshake ,
141.Fn tls_read ,
142.Fn tls_write ,
143.Fn tls_close ,
144or
145.Xr tls_reset 3
146involving
147.Fa ctx ,
148or if memory allocation failed while trying to assemble the string
149describing the most recent error related to
150.Fa ctx .
151.Sh EXAMPLES
152The following example demonstrates how to handle TLS writes on a blocking
153file descriptor:
154.Bd -literal -offset indent
155\&...
156while (len > 0) {
157 ssize_t ret;
158
159 ret = tls_write(ctx, buf, len);
160 if (ret == TLS_WANT_POLLIN || ret == TLS_WANT_POLLOUT)
161 continue;
162 if (ret == -1)
163 errx(1, "tls_write: %s", tls_error(ctx));
164 buf += ret;
165 len -= ret;
166}
167\&...
168.Ed
169.Pp
170The following example demonstrates how to handle TLS writes on a
171non-blocking file descriptor using
172.Xr poll 2 :
173.Bd -literal -offset indent
174\&...
175pfd[0].fd = fd;
176pfd[0].events = POLLIN|POLLOUT;
177while (len > 0) {
178 nready = poll(pfd, 1, 0);
179 if (nready == -1)
180 err(1, "poll");
181 if ((pfd[0].revents & (POLLERR|POLLNVAL)))
182 errx(1, "bad fd %d", pfd[0].fd);
183 if ((pfd[0].revents & (pfd[0].events|POLLHUP))) {
184 ssize_t ret;
185
186 ret = tls_write(ctx, buf, len);
187 if (ret == TLS_WANT_POLLIN)
188 pfd[0].events = POLLIN;
189 else if (ret == TLS_WANT_POLLOUT)
190 pfd[0].events = POLLOUT;
191 else if (ret == -1)
192 errx(1, "tls_write: %s", tls_error(ctx));
193 else {
194 buf += ret;
195 len -= ret;
196 }
197 }
198}
199\&...
200.Ed
201.Sh SEE ALSO
202.Xr tls_accept_socket 3 ,
203.Xr tls_configure 3 ,
204.Xr tls_conn_version 3 ,
205.Xr tls_connect 3 ,
206.Xr tls_init 3 ,
207.Xr tls_ocsp_process_response 3
208.Sh HISTORY
209.Fn tls_read ,
210.Fn tls_write ,
211.Fn tls_error ,
212and
213.Fn tls_close
214appeared in
215.Ox 5.6
216and got their final names in
217.Ox 5.7 .
218.Pp
219.Fn tls_handshake
220appeared in
221.Ox 5.9 .
222.Sh AUTHORS
223.An Joel Sing Aq Mt jsing@openbsd.org
224with contributions from
225.An Bob Beck Aq Mt beck@openbsd.org
226.Sh CAVEATS
227The function
228.Fn tls_error
229returns an internal pointer.
230It must not be freed by the application, or a double free error
231will occur.
232The pointer will become invalid when the next error occurs with
233.Fa ctx .
234Consequently, if the application may need the message at a later
235time, it has to copy the string before calling the next
236.Sy libtls
237function involving
238.Fa ctx ,
239or a segmentation fault or read access to unintended data is the
240likely result.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-12-27 01:34:26 +0000