SSL_CTX_sess_set_get_cb.pod revision 89837
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 6372613Skrisfrom the internal cache. This happens if the session is removed because 6472613Skrisit is expired or when a connection was not shutdown cleanly. The 6572613Skrisremove_session_cb() is passed the B<ctx> and the ssl session B<sess>. 6672613SkrisIt does not provide any feedback. 6772613Skris 6872613SkrisThe get_session_cb() is only called on SSL/TLS servers with the session id 6972613Skrisproposed by the client. The get_session_cb() is always called, also when 7072613Skrissession caching was disabled. The get_session_cb() is passed the 7172613SkrisB<ssl> connection, the session id of length B<length> at the memory location 7272613SkrisB<data>. With the parameter B<copy> the callback can require the 7389837SkrisSSL engine to increment the reference count of the SSL_SESSION object, 7489837SkrisNormally the reference count is not incremented and therefore the 7589837Skrissession must not be explicitly freed with 7689837SkrisL<SSL_SESSION_free(3)|SSL_SESSION_free(3)>. 7772613Skris 7872613Skris=head1 SEE ALSO 7972613Skris 8072613SkrisL<ssl(3)|ssl(3)>, L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>, 8172613SkrisL<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, 8289837SkrisL<SSL_CTX_flush_sessions(3)|<SSL_CTX_flush_sessions(3)>, 8389837SkrisL<SSL_SESSION_free(3)|SSL_SESSION_free(3)> 8472613Skris 8572613Skris=cut 86