172613Skris=pod 272613Skris 372613Skris=head1 NAME 472613Skris 572613SkrisSSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable session caching 672613Skris 772613Skris=head1 SYNOPSIS 872613Skris 972613Skris #include <openssl/ssl.h> 1072613Skris 1172613Skris long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode); 1272613Skris long SSL_CTX_get_session_cache_mode(SSL_CTX ctx); 1372613Skris 1472613Skris=head1 DESCRIPTION 1572613Skris 1672613SkrisSSL_CTX_set_session_cache_mode() enables/disables session caching 1772613Skrisby setting the operational mode for B<ctx> to <mode>. 1872613Skris 1972613SkrisSSL_CTX_get_session_cache_mode() returns the currently used cache mode. 2072613Skris 2172613Skris=head1 NOTES 2272613Skris 2372613SkrisThe OpenSSL library can store/retrieve SSL/TLS sessions for later reuse. 2472613SkrisThe sessions can be held in memory for each B<ctx>, if more than one 2572613SkrisSSL_CTX object is being maintained, the sessions are unique for each SSL_CTX 2672613Skrisobject. 2772613Skris 2872613SkrisIn order to reuse a session, a client must send the session's id to the 29109998Smarkmserver. It can only send exactly one id. The server then either 30109998Smarkmagrees to reuse the session or it starts a full handshake (to create a new 31109998Smarkmsession). 3272613Skris 33109998SmarkmA server will lookup up the session in its internal session storage. If the 34109998Smarkmsession is not found in internal storage or lookups for the internal storage 35109998Smarkmhave been deactivated (SSL_SESS_CACHE_NO_INTERNAL_LOOKUP), the server will try 36109998Smarkmthe external storage if available. 3772613Skris 3872613SkrisSince a client may try to reuse a session intended for use in a different 3972613Skriscontext, the session id context must be set by the server (see 4072613SkrisL<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>). 4172613Skris 4272613SkrisThe following session cache modes and modifiers are available: 4372613Skris 4472613Skris=over 4 4572613Skris 4672613Skris=item SSL_SESS_CACHE_OFF 4772613Skris 4872613SkrisNo session caching for client or server takes place. 4972613Skris 5072613Skris=item SSL_SESS_CACHE_CLIENT 5172613Skris 5272613SkrisClient sessions are added to the session cache. As there is no reliable way 5372613Skrisfor the OpenSSL library to know whether a session should be reused or which 5472613Skrissession to choose (due to the abstract BIO layer the SSL engine does not 5572613Skrishave details about the connection), the application must select the session 5672613Skristo be reused by using the L<SSL_set_session(3)|SSL_set_session(3)> 5772613Skrisfunction. This option is not activated by default. 5872613Skris 5972613Skris=item SSL_SESS_CACHE_SERVER 6072613Skris 6172613SkrisServer sessions are added to the session cache. When a client proposes a 62109998Smarkmsession to be reused, the server looks for the corresponding session in (first) 63109998Smarkmthe internal session cache (unless SSL_SESS_CACHE_NO_INTERNAL_LOOKUP is set), 64109998Smarkmthen (second) in the external cache if available. If the session is found, the 65109998Smarkmserver will try to reuse the session. This is the default. 6672613Skris 6772613Skris=item SSL_SESS_CACHE_BOTH 6872613Skris 6972613SkrisEnable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time. 7072613Skris 7172613Skris=item SSL_SESS_CACHE_NO_AUTO_CLEAR 7272613Skris 7372613SkrisNormally the session cache is checked for expired sessions every 7472613Skris255 connections using the 7572613SkrisL<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> function. Since 7672613Skristhis may lead to a delay which cannot be controlled, the automatic 7772613Skrisflushing may be disabled and 7872613SkrisL<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> can be called 7972613Skrisexplicitly by the application. 8072613Skris 8172613Skris=item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP 8272613Skris 83109998SmarkmBy setting this flag, session-resume operations in an SSL/TLS server will not 84109998Smarkmautomatically look up sessions in the internal cache, even if sessions are 85109998Smarkmautomatically stored there. If external session caching callbacks are in use, 86109998Smarkmthis flag guarantees that all lookups are directed to the external cache. 87109998SmarkmAs automatic lookup only applies for SSL/TLS servers, the flag has no effect on 8872613Skrisclients. 8972613Skris 90109998Smarkm=item SSL_SESS_CACHE_NO_INTERNAL_STORE 91109998Smarkm 92109998SmarkmDepending on the presence of SSL_SESS_CACHE_CLIENT and/or SSL_SESS_CACHE_SERVER, 93109998Smarkmsessions negotiated in an SSL/TLS handshake may be cached for possible reuse. 94109998SmarkmNormally a new session is added to the internal cache as well as any external 95109998Smarkmsession caching (callback) that is configured for the SSL_CTX. This flag will 96109998Smarkmprevent sessions being stored in the internal cache (though the application can 97109998Smarkmadd them manually using L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>). Note: 98109998Smarkmin any SSL/TLS servers where external caching is configured, any successful 99109998Smarkmsession lookups in the external cache (ie. for session-resume requests) would 100109998Smarkmnormally be copied into the local cache before processing continues - this flag 101109998Smarkmprevents these additions to the internal cache as well. 102109998Smarkm 103109998Smarkm=item SSL_SESS_CACHE_NO_INTERNAL 104109998Smarkm 105109998SmarkmEnable both SSL_SESS_CACHE_NO_INTERNAL_LOOKUP and 106109998SmarkmSSL_SESS_CACHE_NO_INTERNAL_STORE at the same time. 107109998Smarkm 108109998Smarkm 10972613Skris=back 11072613Skris 11172613SkrisThe default mode is SSL_SESS_CACHE_SERVER. 11272613Skris 11372613Skris=head1 RETURN VALUES 11472613Skris 11572613SkrisSSL_CTX_set_session_cache_mode() returns the previously set cache mode. 11672613Skris 11772613SkrisSSL_CTX_get_session_cache_mode() returns the currently set cache mode. 11872613Skris 11972613Skris 12072613Skris=head1 SEE ALSO 12172613Skris 12272613SkrisL<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>, 12389837SkrisL<SSL_session_reused(3)|SSL_session_reused(3)>, 124109998SmarkmL<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>, 12576866SkrisL<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>, 12672613SkrisL<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>, 12772613SkrisL<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>, 12872613SkrisL<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>, 12979998SkrisL<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>, 13072613SkrisL<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> 13172613Skris 132109998Smarkm=head1 HISTORY 133109998Smarkm 134109998SmarkmSSL_SESS_CACHE_NO_INTERNAL_STORE and SSL_SESS_CACHE_NO_INTERNAL 135109998Smarkmwere introduced in OpenSSL 0.9.6h. 136109998Smarkm 13772613Skris=cut 138