From 721f84f987db2650c18bfa5c6bfe892cc9cfb1eb Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Tue, 14 Sep 2021 14:30:57 +0000 Subject: provide a small manual page for the SSL_set_psk_use_session_callback(3) stub, written from scratch; OK tb@ on SSL_set_psk_use_session_callback.3 --- src/lib/libssl/man/Makefile | 3 +- .../libssl/man/SSL_set_psk_use_session_callback.3 | 86 ++++++++++++++++++++++ 2 files changed, 88 insertions(+), 1 deletion(-) create mode 100644 src/lib/libssl/man/SSL_set_psk_use_session_callback.3 (limited to 'src/lib/libssl') diff --git a/src/lib/libssl/man/Makefile b/src/lib/libssl/man/Makefile index 0c8805df5e..1dbe53751f 100644 --- a/src/lib/libssl/man/Makefile +++ b/src/lib/libssl/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.72 2021/09/14 14:08:15 schwarze Exp $ +# $OpenBSD: Makefile,v 1.73 2021/09/14 14:30:57 schwarze Exp $ .include @@ -112,6 +112,7 @@ MAN = BIO_f_ssl.3 \ SSL_set_connect_state.3 \ SSL_set_fd.3 \ SSL_set_max_send_fragment.3 \ + SSL_set_psk_use_session_callback.3 \ SSL_set_session.3 \ SSL_set_shutdown.3 \ SSL_set_tmp_ecdh.3 \ diff --git a/src/lib/libssl/man/SSL_set_psk_use_session_callback.3 b/src/lib/libssl/man/SSL_set_psk_use_session_callback.3 new file mode 100644 index 0000000000..7f2bfcc010 --- /dev/null +++ b/src/lib/libssl/man/SSL_set_psk_use_session_callback.3 @@ -0,0 +1,86 @@ +.\" $OpenBSD: SSL_set_psk_use_session_callback.3,v 1.1 2021/09/14 14:30:57 schwarze Exp $ +.\" OpenSSL man3/SSL_CTX_set_psk_client_callback.pod +.\" checked up to 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" Copyright (c) 2021 Ingo Schwarze +.\" +.\" 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: September 14 2021 $ +.Dt SSL_SET_PSK_USE_SESSION_CALLBACK 3 +.Os +.Sh NAME +.Nm SSL_set_psk_use_session_callback , +.Nm SSL_psk_use_session_cb_func +.Nd set TLS pre-shared key client callback +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft typedef int +.Fo (*SSL_psk_use_session_cb_func) +.Fa "SSL *ssl" +.Fa "const EVP_MD *md" +.Fa "const unsigned char **id" +.Fa "size_t *idlen" +.Fa "SSL_SESSION **session" +.Fc +.Ft void +.Fo SSL_set_psk_use_session_callback +.Fa "SSL *ssl" +.Fa "SSL_psk_use_session_cb_func cb" +.Fc +.Sh DESCRIPTION +LibreSSL provides the stub function +.Fn SSL_set_psk_use_session_callback +to allow compiling application programs +that contain optional support for TLSv1.3 pre-shared keys. +.Pp +LibreSSL does not support TLS pre-shared keys, +and no action occurs when +.Fn SSL_set_psk_use_session_callback +is called. +In particular, both arguments are ignored. +During session negotiation, +LibreSSL never calls the callback +.Fa cb +and always behaves as if that callback succeeded and set the +.Pf * Fa session +pointer to +.Dv NULL . +That is, LibreSSL never sends a pre-shared key to the server +and never aborts the handshake for lack of a pre-shared key. +.Pp +With OpenSSL, a client application wishing to use TLSv1.3 pre-shared keys +can install a callback function +.Fa cb +using +.Fn SSL_set_psk_use_session_callback . +The OpenSSL library may call +.Fa cb +once or twice during session negotiation. +If the callback fails, OpenSSL aborts connection setup. +If the callback succeeds but sets the +.Pf * Fa session +pointer to +.Dv NULL , +OpenSSL continues the handshake +but does not send a pre-shared key to the server. +.Sh RETURN VALUES +The +.Fn SSL_psk_use_session_cb_func +callback is expected to return 1 on success or 0 on failure. +.Sh HISTORY +.Fn SSL_set_psk_use_session_callback +and +.Fn SSL_psk_use_session_cb_func +first appeared in OpenSSL 1.1.1 and have been available since +.Ox 7.0 . -- cgit v1.2.3-55-g6feb