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