SSL_CTX_set_session_cache_mode.pod 5.1 KB

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