SSL_CTX_sess_set_get_cb.pod revision 100936
1167550Sdds=pod 2167550Sdds 3167550Sdds=head1 NAME 4167550Sdds 5167550SddsSSL_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 6167550Sdds 7167550Sdds=head1 SYNOPSIS 8167550Sdds 9167550Sdds #include <openssl/ssl.h> 10167550Sdds 11167550Sdds void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx, 12167550Sdds int (*new_session_cb)(SSL *, SSL_SESSION *)); 13167550Sdds void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx, 14167550Sdds void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *)); 15167550Sdds void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx, 16167550Sdds SSL_SESSION (*get_session_cb)(SSL *, unsigned char *, int, int *)); 17167550Sdds 18167550Sdds int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, SSL_SESSION *sess); 19167550Sdds void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, SSL_SESSION *sess); 20167550Sdds SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, unsigned char *data, int len, int *copy); 21167550Sdds 22167550Sdds int (*new_session_cb)(struct ssl_st *ssl, SSL_SESSION *sess); 23167550Sdds void (*remove_session_cb)(struct ssl_ctx_st *ctx, SSL_SESSION *sess); 24167550Sdds SSL_SESSION *(*get_session_cb)(struct ssl_st *ssl, unsigned char *data, 25167550Sdds int len, int *copy); 26167550Sdds 27167550Sdds=head1 DESCRIPTION 28167550Sdds 29167550SddsSSL_CTX_sess_set_new_cb() sets the callback function, which is automatically 30167550Sddscalled whenever a new session was negotiated. 31167550Sdds 32167550SddsSSL_CTX_sess_set_remove_cb() sets the callback function, which is 33167550Sddsautomatically called whenever a session is removed by the SSL engine, 34167550Sddsbecause it is considered faulty or the session has become obsolete because 35167550Sddsof exceeding the timeout value. 36167550Sdds 37167550SddsSSL_CTX_sess_set_get_cb() sets the callback function which is called, 38167550Sddswhenever a SSL/TLS client proposed to resume a session but the session 39167550Sddscould not be found in the internal session cache (see 40167550SddsL<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>). 41167550Sdds(SSL/TLS server only.) 42167550Sdds 43167550SddsSSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and 44167550SddsSSL_CTX_sess_get_get_cb() allow to retrieve the function pointers of the 45167550Sddsprovided callback functions. If a callback function has not been set, 46167550Sddsthe NULL pointer is returned. 47167550Sdds 48167550Sdds=head1 NOTES 49167550Sdds 50167550SddsIn order to allow external session caching, synchronization with the internal 51167550Sddssession cache is realized via callback functions. Inside these callback 52167550Sddsfunctions, session can be saved to disk or put into a database using the 53167550SddsL<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)> interface. 54167550Sdds 55167550SddsThe new_session_cb() is called, whenever a new session has been negotiated 56167550Sddsand session caching is enabled (see 57L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>). 58The new_session_cb() is passed the B<ssl> connection and the ssl session 59B<sess>. If the callback returns B<0>, the session will be immediately 60removed again. 61 62The remove_session_cb() is called, whenever the SSL engine removes a session 63from the internal cache. This happens if the session is removed because 64it is expired or when a connection was not shutdown cleanly. The 65remove_session_cb() is passed the B<ctx> and the ssl session B<sess>. 66It does not provide any feedback. 67 68The get_session_cb() is only called on SSL/TLS servers with the session id 69proposed by the client. The get_session_cb() is always called, also when 70session caching was disabled. The get_session_cb() is passed the 71B<ssl> connection, the session id of length B<length> at the memory location 72B<data>. With the parameter B<copy> the callback can require the 73SSL engine to increment the reference count of the SSL_SESSION object, 74Normally the reference count is not incremented and therefore the 75session must not be explicitly freed with 76L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>. 77 78=head1 SEE ALSO 79 80L<ssl(3)|ssl(3)>, L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>, 81L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, 82L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>, 83L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> 84 85=cut 86