172613Skris=pod 272613Skris 372613Skris=head1 NAME 472613Skris 572613SkrisSSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb - provide callback functions for server side external session caching 672613Skris 772613Skris=head1 SYNOPSIS 872613Skris 972613Skris #include <openssl/ssl.h> 1072613Skris 1172613Skris void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx, 1272613Skris int (*new_session_cb)(SSL *, SSL_SESSION *)); 1372613Skris void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx, 1472613Skris void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *)); 1572613Skris void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx, 1672613Skris SSL_SESSION (*get_session_cb)(SSL *, unsigned char *, int, int *)); 1772613Skris 1872613Skris int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, SSL_SESSION *sess); 1972613Skris void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, SSL_SESSION *sess); 2072613Skris SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, unsigned char *data, int len, int *copy); 2172613Skris 2272613Skris int (*new_session_cb)(struct ssl_st *ssl, SSL_SESSION *sess); 2372613Skris void (*remove_session_cb)(struct ssl_ctx_st *ctx, SSL_SESSION *sess); 2472613Skris SSL_SESSION *(*get_session_cb)(struct ssl_st *ssl, unsigned char *data, 2572613Skris int len, int *copy); 2672613Skris 2772613Skris=head1 DESCRIPTION 2872613Skris 2972613SkrisSSL_CTX_sess_set_new_cb() sets the callback function, which is automatically 3072613Skriscalled whenever a new session was negotiated. 3172613Skris 3272613SkrisSSL_CTX_sess_set_remove_cb() sets the callback function, which is 3372613Skrisautomatically called whenever a session is removed by the SSL engine, 3472613Skrisbecause it is considered faulty or the session has become obsolete because 3572613Skrisof exceeding the timeout value. 3672613Skris 3772613SkrisSSL_CTX_sess_set_get_cb() sets the callback function which is called, 3872613Skriswhenever a SSL/TLS client proposed to resume a session but the session 3972613Skriscould not be found in the internal session cache (see 4072613SkrisL<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>). 4172613Skris(SSL/TLS server only.) 4272613Skris 4372613SkrisSSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and 4472613SkrisSSL_CTX_sess_get_get_cb() allow to retrieve the function pointers of the 4572613Skrisprovided callback functions. If a callback function has not been set, 4672613Skristhe NULL pointer is returned. 4772613Skris 4872613Skris=head1 NOTES 4972613Skris 5072613SkrisIn order to allow external session caching, synchronization with the internal 5172613Skrissession cache is realized via callback functions. Inside these callback 5272613Skrisfunctions, session can be saved to disk or put into a database using the 5372613SkrisL<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)> interface. 5472613Skris 5572613SkrisThe new_session_cb() is called, whenever a new session has been negotiated 5672613Skrisand session caching is enabled (see 5772613SkrisL<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>). 5872613SkrisThe new_session_cb() is passed the B<ssl> connection and the ssl session 5972613SkrisB<sess>. If the callback returns B<0>, the session will be immediately 6072613Skrisremoved again. 6172613Skris 6272613SkrisThe remove_session_cb() is called, whenever the SSL engine removes a session 63120631Snectarfrom the internal cache. This happens when the session is removed because 64120631Snectarit is expired or when a connection was not shutdown cleanly. It also happens 65120631Snectarfor all sessions in the internal session cache when 66120631SnectarL<SSL_CTX_free(3)|SSL_CTX_free(3)> is called. The remove_session_cb() is passed 67120631Snectarthe B<ctx> and the ssl session B<sess>. It does not provide any feedback. 6872613Skris 6972613SkrisThe get_session_cb() is only called on SSL/TLS servers with the session id 7072613Skrisproposed by the client. The get_session_cb() is always called, also when 7172613Skrissession caching was disabled. The get_session_cb() is passed the 7272613SkrisB<ssl> connection, the session id of length B<length> at the memory location 7372613SkrisB<data>. With the parameter B<copy> the callback can require the 7489837SkrisSSL engine to increment the reference count of the SSL_SESSION object, 7589837SkrisNormally the reference count is not incremented and therefore the 7689837Skrissession must not be explicitly freed with 7789837SkrisL<SSL_SESSION_free(3)|SSL_SESSION_free(3)>. 7872613Skris 7972613Skris=head1 SEE ALSO 8072613Skris 8172613SkrisL<ssl(3)|ssl(3)>, L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>, 8272613SkrisL<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, 83100936SnectarL<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>, 84120631SnectarL<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, 85120631SnectarL<SSL_CTX_free(3)|SSL_CTX_free(3)> 8672613Skris 8772613Skris=cut 88