]>
Commit | Line | Data |
---|---|---|
8cbceba6 LJ |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
0bc6597d | 5 | SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable session caching |
8cbceba6 LJ |
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 | |
1bc74519 | 29 | server. It can only send exactly one id. The server then either |
e0db2eed GT |
30 | agrees to reuse the session or it starts a full handshake (to create a new |
31 | session). | |
8cbceba6 | 32 | |
67adf0a7 | 33 | A server will look up the session in its internal session storage. If the |
e0db2eed GT |
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. | |
8cbceba6 LJ |
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 | |
9b86974e | 40 | L<SSL_CTX_set_session_id_context(3)>). |
8cbceba6 LJ |
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 | |
9b86974e | 56 | to be reused by using the L<SSL_set_session(3)> |
8cbceba6 LJ |
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 | |
e0db2eed GT |
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. | |
8cbceba6 LJ |
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 | |
0bc6597d | 74 | 255 connections using the |
9b86974e | 75 | L<SSL_CTX_flush_sessions(3)> function. Since |
8cbceba6 | 76 | this may lead to a delay which cannot be controlled, the automatic |
0bc6597d | 77 | flushing may be disabled and |
9b86974e | 78 | L<SSL_CTX_flush_sessions(3)> can be called |
8cbceba6 LJ |
79 | explicitly by the application. |
80 | ||
81 | =item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP | |
82 | ||
e0db2eed GT |
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 | |
8cbceba6 LJ |
88 | clients. |
89 | ||
e0db2eed GT |
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 | |
9b86974e | 97 | add them manually using L<SSL_CTX_add_session(3)>). Note: |
e0db2eed GT |
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 | ||
d9ec9d99 | 108 | |
8cbceba6 LJ |
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 | ||
b97fdb57 | 122 | L<ssl(7)>, L<SSL_set_session(3)>, |
9b86974e RS |
123 | L<SSL_session_reused(3)>, |
124 | L<SSL_CTX_add_session(3)>, | |
125 | L<SSL_CTX_sess_number(3)>, | |
126 | L<SSL_CTX_sess_set_cache_size(3)>, | |
127 | L<SSL_CTX_sess_set_get_cb(3)>, | |
128 | L<SSL_CTX_set_session_id_context(3)>, | |
129 | L<SSL_CTX_set_timeout(3)>, | |
130 | L<SSL_CTX_flush_sessions(3)> | |
8cbceba6 | 131 | |
e2f92610 RS |
132 | =head1 COPYRIGHT |
133 | ||
134 | Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. | |
135 | ||
4746f25a | 136 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
137 | this file except in compliance with the License. You can obtain a copy |
138 | in the file LICENSE in the source distribution or at | |
139 | L<https://www.openssl.org/source/license.html>. | |
140 | ||
141 | =cut |