SSL_CTX_set_session_cache_mode.pod revision 89837
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 2972613Skrisserver. It can only send exactly one id. The server then decides whether it 3072613Skrisagrees in reusing the session or starts the handshake for a new session. 3172613Skris 3272613SkrisA server will lookup up the session in its internal session storage. If 3372613Skristhe session is not found in internal storage or internal storage is 3472613Skrisdeactivated, the server will try the external storage if available. 3572613Skris 3672613SkrisSince a client may try to reuse a session intended for use in a different 3772613Skriscontext, the session id context must be set by the server (see 3872613SkrisL<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>). 3972613Skris 4072613SkrisThe following session cache modes and modifiers are available: 4172613Skris 4272613Skris=over 4 4372613Skris 4472613Skris=item SSL_SESS_CACHE_OFF 4572613Skris 4672613SkrisNo session caching for client or server takes place. 4772613Skris 4872613Skris=item SSL_SESS_CACHE_CLIENT 4972613Skris 5072613SkrisClient sessions are added to the session cache. As there is no reliable way 5172613Skrisfor the OpenSSL library to know whether a session should be reused or which 5272613Skrissession to choose (due to the abstract BIO layer the SSL engine does not 5372613Skrishave details about the connection), the application must select the session 5472613Skristo be reused by using the L<SSL_set_session(3)|SSL_set_session(3)> 5572613Skrisfunction. This option is not activated by default. 5672613Skris 5772613Skris=item SSL_SESS_CACHE_SERVER 5872613Skris 5972613SkrisServer sessions are added to the session cache. When a client proposes a 6072613Skrissession to be reused, the session is looked up in the internal session cache. 6172613SkrisIf the session is found, the server will try to reuse the session. 6272613SkrisThis is the default. 6372613Skris 6472613Skris=item SSL_SESS_CACHE_BOTH 6572613Skris 6672613SkrisEnable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time. 6772613Skris 6872613Skris=item SSL_SESS_CACHE_NO_AUTO_CLEAR 6972613Skris 7072613SkrisNormally the session cache is checked for expired sessions every 7172613Skris255 connections using the 7272613SkrisL<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> function. Since 7372613Skristhis may lead to a delay which cannot be controlled, the automatic 7472613Skrisflushing may be disabled and 7572613SkrisL<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> can be called 7672613Skrisexplicitly by the application. 7772613Skris 7872613Skris=item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP 7972613Skris 8072613SkrisBy setting this flag sessions are cached in the internal storage but 8172613Skristhey are not looked up automatically. If an external session cache 8272613Skrisis enabled, sessions are looked up in the external cache. As automatic 8372613Skrislookup only applies for SSL/TLS servers, the flag has no effect on 8472613Skrisclients. 8572613Skris 8672613Skris=back 8772613Skris 8872613SkrisThe default mode is SSL_SESS_CACHE_SERVER. 8972613Skris 9072613Skris=head1 RETURN VALUES 9172613Skris 9272613SkrisSSL_CTX_set_session_cache_mode() returns the previously set cache mode. 9372613Skris 9472613SkrisSSL_CTX_get_session_cache_mode() returns the currently set cache mode. 9572613Skris 9672613Skris 9772613Skris=head1 SEE ALSO 9872613Skris 9972613SkrisL<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>, 10089837SkrisL<SSL_session_reused(3)|SSL_session_reused(3)>, 10176866SkrisL<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>, 10272613SkrisL<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>, 10372613SkrisL<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>, 10472613SkrisL<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>, 10579998SkrisL<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>, 10672613SkrisL<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> 10772613Skris 10872613Skris=cut 109