]>
Commit | Line | Data |
---|---|---|
8cbceba6 LJ |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_CTX_set_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 decides whether it | |
30 | agrees in reusing the session or starts the handshake for a new session. | |
31 | ||
32 | A server will lookup up the session in its internal session storage. If | |
33 | the session is not found in internal storage or internal storage is | |
34 | deactivated, the server will try the external storage if available. | |
35 | ||
36 | Since a client may try to reuse a session intended for use in a different | |
37 | context, the session id context must be set by the server (see | |
38 | L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>). | |
39 | ||
40 | The following session cache modes and modifiers are available: | |
41 | ||
42 | =over 4 | |
43 | ||
44 | =item SSL_SESS_CACHE_OFF | |
45 | ||
46 | No session caching for client or server takes place. | |
47 | ||
48 | =item SSL_SESS_CACHE_CLIENT | |
49 | ||
50 | Client sessions are added to the session cache. As there is no reliable way | |
51 | for the OpenSSL library to know whether a session should be reused or which | |
52 | session to choose (due to the abstract BIO layer the SSL engine does not | |
53 | have details about the connection), the application must select the session | |
54 | to be reused by using the L<SSL_set_session(3)|SSL_set_session(3)> | |
55 | function. This option is not activated by default. | |
56 | ||
57 | =item SSL_SESS_CACHE_SERVER | |
58 | ||
59 | Server sessions are added to the session cache. When a client proposes a | |
60 | session to be reused, the session is looked up in the internal session cache. | |
61 | If the session is found, the server will try to reuse the session. | |
62 | This is the default. | |
63 | ||
64 | =item SSL_SESS_CACHE_BOTH | |
65 | ||
66 | Enable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time. | |
67 | ||
68 | =item SSL_SESS_CACHE_NO_AUTO_CLEAR | |
69 | ||
70 | Normally the session cache is checked for expired sessions every | |
71 | 255 connections using the SSL_CTX_flush_sessions() function. Since | |
72 | this may lead to a delay which cannot be controlled, the automatic | |
73 | flushing may be disabled and SSL_CTX_flush_sessions() can be called | |
74 | explicitly by the application. | |
75 | ||
76 | =item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP | |
77 | ||
78 | By setting this flag sessions are cached in the internal storage but | |
79 | they are not looked up automatically. If an external session cache | |
80 | is enabled, sessions are looked up in the external cache. As automatic | |
81 | lookup only applies for SSL/TLS servers, the flag has no effect on | |
82 | clients. | |
83 | ||
84 | =back | |
85 | ||
86 | The default mode is SSL_SESS_CACHE_SERVER. | |
87 | ||
88 | =head1 RETURN VALUES | |
89 | ||
90 | SSL_CTX_set_session_cache_mode() returns the previously set cache mode. | |
91 | ||
92 | SSL_CTX_get_session_cache_mode() returns the currently set cache mode. | |
93 | ||
94 | ||
95 | =head1 SEE ALSO | |
96 | ||
97 | L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>, | |
98 | L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>, | |
99 | L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)> | |
100 | ||
101 | =cut |