.\"	$OpenBSD: SSL_CTX_sess_set_get_cb.3,v 1.6 2018/04/25 14:07:57 schwarze Exp $
.\"	OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
.\"
.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
.\" 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: April 25 2018 $
.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
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
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
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 .