summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--src/lib/libtls/Makefile9
-rw-r--r--src/lib/libtls/man/Makefile23
-rw-r--r--src/lib/libtls/man/tls_accept_socket.384
-rw-r--r--src/lib/libtls/man/tls_client.387
-rw-r--r--src/lib/libtls/man/tls_config_ocsp_require_stapling.359
-rw-r--r--src/lib/libtls/man/tls_config_set_protocols.3146
-rw-r--r--src/lib/libtls/man/tls_config_set_session_id.370
-rw-r--r--src/lib/libtls/man/tls_config_verify.359
-rw-r--r--src/lib/libtls/man/tls_conn_version.3154
-rw-r--r--src/lib/libtls/man/tls_connect.3114
-rw-r--r--src/lib/libtls/man/tls_init.3126
-rw-r--r--src/lib/libtls/man/tls_load_file.3197
-rw-r--r--src/lib/libtls/man/tls_ocsp_process_response.3154
-rw-r--r--src/lib/libtls/man/tls_read.3195
-rw-r--r--src/lib/libtls/tls_init.3885
15 files changed, 1474 insertions, 888 deletions
diff --git a/src/lib/libtls/Makefile b/src/lib/libtls/Makefile
index af860bb067..d528ddf5ee 100644
--- a/src/lib/libtls/Makefile
+++ b/src/lib/libtls/Makefile
@@ -1,4 +1,9 @@
1# $OpenBSD: Makefile,v 1.29 2016/11/05 08:12:22 jsing Exp $ 1# $OpenBSD: Makefile,v 1.30 2017/01/25 23:53:18 schwarze Exp $
2
3.include <bsd.own.mk>
4.ifndef NOMAN
5SUBDIR= man
6.endif
2 7
3CFLAGS+= -Wall -Werror -Wimplicit 8CFLAGS+= -Wall -Werror -Wimplicit
4CFLAGS+= -DLIBRESSL_INTERNAL 9CFLAGS+= -DLIBRESSL_INTERNAL
@@ -30,8 +35,6 @@ SRCS= tls.c \
30 tls_ocsp.c \ 35 tls_ocsp.c \
31 tls_verify.c 36 tls_verify.c
32 37
33MAN= tls_init.3
34
35includes: 38includes:
36 @cd ${.CURDIR}; for i in $(HDRS); do \ 39 @cd ${.CURDIR}; for i in $(HDRS); do \
37 j="cmp -s $$i ${DESTDIR}/usr/include/$$i || \ 40 j="cmp -s $$i ${DESTDIR}/usr/include/$$i || \
diff --git a/src/lib/libtls/man/Makefile b/src/lib/libtls/man/Makefile
new file mode 100644
index 0000000000..4883377669
--- /dev/null
+++ b/src/lib/libtls/man/Makefile
@@ -0,0 +1,23 @@
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
new file mode 100644
index 0000000000..8ea2b03714
--- /dev/null
+++ b/src/lib/libtls/man/tls_accept_socket.3
@@ -0,0 +1,84 @@
1.\" $OpenBSD: tls_accept_socket.3,v 1.1 2017/01/25 23:53:18 schwarze 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: January 25 2017 $
18.Dt TLS_ACCEPT_SOCKET 3
19.Os
20.Sh NAME
21.Nm tls_accept_socket ,
22.Nm tls_accept_fds ,
23.Nm tls_accept_cbs
24.Nd accept an incoming client connection in a TLS server
25.Sh SYNOPSIS
26.In tls.h
27.Ft int
28.Fo tls_accept_socket
29.Fa "struct tls *tls"
30.Fa "struct tls **cctx"
31.Fa "int socket"
32.Fc
33.Ft int
34.Fo tls_accept_fds
35.Fa "struct tls *tls"
36.Fa "struct tls **cctx"
37.Fa "int fd_read"
38.Fa "int fd_write"
39.Fc
40.Ft int
41.Fo tls_accept_cbs
42.Fa "struct tls *tls"
43.Fa "struct tls **cctx"
44.Fa "ssize_t (*tls_read_cb)(struct tls *ctx,\
45 void *buf, size_t buflen, void *cb_arg)"
46.Fa "ssize_t (*tls_write_cb)(struct tls *ctx,\
47 const void *buf, size_t buflen, void *cb_arg)"
48.Fa "void *cb_arg"
49.Fc
50.Sh DESCRIPTION
51After creating a TLS server context
52.Fa tls
53with
54.Xr tls_server 3
55and configuring it with
56.Xr tls_configure 3 ,
57a server can accept a new client connection by calling
58.Fn tls_accept_socket
59on an already established socket connection.
60.Pp
61Alternatively, a new client connection can be accepted over a pair of existing
62file descriptors by calling
63.Fn tls_accept_fds .
64.Pp
65Calling
66.Fn tls_accept_cbs
67allows read and write callback functions to handle data transfers.
68The specified
69.Fa cb_arg
70parameter is passed back to the functions,
71and can contain a pointer to any caller-specified data.
72.Pp
73All these functions create a new context suitable for reading and writing
74and return it in
75.Fa *cctx .
76.Sh RETURN VALUES
77These functions return 0 on success or -1 on error.
78.Sh SEE ALSO
79.Xr tls_close 3 ,
80.Xr tls_config_set_session_id 3 ,
81.Xr tls_configure 3 ,
82.Xr tls_connect 3 ,
83.Xr tls_init 3 ,
84.Xr tls_server 3
diff --git a/src/lib/libtls/man/tls_client.3 b/src/lib/libtls/man/tls_client.3
new file mode 100644
index 0000000000..c8b2cb644e
--- /dev/null
+++ b/src/lib/libtls/man/tls_client.3
@@ -0,0 +1,87 @@
1.\" $OpenBSD: tls_client.3,v 1.1 2017/01/25 23:53:18 schwarze 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: January 25 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_free
25.Nd configure a TLS connection
26.Sh SYNOPSIS
27.In tls.h
28.Ft struct tls *
29.Fn tls_client void
30.Ft struct tls *
31.Fn tls_server void
32.Ft int
33.Fo tls_configure
34.Fa "struct tls *ctx"
35.Fa "struct tls_config *config"
36.Fc
37.Ft void
38.Fn tls_free "struct tls *ctx"
39.Sh DESCRIPTION
40A TLS connection is represented as a
41.Vt struct tls
42object called a
43.Dq context .
44A new context is created by either the
45.Fn tls_client
46or
47.Fn tls_server
48functions.
49.Fn tls_client
50is used in TLS client programs,
51.Fn tls_server
52in TLS server programs.
53.Pp
54The context can then be configured with the function
55.Fn tls_configure .
56The same
57.Vt tls_config
58object can be used to configure multiple contexts.
59.Pp
60After configuration,
61.Xr tls_connect 3
62can be called on objects created with
63.Fn tls_client ,
64and
65.Xr tls_accept_socket 3
66on objects created with
67.Fn tls_server .
68.Pp
69After use, a TLS context should be closed with
70.Xr tls_close 3 ,
71and then freed by calling
72.Fn tls_free .
73.Sh RETURN VALUES
74.Fn tls_client
75and
76.Fn tls_server
77return
78.Dv NULL
79on error or an out of memory condition.
80.Pp
81.Fn tls_configure
82returns 0 on success or -1 on error.
83.Sh SEE ALSO
84.Xr tls_accept_socket 3 ,
85.Xr tls_config_new 3 ,
86.Xr tls_connect 3 ,
87.Xr tls_init 3
diff --git a/src/lib/libtls/man/tls_config_ocsp_require_stapling.3 b/src/lib/libtls/man/tls_config_ocsp_require_stapling.3
new file mode 100644
index 0000000000..9304d8707b
--- /dev/null
+++ b/src/lib/libtls/man/tls_config_ocsp_require_stapling.3
@@ -0,0 +1,59 @@
1.\" $OpenBSD: tls_config_ocsp_require_stapling.3,v 1.1 2017/01/25 23:53:18 schwarze 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: January 25 2017 $
18.Dt TLS_CONFIG_OCSP_REQUIRE_STAPLING 3
19.Os
20.Sh NAME
21.Nm tls_config_ocsp_require_stapling ,
22.Nm tls_config_set_ocsp_staple_mem ,
23.Nm tls_config_set_ocsp_staple_file
24.Nd OCSP configuration for libtls
25.Sh SYNOPSIS
26.In tls.h
27.Ft void
28.Fn tls_config_ocsp_require_stapling "struct tls_config *config"
29.Ft int
30.Fo tls_config_set_ocsp_staple_mem
31.Fa "struct tls_config *config"
32.Fa "const char *staple"
33.Fa "size_t len"
34.Fc
35.Ft int
36.Fo tls_config_set_ocsp_staple_file
37.Fa "struct tls_config *config"
38.Fa "const char *staple_file"
39.Fc
40.Sh DESCRIPTION
41.Fn tls_config_ocsp_require_stapling
42requires that a valid stapled OCSP response be provided during the TLS handshake.
43.Pp
44.Fn tls_config_set_ocsp_staple_file
45sets a DER-encoded OCSP response to be stapled during the TLS handshake from
46the specified file.
47.Pp
48.Fn tls_config_set_ocsp_staple_mem
49sets a DER-encoded OCSP response to be stapled during the TLS handshake from
50memory.
51.Sh RETURN VALUES
52.Fn tls_config_set_ocsp_staple_mem
53and
54.Fn tls_config_set_ocsp_staple_file
55return 0 on success or -1 on error.
56.Sh SEE ALSO
57.Xr tls_handshake 3 ,
58.Xr tls_init 3 ,
59.Xr tls_ocsp_process_response 3
diff --git a/src/lib/libtls/man/tls_config_set_protocols.3 b/src/lib/libtls/man/tls_config_set_protocols.3
new file mode 100644
index 0000000000..7435390edd
--- /dev/null
+++ b/src/lib/libtls/man/tls_config_set_protocols.3
@@ -0,0 +1,146 @@
1.\" $OpenBSD: tls_config_set_protocols.3,v 1.1 2017/01/25 23:53:18 schwarze 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: January 25 2017 $
18.Dt TLS_CONFIG_SET_PROTOCOLS 3
19.Os
20.Sh NAME
21.Nm tls_config_set_protocols ,
22.Nm tls_config_parse_protocols ,
23.Nm tls_config_set_alpn ,
24.Nm tls_config_set_ciphers ,
25.Nm tls_config_set_dheparams ,
26.Nm tls_config_set_ecdhecurve ,
27.Nm tls_config_prefer_ciphers_client ,
28.Nm tls_config_prefer_ciphers_server
29.Nd TLS protocol and cipher selection
30.Sh SYNOPSIS
31.In tls.h
32.Ft int
33.Fo tls_config_set_protocols
34.Fa "struct tls_config *config"
35.Fa "uint32_t protocols"
36.Fc
37.Ft int
38.Fo tls_config_parse_protocols
39.Fa "uint32_t *protocols"
40.Fa "const char *protostr"
41.Fc
42.Ft int
43.Fo tls_config_set_alpn
44.Fa "struct tls_config *config"
45.Fa "const char *alpn"
46.Fc
47.Ft int
48.Fo tls_config_set_ciphers
49.Fa "struct tls_config *config"
50.Fa "const char *ciphers"
51.Fc
52.Ft int
53.Fo tls_config_set_dheparams
54.Fa "struct tls_config *config"
55.Fa "const char *params"
56.Fc
57.Ft int
58.Fo tls_config_set_ecdhecurve
59.Fa "struct tls_config *config"
60.Fa "const char *name"
61.Fc
62.Ft void
63.Fn tls_config_prefer_ciphers_client "struct tls_config *config"
64.Ft void
65.Fn tls_config_prefer_ciphers_server "struct tls_config *config"
66.Sh DESCRIPTION
67These functions modify a configuration by setting parameters.
68The configuration options apply to both clients and servers, unless noted
69otherwise.
70.Pp
71.Fn tls_config_set_protocols
72specifies which versions of the TLS protocol may be used.
73Possible values are the bitwise OR of:
74.Pp
75.Bl -tag -width "TLS_PROTOCOL_TLSv1_2" -offset indent -compact
76.It Dv TLS_PROTOCOL_TLSv1_0
77.It Dv TLS_PROTOCOL_TLSv1_1
78.It Dv TLS_PROTOCOL_TLSv1_2
79.El
80.Pp
81Additionally, the values
82.Dv TLS_PROTOCOL_TLSv1
83(TLSv1.0, TLSv1.1 and TLSv1.2),
84.Dv TLS_PROTOCOLS_ALL
85(all supported protocols) and
86.Dv TLS_PROTOCOLS_DEFAULT
87(TLSv1.2 only) may be used.
88.Pp
89The
90.Fn tls_config_parse_protocols
91utility function parses a protocol string and returns the corresponding
92value via the
93.Ar protocols
94argument.
95This value can then be passed to the
96.Fn tls_config_set_protocols
97function.
98The protocol string is a comma or colon separated list of keywords.
99Valid keywords are tlsv1.0, tlsv1.1, tlsv1.2, all (all supported protocols),
100default (an alias for secure), legacy (an alias for all) and secure (currently
101TLSv1.2 only).
102If a value has a negative prefix (in the form of a leading exclamation mark)
103then it is removed from the list of available protocols, rather than being
104added to it.
105.Pp
106.Fn tls_config_set_alpn
107sets the ALPN protocols that are supported.
108The alpn string is a comma separated list of protocols, in order of preference.
109.Pp
110.Fn tls_config_set_ciphers
111sets the list of ciphers that may be used.
112Lists of ciphers are specified by name, and the
113permitted names are:
114.Pp
115.Bl -tag -width "insecure" -offset indent -compact
116.It Dv "secure" (or alias "default")
117.It Dv "compat"
118.It Dv "legacy"
119.It Dv "insecure" (or alias "all")
120.El
121.Pp
122Alternatively, libssl cipher strings can be specified.
123See the CIPHERS section of
124.Xr openssl 1
125for further information.
126.\" XXX tls_config_set_dheparams does what?
127.\" XXX tls_config_set_ecdhecurve does what?
128.Pp
129.Fn tls_config_prefer_ciphers_client
130prefers ciphers in the client's cipher list when selecting a cipher suite
131(server only).
132This is considered to be less secure than preferring the server's list.
133.Pp
134.Fn tls_config_prefer_ciphers_server
135prefers ciphers in the server's cipher list when selecting a cipher suite
136(server only).
137This is considered to be more secure than preferring the client's list and is
138the default.
139.Sh RETURN VALUES
140These functions return 0 on success or -1 on error.
141.Sh SEE ALSO
142.Xr tls_config_ocsp_require_stapling 3 ,
143.Xr tls_config_set_session_id 3 ,
144.Xr tls_config_verify 3 ,
145.Xr tls_init 3 ,
146.Xr tls_load_file 3
diff --git a/src/lib/libtls/man/tls_config_set_session_id.3 b/src/lib/libtls/man/tls_config_set_session_id.3
new file mode 100644
index 0000000000..0e964c916d
--- /dev/null
+++ b/src/lib/libtls/man/tls_config_set_session_id.3
@@ -0,0 +1,70 @@
1.\" $OpenBSD: tls_config_set_session_id.3,v 1.1 2017/01/25 23:53:18 schwarze 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: January 25 2017 $
18.Dt TLS_CONFIG_SET_SESSION_ID 3
19.Os
20.Sh NAME
21.Nm tls_config_set_session_id ,
22.Nm tls_config_set_session_lifetime ,
23.Nm tls_config_add_ticket_key
24.Nd configure resuming of TLS handshakes
25.Sh SYNOPSIS
26.In tls.h
27.Ft int
28.Fo tls_config_set_session_id
29.Fa "struct tls_config *config"
30.Fa "const unsigned char *session_id"
31.Fa "size_t len"
32.Fc
33.Ft int
34.Fo tls_config_set_session_lifetime
35.Fa "struct tls_config *config"
36.Fa "int lifetime"
37.Fc
38.Ft int
39.Fo tls_config_add_ticket_key
40.Fa "struct tls_config *config"
41.Fa "uint32_t keyrev"
42.Fa "unsigned char *key"
43.Fa "size_t keylen"
44.Fc
45.Sh DESCRIPTION
46.Fn tls_config_set_session_id
47sets the session identifier that will be used by the TLS server when
48sessions are enabled.
49By default a random value is used.
50.Pp
51.Fn tls_config_set_session_lifetime
52sets the lifetime to be used for TLS sessions.
53Session support is disabled if a lifetime of zero is specified, which is the
54default.
55.Pp
56.Fn tls_config_add_ticket_key
57adds a key used for the encryption and authentication of TLS tickets.
58By default keys are generated and rotated automatically based on their lifetime.
59This function should only be used to synchronise ticket encryption key across
60multiple processes.
61Re-adding a known key will result in an error, unless it is the most recently
62added key.
63.Sh RETURN VALUES
64These functions return 0 on success or -1 on error.
65.Sh SEE ALSO
66.Xr tls_accept_socket 3 ,
67.Xr tls_config_set_protocols 3 ,
68.Xr tls_init 3 ,
69.Xr tls_load_file 3 ,
70.Xr tls_server 3
diff --git a/src/lib/libtls/man/tls_config_verify.3 b/src/lib/libtls/man/tls_config_verify.3
new file mode 100644
index 0000000000..ba0c997340
--- /dev/null
+++ b/src/lib/libtls/man/tls_config_verify.3
@@ -0,0 +1,59 @@
1.\" $OpenBSD: tls_config_verify.3,v 1.1 2017/01/25 23:53:18 schwarze 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: January 25 2017 $
18.Dt TLS_CONGIG_VERIFY 3
19.Os
20.Sh NAME
21.Nm tls_config_verify ,
22.Nm tls_config_insecure_noverifycert ,
23.Nm tls_config_insecure_noverifyname ,
24.Nm tls_config_insecure_noverifytime
25.Nd insecure TLS configuration
26.Sh SYNOPSIS
27.In tls.h
28.Ft void
29.Fn tls_config_verify "struct tls_config *config"
30.Ft void
31.Fn tls_config_insecure_noverifycert "struct tls_config *config"
32.Ft void
33.Fn tls_config_insecure_noverifyname "struct tls_config *config"
34.Ft void
35.Fn tls_config_insecure_noverifytime "struct tls_config *config"
36.Sh DESCRIPTION
37These functions disable parts of the normal certificate verification
38process, resulting in insecure configurations.
39Be very careful when using them.
40.Pp
41.Fn tls_config_insecure_noverifycert
42disables certificate verification and OCSP validation.
43.Pp
44.Fn tls_config_insecure_noverifyname
45disables server name verification (client only).
46.Pp
47.Fn tls_config_insecure_noverifytime
48disables validity checking of certificates and OCSP validation.
49.Pp
50.Fn tls_config_verify
51reenables server name and certificate verification.
52.Sh SEE ALSO
53.Xr tls_client 3 ,
54.Xr tls_config_ocsp_require_stapling 3 ,
55.Xr tls_config_set_protocols 3 ,
56.Xr tls_conn_version 3 ,
57.Xr tls_connect 3 ,
58.Xr tls_handshake 3 ,
59.Xr tls_init 3
diff --git a/src/lib/libtls/man/tls_conn_version.3 b/src/lib/libtls/man/tls_conn_version.3
new file mode 100644
index 0000000000..89fb4019c8
--- /dev/null
+++ b/src/lib/libtls/man/tls_conn_version.3
@@ -0,0 +1,154 @@
1.\" $OpenBSD: tls_conn_version.3,v 1.1 2017/01/25 23:53:18 schwarze 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: January 25 2017 $
18.Dt TLS_INIT 3
19.Os
20.Sh NAME
21.Nm tls_conn_version ,
22.Nm tls_conn_cipher ,
23.Nm tls_conn_alpn_selected ,
24.Nm tls_conn_servername ,
25.Nm tls_peer_cert_provided ,
26.Nm tls_peer_cert_contains_name ,
27.Nm tls_peer_cert_issuer ,
28.Nm tls_peer_cert_subject ,
29.Nm tls_peer_cert_hash ,
30.Nm tls_peer_cert_notbefore ,
31.Nm tls_peer_cert_notafter
32.Nd inspect an established TLS connection
33.Sh SYNOPSIS
34.In tls.h
35.Ft const char *
36.Fn tls_conn_version "struct tls *ctx"
37.Ft const char *
38.Fn tls_conn_cipher "struct tls *ctx"
39.Ft const char *
40.Fn tls_conn_alpn_selected "struct tls *ctx"
41.Ft const char *
42.Fn tls_conn_servername "struct tls *ctx"
43.Ft int
44.Fn tls_peer_cert_provided "struct tls *ctx"
45.Ft int
46.Fo tls_peer_cert_contains_name
47.Fa "struct tls *ctx"
48.Fa "const char *name"
49.Fc
50.Ft const char *
51.Fn tls_peer_cert_issuer "struct tls *ctx"
52.Ft const char *
53.Fn tls_peer_cert_subject "struct tls *ctx"
54.Ft const char *
55.Fn tls_peer_cert_hash "struct tls *ctx"
56.Ft time_t
57.Fn tls_peer_cert_notbefore "struct tls *ctx"
58.Ft time_t
59.Fn tls_peer_cert_notafter "struct tls *ctx"
60.Sh DESCRIPTION
61These functions return information about a TLS connection and will only
62succeed after the handshake is complete (the connection information applies
63to both clients and servers, unless noted otherwise):
64.Pp
65.Fn tls_conn_version
66returns a string corresponding to a TLS version negotiated with the peer
67connected to
68.Ar ctx .
69.Pp
70.Fn tls_conn_cipher
71returns a string corresponding to the cipher suite negotiated with the peer
72connected to
73.Ar ctx .
74.Pp
75.Fn tls_conn_alpn_selected
76returns a string that specifies the ALPN protocol selected for use with the peer
77connected to
78.Ar ctx .
79If no protocol was selected then NULL is returned.
80.Pp
81.Fn tls_conn_servername
82returns a string corresponding to the servername that the client connected to
83.Ar ctx
84requested by sending a TLS Server Name Indication extension (server only).
85.Pp
86.Fn tls_peer_cert_provided
87checks if the peer of
88.Ar ctx
89has provided a certificate.
90.Pp
91.Fn tls_peer_cert_contains_name
92checks if the peer of a TLS
93.Ar ctx
94has provided a certificate that contains a
95SAN or CN that matches
96.Ar name .
97.Pp
98.Fn tls_peer_cert_subject
99returns a string
100corresponding to the subject of the peer certificate from
101.Ar ctx .
102.Pp
103.Fn tls_peer_cert_issuer
104returns a string
105corresponding to the issuer of the peer certificate from
106.Ar ctx .
107.Pp
108.Fn tls_peer_cert_hash
109returns a string
110corresponding to a hash of the raw peer certificate from
111.Ar ctx
112prefixed by a hash name followed by a colon.
113The hash currently used is SHA256, though this
114could change in the future.
115The hash string for a certificate in file
116.Ar mycert.crt
117can be generated using the commands:
118.Bd -literal -offset indent
119h=$(openssl x509 -outform der -in mycert.crt | sha256)
120printf "SHA256:${h}\\n"
121.Ed
122.Pp
123.Fn tls_peer_cert_notbefore
124returns the time corresponding to the start of the validity period of
125the peer certificate from
126.Ar ctx .
127.Pp
128.Fn tls_peer_cert_notafter
129returns the time corresponding to the end of the validity period of
130the peer certificate from
131.Ar ctx .
132.Pp
133POINTER TO
134.Xr tls_ocsp_process_response 3
135.Sh RETURN VALUES
136The
137.Fn tls_peer_cert_provided
138and
139.Fn tls_peer_cert_contains_name
140functions return 1 if the check succeeds or 0 if it does not.
141.Pp
142.Fn tls_peer_cert_notbefore
143and
144.Fn tls_peer_cert_notafter
145return a time in epoch-seconds on success or -1 on error.
146.Pp
147The functions that return a pointer return
148.Dv NULL
149on error or an out of memory condition.
150.Sh SEE ALSO
151.Xr tls_configure 3 ,
152.Xr tls_handshake 3 ,
153.Xr tls_init 3 ,
154.Xr tls_ocsp_process_response 3
diff --git a/src/lib/libtls/man/tls_connect.3 b/src/lib/libtls/man/tls_connect.3
new file mode 100644
index 0000000000..8137fba53b
--- /dev/null
+++ b/src/lib/libtls/man/tls_connect.3
@@ -0,0 +1,114 @@
1.\" $OpenBSD: tls_connect.3,v 1.1 2017/01/25 23:53:18 schwarze 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: January 25 2017 $
18.Dt TLS_CONNECT 3
19.Os
20.Sh NAME
21.Nm tls_connect ,
22.Nm tls_connect_fds ,
23.Nm tls_connect_servername ,
24.Nm tls_connect_socket ,
25.Nm tls_connect_cbs
26.Nd instruct a TLS client to establish a connection
27.Sh SYNOPSIS
28.In tls.h
29.Ft int
30.Fo tls_connect
31.Fa "struct tls *ctx"
32.Fa "const char *host"
33.Fa "const char *port"
34.Fc
35.Ft int
36.Fo tls_connect_fds
37.Fa "struct tls *ctx"
38.Fa "int fd_read"
39.Fa "int fd_write"
40.Fa "const char *servername"
41.Fc
42.Ft int
43.Fo tls_connect_servername
44.Fa "struct tls *ctx"
45.Fa "const char *host"
46.Fa "const char *port"
47.Fa "const char *servername"
48.Fc
49.Ft int
50.Fo tls_connect_socket
51.Fa "struct tls *ctx"
52.Fa "int s"
53.Fa "const char *servername"
54.Fc
55.Ft int
56.Fo tls_connect_cbs
57.Fa "struct tls *ctx"
58.Fa "ssize_t (*tls_read_cb)(struct tls *ctx,\
59 void *buf, size_t buflen, void *cb_arg)"
60.Fa "ssize_t (*tls_write_cb)(struct tls *ctx,\
61 const void *buf, size_t buflen, void *cb_arg)"
62.Fa "void *cb_arg"
63.Fa "const char *servername"
64.Fc
65.Sh DESCRIPTION
66After creating a TLS client context with
67.Xr tls_client 3
68and configuring it with
69.Xr tls_configure 3 ,
70a client connection is initiated by calling
71.Fn tls_connect .
72This function will create a new socket, connect to the specified
73.Fa host
74and
75.Fa port ,
76and then establish a secure connection.
77The
78.Fa port
79may be numeric or a service name.
80If it is
81.Dv NULL ,
82then a
83.Fa host
84of the format "hostname:port" is permitted.
85.Pp
86The
87.Fn tls_connect_servername
88function has the same behaviour, however the name to use for verification is
89explicitly provided, rather than being inferred from the
90.Ar host
91value.
92.Pp
93An already existing socket can be upgraded to a secure connection by calling
94.Fn tls_connect_socket .
95.Pp
96Alternatively, a secure connection can be established over a pair of existing
97file descriptors by calling
98.Fn tls_connect_fds .
99.Pp
100Calling
101.Fn tls_connect_cbs
102allows read and write callback functions to handle data transfers.
103The specified cb_arg parameter is passed back to the functions,
104and can contain a pointer to any caller-specified data.
105.Sh RETURN VALUES
106These functions return 0 on success or -1 on error.
107.Sh SEE ALSO
108.Xr tls_accept_socket 3 ,
109.Xr tls_client 3 ,
110.Xr tls_close 3 ,
111.Xr tls_config_ocsp_require_stapling 3 ,
112.Xr tls_configure 3 ,
113.Xr tls_handshake 3 ,
114.Xr tls_init 3
diff --git a/src/lib/libtls/man/tls_init.3 b/src/lib/libtls/man/tls_init.3
new file mode 100644
index 0000000000..af0eec3802
--- /dev/null
+++ b/src/lib/libtls/man/tls_init.3
@@ -0,0 +1,126 @@
1.\" $OpenBSD: tls_init.3,v 1.1 2017/01/25 23:53:18 schwarze 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: January 25 2017 $
18.Dt TLS_INIT 3
19.Os
20.Sh NAME
21.Nm tls_init ,
22.Nm tls_config_new ,
23.Nm tls_config_free ,
24.Nm tls_config_error
25.Nd initialize TLS client and server API
26.Sh SYNOPSIS
27.In tls.h
28.Ft int
29.Fn tls_init void
30.Ft struct tls_config *
31.Fn tls_config_new void
32.Ft void
33.Fn tls_config_free "struct tls_config *config"
34.Ft const char *
35.Fn tls_config_error "struct tls_config *config"
36.Sh DESCRIPTION
37The
38.Nm tls
39family of functions establishes a secure communications channel
40using the TLS socket protocol.
41Both clients and servers are supported.
42.Pp
43The
44.Fn tls_init
45function initializes global data structures.
46It should be called once before any other functions.
47It may be called more than once, but not concurrently.
48.Pp
49Before a connection is created, a configuration must be created.
50The
51.Fn tls_config_new
52function allocates, initializes, and returns a new default configuration
53object that can be used for future connections.
54Several functions exist to change the options of the configuration; see
55.Xr tls_config_set_protocols 3 ,
56.Xr tls_load_file 3 ,
57.Xr tls_config_ocsp_require_stapling 3 ,
58and
59.Xr tls_config_verify 3 .
60.Pp
61The
62.Fn tls_config_error
63function may be used to retrieve a string containing more information
64about the most recent error relating to a configuration.
65.Pp
66A TLS connection object is created by
67.Xr tls_client 3
68or
69.Xr tls_server 3
70and configured with
71.Xr tls_configure 3 .
72.Pp
73A client connection is initiated after configuration by calling
74.Xr tls_connect 3 .
75A server can accept a new client connection by calling
76.Xr tls_accept_socket 3
77on an already established socket connection.
78.Pp
79Two functions are provided for input and output,
80.Xr tls_read 3
81and
82.Xr tls_write 3 .
83Both automatically perform the
84.Xr tls_handshake 3
85when needed.
86.Pp
87The properties of established TLS connections
88can be inspected with the functions described in
89.Xr tls_conn_version 3
90and
91.Xr tls_ocsp_process_response 3 .
92.Pp
93After use, a TLS connection should be closed with
94.Xr tls_close 3
95and then freed by calling
96.Xr tls_free 3 .
97.Pp
98When no more contexts are to be created,
99the configuration object should be freed by calling
100.Fn tls_config_free .
101.Sh RETURN VALUES
102.Fn tls_init
103returns 0 on success or -1 on error.
104.Pp
105.Fn tls_config_new
106returns
107.Dv NULL
108on error or an out of memory condition.
109.Sh SEE ALSO
110.Xr tls_accept_socket 3 ,
111.Xr tls_client 3 ,
112.Xr tls_config_ocsp_require_stapling 3 ,
113.Xr tls_config_set_protocols 3 ,
114.Xr tls_config_verify 3 ,
115.Xr tls_conn_version 3 ,
116.Xr tls_connect 3 ,
117.Xr tls_load_file 3 ,
118.Xr tls_ocsp_process_response 3 ,
119.Xr tls_read 3
120.Sh HISTORY
121The
122.Nm tls
123API first appeared in
124.Ox 5.6
125as a response to the unnecessary challenges other APIs present in
126order to use them safely.
diff --git a/src/lib/libtls/man/tls_load_file.3 b/src/lib/libtls/man/tls_load_file.3
new file mode 100644
index 0000000000..2b2f01a8a9
--- /dev/null
+++ b/src/lib/libtls/man/tls_load_file.3
@@ -0,0 +1,197 @@
1.\" $OpenBSD: tls_load_file.3,v 1.1 2017/01/25 23:53:18 schwarze 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: January 25 2017 $
18.Dt TLS_LOAD_FILE 3
19.Os
20.Sh NAME
21.Nm tls_load_file ,
22.Nm tls_config_set_ca_file ,
23.Nm tls_config_set_ca_path ,
24.Nm tls_config_set_ca_mem ,
25.Nm tls_config_set_cert_file ,
26.Nm tls_config_set_cert_mem ,
27.Nm tls_config_set_key_file ,
28.Nm tls_config_set_key_mem ,
29.Nm tls_config_set_keypair_file ,
30.Nm tls_config_set_keypair_mem ,
31.Nm tls_config_add_keypair_file ,
32.Nm tls_config_add_keypair_mem ,
33.Nm tls_config_clear_keys ,
34.Nm tls_config_set_verify_depth ,
35.Nm tls_config_verify_client ,
36.Nm tls_config_verify_client_optional
37.Nd TLS certificate and key configuration
38.Sh SYNOPSIS
39.In tls.h
40.Ft uint8_t *
41.Fo tls_load_file
42.Fa "const char *file"
43.Fa "size_t *len"
44.Fa "char *password"
45.Fc
46.Ft int
47.Fo tls_config_set_ca_file
48.Fa "struct tls_config *config"
49.Fa "const char *ca_file"
50.Fc
51.Ft int
52.Fo tls_config_set_ca_path
53.Fa "struct tls_config *config"
54.Fa "const char *ca_path"
55.Fc
56.Ft int
57.Fo tls_config_set_ca_mem
58.Fa "struct tls_config *config"
59.Fa "const uint8_t *cert"
60.Fa "size_t len"
61.Fc
62.Ft int
63.Fo tls_config_set_cert_file
64.Fa "struct tls_config *config"
65.Fa "const char *cert_file"
66.Fc
67.Ft int
68.Fo tls_config_set_cert_mem
69.Fa "struct tls_config *config"
70.Fa "const uint8_t *cert"
71.Fa "size_t len"
72.Fc
73.Ft int
74.Fo tls_config_set_key_file
75.Fa "struct tls_config *config"
76.Fa "const char *key_file"
77.Fc
78.Ft int
79.Fo tls_config_set_key_mem
80.Fa "struct tls_config *config"
81.Fa "const uint8_t *key"
82.Fa "size_t len"
83.Fc
84.Ft int
85.Fo tls_config_set_keypair_file
86.Fa "struct tls_config *config"
87.Fa "const char *cert_file"
88.Fa "const char *key_file"
89.Fc
90.Ft int
91.Fo tls_config_set_keypair_mem
92.Fa "struct tls_config *config"
93.Fa "const uint8_t *cert"
94.Fa "size_t cert_len"
95.Fa "const uint8_t *key"
96.Fa "size_t key_len"
97.Fc
98.Ft int
99.Fo tls_config_add_keypair_file
100.Fa "struct tls_config *config"
101.Fa "const char *cert_file"
102.Fa "const char *key_file"
103.Fc
104.Ft int
105.Fo tls_config_add_keypair_mem
106.Fa "struct tls_config *config"
107.Fa "const uint8_t *cert"
108.Fa "size_t cert_len"
109.Fa "const uint8_t *key"
110.Fa "size_t key_len"
111.Fc
112.Ft void
113.Fn tls_config_clear_keys "struct tls_config *config"
114.Ft int
115.Fo tls_config_set_verify_depth
116.Fa "struct tls_config *config"
117.Fa "int verify_depth"
118.Fc
119.Ft void
120.Fn tls_config_verify_client "struct tls_config *config"
121.Ft void
122.Fn tls_config_verify_client_optional "struct tls_config *config"
123.Sh DESCRIPTION
124.Fn tls_load_file
125loads a certificate or key from disk into memory to be loaded with
126.Fn tls_config_set_ca_mem ,
127.Fn tls_config_set_cert_mem
128or
129.Fn tls_config_set_key_mem .
130A private key will be decrypted if the optional
131.Ar password
132argument is specified.
133.Pp
134.Fn tls_config_set_ca_file
135sets the filename used to load a file
136containing the root certificates.
137.Pp
138.Fn tls_config_set_ca_path
139sets the path (directory) which should be searched for root
140certificates.
141.Pp
142.Fn tls_config_set_ca_mem
143sets the root certificates directly from memory.
144.Pp
145.Fn tls_config_set_cert_file
146sets file from which the public certificate will be read.
147.Pp
148.Fn tls_config_set_cert_mem
149sets the public certificate directly from memory.
150.Pp
151.Fn tls_config_set_key_file
152sets the file from which the private key will be read.
153.Pp
154.Fn tls_config_set_key_mem
155directly sets the private key from memory.
156.Pp
157.Fn tls_config_set_keypair_file
158sets the files from which the public certificate and private key will be read.
159.Pp
160.Fn tls_config_set_keypair_mem
161directly sets the public certificate and private key from memory.
162.Pp
163.Fn tls_config_add_keypair_file
164adds an additional public certificate and private key from the specified files,
165used as an alternative certificate for Server Name Indication (server only).
166.Pp
167.Fn tls_config_add_keypair_mem
168adds an additional public certificate and private key from memory,
169used as an alternative certificate for Server Name Indication (server only).
170.Pp
171.Fn tls_config_clear_keys
172clears any secret keys from memory.
173.Pp
174.Fn tls_config_set_verify_depth
175limits the number of intermediate certificates that will be followed during
176certificate validation.
177.Pp
178.Fn tls_config_verify_client
179enables client certificate verification, requiring the client to send
180a certificate (server only).
181.Pp
182.Fn tls_config_verify_client_optional
183enables client certificate verification, without requiring the client
184to send a certificate (server only).
185.Sh RETURN VALUES
186.Fn tls_load_file
187returns
188.Dv NULL
189on error or an out of memory condition.
190.Pp
191The other functions return 0 on success or -1 on error.
192.Sh SEE ALSO
193.Xr tls_config_ocsp_require_stapling 3 ,
194.Xr tls_config_set_protocols 3 ,
195.Xr tls_config_set_session_id 3 ,
196.Xr tls_configure 3 ,
197.Xr tls_init 3
diff --git a/src/lib/libtls/man/tls_ocsp_process_response.3 b/src/lib/libtls/man/tls_ocsp_process_response.3
new file mode 100644
index 0000000000..78dc0ee42c
--- /dev/null
+++ b/src/lib/libtls/man/tls_ocsp_process_response.3
@@ -0,0 +1,154 @@
1.\" $OpenBSD: tls_ocsp_process_response.3,v 1.1 2017/01/25 23:53:18 schwarze 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: January 25 2017 $
18.Dt TLS_OCSP_PROCESS_RESPONSE 3
19.Os
20.Sh NAME
21.Nm tls_ocsp_process_response ,
22.Nm tls_peer_ocsp_cert_status ,
23.Nm tls_peer_ocsp_crl_reason ,
24.Nm tls_peer_ocsp_next_update ,
25.Nm tls_peer_ocsp_response_status ,
26.Nm tls_peer_ocsp_result_msg ,
27.Nm tls_peer_ocsp_revocation_time ,
28.Nm tls_peer_ocsp_this_update ,
29.Nm tls_peer_ocsp_url
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 int
40.Fn tls_peer_ocsp_cert_status "struct tls *ctx"
41.Ft int
42.Fn tls_peer_ocsp_crl_reason "struct tls *ctx"
43.Ft time_t
44.Fn tls_peer_ocsp_next_update "struct tls *ctx"
45.Ft int
46.Fn tls_peer_ocsp_response_status "struct tls *ctx"
47.Ft const char *
48.Fn tls_peer_ocsp_result_msg "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 const char *
54.Fn tls_peer_ocsp_url "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_cert_status
77returns the OCSP certificate status code as per RFC 6960 section 2.2.
78.Pp
79.Fn tls_peer_ocsp_crl_reason
80returns the OCSP certificate revocation reason status code as per RFC 5280
81section 5.3.1.
82.Pp
83.Fn tls_peer_ocsp_next_update
84returns the OCSP next update time.
85.Pp
86.Fn tls_peer_ocsp_response_status
87returns the OCSP response status as per RFC 6960 section 2.3.
88.Pp
89.\" XXX Fn tls_peer_ocsp_result_msg does what?
90.Fn tls_peer_ocsp_revocation_time
91returns the OCSP revocation time.
92.Pp
93.Fn tls_peer_ocsp_this_update
94returns the OCSP this update time.
95.Sh RETURN VALUES
96.Fn tls_ocsp_process_response
97returns 0 on success or -1 on error.
98.Pp
99The
100.Fn tls_peer_ocsp_response_status
101function returns one of
102.Dv TLS_OCSP_RESPONSE_SUCCESSFUL ,
103.Dv TLS_OCSP_RESPONSE_MALFORMED ,
104.Dv TLS_OCSP_RESPONSE_INTERNALERROR ,
105.Dv TLS_OCSP_RESPONSE_TRYLATER ,
106.Dv TLS_OCSP_RESPONSE_SIGREQUIRED ,
107or
108.Dv TLS_OCSP_RESPONSE_UNAUTHORIZED
109on success or -1 on error.
110.Pp
111The
112.Fn tls_peer_ocsp_cert_status
113function returns one of
114.Dv TLS_OCSP_CERT_GOOD ,
115.Dv TLS_OCSP_CERT_REVOKED ,
116or
117.Dv TLS_OCSP_CERT_UNKNOWN
118on success, and -1 on error.
119.Pp
120The
121.Fn tls_peer_ocsp_crl_reason
122function returns one of
123.Dv TLS_CRL_REASON_UNSPECIFIED ,
124.Dv TLS_CRL_REASON_KEY_COMPROMISE ,
125.Dv TLS_CRL_REASON_CA_COMPROMISE ,
126.Dv TLS_CRL_REASON_AFFILIATION_CHANGED ,
127.Dv TLS_CRL_REASON_SUPERSEDED ,
128.Dv TLS_CRL_REASON_CESSATION_OF_OPERATION ,
129.Dv TLS_CRL_REASON_CERTIFICATE_HOLD ,
130.Dv TLS_CRL_REASON_REMOVE_FROM_CRL ,
131.Dv TLS_CRL_REASON_PRIVILEGE_WITHDRAWN ,
132or
133.Dv TLS_CRL_REASON_AA_COMPROMISE
134on success or -1 on error.
135.Pp
136.Fn tls_peer_ocsp_next_update ,
137.Fn tls_peer_ocsp_revocation_time ,
138and
139.Fn tls_peer_ocsp_this_update
140return a time in epoch-seconds on success or -1 on error.
141.Pp
142.Fn tls_peer_ocsp_result_msg
143and
144.Fn tls_peer_ocsp_url
145return
146.Dv NULL
147on error or an out of memory condition.
148.Sh SEE ALSO
149.Xr tls_client 3 ,
150.Xr tls_config_ocsp_require_stapling 3 ,
151.Xr tls_conn_version 3 ,
152.Xr tls_connect 3 ,
153.Xr tls_handshake 3 ,
154.Xr tls_init 3
diff --git a/src/lib/libtls/man/tls_read.3 b/src/lib/libtls/man/tls_read.3
new file mode 100644
index 0000000000..74ce005758
--- /dev/null
+++ b/src/lib/libtls/man/tls_read.3
@@ -0,0 +1,195 @@
1.\" $OpenBSD: tls_read.3,v 1.1 2017/01/25 23:53:18 schwarze 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: January 25 2017 $
18.Dt TLS_READ 3
19.Os
20.Sh NAME
21.Nm tls_read ,
22.Nm tls_write ,
23.Nm tls_handshake ,
24.Nm tls_error ,
25.Nm tls_close ,
26.Nm tls_reset
27.Nd use a TLS connection
28.Sh SYNOPSIS
29.In tls.h
30.Ft ssize_t
31.Fo tls_read
32.Fa "struct tls *ctx"
33.Fa "void *buf"
34.Fa "size_t buflen"
35.Fc
36.Ft ssize_t
37.Fo tls_write
38.Fa "struct tls *ctx"
39.Fa "const void *buf"
40.Fa "size_t buflen"
41.Fc
42.Ft int
43.Fn tls_handshake "struct tls *ctx"
44.Ft const char *
45.Fn tls_error "struct tls *ctx"
46.Ft int
47.Fn tls_close "struct tls *ctx"
48.Ft void
49.Fn tls_reset "struct tls *ctx"
50.Sh DESCRIPTION
51.Fn tls_read
52reads
53.Fa buflen
54bytes of data from the socket into
55.Fa buf .
56It returns the amount of data read.
57.Pp
58.Fn tls_write
59writes
60.Fa buflen
61bytes of data from
62.Fa buf
63to the socket.
64It returns the amount of data written.
65.Pp
66.Fn tls_handshake
67explicitly performs the TLS handshake.
68It is only necessary to call this function if you need to guarantee that the
69handshake has completed, as both
70.Fn tls_read
71and
72.Fn tls_write
73automatically perform the TLS handshake when necessary.
74.Pp
75The
76.Fn tls_error
77function may be used to retrieve a string containing more information
78about the most recent error relating to a context.
79.Pp
80.Fn tls_close
81closes a connection after use.
82Only the TLS layer will be shut down and the caller is responsible for closing
83the file descriptors, unless the connection was established using
84.Xr tls_connect 3
85or
86.Xr tls_connect_servername 3 .
87After closing the connection,
88.Fa ctx
89can be passed to
90.Xr tls_free 3 .
91.\" XXX Fn tls_reset does what?
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
103.Fn tls_error
104returns
105.Dv NULL
106if no error occurred or the first place, or if memory allocation
107failed while trying to assemble the string describing the error.
108.Pp
109The
110.Fn tls_read ,
111.Fn tls_write ,
112.Fn tls_handshake ,
113and
114.Fn tls_close
115functions have two special return values:
116.Pp
117.Bl -tag -width "TLS_WANT_POLLOUT" -offset indent -compact
118.It Dv TLS_WANT_POLLIN
119The underlying read file descriptor needs to be readable in order to continue.
120.It Dv TLS_WANT_POLLOUT
121The underlying write file descriptor needs to be writeable in order to continue.
122.El
123.Pp
124In the case of blocking file descriptors, the same function call should be
125repeated immediately.
126In the case of non-blocking file descriptors, the same function call should be
127repeated when the required condition has been met.
128.Pp
129Callers of these functions cannot rely on the value of the global
130.Ar errno .
131To prevent mishandling of error conditions,
132.Fn tls_read ,
133.Fn tls_write ,
134.Fn tls_handshake ,
135and
136.Fn tls_close
137all explicitly clear
138.Ar errno .
139.Sh EXAMPLES
140The following example demonstrates how to handle TLS writes on a blocking
141file descriptor:
142.Bd -literal -offset indent
143\&...
144while (len > 0) {
145 ssize_t ret;
146
147 ret = tls_write(ctx, buf, len);
148 if (ret == TLS_WANT_POLLIN || ret == TLS_WANT_POLLOUT)
149 continue;
150 if (ret < 0)
151 err(1, "tls_write: %s", tls_error(ctx));
152 buf += ret;
153 len -= ret;
154}
155\&...
156.Ed
157.Pp
158The following example demonstrates how to handle TLS writes on a
159non-blocking file descriptor using
160.Xr poll 2 :
161.Bd -literal -offset indent
162\&...
163pfd[0].fd = fd;
164pfd[0].events = POLLIN|POLLOUT;
165while (len > 0) {
166 nready = poll(pfd, 1, 0);
167 if (nready == -1)
168 err(1, "poll");
169 if ((pfd[0].revents & (POLLERR|POLLNVAL)))
170 errx(1, "bad fd %d", pfd[0].fd);
171 if ((pfd[0].revents & (pfd[0].events|POLLHUP))) {
172 ssize_t ret;
173
174 ret = tls_write(ctx, buf, len);
175 if (ret == TLS_WANT_POLLIN)
176 pfd[0].events = POLLIN;
177 else if (ret == TLS_WANT_POLLOUT)
178 pfd[0].events = POLLOUT;
179 else if (ret < 0)
180 err(1, "tls_write: %s", tls_error(ctx));
181 else {
182 buf += ret;
183 len -= ret;
184 }
185 }
186}
187\&...
188.Ed
189.Sh SEE ALSO
190.Xr tls_accept_socket 3 ,
191.Xr tls_configure 3 ,
192.Xr tls_conn_version 3 ,
193.Xr tls_connect 3 ,
194.Xr tls_init 3 ,
195.Xr tls_ocsp_process_response 3
diff --git a/src/lib/libtls/tls_init.3 b/src/lib/libtls/tls_init.3
deleted file mode 100644
index 5d4be14ede..0000000000
--- a/src/lib/libtls/tls_init.3
+++ /dev/null
@@ -1,885 +0,0 @@
1.\" $OpenBSD: tls_init.3,v 1.86 2017/01/24 07:57:39 jmc 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: January 24 2017 $
18.Dt TLS_INIT 3
19.Os
20.Sh NAME
21.Nm tls_init ,
22.Nm tls_config_error ,
23.Nm tls_error ,
24.Nm tls_config_new ,
25.Nm tls_config_free ,
26.Nm tls_config_parse_protocols ,
27.Nm tls_config_add_keypair_file ,
28.Nm tls_config_add_keypair_mem ,
29.Nm tls_config_add_ticket_key ,
30.Nm tls_config_set_alpn ,
31.Nm tls_config_set_ca_file ,
32.Nm tls_config_set_ca_path ,
33.Nm tls_config_set_ca_mem ,
34.Nm tls_config_set_cert_file ,
35.Nm tls_config_set_cert_mem ,
36.Nm tls_config_set_ciphers ,
37.Nm tls_config_set_dheparams ,
38.Nm tls_config_set_ecdhecurve ,
39.Nm tls_config_set_key_file ,
40.Nm tls_config_set_key_mem ,
41.Nm tls_config_set_keypair_file ,
42.Nm tls_config_set_keypair_mem ,
43.Nm tls_config_set_ocsp_staple_mem ,
44.Nm tls_config_set_ocsp_staple_file ,
45.Nm tls_config_set_protocols ,
46.Nm tls_config_set_session_id ,
47.Nm tls_config_set_session_lifetime ,
48.Nm tls_config_set_verify_depth ,
49.Nm tls_config_prefer_ciphers_client ,
50.Nm tls_config_prefer_ciphers_server ,
51.Nm tls_config_clear_keys ,
52.Nm tls_config_insecure_noverifycert ,
53.Nm tls_config_insecure_noverifyname ,
54.Nm tls_config_insecure_noverifytime ,
55.Nm tls_config_ocsp_require_stapling ,
56.Nm tls_config_verify ,
57.Nm tls_config_verify_client ,
58.Nm tls_config_verify_client_optional ,
59.Nm tls_peer_cert_provided ,
60.Nm tls_peer_cert_contains_name ,
61.Nm tls_peer_cert_issuer ,
62.Nm tls_peer_cert_subject ,
63.Nm tls_peer_cert_hash ,
64.Nm tls_peer_cert_notbefore ,
65.Nm tls_peer_cert_notafter ,
66.Nm tls_ocsp_process_response ,
67.Nm tls_peer_ocsp_cert_status ,
68.Nm tls_peer_ocsp_crl_reason ,
69.Nm tls_peer_ocsp_next_update ,
70.Nm tls_peer_ocsp_response_status ,
71.Nm tls_peer_ocsp_result_msg ,
72.Nm tls_peer_ocsp_revocation_time ,
73.Nm tls_peer_ocsp_this_update ,
74.Nm tls_peer_ocsp_url ,
75.Nm tls_conn_alpn_selected ,
76.Nm tls_conn_cipher ,
77.Nm tls_conn_servername ,
78.Nm tls_conn_version ,
79.Nm tls_load_file ,
80.Nm tls_client ,
81.Nm tls_server ,
82.Nm tls_configure ,
83.Nm tls_reset ,
84.Nm tls_free ,
85.Nm tls_connect ,
86.Nm tls_connect_fds ,
87.Nm tls_connect_servername ,
88.Nm tls_connect_socket ,
89.Nm tls_connect_cbs ,
90.Nm tls_accept_fds ,
91.Nm tls_accept_socket ,
92.Nm tls_accept_cbs ,
93.Nm tls_handshake ,
94.Nm tls_read ,
95.Nm tls_write ,
96.Nm tls_close
97.Nd TLS client and server API
98.Sh SYNOPSIS
99.In tls.h
100.Ft "int"
101.Fn tls_init "void"
102.Ft "const char *"
103.Fn tls_config_error "struct tls_config *config"
104.Ft "const char *"
105.Fn tls_error "struct tls *ctx"
106.Ft "struct tls_config *"
107.Fn tls_config_new "void"
108.Ft "void"
109.Fn tls_config_free "struct tls_config *config"
110.Ft "int"
111.Fn tls_config_parse_protocols "uint32_t *protocols" "const char *protostr"
112.Ft "int"
113.Fn tls_config_add_keypair_file "struct tls_config *config" "const char *cert_file" "const char *key_file"
114.Ft "int"
115.Fn tls_config_add_keypair_mem "struct tls_config *config" "const uint8_t *cert" "size_t cert_len" "const uint8_t *key" "size_t key_len"
116.Ft "int"
117.Fn tls_config_add_ticket_key "struct tls_config *config" "uint32_t keyrev" "unsigned char *key" "size_t keylen"
118.Ft "int"
119.Fn tls_config_set_alpn "struct tls_config *config" "const char *alpn"
120.Ft "int"
121.Fn tls_config_set_ca_file "struct tls_config *config" "const char *ca_file"
122.Ft "int"
123.Fn tls_config_set_ca_path "struct tls_config *config" "const char *ca_path"
124.Ft "int"
125.Fn tls_config_set_ca_mem "struct tls_config *config" "const uint8_t *cert" "size_t len"
126.Ft "int"
127.Fn tls_config_set_cert_file "struct tls_config *config" "const char *cert_file"
128.Ft "int"
129.Fn tls_config_set_cert_mem "struct tls_config *config" "const uint8_t *cert" "size_t len"
130.Ft "int"
131.Fn tls_config_set_ciphers "struct tls_config *config" "const char *ciphers"
132.Ft "int"
133.Fn tls_config_set_dheparams "struct tls_config *config" "const char *params"
134.Ft "int"
135.Fn tls_config_set_ecdhecurve "struct tls_config *config" "const char *name"
136.Ft "int"
137.Fn tls_config_set_key_file "struct tls_config *config" "const char *key_file"
138.Ft "int"
139.Fn tls_config_set_key_mem "struct tls_config *config" "const uint8_t *key" "size_t len"
140.Ft "int"
141.Fn tls_config_set_keypair_file "struct tls_config *config" "const char *cert_file" "const char *key_file"
142.Ft "int"
143.Fn tls_config_set_keypair_mem "struct tls_config *config" "const uint8_t *cert" "size_t cert_len" "const uint8_t *key" "size_t key_len"
144.Ft "int"
145.Fn tls_config_set_ocsp_staple_mem "struct tls_config *config" "const char *staple" "size_t len"
146.Ft "int"
147.Fn tls_config_set_ocsp_staple_file "struct tls_config *config" "const char *staple_file"
148.Ft "int"
149.Fn tls_config_set_protocols "struct tls_config *config" "uint32_t protocols"
150.Ft "int"
151.Fn tls_config_set_session_id "struct tls_config *config" "const unsigned char *session_id" "size_t len"
152.Ft "int"
153.Fn tls_config_set_session_lifetime "struct tls_config *config" "int lifetime"
154.Ft "int"
155.Fn tls_config_set_verify_depth "struct tls_config *config" "int verify_depth"
156.Ft "void"
157.Fn tls_config_prefer_ciphers_client "struct tls_config *config"
158.Ft "void"
159.Fn tls_config_prefer_ciphers_server "struct tls_config *config"
160.Ft "void"
161.Fn tls_config_clear_keys "struct tls_config *config"
162.Ft "void"
163.Fn tls_config_insecure_noverifycert "struct tls_config *config"
164.Ft "void"
165.Fn tls_config_insecure_noverifyname "struct tls_config *config"
166.Ft "void"
167.Fn tls_config_insecure_noverifytime "struct tls_config *config"
168.Ft "void"
169.Fn tls_config_ocsp_require_stapling "struct tls_config *config"
170.Ft "void"
171.Fn tls_config_verify "struct tls_config *config"
172.Ft "void"
173.Fn tls_config_verify_client "struct tls_config *config"
174.Ft "void"
175.Fn tls_config_verify_client_optional "struct tls_config *config"
176.Ft "int"
177.Fn tls_peer_cert_provided "struct tls *ctx"
178.Ft "int"
179.Fn tls_peer_cert_contains_name "struct tls *ctx" "const char *name"
180.Ft "const char *"
181.Fn tls_peer_cert_issuer "struct tls *ctx"
182.Ft "const char *"
183.Fn tls_peer_cert_subject "struct tls *ctx"
184.Ft "const char *"
185.Fn tls_peer_cert_hash "struct tls *ctx"
186.Ft "time_t"
187.Fn tls_peer_cert_notbefore "struct tls *ctx"
188.Ft "time_t"
189.Fn tls_peer_cert_notafter "struct tls *ctx"
190.Ft "int"
191.Fn tls_ocsp_process_response "struct tls *ctx" "const unsigned char *response" "size_t size"
192.Ft "int"
193.Fn tls_peer_ocsp_cert_status "struct tls *ctx"
194.Ft "int"
195.Fn tls_peer_ocsp_crl_reason "struct tls *ctx"
196.Ft time_t
197.Fn tls_peer_ocsp_next_update "struct tls *ctx"
198.Ft "int"
199.Fn tls_peer_ocsp_response_status "struct tls *ctx"
200.Ft "const char *"
201.Fn tls_peer_ocsp_result_msg "struct tls *ctx"
202.Ft "time_t"
203.Fn tls_peer_ocsp_revocation_time "struct tls *ctx"
204.Ft "time_t"
205.Fn tls_peer_ocsp_this_update "struct tls *ctx"
206.Ft "const char *"
207.Fn tls_peer_ocsp_url "struct tls *ctx"
208.Ft "const char *"
209.Fn tls_conn_alpn_selected "struct tls *ctx"
210.Ft "const char *"
211.Fn tls_conn_cipher "struct tls *ctx"
212.Ft "const char *"
213.Fn tls_conn_servername "struct tls *ctx"
214.Ft "const char *"
215.Fn tls_conn_version "struct tls *ctx"
216.Ft "uint8_t *"
217.Fn tls_load_file "const char *file" "size_t *len" "char *password"
218.Ft "struct tls *"
219.Fn tls_client void
220.Ft "struct tls *"
221.Fn tls_server void
222.Ft "int"
223.Fn tls_configure "struct tls *ctx" "struct tls_config *config"
224.Ft "void"
225.Fn tls_reset "struct tls *ctx"
226.Ft "void"
227.Fn tls_free "struct tls *ctx"
228.Ft "int"
229.Fn tls_connect "struct tls *ctx" "const char *host" "const char *port"
230.Ft "int"
231.Fn tls_connect_fds "struct tls *ctx" "int fd_read" "int fd_write" "const char *servername"
232.Ft "int"
233.Fn tls_connect_servername "struct tls *ctx" "const char *host" "const char *port" "const char *servername"
234.Ft "int"
235.Fn tls_connect_socket "struct tls *ctx" "int s" "const char *servername"
236.Ft "int"
237.Fn tls_connect_cbs "struct tls *ctx" "ssize_t (*tls_read_cb)(struct tls *ctx, void *buf, size_t buflen, void *cb_arg)" "ssize_t (*tls_write_cb)(struct tls *ctx, const void *buf, size_t buflen, void *cb_arg)" "void *cb_arg" "const char *servername"
238.Ft "int"
239.Fn tls_accept_fds "struct tls *tls" "struct tls **cctx" "int fd_read" "int fd_write"
240.Ft "int"
241.Fn tls_accept_socket "struct tls *tls" "struct tls **cctx" "int socket"
242.Ft "int"
243.Fn tls_accept_cbs "struct tls *ctx" "struct tls **cctx" "ssize_t (*tls_read_cb)(struct *ctx, void *buf, size_t buflen, void *cb_arg)" "ssize_t (*tls_write_cb)(struct tls *ctx, const void *buf, size_t buflen, void *cb_arg)" "void *cb_arg"
244.Ft "int"
245.Fn tls_handshake "struct tls *ctx"
246.Ft "ssize_t"
247.Fn tls_read "struct tls *ctx" "void *buf" "size_t buflen"
248.Ft "ssize_t"
249.Fn tls_write "struct tls *ctx" "const void *buf" "size_t buflen"
250.Ft "int"
251.Fn tls_close "struct tls *ctx"
252.Sh DESCRIPTION
253The
254.Nm tls
255family of functions establishes a secure communications channel
256using the TLS socket protocol.
257Both clients and servers are supported.
258.Pp
259The
260.Fn tls_init
261function should be called once before any function is used.
262It may be called more than once, but not concurrently.
263.Pp
264Before a connection is created, a configuration must be created.
265The
266.Fn tls_config_new
267function returns a new default configuration that can be used for future
268connections.
269Several functions exist to change the options of the configuration; see below.
270.Pp
271A TLS connection is represented as a
272.Em context .
273A new
274.Em context
275is created by either the
276.Fn tls_client
277or
278.Fn tls_server
279functions.
280The context can then be configured with the function
281.Fn tls_configure .
282The same
283.Em tls_config
284object can be used to configure multiple contexts.
285.Pp
286A client connection is initiated after configuration by calling
287.Fn tls_connect .
288This function will create a new socket, connect to the specified host and
289port, and then establish a secure connection.
290The
291.Fn tls_connect_servername
292function has the same behaviour, however the name to use for verification is
293explicitly provided, rather than being inferred from the
294.Ar host
295value.
296An already existing socket can be upgraded to a secure connection by calling
297.Fn tls_connect_socket .
298Alternatively, a secure connection can be established over a pair of existing
299file descriptors by calling
300.Fn tls_connect_fds .
301Calling
302.Fn tls_connect_cbs
303allows read and write callback functions to handle data transfers.
304The specified cb_arg parameter is passed back to the functions,
305and can contain a pointer to any caller-specified data.
306.Pp
307A server can accept a new client connection by calling
308.Fn tls_accept_socket
309on an already established socket connection.
310Alternatively, a new client connection can be accepted over a pair of existing
311file descriptors by calling
312.Fn tls_accept_fds .
313Calling
314.Fn tls_accept_cbs
315allows read and write callback functions to handle data transfers.
316The specified cb_arg parameter is passed back to the functions,
317and can contain a pointer to any caller-specified data.
318.Pp
319The TLS handshake can be completed by calling
320.Fn tls_handshake .
321Two functions are provided for input and output,
322.Fn tls_read
323and
324.Fn tls_write .
325Both of these functions will result in the TLS handshake being performed if it
326has not already completed.
327.Pp
328After use, a TLS
329.Em context
330should be closed with
331.Fn tls_close ,
332and then freed by calling
333.Fn tls_free .
334When no more contexts are to be created, the
335.Em tls_config
336object should be freed by calling
337.Fn tls_config_free .
338.Sh FUNCTIONS
339The
340.Fn tls_init
341function initializes global data structures.
342It should be called once before any other functions.
343.Pp
344The following functions create and free configuration objects:
345.Bl -bullet -offset four
346.It
347.Fn tls_config_new
348allocates a new default configuration object.
349.It
350.Fn tls_config_free
351frees a configuration object.
352.El
353.Pp
354The
355.Fn tls_config_parse_protocols
356function parses a protocol string and returns the corresponding value via the
357.Ar protocols
358argument.
359This value can then be passed to the
360.Fn tls_config_set_protocols
361function.
362The protocol string is a comma or colon separated list of keywords.
363Valid keywords are tlsv1.0, tlsv1.1, tlsv1.2, all (all supported protocols),
364default (an alias for secure), legacy (an alias for all) and secure (currently
365TLSv1.2 only).
366If a value has a negative prefix (in the form of a leading exclamation mark)
367then it is removed from the list of available protocols, rather than being
368added to it.
369.Pp
370The following functions modify a configuration by setting parameters (the
371configuration options apply to both clients and servers, unless noted
372otherwise):
373.Bl -bullet -offset four
374.It
375.Fn tls_config_add_keypair_file
376adds an additional public certificate and private key from the specified files,
377used as an alternative certificate for Server Name Indication (server only).
378.It
379.Fn tls_config_add_keypair_mem
380adds an additional public certificate and private key from memory,
381used as an alternative certificate for Server Name Indication (server only).
382.It
383.Fn tls_config_add_ticket_key
384adds a key used for the encryption and authentication of TLS tickets.
385By default keys are generated and rotated automatically based on their lifetime.
386This function should only be used to synchronise ticket encryption key across
387multiple processes.
388Re-adding a known key will result in an error, unless it is the most recently
389added key.
390.It
391.Fn tls_config_set_alpn
392sets the ALPN protocols that are supported.
393The alpn string is a comma separated list of protocols, in order of preference.
394.It
395.Fn tls_config_set_ca_file
396sets the filename used to load a file
397containing the root certificates.
398.It
399.Fn tls_config_set_ca_path
400sets the path (directory) which should be searched for root
401certificates.
402.It
403.Fn tls_config_set_ca_mem
404sets the root certificates directly from memory.
405.It
406.Fn tls_config_set_cert_file
407sets file from which the public certificate will be read.
408.It
409.Fn tls_config_set_cert_mem
410sets the public certificate directly from memory.
411.It
412.Fn tls_config_set_ciphers
413sets the list of ciphers that may be used.
414Lists of ciphers are specified by name, and the
415permitted names are:
416.Pp
417.Bl -tag -width "insecure" -offset indent -compact
418.It Dv "secure" (or alias "default")
419.It Dv "compat"
420.It Dv "legacy"
421.It Dv "insecure" (or alias "all")
422.El
423.Pp
424Alternatively, libssl cipher strings can be specified.
425See the CIPHERS section of
426.Xr openssl 1
427for further information.
428.It
429.Fn tls_config_set_key_file
430sets the file from which the private key will be read.
431.It
432.Fn tls_config_set_key_mem
433directly sets the private key from memory.
434.It
435.Fn tls_config_set_keypair_file
436sets the files from which the public certificate and private key will be read.
437.It
438.Fn tls_config_set_keypair_mem
439directly sets the public certificate and private key from memory.
440.It
441.Fn tls_config_set_ocsp_staple_file
442sets a DER-encoded OCSP response to be stapled during the TLS handshake from
443the specified file.
444.It
445.Fn tls_config_set_ocsp_staple_mem
446sets a DER-encoded OCSP response to be stapled during the TLS handshake from
447memory.
448.It
449.Fn tls_config_set_protocols
450sets which versions of the protocol may be used.
451Possible values are the bitwise OR of:
452.Pp
453.Bl -tag -width "TLS_PROTOCOL_TLSv1_2" -offset indent -compact
454.It Dv TLS_PROTOCOL_TLSv1_0
455.It Dv TLS_PROTOCOL_TLSv1_1
456.It Dv TLS_PROTOCOL_TLSv1_2
457.El
458.Pp
459Additionally, the values
460.Dv TLS_PROTOCOL_TLSv1
461(TLSv1.0, TLSv1.1 and TLSv1.2),
462.Dv TLS_PROTOCOLS_ALL
463(all supported protocols) and
464.Dv TLS_PROTOCOLS_DEFAULT
465(TLSv1.2 only) may be used.
466.It
467.Fn tls_config_set_session_id
468sets the session identifier that will be used by the TLS server when
469sessions are enabled.
470By default a random value is used.
471.It
472.Fn tls_config_set_session_lifetime
473sets the lifetime to be used for TLS sessions.
474Session support is disabled if a lifetime of zero is specified, which is the
475default.
476.It
477.Fn tls_config_set_verify_depth
478limits the number of intermediate certificates that will be followed during
479certificate validation.
480.It
481.Fn tls_config_prefer_ciphers_client
482prefers ciphers in the client's cipher list when selecting a cipher suite
483(server only).
484This is considered to be less secure than preferring the server's list.
485.It
486.Fn tls_config_prefer_ciphers_server
487prefers ciphers in the server's cipher list when selecting a cipher suite
488(server only).
489This is considered to be more secure than preferring the client's list and is
490the default.
491.It
492.Fn tls_config_clear_keys
493clears any secret keys from memory.
494.It
495.Fn tls_config_insecure_noverifycert
496disables certificate verification and OCSP validation.
497Be extremely careful when using this option.
498.It
499.Fn tls_config_insecure_noverifyname
500disables server name verification (client only).
501Be careful when using this option.
502.It
503.Fn tls_config_insecure_noverifytime
504disables validity checking of certificates and OCSP validation.
505Be careful when using this option.
506.It
507.Fn tls_config_ocsp_require_stapling
508requires that a valid stapled OCSP response be provided during the TLS handshake.
509.It
510.Fn tls_config_verify
511reenables server name and certificate verification.
512.It
513.Fn tls_config_verify_client
514enables client certificate verification, requiring the client to send
515a certificate (server only).
516.It
517.Fn tls_config_verify_client_optional
518enables client certificate verification, without requiring the client
519to send a certificate (server only).
520.El
521.Pp
522The following functions return information about a TLS connection and will only
523succeed after the handshake is complete (the connection information applies
524to both clients and servers, unless noted otherwise):
525.Bl -bullet -offset four
526.It
527.Fn tls_conn_alpn_selected
528returns a string that specifies the ALPN protocol selected for use with the peer
529connected to
530.Ar ctx .
531If no protocol was selected then NULL is returned.
532.It
533.Fn tls_conn_cipher
534returns a string corresponding to the cipher suite negotiated with the peer
535connected to
536.Ar ctx .
537.It
538.Fn tls_conn_servername
539returns a string corresponding to the servername that the client connected to
540.Ar ctx
541requested by sending a TLS Server Name Indication extension (server only).
542.It
543.Fn tls_conn_version
544returns a string corresponding to a TLS version negotiated with the peer
545connected to
546.Ar ctx .
547.It
548.Fn tls_peer_cert_provided
549checks if the peer of
550.Ar ctx
551has provided a certificate.
552.It
553.Fn tls_peer_cert_contains_name
554checks if the peer of a TLS
555.Ar ctx
556has provided a certificate that contains a
557SAN or CN that matches
558.Ar name .
559.It
560.Fn tls_peer_cert_subject
561returns a string
562corresponding to the subject of the peer certificate from
563.Ar ctx .
564.It
565.Fn tls_peer_cert_issuer
566returns a string
567corresponding to the issuer of the peer certificate from
568.Ar ctx .
569.It
570.Fn tls_peer_cert_hash
571returns a string
572corresponding to a hash of the raw peer certificate from
573.Ar ctx
574prefixed by a hash name followed by a colon.
575The hash currently used is SHA256, though this
576could change in the future.
577The hash string for a certificate in file
578.Ar mycert.crt
579can be generated using the commands:
580.Bd -literal -offset indent
581h=$(openssl x509 -outform der -in mycert.crt | sha256)
582printf "SHA256:${h}\\n"
583.Ed
584.It
585.Fn tls_peer_cert_notbefore
586returns the time corresponding to the start of the validity period of
587the peer certificate from
588.Ar ctx .
589.It
590.Fn tls_peer_cert_notafter
591returns the time corresponding to the end of the validity period of
592the peer certificate from
593.Ar ctx .
594.It
595.Fn tls_ocsp_process_response
596processes a raw OCSP response in
597.Ar response
598of size
599.Ar size
600to check the revocation status of the peer certificate from
601.Ar ctx .
602A successful return code of 0 indicates that the certificate
603has not been revoked.
604.It
605.Fn tls_peer_ocsp_url
606returns the URL for OCSP validation of the peer certificate from
607.Ar ctx
608.El
609.Pp
610The following functions return information about the peer certificate from
611.Ar ctx
612that was obtained by validating a stapled OCSP response during the handshake,
613or via a previous call to
614.Fn tls_ocsp_process_response .
615.Bl -bullet -offset four
616.It
617.Fn tls_peer_ocsp_cert_status
618returns the OCSP certificate status code as per RFC 6960 section 2.2.
619.It
620.Fn tls_peer_ocsp_crl_reason
621returns the OCSP certificate revocation reason status code as per RFC 5280
622section 5.3.1.
623.It
624.Fn tls_peer_ocsp_next_update
625returns the OCSP next update time.
626.It
627.Fn tls_peer_ocsp_response_status
628returns the OCSP response status as per RFC 6960 section 2.3.
629.It
630.Fn tls_peer_ocsp_revocation_time
631returns the OCSP revocation time.
632.It
633.Fn tls_peer_ocsp_this_update
634returns the OCSP this update time.
635.El
636.Pp
637The following are TLS related utility functions:
638.Bl -bullet -offset four
639.It
640.Fn tls_load_file
641loads a certificate or key from disk into memory to be loaded with
642.Fn tls_config_set_ca_mem ,
643.Fn tls_config_set_cert_mem
644or
645.Fn tls_config_set_key_mem .
646A private key will be decrypted if the optional
647.Ar password
648argument is specified.
649.El
650.Pp
651The following functions create, prepare, and free a connection context:
652.Bl -bullet -offset four
653.It
654.Fn tls_client
655creates a new TLS context for client connections.
656.It
657.Fn tls_server
658creates a new TLS context for server connections.
659.It
660.Fn tls_configure
661readies a TLS context for use by applying the configuration
662options.
663.It
664.Fn tls_free
665frees a TLS context after use.
666.El
667.Pp
668The following functions initiate a connection and perform input and output
669operations:
670.Bl -bullet -offset four
671.It
672.Fn tls_connect
673connects a client context to the server named by
674.Fa host .
675The
676.Fa port
677may be numeric or a service name.
678If it is NULL then a host of the format "hostname:port" is permitted.
679.It
680.Fn tls_connect_fds
681connects a client context to a pair of existing file descriptors.
682.It
683.Fn tls_connect_socket
684connects a client context to an already established socket connection.
685.It
686.Fn tls_accept_fds
687creates a new context suitable for reading and writing on an existing pair of
688file descriptors and returns it in
689.Fa *cctx .
690A configured server context should be passed in
691.Fa ctx .
692.It
693.Fn tls_accept_socket
694creates a new context suitable for reading and writing on an already
695established socket connection and returns it in
696.Fa *cctx .
697A configured server context should be passed in
698.Fa ctx .
699.It
700.Fn tls_handshake
701performs the TLS handshake.
702It is only necessary to call this function if you need to guarantee that the
703handshake has completed, as both
704.Fn tls_read
705and
706.Fn tls_write
707will perform the TLS handshake if necessary.
708.It
709.Fn tls_read
710reads
711.Fa buflen
712bytes of data from the socket into
713.Fa buf .
714It returns the amount of data read.
715.It
716.Fn tls_write
717writes
718.Fa buflen
719bytes of data from
720.Fa buf
721to the socket.
722It returns the amount of data written.
723.It
724.Fn tls_close
725closes a connection after use.
726Only the TLS layer will be shut down and the caller is responsible for closing
727the file descriptors, unless the connection was established using
728.Fn tls_connect
729or
730.Fn tls_connect_servername .
731.El
732.Sh RETURN VALUES
733The
734.Fn tls_peer_cert_provided
735and
736.Fn tls_peer_cert_contains_name
737functions return 1 if the check succeeds, and 0 if it does not.
738.Pp
739Functions that return a
740.Vt time_t
741will return a time in epoch-seconds on success, and -1 on error.
742.Pp
743Functions that return a
744.Vt ssize_t
745will return a size on success, and -1 on error.
746.Pp
747The
748.Fn tls_peer_ocsp_response_status
749function returns one of
750.Ar TLS_OCSP_RESPONSE_SUCCESSFUL ,
751.Ar TLS_OCSP_RESPONSE_MALFORMED ,
752.Ar TLS_OCSP_RESPONSE_INTERNALERROR ,
753.Ar TLS_OCSP_RESPONSE_TRYLATER ,
754.Ar TLS_OCSP_RESPONSE_SIGREQUIRED ,
755or
756.Ar TLS_OCSP_RESPONSE_UNAUTHORIZED
757on success, and -1 on error.
758.Pp
759The
760.Fn tls_peer_ocsp_cert_status
761function returns one of
762.Ar TLS_OCSP_CERT_GOOD ,
763.Ar TLS_OCSP_CERT_REVOKED ,
764or
765.Ar TLS_OCSP_CERT_UNKNOWN
766on success, and -1 on error.
767.Pp
768The
769.Fn tls_peer_ocsp_crl_reason
770function returns one of
771.Ar TLS_CRL_REASON_UNSPECIFIED ,
772.Ar TLS_CRL_REASON_KEY_COMPROMISE ,
773.Ar TLS_CRL_REASON_CA_COMPROMISE ,
774.Ar TLS_CRL_REASON_AFFILIATION_CHANGED ,
775.Ar TLS_CRL_REASON_SUPERSEDED ,
776.Ar TLS_CRL_REASON_CESSATION_OF_OPERATION ,
777.Ar TLS_CRL_REASON_CERTIFICATE_HOLD ,
778.Ar TLS_CRL_REASON_REMOVE_FROM_CRL ,
779.Ar TLS_CRL_REASON_PRIVILEGE_WITHDRAWN ,
780or
781.Ar TLS_CRL_REASON_AA_COMPROMISE
782on success, and -1 on error.
783.Pp
784All other functions that return
785.Vt int
786will return 0 on success and -1 on error.
787.Pp
788Functions that return a pointer will return NULL on error or an
789out of memory condition.
790.Pp
791The
792.Fn tls_handshake ,
793.Fn tls_read ,
794.Fn tls_write ,
795and
796.Fn tls_close
797functions have two special return values:
798.Pp
799.Bl -tag -width "TLS_WANT_POLLOUT" -offset indent -compact
800.It Dv TLS_WANT_POLLIN
801The underlying read file descriptor needs to be readable in order to continue.
802.It Dv TLS_WANT_POLLOUT
803The underlying write file descriptor needs to be writeable in order to continue.
804.El
805.Pp
806In the case of blocking file descriptors, the same function call should be
807repeated immediately.
808In the case of non-blocking file descriptors, the same function call should be
809repeated when the required condition has been met.
810.Pp
811Callers of these functions cannot rely on the value of the global
812.Ar errno .
813To prevent mishandling of error conditions,
814.Fn tls_handshake ,
815.Fn tls_read ,
816.Fn tls_write ,
817and
818.Fn tls_close
819all explicitly clear
820.Ar errno .
821.Sh EXAMPLES
822The following example demonstrates how to handle TLS writes on a blocking
823file descriptor:
824.Bd -literal -offset indent
825\&...
826while (len > 0) {
827 ssize_t ret;
828
829 ret = tls_write(ctx, buf, len);
830 if (ret == TLS_WANT_POLLIN || ret == TLS_WANT_POLLOUT)
831 continue;
832 if (ret < 0)
833 err(1, "tls_write: %s", tls_error(ctx));
834 buf += ret;
835 len -= ret;
836}
837\&...
838.Ed
839.Pp
840The following example demonstrates how to handle TLS writes on a
841non-blocking file descriptor using
842.Xr poll 2 :
843.Bd -literal -offset indent
844\&...
845pfd[0].fd = fd;
846pfd[0].events = POLLIN|POLLOUT;
847while (len > 0) {
848 nready = poll(pfd, 1, 0);
849 if (nready == -1)
850 err(1, "poll");
851 if ((pfd[0].revents & (POLLERR|POLLNVAL)))
852 errx(1, "bad fd %d", pfd[0].fd);
853 if ((pfd[0].revents & (pfd[0].events|POLLHUP))) {
854 ssize_t ret;
855
856 ret = tls_write(ctx, buf, len);
857 if (ret == TLS_WANT_POLLIN)
858 pfd[0].events = POLLIN;
859 else if (ret == TLS_WANT_POLLOUT)
860 pfd[0].events = POLLOUT;
861 else if (ret < 0)
862 err(1, "tls_write: %s", tls_error(ctx));
863 else {
864 buf += ret;
865 len -= ret;
866 }
867 }
868}
869\&...
870.Ed
871.Sh ERRORS
872The
873.Fn tls_config_error
874and
875.Fn tls_error
876functions may be used to retrieve a string containing more information
877about the most recent error relating to a configuration or context.
878.\" .Sh SEE ALSO
879.Sh HISTORY
880The
881.Nm tls
882API first appeared in
883.Ox 5.6
884as a response to the unnecessary challenges other APIs present in
885order to use them safely.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-20 23:27:24 +0000