lib/libssl/man/SSL_CTX_set_session_cache_mode.3

   1 .\"     $OpenBSD: SSL_CTX_set_session_cache_mode.3,v 1.3 2016/12/29 14:03:55 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: December 29 2016 $
  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 3 ,
 178 .Xr SSL_CTX_add_session 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 .Dv SSL_SESS_CACHE_NO_INTERNAL_STORE
 189 and
 190 .Dv SSL_SESS_CACHE_NO_INTERNAL
 191 were introduced in OpenSSL 0.9.6h.