| blob | 9e8e8500e8f3ecbe03a2084118119dbbe2238790 |
1 .\" $OpenBSD: SSL_CTX_set_session_cache_mode.3,v 1.5 2018/03/21 05:07:04 schwarze Exp $
2 .\" OpenSSL 67adf0a7 Dec 25 19:58:38 2016 +0100
3 .\"
4 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org> and
5 .\" Geoff Thorpe <geoff@openssl.org>.
6 .\" Copyright (c) 2001, 2002 The OpenSSL Project. All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\"
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\"
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in
17 .\" the documentation and/or other materials provided with the
18 .\" distribution.
19 .\"
20 .\" 3. All advertising materials mentioning features or use of this
21 .\" software must display the following acknowledgment:
22 .\" "This product includes software developed by the OpenSSL Project
23 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
24 .\"
25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26 .\" endorse or promote products derived from this software without
27 .\" prior written permission. For written permission, please contact
28 .\" openssl-core@openssl.org.
29 .\"
30 .\" 5. Products derived from this software may not be called "OpenSSL"
31 .\" nor may "OpenSSL" appear in their names without prior written
32 .\" permission of the OpenSSL Project.
33 .\"
34 .\" 6. Redistributions of any form whatsoever must retain the following
35 .\" acknowledgment:
36 .\" "This product includes software developed by the OpenSSL Project
37 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38 .\"
39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
51 .\"
52 .Dd $Mdocdate: March 21 2018 $
53 .Dt SSL_CTX_SET_SESSION_CACHE_MODE 3
54 .Os
55 .Sh NAME
56 .Nm SSL_CTX_set_session_cache_mode ,
57 .Nm SSL_CTX_get_session_cache_mode
58 .Nd enable/disable session caching
59 .Sh SYNOPSIS
60 .In openssl/ssl.h
61 .Ft long
62 .Fn SSL_CTX_set_session_cache_mode "SSL_CTX ctx" "long mode"
63 .Ft long
64 .Fn SSL_CTX_get_session_cache_mode "SSL_CTX ctx"
65 .Sh DESCRIPTION
66 .Fn SSL_CTX_set_session_cache_mode
67 enables/disables session caching by setting the operational mode for
68 .Ar ctx
69 to
70 .Ar mode .
71 .Pp
72 .Fn SSL_CTX_get_session_cache_mode
73 returns the currently used cache mode.
74 .Pp
75 The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse.
76 The sessions can be held in memory for each
77 .Fa ctx ,
78 if more than one
79 .Vt SSL_CTX
80 object is being maintained, the sessions are unique for each
81 .Vt SSL_CTX
82 object.
83 .Pp
84 In order to reuse a session, a client must send the session's id to the server.
85 It can only send exactly one id.
86 The server then either agrees to reuse the session or it starts a full
87 handshake (to create a new session).
88 .Pp
89 A server will look up the session in its internal session storage.
90 If the session is not found in internal storage or lookups for the internal
91 storage have been deactivated
92 .Pq Dv SSL_SESS_CACHE_NO_INTERNAL_LOOKUP ,
93 the server will try the external storage if available.
94 .Pp
95 Since a client may try to reuse a session intended for use in a different
96 context, the session id context must be set by the server (see
97 .Xr SSL_CTX_set_session_id_context 3 ) .
98 .Pp
99 The following session cache modes and modifiers are available:
100 .Bl -tag -width Ds
101 .It Dv SSL_SESS_CACHE_OFF
102 No session caching for client or server takes place.
103 .It Dv SSL_SESS_CACHE_CLIENT
104 Client sessions are added to the session cache.
105 As there is no reliable way for the OpenSSL library to know whether a session
106 should be reused or which session to choose (due to the abstract BIO layer the
107 SSL engine does not have details about the connection),
108 the application must select the session to be reused by using the
109 .Xr SSL_set_session 3
110 function.
111 This option is not activated by default.
112 .It Dv SSL_SESS_CACHE_SERVER
113 Server sessions are added to the session cache.
114 When a client proposes a session to be reused, the server looks for the
115 corresponding session in (first) the internal session cache (unless
116 .Dv SSL_SESS_CACHE_NO_INTERNAL_LOOKUP
117 is set), then (second) in the external cache if available.
118 If the session is found, the server will try to reuse the session.
119 This is the default.
120 .It Dv SSL_SESS_CACHE_BOTH
121 Enable both
122 .Dv SSL_SESS_CACHE_CLIENT
123 and
124 .Dv SSL_SESS_CACHE_SERVER
125 at the same time.
126 .It Dv SSL_SESS_CACHE_NO_AUTO_CLEAR
127 Normally the session cache is checked for expired sessions every 255
128 connections using the
129 .Xr SSL_CTX_flush_sessions 3
130 function.
131 Since this may lead to a delay which cannot be controlled,
132 the automatic flushing may be disabled and
133 .Xr SSL_CTX_flush_sessions 3
134 can be called explicitly by the application.
135 .It Dv SSL_SESS_CACHE_NO_INTERNAL_LOOKUP
136 By setting this flag, session-resume operations in an SSL/TLS server will not
137 automatically look up sessions in the internal cache,
138 even if sessions are automatically stored there.
139 If external session caching callbacks are in use,
140 this flag guarantees that all lookups are directed to the external cache.
141 As automatic lookup only applies for SSL/TLS servers,
142 the flag has no effect on clients.
143 .It Dv SSL_SESS_CACHE_NO_INTERNAL_STORE
144 Depending on the presence of
145 .Dv SSL_SESS_CACHE_CLIENT
146 and/or
147 .Dv SSL_SESS_CACHE_SERVER ,
148 sessions negotiated in an SSL/TLS handshake may be cached for possible reuse.
149 Normally a new session is added to the internal cache as well as any external
150 session caching (callback) that is configured for the
151 .Vt SSL_CTX .
152 This flag will prevent sessions being stored in the internal cache
153 (though the application can add them manually using
154 .Xr SSL_CTX_add_session 3 ) .
155 Note:
156 in any SSL/TLS servers where external caching is configured, any successful
157 session lookups in the external cache (e.g., for session-resume requests) would
158 normally be copied into the local cache before processing continues \(en this
159 flag prevents these additions to the internal cache as well.
160 .It Dv SSL_SESS_CACHE_NO_INTERNAL
161 Enable both
162 .Dv SSL_SESS_CACHE_NO_INTERNAL_LOOKUP
163 and
164 .Dv SSL_SESS_CACHE_NO_INTERNAL_STORE
165 at the same time.
166 .El
167 .Pp
168 The default mode is
169 .Dv SSL_SESS_CACHE_SERVER .
170 .Sh RETURN VALUES
171 .Fn SSL_CTX_set_session_cache_mode
172 returns the previously set cache mode.
173 .Pp
174 .Fn SSL_CTX_get_session_cache_mode
175 returns the currently set cache mode.
176 .Sh SEE ALSO
177 .Xr SSL_CTX_add_session 3 ,
178 .Xr SSL_CTX_ctrl 3 ,
179 .Xr SSL_CTX_flush_sessions 3 ,
180 .Xr SSL_CTX_sess_number 3 ,
181 .Xr SSL_CTX_sess_set_cache_size 3 ,
182 .Xr SSL_CTX_sess_set_get_cb 3 ,
183 .Xr SSL_CTX_set_session_id_context 3 ,
184 .Xr SSL_CTX_set_timeout 3 ,
185 .Xr SSL_session_reused 3 ,
186 .Xr SSL_set_session 3
187 .Sh HISTORY
188 .Fn SSL_CTX_set_session_cache_mode
189 and
190 .Fn SSL_CTX_get_session_cache_mode
191 appeared before SSLeay 0.8 and have been available since
192 .Ox 2.4 .
193 .Pp
194 .Dv SSL_SESS_CACHE_NO_INTERNAL_STORE
195 and
196 .Dv SSL_SESS_CACHE_NO_INTERNAL
197 were introduced in OpenSSL 0.9.6h.