From 940f9ff5fa3d59fb4accce6db9ea98c62da146cb Mon Sep 17 00:00:00 2001 From: jsing Date: Sat, 10 Feb 2018 04:43:16 +0000 Subject: [PATCH] Document functions for client-side TLS session support. --- lib/libtls/man/tls_config_set_session_id.3 | 42 ++++++++++++++++++---- lib/libtls/man/tls_conn_version.3 | 23 ++++++++++-- 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 +.\" Copyright (c) 2018 Joel Sing .\" .\" 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 -.\" Copyright (c) 2016 Joel Sing +.\" Copyright (c) 2016, 2018 Joel Sing .\" .\" 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 -- 2.20.1