SSL_CTX_sess_set_get_cb.pod revision 72613
1234285Sdim=pod 2234285Sdim 3234285Sdim=head1 NAME 4234285Sdim 5234285SdimSSL_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 6234285Sdim 7234285Sdim=head1 SYNOPSIS 8234285Sdim 9234285Sdim #include <openssl/ssl.h> 10234285Sdim 11234285Sdim void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx, 12234285Sdim int (*new_session_cb)(SSL *, SSL_SESSION *)); 13234285Sdim void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx, 14234285Sdim void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *)); 15249423Sdim void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx, 16249423Sdim SSL_SESSION (*get_session_cb)(SSL *, unsigned char *, int, int *)); 17234285Sdim 18249423Sdim int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, SSL_SESSION *sess); 19249423Sdim void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, SSL_SESSION *sess); 20234285Sdim SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, unsigned char *data, int len, int *copy); 21243830Sdim 22234285Sdim int (*new_session_cb)(struct ssl_st *ssl, SSL_SESSION *sess); 23234285Sdim void (*remove_session_cb)(struct ssl_ctx_st *ctx, SSL_SESSION *sess); 24234285Sdim SSL_SESSION *(*get_session_cb)(struct ssl_st *ssl, unsigned char *data, 25234285Sdim int len, int *copy); 26249423Sdim 27234285Sdim=head1 DESCRIPTION 28234285Sdim 29234285SdimSSL_CTX_sess_set_new_cb() sets the callback function, which is automatically 30239462Sdimcalled whenever a new session was negotiated. 31234285Sdim 32234285SdimSSL_CTX_sess_set_remove_cb() sets the callback function, which is 33234285Sdimautomatically called whenever a session is removed by the SSL engine, 34234285Sdimbecause it is considered faulty or the session has become obsolete because 35234285Sdimof exceeding the timeout value. 36234285Sdim 37234285SdimSSL_CTX_sess_set_get_cb() sets the callback function which is called, 38234285Sdimwhenever a SSL/TLS client proposed to resume a session but the session 39239462Sdimcould not be found in the internal session cache (see 40234285SdimL<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>). 41234285Sdim(SSL/TLS server only.) 42234285Sdim 43234285SdimSSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and 44243830SdimSSL_CTX_sess_get_get_cb() allow to retrieve the function pointers of the 45243830Sdimprovided callback functions. If a callback function has not been set, 46243830Sdimthe NULL pointer is returned. 47243830Sdim 48243830Sdim=head1 NOTES 49249423Sdim 50243830SdimIn order to allow external session caching, synchronization with the internal 51249423Sdimsession cache is realized via callback functions. Inside these callback 52249423Sdimfunctions, session can be saved to disk or put into a database using the 53249423SdimL<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)> interface. 54243830Sdim 55243830SdimThe new_session_cb() is called, whenever a new session has been negotiated 56249423Sdimand session caching is enabled (see 57249423SdimL<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>). 58249423SdimThe new_session_cb() is passed the B<ssl> connection and the ssl session 59249423SdimB<sess>. If the callback returns B<0>, the session will be immediately 60234285Sdimremoved again. 61234285Sdim 62234285SdimThe remove_session_cb() is called, whenever the SSL engine removes a session 63234285Sdimfrom the internal cache. This happens if the session is removed because 64234285Sdimit is expired or when a connection was not shutdown cleanly. The 65239462Sdimremove_session_cb() is passed the B<ctx> and the ssl session B<sess>. 66234285SdimIt does not provide any feedback. 67234285Sdim 68234285SdimThe get_session_cb() is only called on SSL/TLS servers with the session id 69234285Sdimproposed by the client. The get_session_cb() is always called, also when 70234285Sdimsession caching was disabled. The get_session_cb() is passed the 71234285SdimB<ssl> connection, the session id of length B<length> at the memory location 72234285SdimB<data>. With the parameter B<copy> the callback can require the 73234285SdimSSL engine to increment the reference count of the SSL_SESSION object. 74234285Sdim 75234285Sdim=head1 SEE ALSO 76234285Sdim 77234285SdimL<ssl(3)|ssl(3)>, L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>, 78243830SdimL<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, 79243830SdimL<SSL_CTX_flush_sessions(3)|<SSL_CTX_flush_sessions(3)> 80243830Sdim 81234285Sdim=cut 82234285Sdim