1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable session caching
    6: 
    7: =head1 SYNOPSIS
    8: 
    9:  #include <openssl/ssl.h>
   10: 
   11:  long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode);
   12:  long SSL_CTX_get_session_cache_mode(SSL_CTX ctx);
   13: 
   14: =head1 DESCRIPTION
   15: 
   16: SSL_CTX_set_session_cache_mode() enables/disables session caching
   17: by setting the operational mode for B<ctx> to <mode>.
   18: 
   19: SSL_CTX_get_session_cache_mode() returns the currently used cache mode.
   20: 
   21: =head1 NOTES
   22: 
   23: The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse.
   24: The sessions can be held in memory for each B<ctx>, if more than one
   25: SSL_CTX object is being maintained, the sessions are unique for each SSL_CTX
   26: object.
   27: 
   28: In order to reuse a session, a client must send the session's id to the
   29: server. It can only send exactly one id.  The server then either 
   30: agrees to reuse the session or it starts a full handshake (to create a new
   31: session).
   32: 
   33: A server will lookup up the session in its internal session storage. If the
   34: session is not found in internal storage or lookups for the internal storage
   35: have been deactivated (SSL_SESS_CACHE_NO_INTERNAL_LOOKUP), the server will try
   36: the external storage if available.
   37: 
   38: Since a client may try to reuse a session intended for use in a different
   39: context, the session id context must be set by the server (see
   40: L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>).
   41: 
   42: The following session cache modes and modifiers are available:
   43: 
   44: =over 4
   45: 
   46: =item SSL_SESS_CACHE_OFF
   47: 
   48: No session caching for client or server takes place.
   49: 
   50: =item SSL_SESS_CACHE_CLIENT
   51: 
   52: Client sessions are added to the session cache. As there is no reliable way
   53: for the OpenSSL library to know whether a session should be reused or which
   54: session to choose (due to the abstract BIO layer the SSL engine does not
   55: have details about the connection), the application must select the session
   56: to be reused by using the L<SSL_set_session(3)|SSL_set_session(3)>
   57: function. This option is not activated by default.
   58: 
   59: =item SSL_SESS_CACHE_SERVER
   60: 
   61: Server sessions are added to the session cache. When a client proposes a
   62: session to be reused, the server looks for the corresponding session in (first)
   63: the internal session cache (unless SSL_SESS_CACHE_NO_INTERNAL_LOOKUP is set),
   64: then (second) in the external cache if available. If the session is found, the
   65: server will try to reuse the session.  This is the default.
   66: 
   67: =item SSL_SESS_CACHE_BOTH
   68: 
   69: Enable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time.
   70: 
   71: =item SSL_SESS_CACHE_NO_AUTO_CLEAR
   72: 
   73: Normally the session cache is checked for expired sessions every
   74: 255 connections using the
   75: L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> function. Since
   76: this may lead to a delay which cannot be controlled, the automatic
   77: flushing may be disabled and
   78: L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> can be called
   79: explicitly by the application.
   80: 
   81: =item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP
   82: 
   83: By setting this flag, session-resume operations in an SSL/TLS server will not
   84: automatically look up sessions in the internal cache, even if sessions are
   85: automatically stored there. If external session caching callbacks are in use,
   86: this flag guarantees that all lookups are directed to the external cache.
   87: As automatic lookup only applies for SSL/TLS servers, the flag has no effect on
   88: clients.
   89: 
   90: =item SSL_SESS_CACHE_NO_INTERNAL_STORE
   91: 
   92: Depending on the presence of SSL_SESS_CACHE_CLIENT and/or SSL_SESS_CACHE_SERVER,
   93: sessions negotiated in an SSL/TLS handshake may be cached for possible reuse.
   94: Normally a new session is added to the internal cache as well as any external
   95: session caching (callback) that is configured for the SSL_CTX. This flag will
   96: prevent sessions being stored in the internal cache (though the application can
   97: add them manually using L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>). Note:
   98: in any SSL/TLS servers where external caching is configured, any successful
   99: session lookups in the external cache (ie. for session-resume requests) would
  100: normally be copied into the local cache before processing continues - this flag
  101: prevents these additions to the internal cache as well.
  102: 
  103: =item SSL_SESS_CACHE_NO_INTERNAL
  104: 
  105: Enable both SSL_SESS_CACHE_NO_INTERNAL_LOOKUP and
  106: SSL_SESS_CACHE_NO_INTERNAL_STORE at the same time.
  107: 
  108: 
  109: =back
  110: 
  111: The default mode is SSL_SESS_CACHE_SERVER.
  112: 
  113: =head1 RETURN VALUES
  114: 
  115: SSL_CTX_set_session_cache_mode() returns the previously set cache mode.
  116: 
  117: SSL_CTX_get_session_cache_mode() returns the currently set cache mode.
  118: 
  119: 
  120: =head1 SEE ALSO
  121: 
  122: L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>,
  123: L<SSL_session_reused(3)|SSL_session_reused(3)>,
  124: L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>,
  125: L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>,
  126: L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>,
  127: L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>,
  128: L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>,
  129: L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>,
  130: L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>
  131: 
  132: =head1 HISTORY
  133: 
  134: SSL_SESS_CACHE_NO_INTERNAL_STORE and SSL_SESS_CACHE_NO_INTERNAL
  135: were introduced in OpenSSL 0.9.6h.
  136: 
  137: =cut