Document functions for client-side TLS session support.

2 files changed, 56 insertions, 9 deletions

diff --git a/lib/libtls/man/tls_config_set_session_id.3 b/lib/libtls/man/tls_config_set_session_id.3
index 7106de46df2..e8a5e60cd7b 100644
--- a/lib/libtls/man/tls_config_set_session_id.3
+++ b/lib/libtls/man/tls_config_set_session_id.3
@@ -1,6 +1,7 @@
-.\" $OpenBSD: tls_config_set_session_id.3,v 1.3 2017/01/28 00:59:36 schwarze Exp $
+.\" $OpenBSD: tls_config_set_session_id.3,v 1.4 2018/02/10 04:43:16 jsing Exp $
 .\"
 .\" Copyright (c) 2017 Claudio Jeker <claudio@openbsd.org>
+.\" Copyright (c) 2018 Joel Sing <jsing@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
@@ -14,10 +15,11 @@
 .\" 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 28 2017 $
+.Dd $Mdocdate: February 10 2018 $
 .Dt TLS_CONFIG_SET_SESSION_ID 3
 .Os
 .Sh NAME
+.Nm tls_config_set_session_fd ,
 .Nm tls_config_set_session_id ,
 .Nm tls_config_set_session_lifetime ,
 .Nm tls_config_add_ticket_key
@@ -25,6 +27,11 @@
 .Sh SYNOPSIS
 .In tls.h
 .Ft int
+.Fo tls_config_set_session_fd
+.Fa "struct tls_config *config"
+.Fa "int session_fd"
+.Fc
+.Ft int
 .Fo tls_config_set_session_id
 .Fa "struct tls_config *config"
 .Fa "const unsigned char *session_id"
@@ -43,18 +50,32 @@
 .Fa "size_t keylen"
 .Fc
 .Sh DESCRIPTION
+.Fn tls_config_set_session_fd
+sets a file descriptor to be used to manage data for TLS sessions (client only).
+The given file descriptor must be a regular file and be owned by the current
+user, with permissions being restricted to only allow the owner to read and
+write the file (0600).
+If the file has a non-zero length, the client will attempt to read session
+data from this file and resume the previous TLS session with the server.
+Upon a successful handshake the file will be updated with current session
+data.
+The caller is responsible for closing this file descriptor, after all TLS
+contexts that have been configured to use it have been freed via
+.Fn tls_free .
+.Pp
 .Fn tls_config_set_session_id
 sets the session identifier that will be used by the TLS server when
-sessions are enabled.
+sessions are enabled (server only).
 By default a random value is used.
 .Pp
 .Fn tls_config_set_session_lifetime
-sets the lifetime to be used for TLS sessions.
+sets the lifetime to be used for TLS sessions (server only).
 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.
+adds a key used for the encryption and authentication of TLS tickets
+(server only).
 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.
@@ -69,7 +90,16 @@ These functions return 0 on success or -1 on error.
 .Xr tls_load_file 3 ,
 .Xr tls_server 3
 .Sh HISTORY
-These functions appeared in
+.Fn tls_config_set_session_id ,
+.Fn tls_config_set_session_lifetime
+and
+.Fn tls_config_add_ticket_key
+appeared in
 .Ox 6.1 .
+.Pp
+.Fn tls_config_set_session_fd
+appeared in
+.Ox 6.3 .
 .Sh AUTHORS
 .An Claudio Jeker Aq Mt claudio@openbsd.org
+.An Joel Sing Aq Mt jsing@openbsd.org
diff --git a/lib/libtls/man/tls_conn_version.3 b/lib/libtls/man/tls_conn_version.3
index f8a1678e8ca..d9ee4ac4b60 100644
--- a/lib/libtls/man/tls_conn_version.3
+++ b/lib/libtls/man/tls_conn_version.3
@@ -1,7 +1,7 @@
-.\" $OpenBSD: tls_conn_version.3,v 1.6 2017/10/08 06:56:36 jmc Exp $
+.\" $OpenBSD: tls_conn_version.3,v 1.7 2018/02/10 04:43:16 jsing Exp $
 .\"
 .\" Copyright (c) 2015 Bob Beck <beck@openbsd.org>
-.\" Copyright (c) 2016 Joel Sing <jsing@openbsd.org>
+.\" Copyright (c) 2016, 2018 Joel Sing <jsing@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
@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: October 8 2017 $
+.Dd $Mdocdate: February 10 2018 $
 .Dt TLS_CONN_VERSION 3
 .Os
 .Sh NAME
@@ -23,6 +23,7 @@
 .Nm tls_conn_cipher ,
 .Nm tls_conn_alpn_selected ,
 .Nm tls_conn_servername ,
+.Nm tls_conn_session_resumed ,
 .Nm tls_peer_cert_provided ,
 .Nm tls_peer_cert_contains_name ,
 .Nm tls_peer_cert_chain_pem ,
@@ -43,6 +44,8 @@
 .Ft const char *
 .Fn tls_conn_servername "struct tls *ctx"
 .Ft int
+.Fn tls_conn_session_resumed "struct tls *ctx"
+.Ft int
 .Fn tls_peer_cert_provided "struct tls *ctx"
 .Ft int
 .Fo tls_peer_cert_contains_name
@@ -90,6 +93,12 @@ 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_conn_session_resumed
+indicates whether a TLS session has been resumed during the handshake with
+the server connected to
+.Ar ctx
+(client only).
+.Pp
 .Fn tls_peer_cert_provided
 checks if the peer of
 .Ar ctx
@@ -146,6 +155,10 @@ POINTER TO
 .Xr tls_ocsp_process_response 3
 .Sh RETURN VALUES
 The
+.Fn tls_conn_session_resumed
+function returns 1 if a TLS session was resumed or 0 if it was not.
+.Pp
+The
 .Fn tls_peer_cert_provided
 and
 .Fn tls_peer_cert_contains_name
@@ -183,6 +196,10 @@ and
 .Fn tls_conn_alpn_selected
 appeared in
 .Ox 6.1 .
+.Pp
+.Fn tls_conn_session_resumed
+appeared in
+.Ox 6.3 .
 .Sh AUTHORS
 .An Bob Beck Aq Mt beck@openbsd.org
 .An Joel Sing Aq Mt jsing@openbsd.org