SSL_CTX_set_session_cache_mode.pod revision 79998
118334Speter=pod 290075Sobrien 3169689Skan=head1 NAME 418334Speter 518334SpeterSSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable session caching 690075Sobrien 718334Speter=head1 SYNOPSIS 890075Sobrien 990075Sobrien #include <openssl/ssl.h> 1090075Sobrien 1190075Sobrien long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode); 1218334Speter long SSL_CTX_get_session_cache_mode(SSL_CTX ctx); 1390075Sobrien 1490075Sobrien=head1 DESCRIPTION 1590075Sobrien 1690075SobrienSSL_CTX_set_session_cache_mode() enables/disables session caching 1718334Speterby setting the operational mode for B<ctx> to <mode>. 1818334Speter 1990075SobrienSSL_CTX_get_session_cache_mode() returns the currently used cache mode. 20169689Skan 21169689Skan=head1 NOTES 2218334Speter 2318334SpeterThe OpenSSL library can store/retrieve SSL/TLS sessions for later reuse. 24169689SkanThe sessions can be held in memory for each B<ctx>, if more than one 2518334SpeterSSL_CTX object is being maintained, the sessions are unique for each SSL_CTX 2618334Speterobject. 2718334Speter 2818334SpeterIn order to reuse a session, a client must send the session's id to the 2918334Speterserver. It can only send exactly one id. The server then decides whether it 3018334Speteragrees in reusing the session or starts the handshake for a new session. 3118334Speter 3218334SpeterA server will lookup up the session in its internal session storage. If 3318334Speterthe session is not found in internal storage or internal storage is 3418334Speterdeactivated, the server will try the external storage if available. 3518334Speter 3618334SpeterSince a client may try to reuse a session intended for use in a different 3718334Spetercontext, the session id context must be set by the server (see 3852284SobrienL<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>). 3918334Speter 4090075SobrienThe following session cache modes and modifiers are available: 4118334Speter 4218334Speter=over 4 4318334Speter 4418334Speter=item SSL_SESS_CACHE_OFF 4518334Speter 4618334SpeterNo session caching for client or server takes place. 4718334Speter 4818334Speter=item SSL_SESS_CACHE_CLIENT 4918334Speter 5018334SpeterClient sessions are added to the session cache. As there is no reliable way 5118334Speterfor the OpenSSL library to know whether a session should be reused or which 5218334Spetersession to choose (due to the abstract BIO layer the SSL engine does not 5318334Speterhave details about the connection), the application must select the session 5418334Speterto be reused by using the L<SSL_set_session(3)|SSL_set_session(3)> 5590075Sobrienfunction. This option is not activated by default. 5618334Speter 57169689Skan=item SSL_SESS_CACHE_SERVER 5818334Speter 5918334SpeterServer sessions are added to the session cache. When a client proposes a 6018334Spetersession to be reused, the session is looked up in the internal session cache. 6118334SpeterIf the session is found, the server will try to reuse the session. 6218334SpeterThis is the default. 6318334Speter 6418334Speter=item SSL_SESS_CACHE_BOTH 6518334Speter 6618334SpeterEnable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time. 6718334Speter 6818334Speter=item SSL_SESS_CACHE_NO_AUTO_CLEAR 6918334Speter 7018334SpeterNormally the session cache is checked for expired sessions every 7118334Speter255 connections using the 7218334SpeterL<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> function. Since 73169689Skanthis may lead to a delay which cannot be controlled, the automatic 74169689Skanflushing may be disabled and 7518334SpeterL<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> can be called 7618334Speterexplicitly by the application. 7718334Speter 7818334Speter=item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP 7918334Speter 8018334SpeterBy setting this flag sessions are cached in the internal storage but 8118334Speterthey are not looked up automatically. If an external session cache 8218334Speteris enabled, sessions are looked up in the external cache. As automatic 8318334Speterlookup only applies for SSL/TLS servers, the flag has no effect on 8418334Speterclients. 8518334Speter 8618334Speter=back 8718334Speter 88117395SkanThe default mode is SSL_SESS_CACHE_SERVER. 8918334Speter 90117395Skan=head1 RETURN VALUES 9118334Speter 92169689SkanSSL_CTX_set_session_cache_mode() returns the previously set cache mode. 93169689Skan 9418334SpeterSSL_CTX_get_session_cache_mode() returns the currently set cache mode. 95117395Skan 96117395Skan 97169689Skan=head1 SEE ALSO 98117395Skan 99132718SkanL<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>, 100132718SkanL<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>, 101132718SkanL<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>, 102169689SkanL<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>, 103132718SkanL<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>, 104132718SkanL<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>, 105132718SkanL<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> 106132718Skan 107132718Skan=cut 10850397Sobrien