.\"
.\"	$OpenBSD: SSL_CTX_sess_set_get_cb.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $
.\"
.Dd $Mdocdate: November 5 2016 $
.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 *, unsigned char *, int, int *)"
.Fc
.Ft int
.Fo "(*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))"
.Fa "struct ssl_st *ssl"
.Fa "SSL_SESSION *sess"
.Fc
.Ft void
.Fo "(*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))"
.Fa "struct ssl_ctx_st *ctx"
.Fa "SSL_SESSION *sess"
.Fc
.Ft SSL_SESSION *
.Fo "(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))"
.Fa "struct ssl_st *ssl"
.Fa "unsigned char *data"
.Fa "int len"
.Fa "int *copy"
.Fc
.Ft int
.Fo "(*new_session_cb)"
.Fa "struct ssl_st *ssl"
.Fa "SSL_SESSION *sess"
.Fc
.Ft void
.Fo "(*remove_session_cb)"
.Fa "struct ssl_ctx_st *ctx"
.Fa "SSL_SESSION *sess"
.Fc
.Ft SSL_SESSION *
.Fo "(*get_session_cb)"
.Fa "struct ssl_st *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.
.Sh NOTES
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