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.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
13 files changed, 1468 insertions, 0 deletions
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
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-01 07:05:35 +0000