diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/libtls/Makefile | 9 | ||||
| -rw-r--r-- | lib/libtls/man/Makefile | 23 | ||||
| -rw-r--r-- | lib/libtls/man/tls_accept_socket.3 | 84 | ||||
| -rw-r--r-- | lib/libtls/man/tls_client.3 | 87 | ||||
| -rw-r--r-- | lib/libtls/man/tls_config_ocsp_require_stapling.3 | 59 | ||||
| -rw-r--r-- | lib/libtls/man/tls_config_set_protocols.3 | 146 | ||||
| -rw-r--r-- | lib/libtls/man/tls_config_set_session_id.3 | 70 | ||||
| -rw-r--r-- | lib/libtls/man/tls_config_verify.3 | 59 | ||||
| -rw-r--r-- | lib/libtls/man/tls_conn_version.3 | 154 | ||||
| -rw-r--r-- | lib/libtls/man/tls_connect.3 | 114 | ||||
| -rw-r--r-- | lib/libtls/man/tls_init.3 | 126 | ||||
| -rw-r--r-- | lib/libtls/man/tls_load_file.3 | 197 | ||||
| -rw-r--r-- | lib/libtls/man/tls_ocsp_process_response.3 | 154 | ||||
| -rw-r--r-- | lib/libtls/man/tls_read.3 | 195 | ||||
| -rw-r--r-- | lib/libtls/tls_init.3 | 885 |
15 files changed, 1474 insertions, 888 deletions
diff --git a/lib/libtls/Makefile b/lib/libtls/Makefile index af860bb0670..d528ddf5eeb 100644 --- a/lib/libtls/Makefile +++ b/lib/libtls/Makefile @@ -1,4 +1,9 @@ -# $OpenBSD: Makefile,v 1.29 2016/11/05 08:12:22 jsing Exp $ +# $OpenBSD: Makefile,v 1.30 2017/01/25 23:53:18 schwarze Exp $ + +.include <bsd.own.mk> +.ifndef NOMAN +SUBDIR= man +.endif CFLAGS+= -Wall -Werror -Wimplicit CFLAGS+= -DLIBRESSL_INTERNAL @@ -30,8 +35,6 @@ SRCS= tls.c \ tls_ocsp.c \ tls_verify.c -MAN= tls_init.3 - includes: @cd ${.CURDIR}; for i in $(HDRS); do \ j="cmp -s $$i ${DESTDIR}/usr/include/$$i || \ diff --git a/lib/libtls/man/Makefile b/lib/libtls/man/Makefile new file mode 100644 index 00000000000..4883377669a --- /dev/null +++ b/lib/libtls/man/Makefile @@ -0,0 +1,23 @@ +# $OpenBSD: Makefile,v 1.1 2017/01/25 23:53:18 schwarze Exp $ + +.include <bsd.own.mk> + +MAN = \ + tls_accept_socket.3 \ + tls_client.3 \ + tls_config_ocsp_require_stapling.3 \ + tls_config_set_protocols.3 \ + tls_config_set_session_id.3 \ + tls_config_verify.3 \ + tls_conn_version.3 \ + tls_connect.3 \ + tls_init.3 \ + tls_load_file.3 \ + tls_ocsp_process_response.3 \ + tls_read.3 \ + +all clean cleandir depend includes obj tags: + +install: maninstall + +.include <bsd.man.mk> diff --git a/lib/libtls/man/tls_accept_socket.3 b/lib/libtls/man/tls_accept_socket.3 new file mode 100644 index 00000000000..8ea2b03714b --- /dev/null +++ b/lib/libtls/man/tls_accept_socket.3 @@ -0,0 +1,84 @@ +.\" $OpenBSD: tls_accept_socket.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: January 25 2017 $ +.Dt TLS_ACCEPT_SOCKET 3 +.Os +.Sh NAME +.Nm tls_accept_socket , +.Nm tls_accept_fds , +.Nm tls_accept_cbs +.Nd accept an incoming client connection in a TLS server +.Sh SYNOPSIS +.In tls.h +.Ft int +.Fo tls_accept_socket +.Fa "struct tls *tls" +.Fa "struct tls **cctx" +.Fa "int socket" +.Fc +.Ft int +.Fo tls_accept_fds +.Fa "struct tls *tls" +.Fa "struct tls **cctx" +.Fa "int fd_read" +.Fa "int fd_write" +.Fc +.Ft int +.Fo tls_accept_cbs +.Fa "struct tls *tls" +.Fa "struct tls **cctx" +.Fa "ssize_t (*tls_read_cb)(struct tls *ctx,\ + void *buf, size_t buflen, void *cb_arg)" +.Fa "ssize_t (*tls_write_cb)(struct tls *ctx,\ + const void *buf, size_t buflen, void *cb_arg)" +.Fa "void *cb_arg" +.Fc +.Sh DESCRIPTION +After creating a TLS server context +.Fa tls +with +.Xr tls_server 3 +and configuring it with +.Xr tls_configure 3 , +a server can accept a new client connection by calling +.Fn tls_accept_socket +on an already established socket connection. +.Pp +Alternatively, a new client connection can be accepted over a pair of existing +file descriptors by calling +.Fn tls_accept_fds . +.Pp +Calling +.Fn tls_accept_cbs +allows read and write callback functions to handle data transfers. +The specified +.Fa cb_arg +parameter is passed back to the functions, +and can contain a pointer to any caller-specified data. +.Pp +All these functions create a new context suitable for reading and writing +and return it in +.Fa *cctx . +.Sh RETURN VALUES +These functions return 0 on success or -1 on error. +.Sh SEE ALSO +.Xr tls_close 3 , +.Xr tls_config_set_session_id 3 , +.Xr tls_configure 3 , +.Xr tls_connect 3 , +.Xr tls_init 3 , +.Xr tls_server 3 diff --git a/lib/libtls/man/tls_client.3 b/lib/libtls/man/tls_client.3 new file mode 100644 index 00000000000..c8b2cb644ed --- /dev/null +++ b/lib/libtls/man/tls_client.3 @@ -0,0 +1,87 @@ +.\" $OpenBSD: tls_client.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: January 25 2017 $ +.Dt TLS_CLIENT 3 +.Os +.Sh NAME +.Nm tls_client , +.Nm tls_server , +.Nm tls_configure , +.Nm tls_free +.Nd configure a TLS connection +.Sh SYNOPSIS +.In tls.h +.Ft struct tls * +.Fn tls_client void +.Ft struct tls * +.Fn tls_server void +.Ft int +.Fo tls_configure +.Fa "struct tls *ctx" +.Fa "struct tls_config *config" +.Fc +.Ft void +.Fn tls_free "struct tls *ctx" +.Sh DESCRIPTION +A TLS connection is represented as a +.Vt struct tls +object called a +.Dq context . +A new context is created by either the +.Fn tls_client +or +.Fn tls_server +functions. +.Fn tls_client +is used in TLS client programs, +.Fn tls_server +in TLS server programs. +.Pp +The context can then be configured with the function +.Fn tls_configure . +The same +.Vt tls_config +object can be used to configure multiple contexts. +.Pp +After configuration, +.Xr tls_connect 3 +can be called on objects created with +.Fn tls_client , +and +.Xr tls_accept_socket 3 +on objects created with +.Fn tls_server . +.Pp +After use, a TLS context should be closed with +.Xr tls_close 3 , +and then freed by calling +.Fn tls_free . +.Sh RETURN VALUES +.Fn tls_client +and +.Fn tls_server +return +.Dv NULL +on error or an out of memory condition. +.Pp +.Fn tls_configure +returns 0 on success or -1 on error. +.Sh SEE ALSO +.Xr tls_accept_socket 3 , +.Xr tls_config_new 3 , +.Xr tls_connect 3 , +.Xr tls_init 3 diff --git a/lib/libtls/man/tls_config_ocsp_require_stapling.3 b/lib/libtls/man/tls_config_ocsp_require_stapling.3 new file mode 100644 index 00000000000..9304d8707b1 --- /dev/null +++ b/lib/libtls/man/tls_config_ocsp_require_stapling.3 @@ -0,0 +1,59 @@ +.\" $OpenBSD: tls_config_ocsp_require_stapling.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: January 25 2017 $ +.Dt TLS_CONFIG_OCSP_REQUIRE_STAPLING 3 +.Os +.Sh NAME +.Nm tls_config_ocsp_require_stapling , +.Nm tls_config_set_ocsp_staple_mem , +.Nm tls_config_set_ocsp_staple_file +.Nd OCSP configuration for libtls +.Sh SYNOPSIS +.In tls.h +.Ft void +.Fn tls_config_ocsp_require_stapling "struct tls_config *config" +.Ft int +.Fo tls_config_set_ocsp_staple_mem +.Fa "struct tls_config *config" +.Fa "const char *staple" +.Fa "size_t len" +.Fc +.Ft int +.Fo tls_config_set_ocsp_staple_file +.Fa "struct tls_config *config" +.Fa "const char *staple_file" +.Fc +.Sh DESCRIPTION +.Fn tls_config_ocsp_require_stapling +requires that a valid stapled OCSP response be provided during the TLS handshake. +.Pp +.Fn tls_config_set_ocsp_staple_file +sets a DER-encoded OCSP response to be stapled during the TLS handshake from +the specified file. +.Pp +.Fn tls_config_set_ocsp_staple_mem +sets a DER-encoded OCSP response to be stapled during the TLS handshake from +memory. +.Sh RETURN VALUES +.Fn tls_config_set_ocsp_staple_mem +and +.Fn tls_config_set_ocsp_staple_file +return 0 on success or -1 on error. +.Sh SEE ALSO +.Xr tls_handshake 3 , +.Xr tls_init 3 , +.Xr tls_ocsp_process_response 3 diff --git a/lib/libtls/man/tls_config_set_protocols.3 b/lib/libtls/man/tls_config_set_protocols.3 new file mode 100644 index 00000000000..7435390edd6 --- /dev/null +++ b/lib/libtls/man/tls_config_set_protocols.3 @@ -0,0 +1,146 @@ +.\" $OpenBSD: tls_config_set_protocols.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: January 25 2017 $ +.Dt TLS_CONFIG_SET_PROTOCOLS 3 +.Os +.Sh NAME +.Nm tls_config_set_protocols , +.Nm tls_config_parse_protocols , +.Nm tls_config_set_alpn , +.Nm tls_config_set_ciphers , +.Nm tls_config_set_dheparams , +.Nm tls_config_set_ecdhecurve , +.Nm tls_config_prefer_ciphers_client , +.Nm tls_config_prefer_ciphers_server +.Nd TLS protocol and cipher selection +.Sh SYNOPSIS +.In tls.h +.Ft int +.Fo tls_config_set_protocols +.Fa "struct tls_config *config" +.Fa "uint32_t protocols" +.Fc +.Ft int +.Fo tls_config_parse_protocols +.Fa "uint32_t *protocols" +.Fa "const char *protostr" +.Fc +.Ft int +.Fo tls_config_set_alpn +.Fa "struct tls_config *config" +.Fa "const char *alpn" +.Fc +.Ft int +.Fo tls_config_set_ciphers +.Fa "struct tls_config *config" +.Fa "const char *ciphers" +.Fc +.Ft int +.Fo tls_config_set_dheparams +.Fa "struct tls_config *config" +.Fa "const char *params" +.Fc +.Ft int +.Fo tls_config_set_ecdhecurve +.Fa "struct tls_config *config" +.Fa "const char *name" +.Fc +.Ft void +.Fn tls_config_prefer_ciphers_client "struct tls_config *config" +.Ft void +.Fn tls_config_prefer_ciphers_server "struct tls_config *config" +.Sh DESCRIPTION +These functions modify a configuration by setting parameters. +The configuration options apply to both clients and servers, unless noted +otherwise. +.Pp +.Fn tls_config_set_protocols +specifies which versions of the TLS protocol may be used. +Possible values are the bitwise OR of: +.Pp +.Bl -tag -width "TLS_PROTOCOL_TLSv1_2" -offset indent -compact +.It Dv TLS_PROTOCOL_TLSv1_0 +.It Dv TLS_PROTOCOL_TLSv1_1 +.It Dv TLS_PROTOCOL_TLSv1_2 +.El +.Pp +Additionally, the values +.Dv TLS_PROTOCOL_TLSv1 +(TLSv1.0, TLSv1.1 and TLSv1.2), +.Dv TLS_PROTOCOLS_ALL +(all supported protocols) and +.Dv TLS_PROTOCOLS_DEFAULT +(TLSv1.2 only) may be used. +.Pp +The +.Fn tls_config_parse_protocols +utility function parses a protocol string and returns the corresponding +value via the +.Ar protocols +argument. +This value can then be passed to the +.Fn tls_config_set_protocols +function. +The protocol string is a comma or colon separated list of keywords. +Valid keywords are tlsv1.0, tlsv1.1, tlsv1.2, all (all supported protocols), +default (an alias for secure), legacy (an alias for all) and secure (currently +TLSv1.2 only). +If a value has a negative prefix (in the form of a leading exclamation mark) +then it is removed from the list of available protocols, rather than being +added to it. +.Pp +.Fn tls_config_set_alpn +sets the ALPN protocols that are supported. +The alpn string is a comma separated list of protocols, in order of preference. +.Pp +.Fn tls_config_set_ciphers +sets the list of ciphers that may be used. +Lists of ciphers are specified by name, and the +permitted names are: +.Pp +.Bl -tag -width "insecure" -offset indent -compact +.It Dv "secure" (or alias "default") +.It Dv "compat" +.It Dv "legacy" +.It Dv "insecure" (or alias "all") +.El +.Pp +Alternatively, libssl cipher strings can be specified. +See the CIPHERS section of +.Xr openssl 1 +for further information. +.\" XXX tls_config_set_dheparams does what? +.\" XXX tls_config_set_ecdhecurve does what? +.Pp +.Fn tls_config_prefer_ciphers_client +prefers ciphers in the client's cipher list when selecting a cipher suite +(server only). +This is considered to be less secure than preferring the server's list. +.Pp +.Fn tls_config_prefer_ciphers_server +prefers ciphers in the server's cipher list when selecting a cipher suite +(server only). +This is considered to be more secure than preferring the client's list and is +the default. +.Sh RETURN VALUES +These functions return 0 on success or -1 on error. +.Sh SEE ALSO +.Xr tls_config_ocsp_require_stapling 3 , +.Xr tls_config_set_session_id 3 , +.Xr tls_config_verify 3 , +.Xr tls_init 3 , +.Xr tls_load_file 3 diff --git a/lib/libtls/man/tls_config_set_session_id.3 b/lib/libtls/man/tls_config_set_session_id.3 new file mode 100644 index 00000000000..0e964c916dd --- /dev/null +++ b/lib/libtls/man/tls_config_set_session_id.3 @@ -0,0 +1,70 @@ +.\" $OpenBSD: tls_config_set_session_id.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: January 25 2017 $ +.Dt TLS_CONFIG_SET_SESSION_ID 3 +.Os +.Sh NAME +.Nm tls_config_set_session_id , +.Nm tls_config_set_session_lifetime , +.Nm tls_config_add_ticket_key +.Nd configure resuming of TLS handshakes +.Sh SYNOPSIS +.In tls.h +.Ft int +.Fo tls_config_set_session_id +.Fa "struct tls_config *config" +.Fa "const unsigned char *session_id" +.Fa "size_t len" +.Fc +.Ft int +.Fo tls_config_set_session_lifetime +.Fa "struct tls_config *config" +.Fa "int lifetime" +.Fc +.Ft int +.Fo tls_config_add_ticket_key +.Fa "struct tls_config *config" +.Fa "uint32_t keyrev" +.Fa "unsigned char *key" +.Fa "size_t keylen" +.Fc +.Sh DESCRIPTION +.Fn tls_config_set_session_id +sets the session identifier that will be used by the TLS server when +sessions are enabled. +By default a random value is used. +.Pp +.Fn tls_config_set_session_lifetime +sets the lifetime to be used for TLS sessions. +Session support is disabled if a lifetime of zero is specified, which is the +default. +.Pp +.Fn tls_config_add_ticket_key +adds a key used for the encryption and authentication of TLS tickets. +By default keys are generated and rotated automatically based on their lifetime. +This function should only be used to synchronise ticket encryption key across +multiple processes. +Re-adding a known key will result in an error, unless it is the most recently +added key. +.Sh RETURN VALUES +These functions return 0 on success or -1 on error. +.Sh SEE ALSO +.Xr tls_accept_socket 3 , +.Xr tls_config_set_protocols 3 , +.Xr tls_init 3 , +.Xr tls_load_file 3 , +.Xr tls_server 3 diff --git a/lib/libtls/man/tls_config_verify.3 b/lib/libtls/man/tls_config_verify.3 new file mode 100644 index 00000000000..ba0c997340d --- /dev/null +++ b/lib/libtls/man/tls_config_verify.3 @@ -0,0 +1,59 @@ +.\" $OpenBSD: tls_config_verify.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: January 25 2017 $ +.Dt TLS_CONGIG_VERIFY 3 +.Os +.Sh NAME +.Nm tls_config_verify , +.Nm tls_config_insecure_noverifycert , +.Nm tls_config_insecure_noverifyname , +.Nm tls_config_insecure_noverifytime +.Nd insecure TLS configuration +.Sh SYNOPSIS +.In tls.h +.Ft void +.Fn tls_config_verify "struct tls_config *config" +.Ft void +.Fn tls_config_insecure_noverifycert "struct tls_config *config" +.Ft void +.Fn tls_config_insecure_noverifyname "struct tls_config *config" +.Ft void +.Fn tls_config_insecure_noverifytime "struct tls_config *config" +.Sh DESCRIPTION +These functions disable parts of the normal certificate verification +process, resulting in insecure configurations. +Be very careful when using them. +.Pp +.Fn tls_config_insecure_noverifycert +disables certificate verification and OCSP validation. +.Pp +.Fn tls_config_insecure_noverifyname +disables server name verification (client only). +.Pp +.Fn tls_config_insecure_noverifytime +disables validity checking of certificates and OCSP validation. +.Pp +.Fn tls_config_verify +reenables server name and certificate verification. +.Sh SEE ALSO +.Xr tls_client 3 , +.Xr tls_config_ocsp_require_stapling 3 , +.Xr tls_config_set_protocols 3 , +.Xr tls_conn_version 3 , +.Xr tls_connect 3 , +.Xr tls_handshake 3 , +.Xr tls_init 3 diff --git a/lib/libtls/man/tls_conn_version.3 b/lib/libtls/man/tls_conn_version.3 new file mode 100644 index 00000000000..89fb4019c8a --- /dev/null +++ b/lib/libtls/man/tls_conn_version.3 @@ -0,0 +1,154 @@ +.\" $OpenBSD: tls_conn_version.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: January 25 2017 $ +.Dt TLS_INIT 3 +.Os +.Sh NAME +.Nm tls_conn_version , +.Nm tls_conn_cipher , +.Nm tls_conn_alpn_selected , +.Nm tls_conn_servername , +.Nm tls_peer_cert_provided , +.Nm tls_peer_cert_contains_name , +.Nm tls_peer_cert_issuer , +.Nm tls_peer_cert_subject , +.Nm tls_peer_cert_hash , +.Nm tls_peer_cert_notbefore , +.Nm tls_peer_cert_notafter +.Nd inspect an established TLS connection +.Sh SYNOPSIS +.In tls.h +.Ft const char * +.Fn tls_conn_version "struct tls *ctx" +.Ft const char * +.Fn tls_conn_cipher "struct tls *ctx" +.Ft const char * +.Fn tls_conn_alpn_selected "struct tls *ctx" +.Ft const char * +.Fn tls_conn_servername "struct tls *ctx" +.Ft int +.Fn tls_peer_cert_provided "struct tls *ctx" +.Ft int +.Fo tls_peer_cert_contains_name +.Fa "struct tls *ctx" +.Fa "const char *name" +.Fc +.Ft const char * +.Fn tls_peer_cert_issuer "struct tls *ctx" +.Ft const char * +.Fn tls_peer_cert_subject "struct tls *ctx" +.Ft const char * +.Fn tls_peer_cert_hash "struct tls *ctx" +.Ft time_t +.Fn tls_peer_cert_notbefore "struct tls *ctx" +.Ft time_t +.Fn tls_peer_cert_notafter "struct tls *ctx" +.Sh DESCRIPTION +These functions return information about a TLS connection and will only +succeed after the handshake is complete (the connection information applies +to both clients and servers, unless noted otherwise): +.Pp +.Fn tls_conn_version +returns a string corresponding to a TLS version negotiated with the peer +connected to +.Ar ctx . +.Pp +.Fn tls_conn_cipher +returns a string corresponding to the cipher suite negotiated with the peer +connected to +.Ar ctx . +.Pp +.Fn tls_conn_alpn_selected +returns a string that specifies the ALPN protocol selected for use with the peer +connected to +.Ar ctx . +If no protocol was selected then NULL is returned. +.Pp +.Fn tls_conn_servername +returns a string corresponding to the servername that the client connected to +.Ar ctx +requested by sending a TLS Server Name Indication extension (server only). +.Pp +.Fn tls_peer_cert_provided +checks if the peer of +.Ar ctx +has provided a certificate. +.Pp +.Fn tls_peer_cert_contains_name +checks if the peer of a TLS +.Ar ctx +has provided a certificate that contains a +SAN or CN that matches +.Ar name . +.Pp +.Fn tls_peer_cert_subject +returns a string +corresponding to the subject of the peer certificate from +.Ar ctx . +.Pp +.Fn tls_peer_cert_issuer +returns a string +corresponding to the issuer of the peer certificate from +.Ar ctx . +.Pp +.Fn tls_peer_cert_hash +returns a string +corresponding to a hash of the raw peer certificate from +.Ar ctx +prefixed by a hash name followed by a colon. +The hash currently used is SHA256, though this +could change in the future. +The hash string for a certificate in file +.Ar mycert.crt +can be generated using the commands: +.Bd -literal -offset indent +h=$(openssl x509 -outform der -in mycert.crt | sha256) +printf "SHA256:${h}\\n" +.Ed +.Pp +.Fn tls_peer_cert_notbefore +returns the time corresponding to the start of the validity period of +the peer certificate from +.Ar ctx . +.Pp +.Fn tls_peer_cert_notafter +returns the time corresponding to the end of the validity period of +the peer certificate from +.Ar ctx . +.Pp +POINTER TO +.Xr tls_ocsp_process_response 3 +.Sh RETURN VALUES +The +.Fn tls_peer_cert_provided +and +.Fn tls_peer_cert_contains_name +functions return 1 if the check succeeds or 0 if it does not. +.Pp +.Fn tls_peer_cert_notbefore +and +.Fn tls_peer_cert_notafter +return a time in epoch-seconds on success or -1 on error. +.Pp +The functions that return a pointer return +.Dv NULL +on error or an out of memory condition. +.Sh SEE ALSO +.Xr tls_configure 3 , +.Xr tls_handshake 3 , +.Xr tls_init 3 , +.Xr tls_ocsp_process_response 3 diff --git a/lib/libtls/man/tls_connect.3 b/lib/libtls/man/tls_connect.3 new file mode 100644 index 00000000000..8137fba53b5 --- /dev/null +++ b/lib/libtls/man/tls_connect.3 @@ -0,0 +1,114 @@ +.\" $OpenBSD: tls_connect.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: January 25 2017 $ +.Dt TLS_CONNECT 3 +.Os +.Sh NAME +.Nm tls_connect , +.Nm tls_connect_fds , +.Nm tls_connect_servername , +.Nm tls_connect_socket , +.Nm tls_connect_cbs +.Nd instruct a TLS client to establish a connection +.Sh SYNOPSIS +.In tls.h +.Ft int +.Fo tls_connect +.Fa "struct tls *ctx" +.Fa "const char *host" +.Fa "const char *port" +.Fc +.Ft int +.Fo tls_connect_fds +.Fa "struct tls *ctx" +.Fa "int fd_read" +.Fa "int fd_write" +.Fa "const char *servername" +.Fc +.Ft int +.Fo tls_connect_servername +.Fa "struct tls *ctx" +.Fa "const char *host" +.Fa "const char *port" +.Fa "const char *servername" +.Fc +.Ft int +.Fo tls_connect_socket +.Fa "struct tls *ctx" +.Fa "int s" +.Fa "const char *servername" +.Fc +.Ft int +.Fo tls_connect_cbs +.Fa "struct tls *ctx" +.Fa "ssize_t (*tls_read_cb)(struct tls *ctx,\ + void *buf, size_t buflen, void *cb_arg)" +.Fa "ssize_t (*tls_write_cb)(struct tls *ctx,\ + const void *buf, size_t buflen, void *cb_arg)" +.Fa "void *cb_arg" +.Fa "const char *servername" +.Fc +.Sh DESCRIPTION +After creating a TLS client context with +.Xr tls_client 3 +and configuring it with +.Xr tls_configure 3 , +a client connection is initiated by calling +.Fn tls_connect . +This function will create a new socket, connect to the specified +.Fa host +and +.Fa port , +and then establish a secure connection. +The +.Fa port +may be numeric or a service name. +If it is +.Dv NULL , +then a +.Fa host +of the format "hostname:port" is permitted. +.Pp +The +.Fn tls_connect_servername +function has the same behaviour, however the name to use for verification is +explicitly provided, rather than being inferred from the +.Ar host +value. +.Pp +An already existing socket can be upgraded to a secure connection by calling +.Fn tls_connect_socket . +.Pp +Alternatively, a secure connection can be established over a pair of existing +file descriptors by calling +.Fn tls_connect_fds . +.Pp +Calling +.Fn tls_connect_cbs +allows read and write callback functions to handle data transfers. +The specified cb_arg parameter is passed back to the functions, +and can contain a pointer to any caller-specified data. +.Sh RETURN VALUES +These functions return 0 on success or -1 on error. +.Sh SEE ALSO +.Xr tls_accept_socket 3 , +.Xr tls_client 3 , +.Xr tls_close 3 , +.Xr tls_config_ocsp_require_stapling 3 , +.Xr tls_configure 3 , +.Xr tls_handshake 3 , +.Xr tls_init 3 diff --git a/lib/libtls/man/tls_init.3 b/lib/libtls/man/tls_init.3 new file mode 100644 index 00000000000..af0eec38020 --- /dev/null +++ b/lib/libtls/man/tls_init.3 @@ -0,0 +1,126 @@ +.\" $OpenBSD: tls_init.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: January 25 2017 $ +.Dt TLS_INIT 3 +.Os +.Sh NAME +.Nm tls_init , +.Nm tls_config_new , +.Nm tls_config_free , +.Nm tls_config_error +.Nd initialize TLS client and server API +.Sh SYNOPSIS +.In tls.h +.Ft int +.Fn tls_init void +.Ft struct tls_config * +.Fn tls_config_new void +.Ft void +.Fn tls_config_free "struct tls_config *config" +.Ft const char * +.Fn tls_config_error "struct tls_config *config" +.Sh DESCRIPTION +The +.Nm tls +family of functions establishes a secure communications channel +using the TLS socket protocol. +Both clients and servers are supported. +.Pp +The +.Fn tls_init +function initializes global data structures. +It should be called once before any other functions. +It may be called more than once, but not concurrently. +.Pp +Before a connection is created, a configuration must be created. +The +.Fn tls_config_new +function allocates, initializes, and returns a new default configuration +object that can be used for future connections. +Several functions exist to change the options of the configuration; see +.Xr tls_config_set_protocols 3 , +.Xr tls_load_file 3 , +.Xr tls_config_ocsp_require_stapling 3 , +and +.Xr tls_config_verify 3 . +.Pp +The +.Fn tls_config_error +function may be used to retrieve a string containing more information +about the most recent error relating to a configuration. +.Pp +A TLS connection object is created by +.Xr tls_client 3 +or +.Xr tls_server 3 +and configured with +.Xr tls_configure 3 . +.Pp +A client connection is initiated after configuration by calling +.Xr tls_connect 3 . +A server can accept a new client connection by calling +.Xr tls_accept_socket 3 +on an already established socket connection. +.Pp +Two functions are provided for input and output, +.Xr tls_read 3 +and +.Xr tls_write 3 . +Both automatically perform the +.Xr tls_handshake 3 +when needed. +.Pp +The properties of established TLS connections +can be inspected with the functions described in +.Xr tls_conn_version 3 +and +.Xr tls_ocsp_process_response 3 . +.Pp +After use, a TLS connection should be closed with +.Xr tls_close 3 +and then freed by calling +.Xr tls_free 3 . +.Pp +When no more contexts are to be created, +the configuration object should be freed by calling +.Fn tls_config_free . +.Sh RETURN VALUES +.Fn tls_init +returns 0 on success or -1 on error. +.Pp +.Fn tls_config_new +returns +.Dv NULL +on error or an out of memory condition. +.Sh SEE ALSO +.Xr tls_accept_socket 3 , +.Xr tls_client 3 , +.Xr tls_config_ocsp_require_stapling 3 , +.Xr tls_config_set_protocols 3 , +.Xr tls_config_verify 3 , +.Xr tls_conn_version 3 , +.Xr tls_connect 3 , +.Xr tls_load_file 3 , +.Xr tls_ocsp_process_response 3 , +.Xr tls_read 3 +.Sh HISTORY +The +.Nm tls +API first appeared in +.Ox 5.6 +as a response to the unnecessary challenges other APIs present in +order to use them safely. diff --git a/lib/libtls/man/tls_load_file.3 b/lib/libtls/man/tls_load_file.3 new file mode 100644 index 00000000000..2b2f01a8a9d --- /dev/null +++ b/lib/libtls/man/tls_load_file.3 @@ -0,0 +1,197 @@ +.\" $OpenBSD: tls_load_file.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: January 25 2017 $ +.Dt TLS_LOAD_FILE 3 +.Os +.Sh NAME +.Nm tls_load_file , +.Nm tls_config_set_ca_file , +.Nm tls_config_set_ca_path , +.Nm tls_config_set_ca_mem , +.Nm tls_config_set_cert_file , +.Nm tls_config_set_cert_mem , +.Nm tls_config_set_key_file , +.Nm tls_config_set_key_mem , +.Nm tls_config_set_keypair_file , +.Nm tls_config_set_keypair_mem , +.Nm tls_config_add_keypair_file , +.Nm tls_config_add_keypair_mem , +.Nm tls_config_clear_keys , +.Nm tls_config_set_verify_depth , +.Nm tls_config_verify_client , +.Nm tls_config_verify_client_optional +.Nd TLS certificate and key configuration +.Sh SYNOPSIS +.In tls.h +.Ft uint8_t * +.Fo tls_load_file +.Fa "const char *file" +.Fa "size_t *len" +.Fa "char *password" +.Fc +.Ft int +.Fo tls_config_set_ca_file +.Fa "struct tls_config *config" +.Fa "const char *ca_file" +.Fc +.Ft int +.Fo tls_config_set_ca_path +.Fa "struct tls_config *config" +.Fa "const char *ca_path" +.Fc +.Ft int +.Fo tls_config_set_ca_mem +.Fa "struct tls_config *config" +.Fa "const uint8_t *cert" +.Fa "size_t len" +.Fc +.Ft int +.Fo tls_config_set_cert_file +.Fa "struct tls_config *config" +.Fa "const char *cert_file" +.Fc +.Ft int +.Fo tls_config_set_cert_mem +.Fa "struct tls_config *config" +.Fa "const uint8_t *cert" +.Fa "size_t len" +.Fc +.Ft int +.Fo tls_config_set_key_file +.Fa "struct tls_config *config" +.Fa "const char *key_file" +.Fc +.Ft int +.Fo tls_config_set_key_mem +.Fa "struct tls_config *config" +.Fa "const uint8_t *key" +.Fa "size_t len" +.Fc +.Ft int +.Fo tls_config_set_keypair_file +.Fa "struct tls_config *config" +.Fa "const char *cert_file" +.Fa "const char *key_file" +.Fc +.Ft int +.Fo tls_config_set_keypair_mem +.Fa "struct tls_config *config" +.Fa "const uint8_t *cert" +.Fa "size_t cert_len" +.Fa "const uint8_t *key" +.Fa "size_t key_len" +.Fc +.Ft int +.Fo tls_config_add_keypair_file +.Fa "struct tls_config *config" +.Fa "const char *cert_file" +.Fa "const char *key_file" +.Fc +.Ft int +.Fo tls_config_add_keypair_mem +.Fa "struct tls_config *config" +.Fa "const uint8_t *cert" +.Fa "size_t cert_len" +.Fa "const uint8_t *key" +.Fa "size_t key_len" +.Fc +.Ft void +.Fn tls_config_clear_keys "struct tls_config *config" +.Ft int +.Fo tls_config_set_verify_depth +.Fa "struct tls_config *config" +.Fa "int verify_depth" +.Fc +.Ft void +.Fn tls_config_verify_client "struct tls_config *config" +.Ft void +.Fn tls_config_verify_client_optional "struct tls_config *config" +.Sh DESCRIPTION +.Fn tls_load_file +loads a certificate or key from disk into memory to be loaded with +.Fn tls_config_set_ca_mem , +.Fn tls_config_set_cert_mem +or +.Fn tls_config_set_key_mem . +A private key will be decrypted if the optional +.Ar password +argument is specified. +.Pp +.Fn tls_config_set_ca_file +sets the filename used to load a file +containing the root certificates. +.Pp +.Fn tls_config_set_ca_path +sets the path (directory) which should be searched for root +certificates. +.Pp +.Fn tls_config_set_ca_mem +sets the root certificates directly from memory. +.Pp +.Fn tls_config_set_cert_file +sets file from which the public certificate will be read. +.Pp +.Fn tls_config_set_cert_mem +sets the public certificate directly from memory. +.Pp +.Fn tls_config_set_key_file +sets the file from which the private key will be read. +.Pp +.Fn tls_config_set_key_mem +directly sets the private key from memory. +.Pp +.Fn tls_config_set_keypair_file +sets the files from which the public certificate and private key will be read. +.Pp +.Fn tls_config_set_keypair_mem +directly sets the public certificate and private key from memory. +.Pp +.Fn tls_config_add_keypair_file +adds an additional public certificate and private key from the specified files, +used as an alternative certificate for Server Name Indication (server only). +.Pp +.Fn tls_config_add_keypair_mem +adds an additional public certificate and private key from memory, +used as an alternative certificate for Server Name Indication (server only). +.Pp +.Fn tls_config_clear_keys +clears any secret keys from memory. +.Pp +.Fn tls_config_set_verify_depth +limits the number of intermediate certificates that will be followed during +certificate validation. +.Pp +.Fn tls_config_verify_client +enables client certificate verification, requiring the client to send +a certificate (server only). +.Pp +.Fn tls_config_verify_client_optional +enables client certificate verification, without requiring the client +to send a certificate (server only). +.Sh RETURN VALUES +.Fn tls_load_file +returns +.Dv NULL +on error or an out of memory condition. +.Pp +The other functions return 0 on success or -1 on error. +.Sh SEE ALSO +.Xr tls_config_ocsp_require_stapling 3 , +.Xr tls_config_set_protocols 3 , +.Xr tls_config_set_session_id 3 , +.Xr tls_configure 3 , +.Xr tls_init 3 diff --git a/lib/libtls/man/tls_ocsp_process_response.3 b/lib/libtls/man/tls_ocsp_process_response.3 new file mode 100644 index 00000000000..78dc0ee42c2 --- /dev/null +++ b/lib/libtls/man/tls_ocsp_process_response.3 @@ -0,0 +1,154 @@ +.\" $OpenBSD: tls_ocsp_process_response.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: January 25 2017 $ +.Dt TLS_OCSP_PROCESS_RESPONSE 3 +.Os +.Sh NAME +.Nm tls_ocsp_process_response , +.Nm tls_peer_ocsp_cert_status , +.Nm tls_peer_ocsp_crl_reason , +.Nm tls_peer_ocsp_next_update , +.Nm tls_peer_ocsp_response_status , +.Nm tls_peer_ocsp_result_msg , +.Nm tls_peer_ocsp_revocation_time , +.Nm tls_peer_ocsp_this_update , +.Nm tls_peer_ocsp_url +.Nd inspect an OCSP response +.Sh SYNOPSIS +.In tls.h +.Ft int +.Fo tls_ocsp_process_response +.Fa "struct tls *ctx" +.Fa "const unsigned char *response" +.Fa "size_t size" +.Fc +.Ft int +.Fn tls_peer_ocsp_cert_status "struct tls *ctx" +.Ft int +.Fn tls_peer_ocsp_crl_reason "struct tls *ctx" +.Ft time_t +.Fn tls_peer_ocsp_next_update "struct tls *ctx" +.Ft int +.Fn tls_peer_ocsp_response_status "struct tls *ctx" +.Ft const char * +.Fn tls_peer_ocsp_result_msg "struct tls *ctx" +.Ft time_t +.Fn tls_peer_ocsp_revocation_time "struct tls *ctx" +.Ft time_t +.Fn tls_peer_ocsp_this_update "struct tls *ctx" +.Ft const char * +.Fn tls_peer_ocsp_url "struct tls *ctx" +.Sh DESCRIPTION +.Fn tls_ocsp_process_response +processes a raw OCSP response in +.Ar response +of size +.Ar size +to check the revocation status of the peer certificate from +.Ar ctx . +A successful return code of 0 indicates that the certificate +has not been revoked. +.Pp +.Fn tls_peer_ocsp_url +returns the URL for OCSP validation of the peer certificate from +.Ar ctx . +.Pp +The following functions return information about the peer certificate from +.Ar ctx +that was obtained by validating a stapled OCSP response during the handshake, +or via a previous call to +.Fn tls_ocsp_process_response . +.Pp +.Fn tls_peer_ocsp_cert_status +returns the OCSP certificate status code as per RFC 6960 section 2.2. +.Pp +.Fn tls_peer_ocsp_crl_reason +returns the OCSP certificate revocation reason status code as per RFC 5280 +section 5.3.1. +.Pp +.Fn tls_peer_ocsp_next_update +returns the OCSP next update time. +.Pp +.Fn tls_peer_ocsp_response_status +returns the OCSP response status as per RFC 6960 section 2.3. +.Pp +.\" XXX Fn tls_peer_ocsp_result_msg does what? +.Fn tls_peer_ocsp_revocation_time +returns the OCSP revocation time. +.Pp +.Fn tls_peer_ocsp_this_update +returns the OCSP this update time. +.Sh RETURN VALUES +.Fn tls_ocsp_process_response +returns 0 on success or -1 on error. +.Pp +The +.Fn tls_peer_ocsp_response_status +function returns one of +.Dv TLS_OCSP_RESPONSE_SUCCESSFUL , +.Dv TLS_OCSP_RESPONSE_MALFORMED , +.Dv TLS_OCSP_RESPONSE_INTERNALERROR , +.Dv TLS_OCSP_RESPONSE_TRYLATER , +.Dv TLS_OCSP_RESPONSE_SIGREQUIRED , +or +.Dv TLS_OCSP_RESPONSE_UNAUTHORIZED +on success or -1 on error. +.Pp +The +.Fn tls_peer_ocsp_cert_status +function returns one of +.Dv TLS_OCSP_CERT_GOOD , +.Dv TLS_OCSP_CERT_REVOKED , +or +.Dv TLS_OCSP_CERT_UNKNOWN +on success, and -1 on error. +.Pp +The +.Fn tls_peer_ocsp_crl_reason +function returns one of +.Dv TLS_CRL_REASON_UNSPECIFIED , +.Dv TLS_CRL_REASON_KEY_COMPROMISE , +.Dv TLS_CRL_REASON_CA_COMPROMISE , +.Dv TLS_CRL_REASON_AFFILIATION_CHANGED , +.Dv TLS_CRL_REASON_SUPERSEDED , +.Dv TLS_CRL_REASON_CESSATION_OF_OPERATION , +.Dv TLS_CRL_REASON_CERTIFICATE_HOLD , +.Dv TLS_CRL_REASON_REMOVE_FROM_CRL , +.Dv TLS_CRL_REASON_PRIVILEGE_WITHDRAWN , +or +.Dv TLS_CRL_REASON_AA_COMPROMISE +on success or -1 on error. +.Pp +.Fn tls_peer_ocsp_next_update , +.Fn tls_peer_ocsp_revocation_time , +and +.Fn tls_peer_ocsp_this_update +return a time in epoch-seconds on success or -1 on error. +.Pp +.Fn tls_peer_ocsp_result_msg +and +.Fn tls_peer_ocsp_url +return +.Dv NULL +on error or an out of memory condition. +.Sh SEE ALSO +.Xr tls_client 3 , +.Xr tls_config_ocsp_require_stapling 3 , +.Xr tls_conn_version 3 , +.Xr tls_connect 3 , +.Xr tls_handshake 3 , +.Xr tls_init 3 diff --git a/lib/libtls/man/tls_read.3 b/lib/libtls/man/tls_read.3 new file mode 100644 index 00000000000..74ce0057585 --- /dev/null +++ b/lib/libtls/man/tls_read.3 @@ -0,0 +1,195 @@ +.\" $OpenBSD: tls_read.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: January 25 2017 $ +.Dt TLS_READ 3 +.Os +.Sh NAME +.Nm tls_read , +.Nm tls_write , +.Nm tls_handshake , +.Nm tls_error , +.Nm tls_close , +.Nm tls_reset +.Nd use a TLS connection +.Sh SYNOPSIS +.In tls.h +.Ft ssize_t +.Fo tls_read +.Fa "struct tls *ctx" +.Fa "void *buf" +.Fa "size_t buflen" +.Fc +.Ft ssize_t +.Fo tls_write +.Fa "struct tls *ctx" +.Fa "const void *buf" +.Fa "size_t buflen" +.Fc +.Ft int +.Fn tls_handshake "struct tls *ctx" +.Ft const char * +.Fn tls_error "struct tls *ctx" +.Ft int +.Fn tls_close "struct tls *ctx" +.Ft void +.Fn tls_reset "struct tls *ctx" +.Sh DESCRIPTION +.Fn tls_read +reads +.Fa buflen +bytes of data from the socket into +.Fa buf . +It returns the amount of data read. +.Pp +.Fn tls_write +writes +.Fa buflen +bytes of data from +.Fa buf +to the socket. +It returns the amount of data written. +.Pp +.Fn tls_handshake +explicitly performs the TLS handshake. +It is only necessary to call this function if you need to guarantee that the +handshake has completed, as both +.Fn tls_read +and +.Fn tls_write +automatically perform the TLS handshake when necessary. +.Pp +The +.Fn tls_error +function may be used to retrieve a string containing more information +about the most recent error relating to a context. +.Pp +.Fn tls_close +closes a connection after use. +Only the TLS layer will be shut down and the caller is responsible for closing +the file descriptors, unless the connection was established using +.Xr tls_connect 3 +or +.Xr tls_connect_servername 3 . +After closing the connection, +.Fa ctx +can be passed to +.Xr tls_free 3 . +.\" XXX Fn tls_reset does what? +.Sh RETURN VALUES +.Fn tls_read +and +.Fn tls_write +return a size on success or -1 on error. +.Pp +.Fn tls_handshake +and +.Fn tls_close +return 0 on success or -1 on error. +.Pp +.Fn tls_error +returns +.Dv NULL +if no error occurred or the first place, or if memory allocation +failed while trying to assemble the string describing the error. +.Pp +The +.Fn tls_read , +.Fn tls_write , +.Fn tls_handshake , +and +.Fn tls_close +functions have two special return values: +.Pp +.Bl -tag -width "TLS_WANT_POLLOUT" -offset indent -compact +.It Dv TLS_WANT_POLLIN +The underlying read file descriptor needs to be readable in order to continue. +.It Dv TLS_WANT_POLLOUT +The underlying write file descriptor needs to be writeable in order to continue. +.El +.Pp +In the case of blocking file descriptors, the same function call should be +repeated immediately. +In the case of non-blocking file descriptors, the same function call should be +repeated when the required condition has been met. +.Pp +Callers of these functions cannot rely on the value of the global +.Ar errno . +To prevent mishandling of error conditions, +.Fn tls_read , +.Fn tls_write , +.Fn tls_handshake , +and +.Fn tls_close +all explicitly clear +.Ar errno . +.Sh EXAMPLES +The following example demonstrates how to handle TLS writes on a blocking +file descriptor: +.Bd -literal -offset indent +\&... +while (len > 0) { + ssize_t ret; + + ret = tls_write(ctx, buf, len); + if (ret == TLS_WANT_POLLIN || ret == TLS_WANT_POLLOUT) + continue; + if (ret < 0) + err(1, "tls_write: %s", tls_error(ctx)); + buf += ret; + len -= ret; +} +\&... +.Ed +.Pp +The following example demonstrates how to handle TLS writes on a +non-blocking file descriptor using +.Xr poll 2 : +.Bd -literal -offset indent +\&... +pfd[0].fd = fd; +pfd[0].events = POLLIN|POLLOUT; +while (len > 0) { + nready = poll(pfd, 1, 0); + if (nready == -1) + err(1, "poll"); + if ((pfd[0].revents & (POLLERR|POLLNVAL))) + errx(1, "bad fd %d", pfd[0].fd); + if ((pfd[0].revents & (pfd[0].events|POLLHUP))) { + ssize_t ret; + + ret = tls_write(ctx, buf, len); + if (ret == TLS_WANT_POLLIN) + pfd[0].events = POLLIN; + else if (ret == TLS_WANT_POLLOUT) + pfd[0].events = POLLOUT; + else if (ret < 0) + err(1, "tls_write: %s", tls_error(ctx)); + else { + buf += ret; + len -= ret; + } + } +} +\&... +.Ed +.Sh SEE ALSO +.Xr tls_accept_socket 3 , +.Xr tls_configure 3 , +.Xr tls_conn_version 3 , +.Xr tls_connect 3 , +.Xr tls_init 3 , +.Xr tls_ocsp_process_response 3 diff --git a/lib/libtls/tls_init.3 b/lib/libtls/tls_init.3 deleted file mode 100644 index 5d4be14edec..00000000000 --- a/lib/libtls/tls_init.3 +++ /dev/null @@ -1,885 +0,0 @@ -.\" $OpenBSD: tls_init.3,v 1.86 2017/01/24 07:57:39 jmc Exp $ -.\" -.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> -.\" -.\" Permission to use, copy, modify, and distribute this software for any -.\" purpose with or without fee is hereby granted, provided that the above -.\" copyright notice and this permission notice appear in all copies. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF -.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.\" -.Dd $Mdocdate: January 24 2017 $ -.Dt TLS_INIT 3 -.Os -.Sh NAME -.Nm tls_init , -.Nm tls_config_error , -.Nm tls_error , -.Nm tls_config_new , -.Nm tls_config_free , -.Nm tls_config_parse_protocols , -.Nm tls_config_add_keypair_file , -.Nm tls_config_add_keypair_mem , -.Nm tls_config_add_ticket_key , -.Nm tls_config_set_alpn , -.Nm tls_config_set_ca_file , -.Nm tls_config_set_ca_path , -.Nm tls_config_set_ca_mem , -.Nm tls_config_set_cert_file , -.Nm tls_config_set_cert_mem , -.Nm tls_config_set_ciphers , -.Nm tls_config_set_dheparams , -.Nm tls_config_set_ecdhecurve , -.Nm tls_config_set_key_file , -.Nm tls_config_set_key_mem , -.Nm tls_config_set_keypair_file , -.Nm tls_config_set_keypair_mem , -.Nm tls_config_set_ocsp_staple_mem , -.Nm tls_config_set_ocsp_staple_file , -.Nm tls_config_set_protocols , -.Nm tls_config_set_session_id , -.Nm tls_config_set_session_lifetime , -.Nm tls_config_set_verify_depth , -.Nm tls_config_prefer_ciphers_client , -.Nm tls_config_prefer_ciphers_server , -.Nm tls_config_clear_keys , -.Nm tls_config_insecure_noverifycert , -.Nm tls_config_insecure_noverifyname , -.Nm tls_config_insecure_noverifytime , -.Nm tls_config_ocsp_require_stapling , -.Nm tls_config_verify , -.Nm tls_config_verify_client , -.Nm tls_config_verify_client_optional , -.Nm tls_peer_cert_provided , -.Nm tls_peer_cert_contains_name , -.Nm tls_peer_cert_issuer , -.Nm tls_peer_cert_subject , -.Nm tls_peer_cert_hash , -.Nm tls_peer_cert_notbefore , -.Nm tls_peer_cert_notafter , -.Nm tls_ocsp_process_response , -.Nm tls_peer_ocsp_cert_status , -.Nm tls_peer_ocsp_crl_reason , -.Nm tls_peer_ocsp_next_update , -.Nm tls_peer_ocsp_response_status , -.Nm tls_peer_ocsp_result_msg , -.Nm tls_peer_ocsp_revocation_time , -.Nm tls_peer_ocsp_this_update , -.Nm tls_peer_ocsp_url , -.Nm tls_conn_alpn_selected , -.Nm tls_conn_cipher , -.Nm tls_conn_servername , -.Nm tls_conn_version , -.Nm tls_load_file , -.Nm tls_client , -.Nm tls_server , -.Nm tls_configure , -.Nm tls_reset , -.Nm tls_free , -.Nm tls_connect , -.Nm tls_connect_fds , -.Nm tls_connect_servername , -.Nm tls_connect_socket , -.Nm tls_connect_cbs , -.Nm tls_accept_fds , -.Nm tls_accept_socket , -.Nm tls_accept_cbs , -.Nm tls_handshake , -.Nm tls_read , -.Nm tls_write , -.Nm tls_close -.Nd TLS client and server API -.Sh SYNOPSIS -.In tls.h -.Ft "int" -.Fn tls_init "void" -.Ft "const char *" -.Fn tls_config_error "struct tls_config *config" -.Ft "const char *" -.Fn tls_error "struct tls *ctx" -.Ft "struct tls_config *" -.Fn tls_config_new "void" -.Ft "void" -.Fn tls_config_free "struct tls_config *config" -.Ft "int" -.Fn tls_config_parse_protocols "uint32_t *protocols" "const char *protostr" -.Ft "int" -.Fn tls_config_add_keypair_file "struct tls_config *config" "const char *cert_file" "const char *key_file" -.Ft "int" -.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" -.Ft "int" -.Fn tls_config_add_ticket_key "struct tls_config *config" "uint32_t keyrev" "unsigned char *key" "size_t keylen" -.Ft "int" -.Fn tls_config_set_alpn "struct tls_config *config" "const char *alpn" -.Ft "int" -.Fn tls_config_set_ca_file "struct tls_config *config" "const char *ca_file" -.Ft "int" -.Fn tls_config_set_ca_path "struct tls_config *config" "const char *ca_path" -.Ft "int" -.Fn tls_config_set_ca_mem "struct tls_config *config" "const uint8_t *cert" "size_t len" -.Ft "int" -.Fn tls_config_set_cert_file "struct tls_config *config" "const char *cert_file" -.Ft "int" -.Fn tls_config_set_cert_mem "struct tls_config *config" "const uint8_t *cert" "size_t len" -.Ft "int" -.Fn tls_config_set_ciphers "struct tls_config *config" "const char *ciphers" -.Ft "int" -.Fn tls_config_set_dheparams "struct tls_config *config" "const char *params" -.Ft "int" -.Fn tls_config_set_ecdhecurve "struct tls_config *config" "const char *name" -.Ft "int" -.Fn tls_config_set_key_file "struct tls_config *config" "const char *key_file" -.Ft "int" -.Fn tls_config_set_key_mem "struct tls_config *config" "const uint8_t *key" "size_t len" -.Ft "int" -.Fn tls_config_set_keypair_file "struct tls_config *config" "const char *cert_file" "const char *key_file" -.Ft "int" -.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" -.Ft "int" -.Fn tls_config_set_ocsp_staple_mem "struct tls_config *config" "const char *staple" "size_t len" -.Ft "int" -.Fn tls_config_set_ocsp_staple_file "struct tls_config *config" "const char *staple_file" -.Ft "int" -.Fn tls_config_set_protocols "struct tls_config *config" "uint32_t protocols" -.Ft "int" -.Fn tls_config_set_session_id "struct tls_config *config" "const unsigned char *session_id" "size_t len" -.Ft "int" -.Fn tls_config_set_session_lifetime "struct tls_config *config" "int lifetime" -.Ft "int" -.Fn tls_config_set_verify_depth "struct tls_config *config" "int verify_depth" -.Ft "void" -.Fn tls_config_prefer_ciphers_client "struct tls_config *config" -.Ft "void" -.Fn tls_config_prefer_ciphers_server "struct tls_config *config" -.Ft "void" -.Fn tls_config_clear_keys "struct tls_config *config" -.Ft "void" -.Fn tls_config_insecure_noverifycert "struct tls_config *config" -.Ft "void" -.Fn tls_config_insecure_noverifyname "struct tls_config *config" -.Ft "void" -.Fn tls_config_insecure_noverifytime "struct tls_config *config" -.Ft "void" -.Fn tls_config_ocsp_require_stapling "struct tls_config *config" -.Ft "void" -.Fn tls_config_verify "struct tls_config *config" -.Ft "void" -.Fn tls_config_verify_client "struct tls_config *config" -.Ft "void" -.Fn tls_config_verify_client_optional "struct tls_config *config" -.Ft "int" -.Fn tls_peer_cert_provided "struct tls *ctx" -.Ft "int" -.Fn tls_peer_cert_contains_name "struct tls *ctx" "const char *name" -.Ft "const char *" -.Fn tls_peer_cert_issuer "struct tls *ctx" -.Ft "const char *" -.Fn tls_peer_cert_subject "struct tls *ctx" -.Ft "const char *" -.Fn tls_peer_cert_hash "struct tls *ctx" -.Ft "time_t" -.Fn tls_peer_cert_notbefore "struct tls *ctx" -.Ft "time_t" -.Fn tls_peer_cert_notafter "struct tls *ctx" -.Ft "int" -.Fn tls_ocsp_process_response "struct tls *ctx" "const unsigned char *response" "size_t size" -.Ft "int" -.Fn tls_peer_ocsp_cert_status "struct tls *ctx" -.Ft "int" -.Fn tls_peer_ocsp_crl_reason "struct tls *ctx" -.Ft time_t -.Fn tls_peer_ocsp_next_update "struct tls *ctx" -.Ft "int" -.Fn tls_peer_ocsp_response_status "struct tls *ctx" -.Ft "const char *" -.Fn tls_peer_ocsp_result_msg "struct tls *ctx" -.Ft "time_t" -.Fn tls_peer_ocsp_revocation_time "struct tls *ctx" -.Ft "time_t" -.Fn tls_peer_ocsp_this_update "struct tls *ctx" -.Ft "const char *" -.Fn tls_peer_ocsp_url "struct tls *ctx" -.Ft "const char *" -.Fn tls_conn_alpn_selected "struct tls *ctx" -.Ft "const char *" -.Fn tls_conn_cipher "struct tls *ctx" -.Ft "const char *" -.Fn tls_conn_servername "struct tls *ctx" -.Ft "const char *" -.Fn tls_conn_version "struct tls *ctx" -.Ft "uint8_t *" -.Fn tls_load_file "const char *file" "size_t *len" "char *password" -.Ft "struct tls *" -.Fn tls_client void -.Ft "struct tls *" -.Fn tls_server void -.Ft "int" -.Fn tls_configure "struct tls *ctx" "struct tls_config *config" -.Ft "void" -.Fn tls_reset "struct tls *ctx" -.Ft "void" -.Fn tls_free "struct tls *ctx" -.Ft "int" -.Fn tls_connect "struct tls *ctx" "const char *host" "const char *port" -.Ft "int" -.Fn tls_connect_fds "struct tls *ctx" "int fd_read" "int fd_write" "const char *servername" -.Ft "int" -.Fn tls_connect_servername "struct tls *ctx" "const char *host" "const char *port" "const char *servername" -.Ft "int" -.Fn tls_connect_socket "struct tls *ctx" "int s" "const char *servername" -.Ft "int" -.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" -.Ft "int" -.Fn tls_accept_fds "struct tls *tls" "struct tls **cctx" "int fd_read" "int fd_write" -.Ft "int" -.Fn tls_accept_socket "struct tls *tls" "struct tls **cctx" "int socket" -.Ft "int" -.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" -.Ft "int" -.Fn tls_handshake "struct tls *ctx" -.Ft "ssize_t" -.Fn tls_read "struct tls *ctx" "void *buf" "size_t buflen" -.Ft "ssize_t" -.Fn tls_write "struct tls *ctx" "const void *buf" "size_t buflen" -.Ft "int" -.Fn tls_close "struct tls *ctx" -.Sh DESCRIPTION -The -.Nm tls -family of functions establishes a secure communications channel -using the TLS socket protocol. -Both clients and servers are supported. -.Pp -The -.Fn tls_init -function should be called once before any function is used. -It may be called more than once, but not concurrently. -.Pp -Before a connection is created, a configuration must be created. -The -.Fn tls_config_new -function returns a new default configuration that can be used for future -connections. -Several functions exist to change the options of the configuration; see below. -.Pp -A TLS connection is represented as a -.Em context . -A new -.Em context -is created by either the -.Fn tls_client -or -.Fn tls_server -functions. -The context can then be configured with the function -.Fn tls_configure . -The same -.Em tls_config -object can be used to configure multiple contexts. -.Pp -A client connection is initiated after configuration by calling -.Fn tls_connect . -This function will create a new socket, connect to the specified host and -port, and then establish a secure connection. -The -.Fn tls_connect_servername -function has the same behaviour, however the name to use for verification is -explicitly provided, rather than being inferred from the -.Ar host -value. -An already existing socket can be upgraded to a secure connection by calling -.Fn tls_connect_socket . -Alternatively, a secure connection can be established over a pair of existing -file descriptors by calling -.Fn tls_connect_fds . -Calling -.Fn tls_connect_cbs -allows read and write callback functions to handle data transfers. -The specified cb_arg parameter is passed back to the functions, -and can contain a pointer to any caller-specified data. -.Pp -A server can accept a new client connection by calling -.Fn tls_accept_socket -on an already established socket connection. -Alternatively, a new client connection can be accepted over a pair of existing -file descriptors by calling -.Fn tls_accept_fds . -Calling -.Fn tls_accept_cbs -allows read and write callback functions to handle data transfers. -The specified cb_arg parameter is passed back to the functions, -and can contain a pointer to any caller-specified data. -.Pp -The TLS handshake can be completed by calling -.Fn tls_handshake . -Two functions are provided for input and output, -.Fn tls_read -and -.Fn tls_write . -Both of these functions will result in the TLS handshake being performed if it -has not already completed. -.Pp -After use, a TLS -.Em context -should be closed with -.Fn tls_close , -and then freed by calling -.Fn tls_free . -When no more contexts are to be created, the -.Em tls_config -object should be freed by calling -.Fn tls_config_free . -.Sh FUNCTIONS -The -.Fn tls_init -function initializes global data structures. -It should be called once before any other functions. -.Pp -The following functions create and free configuration objects: -.Bl -bullet -offset four -.It -.Fn tls_config_new -allocates a new default configuration object. -.It -.Fn tls_config_free -frees a configuration object. -.El -.Pp -The -.Fn tls_config_parse_protocols -function parses a protocol string and returns the corresponding value via the -.Ar protocols -argument. -This value can then be passed to the -.Fn tls_config_set_protocols -function. -The protocol string is a comma or colon separated list of keywords. -Valid keywords are tlsv1.0, tlsv1.1, tlsv1.2, all (all supported protocols), -default (an alias for secure), legacy (an alias for all) and secure (currently -TLSv1.2 only). -If a value has a negative prefix (in the form of a leading exclamation mark) -then it is removed from the list of available protocols, rather than being -added to it. -.Pp -The following functions modify a configuration by setting parameters (the -configuration options apply to both clients and servers, unless noted -otherwise): -.Bl -bullet -offset four -.It -.Fn tls_config_add_keypair_file -adds an additional public certificate and private key from the specified files, -used as an alternative certificate for Server Name Indication (server only). -.It -.Fn tls_config_add_keypair_mem -adds an additional public certificate and private key from memory, -used as an alternative certificate for Server Name Indication (server only). -.It -.Fn tls_config_add_ticket_key -adds a key used for the encryption and authentication of TLS tickets. -By default keys are generated and rotated automatically based on their lifetime. -This function should only be used to synchronise ticket encryption key across -multiple processes. -Re-adding a known key will result in an error, unless it is the most recently -added key. -.It -.Fn tls_config_set_alpn -sets the ALPN protocols that are supported. -The alpn string is a comma separated list of protocols, in order of preference. -.It -.Fn tls_config_set_ca_file -sets the filename used to load a file -containing the root certificates. -.It -.Fn tls_config_set_ca_path -sets the path (directory) which should be searched for root -certificates. -.It -.Fn tls_config_set_ca_mem -sets the root certificates directly from memory. -.It -.Fn tls_config_set_cert_file -sets file from which the public certificate will be read. -.It -.Fn tls_config_set_cert_mem -sets the public certificate directly from memory. -.It -.Fn tls_config_set_ciphers -sets the list of ciphers that may be used. -Lists of ciphers are specified by name, and the -permitted names are: -.Pp -.Bl -tag -width "insecure" -offset indent -compact -.It Dv "secure" (or alias "default") -.It Dv "compat" -.It Dv "legacy" -.It Dv "insecure" (or alias "all") -.El -.Pp -Alternatively, libssl cipher strings can be specified. -See the CIPHERS section of -.Xr openssl 1 -for further information. -.It -.Fn tls_config_set_key_file -sets the file from which the private key will be read. -.It -.Fn tls_config_set_key_mem -directly sets the private key from memory. -.It -.Fn tls_config_set_keypair_file -sets the files from which the public certificate and private key will be read. -.It -.Fn tls_config_set_keypair_mem -directly sets the public certificate and private key from memory. -.It -.Fn tls_config_set_ocsp_staple_file -sets a DER-encoded OCSP response to be stapled during the TLS handshake from -the specified file. -.It -.Fn tls_config_set_ocsp_staple_mem -sets a DER-encoded OCSP response to be stapled during the TLS handshake from -memory. -.It -.Fn tls_config_set_protocols -sets which versions of the protocol may be used. -Possible values are the bitwise OR of: -.Pp -.Bl -tag -width "TLS_PROTOCOL_TLSv1_2" -offset indent -compact -.It Dv TLS_PROTOCOL_TLSv1_0 -.It Dv TLS_PROTOCOL_TLSv1_1 -.It Dv TLS_PROTOCOL_TLSv1_2 -.El -.Pp -Additionally, the values -.Dv TLS_PROTOCOL_TLSv1 -(TLSv1.0, TLSv1.1 and TLSv1.2), -.Dv TLS_PROTOCOLS_ALL -(all supported protocols) and -.Dv TLS_PROTOCOLS_DEFAULT -(TLSv1.2 only) may be used. -.It -.Fn tls_config_set_session_id -sets the session identifier that will be used by the TLS server when -sessions are enabled. -By default a random value is used. -.It -.Fn tls_config_set_session_lifetime -sets the lifetime to be used for TLS sessions. -Session support is disabled if a lifetime of zero is specified, which is the -default. -.It -.Fn tls_config_set_verify_depth -limits the number of intermediate certificates that will be followed during -certificate validation. -.It -.Fn tls_config_prefer_ciphers_client -prefers ciphers in the client's cipher list when selecting a cipher suite -(server only). -This is considered to be less secure than preferring the server's list. -.It -.Fn tls_config_prefer_ciphers_server -prefers ciphers in the server's cipher list when selecting a cipher suite -(server only). -This is considered to be more secure than preferring the client's list and is -the default. -.It -.Fn tls_config_clear_keys -clears any secret keys from memory. -.It -.Fn tls_config_insecure_noverifycert -disables certificate verification and OCSP validation. -Be extremely careful when using this option. -.It -.Fn tls_config_insecure_noverifyname -disables server name verification (client only). -Be careful when using this option. -.It -.Fn tls_config_insecure_noverifytime -disables validity checking of certificates and OCSP validation. -Be careful when using this option. -.It -.Fn tls_config_ocsp_require_stapling -requires that a valid stapled OCSP response be provided during the TLS handshake. -.It -.Fn tls_config_verify -reenables server name and certificate verification. -.It -.Fn tls_config_verify_client -enables client certificate verification, requiring the client to send -a certificate (server only). -.It -.Fn tls_config_verify_client_optional -enables client certificate verification, without requiring the client -to send a certificate (server only). -.El -.Pp -The following functions return information about a TLS connection and will only -succeed after the handshake is complete (the connection information applies -to both clients and servers, unless noted otherwise): -.Bl -bullet -offset four -.It -.Fn tls_conn_alpn_selected -returns a string that specifies the ALPN protocol selected for use with the peer -connected to -.Ar ctx . -If no protocol was selected then NULL is returned. -.It -.Fn tls_conn_cipher -returns a string corresponding to the cipher suite negotiated with the peer -connected to -.Ar ctx . -.It -.Fn tls_conn_servername -returns a string corresponding to the servername that the client connected to -.Ar ctx -requested by sending a TLS Server Name Indication extension (server only). -.It -.Fn tls_conn_version -returns a string corresponding to a TLS version negotiated with the peer -connected to -.Ar ctx . -.It -.Fn tls_peer_cert_provided -checks if the peer of -.Ar ctx -has provided a certificate. -.It -.Fn tls_peer_cert_contains_name -checks if the peer of a TLS -.Ar ctx -has provided a certificate that contains a -SAN or CN that matches -.Ar name . -.It -.Fn tls_peer_cert_subject -returns a string -corresponding to the subject of the peer certificate from -.Ar ctx . -.It -.Fn tls_peer_cert_issuer -returns a string -corresponding to the issuer of the peer certificate from -.Ar ctx . -.It -.Fn tls_peer_cert_hash -returns a string -corresponding to a hash of the raw peer certificate from -.Ar ctx -prefixed by a hash name followed by a colon. -The hash currently used is SHA256, though this -could change in the future. -The hash string for a certificate in file -.Ar mycert.crt -can be generated using the commands: -.Bd -literal -offset indent -h=$(openssl x509 -outform der -in mycert.crt | sha256) -printf "SHA256:${h}\\n" -.Ed -.It -.Fn tls_peer_cert_notbefore -returns the time corresponding to the start of the validity period of -the peer certificate from -.Ar ctx . -.It -.Fn tls_peer_cert_notafter -returns the time corresponding to the end of the validity period of -the peer certificate from -.Ar ctx . -.It -.Fn tls_ocsp_process_response -processes a raw OCSP response in -.Ar response -of size -.Ar size -to check the revocation status of the peer certificate from -.Ar ctx . -A successful return code of 0 indicates that the certificate -has not been revoked. -.It -.Fn tls_peer_ocsp_url -returns the URL for OCSP validation of the peer certificate from -.Ar ctx -.El -.Pp -The following functions return information about the peer certificate from -.Ar ctx -that was obtained by validating a stapled OCSP response during the handshake, -or via a previous call to -.Fn tls_ocsp_process_response . -.Bl -bullet -offset four -.It -.Fn tls_peer_ocsp_cert_status -returns the OCSP certificate status code as per RFC 6960 section 2.2. -.It -.Fn tls_peer_ocsp_crl_reason -returns the OCSP certificate revocation reason status code as per RFC 5280 -section 5.3.1. -.It -.Fn tls_peer_ocsp_next_update -returns the OCSP next update time. -.It -.Fn tls_peer_ocsp_response_status -returns the OCSP response status as per RFC 6960 section 2.3. -.It -.Fn tls_peer_ocsp_revocation_time -returns the OCSP revocation time. -.It -.Fn tls_peer_ocsp_this_update -returns the OCSP this update time. -.El -.Pp -The following are TLS related utility functions: -.Bl -bullet -offset four -.It -.Fn tls_load_file -loads a certificate or key from disk into memory to be loaded with -.Fn tls_config_set_ca_mem , -.Fn tls_config_set_cert_mem -or -.Fn tls_config_set_key_mem . -A private key will be decrypted if the optional -.Ar password -argument is specified. -.El -.Pp -The following functions create, prepare, and free a connection context: -.Bl -bullet -offset four -.It -.Fn tls_client -creates a new TLS context for client connections. -.It -.Fn tls_server -creates a new TLS context for server connections. -.It -.Fn tls_configure -readies a TLS context for use by applying the configuration -options. -.It -.Fn tls_free -frees a TLS context after use. -.El -.Pp -The following functions initiate a connection and perform input and output -operations: -.Bl -bullet -offset four -.It -.Fn tls_connect -connects a client context to the server named by -.Fa host . -The -.Fa port -may be numeric or a service name. -If it is NULL then a host of the format "hostname:port" is permitted. -.It -.Fn tls_connect_fds -connects a client context to a pair of existing file descriptors. -.It -.Fn tls_connect_socket -connects a client context to an already established socket connection. -.It -.Fn tls_accept_fds -creates a new context suitable for reading and writing on an existing pair of -file descriptors and returns it in -.Fa *cctx . -A configured server context should be passed in -.Fa ctx . -.It -.Fn tls_accept_socket -creates a new context suitable for reading and writing on an already -established socket connection and returns it in -.Fa *cctx . -A configured server context should be passed in -.Fa ctx . -.It -.Fn tls_handshake -performs the TLS handshake. -It is only necessary to call this function if you need to guarantee that the -handshake has completed, as both -.Fn tls_read -and -.Fn tls_write -will perform the TLS handshake if necessary. -.It -.Fn tls_read -reads -.Fa buflen -bytes of data from the socket into -.Fa buf . -It returns the amount of data read. -.It -.Fn tls_write -writes -.Fa buflen -bytes of data from -.Fa buf -to the socket. -It returns the amount of data written. -.It -.Fn tls_close -closes a connection after use. -Only the TLS layer will be shut down and the caller is responsible for closing -the file descriptors, unless the connection was established using -.Fn tls_connect -or -.Fn tls_connect_servername . -.El -.Sh RETURN VALUES -The -.Fn tls_peer_cert_provided -and -.Fn tls_peer_cert_contains_name -functions return 1 if the check succeeds, and 0 if it does not. -.Pp -Functions that return a -.Vt time_t -will return a time in epoch-seconds on success, and -1 on error. -.Pp -Functions that return a -.Vt ssize_t -will return a size on success, and -1 on error. -.Pp -The -.Fn tls_peer_ocsp_response_status -function returns one of -.Ar TLS_OCSP_RESPONSE_SUCCESSFUL , -.Ar TLS_OCSP_RESPONSE_MALFORMED , -.Ar TLS_OCSP_RESPONSE_INTERNALERROR , -.Ar TLS_OCSP_RESPONSE_TRYLATER , -.Ar TLS_OCSP_RESPONSE_SIGREQUIRED , -or -.Ar TLS_OCSP_RESPONSE_UNAUTHORIZED -on success, and -1 on error. -.Pp -The -.Fn tls_peer_ocsp_cert_status -function returns one of -.Ar TLS_OCSP_CERT_GOOD , -.Ar TLS_OCSP_CERT_REVOKED , -or -.Ar TLS_OCSP_CERT_UNKNOWN -on success, and -1 on error. -.Pp -The -.Fn tls_peer_ocsp_crl_reason -function returns one of -.Ar TLS_CRL_REASON_UNSPECIFIED , -.Ar TLS_CRL_REASON_KEY_COMPROMISE , -.Ar TLS_CRL_REASON_CA_COMPROMISE , -.Ar TLS_CRL_REASON_AFFILIATION_CHANGED , -.Ar TLS_CRL_REASON_SUPERSEDED , -.Ar TLS_CRL_REASON_CESSATION_OF_OPERATION , -.Ar TLS_CRL_REASON_CERTIFICATE_HOLD , -.Ar TLS_CRL_REASON_REMOVE_FROM_CRL , -.Ar TLS_CRL_REASON_PRIVILEGE_WITHDRAWN , -or -.Ar TLS_CRL_REASON_AA_COMPROMISE -on success, and -1 on error. -.Pp -All other functions that return -.Vt int -will return 0 on success and -1 on error. -.Pp -Functions that return a pointer will return NULL on error or an -out of memory condition. -.Pp -The -.Fn tls_handshake , -.Fn tls_read , -.Fn tls_write , -and -.Fn tls_close -functions have two special return values: -.Pp -.Bl -tag -width "TLS_WANT_POLLOUT" -offset indent -compact -.It Dv TLS_WANT_POLLIN -The underlying read file descriptor needs to be readable in order to continue. -.It Dv TLS_WANT_POLLOUT -The underlying write file descriptor needs to be writeable in order to continue. -.El -.Pp -In the case of blocking file descriptors, the same function call should be -repeated immediately. -In the case of non-blocking file descriptors, the same function call should be -repeated when the required condition has been met. -.Pp -Callers of these functions cannot rely on the value of the global -.Ar errno . -To prevent mishandling of error conditions, -.Fn tls_handshake , -.Fn tls_read , -.Fn tls_write , -and -.Fn tls_close -all explicitly clear -.Ar errno . -.Sh EXAMPLES -The following example demonstrates how to handle TLS writes on a blocking -file descriptor: -.Bd -literal -offset indent -\&... -while (len > 0) { - ssize_t ret; - - ret = tls_write(ctx, buf, len); - if (ret == TLS_WANT_POLLIN || ret == TLS_WANT_POLLOUT) - continue; - if (ret < 0) - err(1, "tls_write: %s", tls_error(ctx)); - buf += ret; - len -= ret; -} -\&... -.Ed -.Pp -The following example demonstrates how to handle TLS writes on a -non-blocking file descriptor using -.Xr poll 2 : -.Bd -literal -offset indent -\&... -pfd[0].fd = fd; -pfd[0].events = POLLIN|POLLOUT; -while (len > 0) { - nready = poll(pfd, 1, 0); - if (nready == -1) - err(1, "poll"); - if ((pfd[0].revents & (POLLERR|POLLNVAL))) - errx(1, "bad fd %d", pfd[0].fd); - if ((pfd[0].revents & (pfd[0].events|POLLHUP))) { - ssize_t ret; - - ret = tls_write(ctx, buf, len); - if (ret == TLS_WANT_POLLIN) - pfd[0].events = POLLIN; - else if (ret == TLS_WANT_POLLOUT) - pfd[0].events = POLLOUT; - else if (ret < 0) - err(1, "tls_write: %s", tls_error(ctx)); - else { - buf += ret; - len -= ret; - } - } -} -\&... -.Ed -.Sh ERRORS -The -.Fn tls_config_error -and -.Fn tls_error -functions may be used to retrieve a string containing more information -about the most recent error relating to a configuration or context. -.\" .Sh SEE ALSO -.Sh HISTORY -The -.Nm tls -API first appeared in -.Ox 5.6 -as a response to the unnecessary challenges other APIs present in -order to use them safely. |