1.\" $OpenBSD: SSL_set_psk_use_session_callback.3,v 1.1 2021/09/14 14:30:57 schwarze Exp $ 2.\" OpenSSL man3/SSL_CTX_set_psk_client_callback.pod 3.\" checked up to 24a535ea Sep 22 13:14:20 2020 +0100 4.\" 5.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org> 6.\" 7.\" Permission to use, copy, modify, and distribute this software for any 8.\" purpose with or without fee is hereby granted, provided that the above 9.\" copyright notice and this permission notice appear in all copies. 10.\" 11.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 12.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 13.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 14.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 15.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 16.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 17.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 18.\" 19.Dd $Mdocdate: September 14 2021 $ 20.Dt SSL_SET_PSK_USE_SESSION_CALLBACK 3 21.Os 22.Sh NAME 23.Nm SSL_set_psk_use_session_callback , 24.Nm SSL_psk_use_session_cb_func 25.Nd set TLS pre-shared key client callback 26.Sh SYNOPSIS 27.In openssl/ssl.h 28.Ft typedef int 29.Fo (*SSL_psk_use_session_cb_func) 30.Fa "SSL *ssl" 31.Fa "const EVP_MD *md" 32.Fa "const unsigned char **id" 33.Fa "size_t *idlen" 34.Fa "SSL_SESSION **session" 35.Fc 36.Ft void 37.Fo SSL_set_psk_use_session_callback 38.Fa "SSL *ssl" 39.Fa "SSL_psk_use_session_cb_func cb" 40.Fc 41.Sh DESCRIPTION 42LibreSSL provides the stub function 43.Fn SSL_set_psk_use_session_callback 44to allow compiling application programs 45that contain optional support for TLSv1.3 pre-shared keys. 46.Pp 47LibreSSL does not support TLS pre-shared keys, 48and no action occurs when 49.Fn SSL_set_psk_use_session_callback 50is called. 51In particular, both arguments are ignored. 52During session negotiation, 53LibreSSL never calls the callback 54.Fa cb 55and always behaves as if that callback succeeded and set the 56.Pf * Fa session 57pointer to 58.Dv NULL . 59That is, LibreSSL never sends a pre-shared key to the server 60and never aborts the handshake for lack of a pre-shared key. 61.Pp 62With OpenSSL, a client application wishing to use TLSv1.3 pre-shared keys 63can install a callback function 64.Fa cb 65using 66.Fn SSL_set_psk_use_session_callback . 67The OpenSSL library may call 68.Fa cb 69once or twice during session negotiation. 70If the callback fails, OpenSSL aborts connection setup. 71If the callback succeeds but sets the 72.Pf * Fa session 73pointer to 74.Dv NULL , 75OpenSSL continues the handshake 76but does not send a pre-shared key to the server. 77.Sh RETURN VALUES 78The 79.Fn SSL_psk_use_session_cb_func 80callback is expected to return 1 on success or 0 on failure. 81.Sh HISTORY 82.Fn SSL_set_psk_use_session_callback 83and 84.Fn SSL_psk_use_session_cb_func 85first appeared in OpenSSL 1.1.1 and have been available since 86.Ox 7.0 . 87