diff options
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.3 | 143 |
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 | ||
19 | enables/disables session caching by setting the operational mode for | ||
20 | .Ar ctx | ||
21 | to | ||
22 | .Ar mode . | ||
23 | .Pp | ||
24 | .Fn SSL_CTX_get_session_cache_mode | ||
25 | returns the currently used cache mode. | ||
26 | .Sh NOTES | ||
27 | The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse. | ||
28 | The sessions can be held in memory for each | ||
29 | .Fa ctx , | ||
30 | if more than one | ||
31 | .Vt SSL_CTX | ||
32 | object is being maintained, the sessions are unique for each | ||
33 | .Vt SSL_CTX | ||
34 | object. | ||
35 | .Pp | ||
36 | In order to reuse a session, a client must send the session's id to the server. | ||
37 | It can only send exactly one id. | ||
38 | The server then either agrees to reuse the session or it starts a full | ||
39 | handshake (to create a new session). | ||
40 | .Pp | ||
41 | A server will lookup up the session in its internal session storage. | ||
42 | If the session is not found in internal storage or lookups for the internal | ||
43 | storage have been deactivated | ||
44 | .Pq Dv SSL_SESS_CACHE_NO_INTERNAL_LOOKUP , | ||
45 | the server will try the external storage if available. | ||
46 | .Pp | ||
47 | Since a client may try to reuse a session intended for use in a different | ||
48 | context, the session id context must be set by the server (see | ||
49 | .Xr SSL_CTX_set_session_id_context 3 ) . | ||
50 | .Pp | ||
51 | The following session cache modes and modifiers are available: | ||
52 | .Bl -tag -width Ds | ||
53 | .It Dv SSL_SESS_CACHE_OFF | ||
54 | No session caching for client or server takes place. | ||
55 | .It Dv SSL_SESS_CACHE_CLIENT | ||
56 | Client sessions are added to the session cache. | ||
57 | As there is no reliable way for the OpenSSL library to know whether a session | ||
58 | should be reused or which session to choose (due to the abstract BIO layer the | ||
59 | SSL engine does not have details about the connection), | ||
60 | the application must select the session to be reused by using the | ||
61 | .Xr SSL_set_session 3 | ||
62 | function. | ||
63 | This option is not activated by default. | ||
64 | .It Dv SSL_SESS_CACHE_SERVER | ||
65 | Server sessions are added to the session cache. | ||
66 | When a client proposes a session to be reused, the server looks for the | ||
67 | corresponding session in (first) the internal session cache (unless | ||
68 | .Dv SSL_SESS_CACHE_NO_INTERNAL_LOOKUP | ||
69 | is set), then (second) in the external cache if available. | ||
70 | If the session is found, the server will try to reuse the session. | ||
71 | This is the default. | ||
72 | .It Dv SSL_SESS_CACHE_BOTH | ||
73 | Enable both | ||
74 | .Dv SSL_SESS_CACHE_CLIENT | ||
75 | and | ||
76 | .Dv SSL_SESS_CACHE_SERVER | ||
77 | at the same time. | ||
78 | .It Dv SSL_SESS_CACHE_NO_AUTO_CLEAR | ||
79 | Normally the session cache is checked for expired sessions every 255 | ||
80 | connections using the | ||
81 | .Xr SSL_CTX_flush_sessions 3 | ||
82 | function. | ||
83 | Since this may lead to a delay which cannot be controlled, | ||
84 | the automatic flushing may be disabled and | ||
85 | .Xr SSL_CTX_flush_sessions 3 | ||
86 | can be called explicitly by the application. | ||
87 | .It Dv SSL_SESS_CACHE_NO_INTERNAL_LOOKUP | ||
88 | By setting this flag, session-resume operations in an SSL/TLS server will not | ||
89 | automatically look up sessions in the internal cache, | ||
90 | even if sessions are automatically stored there. | ||
91 | If external session caching callbacks are in use, | ||
92 | this flag guarantees that all lookups are directed to the external cache. | ||
93 | As automatic lookup only applies for SSL/TLS servers, | ||
94 | the flag has no effect on clients. | ||
95 | .It Dv SSL_SESS_CACHE_NO_INTERNAL_STORE | ||
96 | Depending on the presence of | ||
97 | .Dv SSL_SESS_CACHE_CLIENT | ||
98 | and/or | ||
99 | .Dv SSL_SESS_CACHE_SERVER , | ||
100 | sessions negotiated in an SSL/TLS handshake may be cached for possible reuse. | ||
101 | Normally a new session is added to the internal cache as well as any external | ||
102 | session caching (callback) that is configured for the | ||
103 | .Vt SSL_CTX . | ||
104 | This 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 ) . | ||
107 | Note: | ||
108 | in any SSL/TLS servers where external caching is configured, any successful | ||
109 | session lookups in the external cache (e.g., for session-resume requests) would | ||
110 | normally be copied into the local cache before processing continues \(en this | ||
111 | flag prevents these additions to the internal cache as well. | ||
112 | .It Dv SSL_SESS_CACHE_NO_INTERNAL | ||
113 | Enable both | ||
114 | .Dv SSL_SESS_CACHE_NO_INTERNAL_LOOKUP | ||
115 | and | ||
116 | .Dv SSL_SESS_CACHE_NO_INTERNAL_STORE | ||
117 | at the same time. | ||
118 | .El | ||
119 | .Pp | ||
120 | The default mode is | ||
121 | .Dv SSL_SESS_CACHE_SERVER . | ||
122 | .Sh RETURN VALUES | ||
123 | .Fn SSL_CTX_set_session_cache_mode | ||
124 | returns the previously set cache mode. | ||
125 | .Pp | ||
126 | .Fn SSL_CTX_get_session_cache_mode | ||
127 | returns 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 | ||
141 | and | ||
142 | .Dv SSL_SESS_CACHE_NO_INTERNAL | ||
143 | were introduced in OpenSSL 0.9.6h. | ||