.\" $OpenBSD: SSL_CTX_sess_set_get_cb.3,v 1.7 2022/03/29 18:15:52 naddy Exp $ .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 .\" .\" This file was written by Lutz Jaenicke . .\" Copyright (c) 2001, 2002, 2003, 2016 The OpenSSL Project. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in .\" the documentation and/or other materials provided with the .\" distribution. .\" .\" 3. All advertising materials mentioning features or use of this .\" software must display the following acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" .\" .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to .\" endorse or promote products derived from this software without .\" prior written permission. For written permission, please contact .\" openssl-core@openssl.org. .\" .\" 5. Products derived from this software may not be called "OpenSSL" .\" nor may "OpenSSL" appear in their names without prior written .\" permission of the OpenSSL Project. .\" .\" 6. Redistributions of any form whatsoever must retain the following .\" acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" .\" .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd $Mdocdate: March 29 2022 $ .Dt SSL_CTX_SESS_SET_GET_CB 3 .Os .Sh NAME .Nm SSL_CTX_sess_set_new_cb , .Nm SSL_CTX_sess_set_remove_cb , .Nm SSL_CTX_sess_set_get_cb , .Nm SSL_CTX_sess_get_new_cb , .Nm SSL_CTX_sess_get_remove_cb , .Nm SSL_CTX_sess_get_get_cb .Nd provide callback functions for server side external session caching .Sh SYNOPSIS .In openssl/ssl.h .Ft void .Fo SSL_CTX_sess_set_new_cb .Fa "SSL_CTX *ctx" .Fa "int (*new_session_cb)(SSL *, SSL_SESSION *)" .Fc .Ft void .Fo SSL_CTX_sess_set_remove_cb .Fa "SSL_CTX *ctx" .Fa "void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *)" .Fc .Ft void .Fo SSL_CTX_sess_set_get_cb .Fa "SSL_CTX *ctx" .Fa "SSL_SESSION (*get_session_cb)(SSL *, const unsigned char *, int, int *)" .Fc .Ft int .Fo "(*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))" .Fa "SSL *ssl" .Fa "SSL_SESSION *sess" .Fc .Ft void .Fo "(*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))" .Fa "SSL_CTX *ctx" .Fa "SSL_SESSION *sess" .Fc .Ft SSL_SESSION * .Fo "(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))" .Fa "SSL *ssl" .Fa "const unsigned char *data" .Fa "int len" .Fa "int *copy" .Fc .Ft int .Fo "(*new_session_cb)" .Fa "SSL *ssl" .Fa "SSL_SESSION *sess" .Fc .Ft void .Fo "(*remove_session_cb)" .Fa "SSL_CTX *ctx" .Fa "SSL_SESSION *sess" .Fc .Ft SSL_SESSION * .Fo "(*get_session_cb)" .Fa "SSL *ssl" .Fa "unsigned char *data" .Fa "int len" .Fa "int *copy" .Fc .Sh DESCRIPTION .Fn SSL_CTX_sess_set_new_cb sets the callback function which is automatically called whenever a new session was negotiated. .Pp .Fn SSL_CTX_sess_set_remove_cb sets the callback function which is automatically called whenever a session is removed by the SSL engine (because it is considered faulty or the session has become obsolete because of exceeding the timeout value). .Pp .Fn SSL_CTX_sess_set_get_cb sets the callback function which is called whenever a SSL/TLS client proposes to resume a session but the session cannot be found in the internal session cache (see .Xr SSL_CTX_set_session_cache_mode 3 ) . (SSL/TLS server only.) .Pp .Fn SSL_CTX_sess_get_new_cb , .Fn SSL_CTX_sess_get_remove_cb , and .Fn SSL_CTX_sess_get_get_cb retrieve the function pointers of the provided callback functions. If a callback function has not been set, the .Dv NULL pointer is returned. .Pp In order to allow external session caching, synchronization with the internal session cache is realized via callback functions. Inside these callback functions, session can be saved to disk or put into a database using the .Xr d2i_SSL_SESSION 3 interface. .Pp The .Fn new_session_cb function is called whenever a new session has been negotiated and session caching is enabled (see .Xr SSL_CTX_set_session_cache_mode 3 ) . The .Fn new_session_cb function is passed the .Fa ssl connection and the ssl session .Fa sess . If the callback returns 0, the session will be immediately removed again. .Pp The .Fn remove_session_cb function is called whenever the SSL engine removes a session from the internal cache. This happens when the session is removed because it is expired or when a connection was not shut down cleanly. It also happens for all sessions in the internal session cache when .Xr SSL_CTX_free 3 is called. The .Fn remove_session_cb function is passed the .Fa ctx and the .Vt ssl session .Fa sess . It does not provide any feedback. .Pp The .Fn get_session_cb function is only called on SSL/TLS servers with the session id proposed by the client. The .Fn get_session_cb function is always called, also when session caching was disabled. The .Fn get_session_cb function is passed the .Fa ssl connection, the session id of length .Fa length at the memory location .Fa data . With the parameter .Fa copy the callback can require the SSL engine to increment the reference count of the .Vt SSL_SESSION object, Normally the reference count is not incremented and therefore the session must not be explicitly freed with .Xr SSL_SESSION_free 3 . .Sh SEE ALSO .Xr d2i_SSL_SESSION 3 , .Xr ssl 3 , .Xr SSL_CTX_flush_sessions 3 , .Xr SSL_CTX_free 3 , .Xr SSL_CTX_set_session_cache_mode 3 , .Xr SSL_SESSION_free 3 .Sh HISTORY .Fn SSL_CTX_sess_set_new_cb , .Fn SSL_CTX_sess_set_get_cb , .Fn SSL_CTX_sess_get_new_cb , and .Fn SSL_CTX_sess_get_get_cb first appeared in SSLeay 0.6.0. .Fn SSL_CTX_sess_set_remove_cb and .Fn SSL_CTX_sess_get_remove_cb first appeared in SSLeay 0.8.0. These functions have been available since .Ox 2.4 .