From a65702226b7ff26155233ebc9d8ece695d77fba7 Mon Sep 17 00:00:00 2001 From: jsing <> Date: Sat, 10 Feb 2018 04:43:16 +0000 Subject: Document functions for client-side TLS session support. --- src/lib/libtls/man/tls_config_set_session_id.3 | 42 ++++++++++++++++++++++---- src/lib/libtls/man/tls_conn_version.3 | 23 ++++++++++++-- 2 files changed, 56 insertions(+), 9 deletions(-) (limited to 'src') diff --git a/src/lib/libtls/man/tls_config_set_session_id.3 b/src/lib/libtls/man/tls_config_set_session_id.3 index 7106de46df..e8a5e60cd7 100644 --- a/src/lib/libtls/man/tls_config_set_session_id.3 +++ b/src/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/src/lib/libtls/man/tls_conn_version.3 b/src/lib/libtls/man/tls_conn_version.3 index f8a1678e8c..d9ee4ac4b6 100644 --- a/src/lib/libtls/man/tls_conn_version.3 +++ b/src/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 -- cgit v1.2.3-55-g6feb