1.\" $OpenBSD: SSL_CTX_sess_set_get_cb.3,v 1.7 2022/03/29 18:15:52 naddy Exp $ 2.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 3.\" 4.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>. 5.\" Copyright (c) 2001, 2002, 2003, 2016 The OpenSSL Project. 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: March 29 2022 $ 53.Dt SSL_CTX_SESS_SET_GET_CB 3 54.Os 55.Sh NAME 56.Nm SSL_CTX_sess_set_new_cb , 57.Nm SSL_CTX_sess_set_remove_cb , 58.Nm SSL_CTX_sess_set_get_cb , 59.Nm SSL_CTX_sess_get_new_cb , 60.Nm SSL_CTX_sess_get_remove_cb , 61.Nm SSL_CTX_sess_get_get_cb 62.Nd provide callback functions for server side external session caching 63.Sh SYNOPSIS 64.In openssl/ssl.h 65.Ft void 66.Fo SSL_CTX_sess_set_new_cb 67.Fa "SSL_CTX *ctx" 68.Fa "int (*new_session_cb)(SSL *, SSL_SESSION *)" 69.Fc 70.Ft void 71.Fo SSL_CTX_sess_set_remove_cb 72.Fa "SSL_CTX *ctx" 73.Fa "void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *)" 74.Fc 75.Ft void 76.Fo SSL_CTX_sess_set_get_cb 77.Fa "SSL_CTX *ctx" 78.Fa "SSL_SESSION (*get_session_cb)(SSL *, const unsigned char *, int, int *)" 79.Fc 80.Ft int 81.Fo "(*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))" 82.Fa "SSL *ssl" 83.Fa "SSL_SESSION *sess" 84.Fc 85.Ft void 86.Fo "(*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))" 87.Fa "SSL_CTX *ctx" 88.Fa "SSL_SESSION *sess" 89.Fc 90.Ft SSL_SESSION * 91.Fo "(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))" 92.Fa "SSL *ssl" 93.Fa "const unsigned char *data" 94.Fa "int len" 95.Fa "int *copy" 96.Fc 97.Ft int 98.Fo "(*new_session_cb)" 99.Fa "SSL *ssl" 100.Fa "SSL_SESSION *sess" 101.Fc 102.Ft void 103.Fo "(*remove_session_cb)" 104.Fa "SSL_CTX *ctx" 105.Fa "SSL_SESSION *sess" 106.Fc 107.Ft SSL_SESSION * 108.Fo "(*get_session_cb)" 109.Fa "SSL *ssl" 110.Fa "unsigned char *data" 111.Fa "int len" 112.Fa "int *copy" 113.Fc 114.Sh DESCRIPTION 115.Fn SSL_CTX_sess_set_new_cb 116sets the callback function which is automatically called whenever a new session 117was negotiated. 118.Pp 119.Fn SSL_CTX_sess_set_remove_cb 120sets the callback function which is automatically called whenever a session is 121removed by the SSL engine (because it is considered faulty or the session has 122become obsolete because of exceeding the timeout value). 123.Pp 124.Fn SSL_CTX_sess_set_get_cb 125sets the callback function which is called whenever a SSL/TLS client proposes 126to resume a session but the session cannot be found in the internal session 127cache (see 128.Xr SSL_CTX_set_session_cache_mode 3 ) . 129(SSL/TLS server only.) 130.Pp 131.Fn SSL_CTX_sess_get_new_cb , 132.Fn SSL_CTX_sess_get_remove_cb , 133and 134.Fn SSL_CTX_sess_get_get_cb 135retrieve the function pointers of the provided callback functions. 136If a callback function has not been set, the 137.Dv NULL 138pointer is returned. 139.Pp 140In order to allow external session caching, synchronization with the internal 141session cache is realized via callback functions. 142Inside these callback functions, session can be saved to disk or put into a 143database using the 144.Xr d2i_SSL_SESSION 3 145interface. 146.Pp 147The 148.Fn new_session_cb 149function is called whenever a new session has been negotiated and session 150caching is enabled (see 151.Xr SSL_CTX_set_session_cache_mode 3 ) . 152The 153.Fn new_session_cb 154function is passed the 155.Fa ssl 156connection and the ssl session 157.Fa sess . 158If the callback returns 0, the session will be immediately removed again. 159.Pp 160The 161.Fn remove_session_cb 162function is called whenever the SSL engine removes a session from the 163internal cache. 164This happens when the session is removed because it is expired or when a 165connection was not shut down cleanly. 166It also happens for all sessions in the internal session cache when 167.Xr SSL_CTX_free 3 168is called. 169The 170.Fn remove_session_cb 171function is passed the 172.Fa ctx 173and the 174.Vt ssl 175session 176.Fa sess . 177It does not provide any feedback. 178.Pp 179The 180.Fn get_session_cb 181function is only called on SSL/TLS servers with the session id proposed by the 182client. 183The 184.Fn get_session_cb 185function is always called, also when session caching was disabled. 186The 187.Fn get_session_cb 188function is passed the 189.Fa ssl 190connection, the session id of length 191.Fa length 192at the memory location 193.Fa data . 194With the parameter 195.Fa copy 196the callback can require the SSL engine to increment the reference count of the 197.Vt SSL_SESSION 198object, 199Normally the reference count is not incremented and therefore the session must 200not be explicitly freed with 201.Xr SSL_SESSION_free 3 . 202.Sh SEE ALSO 203.Xr d2i_SSL_SESSION 3 , 204.Xr ssl 3 , 205.Xr SSL_CTX_flush_sessions 3 , 206.Xr SSL_CTX_free 3 , 207.Xr SSL_CTX_set_session_cache_mode 3 , 208.Xr SSL_SESSION_free 3 209.Sh HISTORY 210.Fn SSL_CTX_sess_set_new_cb , 211.Fn SSL_CTX_sess_set_get_cb , 212.Fn SSL_CTX_sess_get_new_cb , 213and 214.Fn SSL_CTX_sess_get_get_cb 215first appeared in SSLeay 0.6.0. 216.Fn SSL_CTX_sess_set_remove_cb 217and 218.Fn SSL_CTX_sess_get_remove_cb 219first appeared in SSLeay 0.8.0. 220These functions have been available since 221.Ox 2.4 . 222