From 35fdef4d614c3469f40e63e53b292de178a9e20c Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 25 Jan 2017 23:53:18 +0000 Subject: split the tls_init(3) that had grown fat to allow healthy future growth; suggested by jsing@; "i would just chuck it in" jmc@ --- src/lib/libtls/man/Makefile | 23 +++ src/lib/libtls/man/tls_accept_socket.3 | 84 +++++++++ src/lib/libtls/man/tls_client.3 | 87 +++++++++ .../libtls/man/tls_config_ocsp_require_stapling.3 | 59 ++++++ src/lib/libtls/man/tls_config_set_protocols.3 | 146 +++++++++++++++ src/lib/libtls/man/tls_config_set_session_id.3 | 70 ++++++++ src/lib/libtls/man/tls_config_verify.3 | 59 ++++++ src/lib/libtls/man/tls_conn_version.3 | 154 ++++++++++++++++ src/lib/libtls/man/tls_connect.3 | 114 ++++++++++++ src/lib/libtls/man/tls_init.3 | 126 +++++++++++++ src/lib/libtls/man/tls_load_file.3 | 197 +++++++++++++++++++++ src/lib/libtls/man/tls_ocsp_process_response.3 | 154 ++++++++++++++++ src/lib/libtls/man/tls_read.3 | 195 ++++++++++++++++++++ 13 files changed, 1468 insertions(+) create mode 100644 src/lib/libtls/man/Makefile create mode 100644 src/lib/libtls/man/tls_accept_socket.3 create mode 100644 src/lib/libtls/man/tls_client.3 create mode 100644 src/lib/libtls/man/tls_config_ocsp_require_stapling.3 create mode 100644 src/lib/libtls/man/tls_config_set_protocols.3 create mode 100644 src/lib/libtls/man/tls_config_set_session_id.3 create mode 100644 src/lib/libtls/man/tls_config_verify.3 create mode 100644 src/lib/libtls/man/tls_conn_version.3 create mode 100644 src/lib/libtls/man/tls_connect.3 create mode 100644 src/lib/libtls/man/tls_init.3 create mode 100644 src/lib/libtls/man/tls_load_file.3 create mode 100644 src/lib/libtls/man/tls_ocsp_process_response.3 create mode 100644 src/lib/libtls/man/tls_read.3 (limited to 'src/lib/libtls/man') 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 @@ +# $OpenBSD: Makefile,v 1.1 2017/01/25 23:53:18 schwarze Exp $ + +.include + +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 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 @@ +.\" $OpenBSD: tls_accept_socket.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst +.\" +.\" 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/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 @@ +.\" $OpenBSD: tls_client.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst +.\" +.\" 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/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 @@ +.\" $OpenBSD: tls_config_ocsp_require_stapling.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst +.\" +.\" 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/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 @@ +.\" $OpenBSD: tls_config_set_protocols.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst +.\" +.\" 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/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 @@ +.\" $OpenBSD: tls_config_set_session_id.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst +.\" +.\" 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/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 @@ +.\" $OpenBSD: tls_config_verify.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst +.\" +.\" 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/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 @@ +.\" $OpenBSD: tls_conn_version.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst +.\" +.\" 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/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 @@ +.\" $OpenBSD: tls_connect.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst +.\" +.\" 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/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 @@ +.\" $OpenBSD: tls_init.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst +.\" +.\" 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/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 @@ +.\" $OpenBSD: tls_load_file.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst +.\" +.\" 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/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 @@ +.\" $OpenBSD: tls_ocsp_process_response.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst +.\" +.\" 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/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 @@ +.\" $OpenBSD: tls_read.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst +.\" +.\" 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 -- cgit v1.2.3-55-g6feb