lib/libssl/man/SSL_CTX_set_generate_session_id.3

   1 .\"     $OpenBSD: SSL_CTX_set_generate_session_id.3,v 1.2 2016/11/30 18:07:12 schwarze Exp $
   2 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
   3 .\"
   4 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
   5 .\" Copyright (c) 2001, 2014 The OpenSSL Project.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\"
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in
  16 .\"    the documentation and/or other materials provided with the
  17 .\"    distribution.
  18 .\"
  19 .\" 3. All advertising materials mentioning features or use of this
  20 .\"    software must display the following acknowledgment:
  21 .\"    "This product includes software developed by the OpenSSL Project
  22 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  23 .\"
  24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  25 .\"    endorse or promote products derived from this software without
  26 .\"    prior written permission. For written permission, please contact
  27 .\"    openssl-core@openssl.org.
  28 .\"
  29 .\" 5. Products derived from this software may not be called "OpenSSL"
  30 .\"    nor may "OpenSSL" appear in their names without prior written
  31 .\"    permission of the OpenSSL Project.
  32 .\"
  33 .\" 6. Redistributions of any form whatsoever must retain the following
  34 .\"    acknowledgment:
  35 .\"    "This product includes software developed by the OpenSSL Project
  36 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  37 .\"
  38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  41 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  50 .\"
  51 .Dd $Mdocdate: November 30 2016 $
  52 .Dt SSL_CTX_SET_GENERATE_SESSION_ID 3
  53 .Os
  54 .Sh NAME
  55 .Nm SSL_CTX_set_generate_session_id ,
  56 .Nm SSL_set_generate_session_id ,
  57 .Nm SSL_has_matching_session_id
  58 .Nd manipulate generation of SSL session IDs (server only)
  59 .Sh SYNOPSIS
  60 .In openssl/ssl.h
  61 .Ft typedef int
  62 .Fo (*GEN_SESSION_CB)
  63 .Fa "const SSL *ssl"
  64 .Fa "unsigned char *id"
  65 .Fa "unsigned int *id_len"
  66 .Fc
  67 .Ft int
  68 .Fn SSL_CTX_set_generate_session_id "SSL_CTX *ctx" "GEN_SESSION_CB cb"
  69 .Ft int
  70 .Fn SSL_set_generate_session_id "SSL *ssl" "GEN_SESSION_CB" "cb);"
  71 .Ft int
  72 .Fo SSL_has_matching_session_id
  73 .Fa "const SSL *ssl" "const unsigned char *id" "unsigned int id_len"
  74 .Fc
  75 .Sh DESCRIPTION
  76 .Fn SSL_CTX_set_generate_session_id
  77 sets the callback function for generating new session ids for SSL/TLS sessions
  78 for
  79 .Fa ctx
  80 to be
  81 .Fa cb .
  82 .Pp
  83 .Fn SSL_set_generate_session_id
  84 sets the callback function for generating new session ids for SSL/TLS sessions
  85 for
  86 .Fa ssl
  87 to be
  88 .Fa cb .
  89 .Pp
  90 .Fn SSL_has_matching_session_id
  91 checks, whether a session with id
  92 .Fa id
  93 (of length
  94 .Fa id_len )
  95 is already contained in the internal session cache
  96 of the parent context of
  97 .Fa ssl .
  98 .Pp
  99 When a new session is established between client and server,
 100 the server generates a session id.
 101 The session id is an arbitrary sequence of bytes.
 102 The length of the session id is between 1 and 32 bytes.
 103 The session id is not security critical but must be unique for the server.
 104 Additionally, the session id is transmitted in the clear when reusing the
 105 session so it must not contain sensitive information.
 106 .Pp
 107 Without a callback being set, an OpenSSL server will generate a unique session
 108 id from pseudo random numbers of the maximum possible length.
 109 Using the callback function, the session id can be changed to contain
 110 additional information like, e.g., a host id in order to improve load balancing
 111 or external caching techniques.
 112 .Pp
 113 The callback function receives a pointer to the memory location to put
 114 .Fa id
 115 into and a pointer to the maximum allowed length
 116 .Fa id_len .
 117 The buffer at location
 118 .Fa id
 119 is only guaranteed to have the size
 120 .Fa id_len .
 121 The callback is only allowed to generate a shorter id and reduce
 122 .Fa id_len ;
 123 the callback
 124 .Em must never
 125 increase
 126 .Fa id_len
 127 or write to the location
 128 .Fa id
 129 exceeding the given limit.
 130 .Pp
 131 The location
 132 .Fa id
 133 is filled with 0x00 before the callback is called,
 134 so the callback may only fill part of the possible length and leave
 135 .Fa id_len
 136 untouched while maintaining reproducibility.
 137 .Pp
 138 Since the sessions must be distinguished, session ids must be unique.
 139 Without the callback a random number is used,
 140 so that the probability of generating the same session id is extremely small
 141 (2^256 for TLSv1).
 142 In order to ensure the uniqueness of the generated session id,
 143 the callback must call
 144 .Fn SSL_has_matching_session_id
 145 and generate another id if a conflict occurs.
 146 If an id conflict is not resolved, the handshake will fail.
 147 If the application codes, e.g., a unique host id, a unique process number, and
 148 a unique sequence number into the session id, uniqueness could easily be
 149 achieved without randomness added (it should however be taken care that
 150 no confidential information is leaked this way).
 151 If the application cannot guarantee uniqueness,
 152 it is recommended to use the maximum
 153 .Fa id_len
 154 and fill in the bytes not used to code special information with random data to
 155 avoid collisions.
 156 .Pp
 157 .Fn SSL_has_matching_session_id
 158 will only query the internal session cache, not the external one.
 159 Since the session id is generated before the handshake is completed,
 160 it is not immediately added to the cache.
 161 If another thread is using the same internal session cache,
 162 a race condition can occur in that another thread generates the same session id.
 163 Collisions can also occur when using an external session cache,
 164 since the external cache is not tested with
 165 .Fn SSL_has_matching_session_id
 166 and the same race condition applies.
 167 .Pp
 168 The callback must return 0 if it cannot generate a session id for whatever
 169 reason and return 1 on success.
 170 .Sh RETURN VALUES
 171 .Fn SSL_CTX_set_generate_session_id
 172 and
 173 .Fn SSL_set_generate_session_id
 174 always return 1.
 175 .Pp
 176 .Fn SSL_has_matching_session_id
 177 returns 1 if another session with the same id is already in the cache.
 178 .Sh EXAMPLES
 179 The callback function listed will generate a session id with the server id
 180 given, and will fill the rest with pseudo random bytes:
 181 .Bd -literal
 182 const char session_id_prefix = "www-18";
 183
 184 #define MAX_SESSION_ID_ATTEMPTS 10
 185 static int
 186 generate_session_id(const SSL *ssl, unsigned char *id,
 187     unsigned int *id_len)
 188 {
 189         unsigned int count = 0;
 190
 191         do {
 192                 RAND_pseudo_bytes(id, *id_len);
 193                 /*
 194                  * Prefix the session_id with the required prefix. NB: If
 195                  * our prefix is too long, clip it \(en but there will be
 196                  * worse effects anyway, e.g., the server could only
 197                  * possibly create one session ID (the prefix!) so all
 198                  * future session negotiations will fail due to conflicts.
 199                  */
 200                 memcpy(id, session_id_prefix,
 201                     (strlen(session_id_prefix) < *id_len) ?
 202                     strlen(session_id_prefix) : *id_len);
 203         } while (SSL_has_matching_session_id(ssl, id, *id_len) &&
 204             (++count < MAX_SESSION_ID_ATTEMPTS));
 205
 206         if (count >= MAX_SESSION_ID_ATTEMPTS)
 207                 return 0;
 208         return 1;
 209 }
 210 .Ed
 211 .Sh SEE ALSO
 212 .Xr ssl 3 ,
 213 .Xr SSL_get_version 3
 214 .Sh HISTORY
 215 .Fn SSL_CTX_set_generate_session_id ,
 216 .Fn SSL_set_generate_session_id
 217 and
 218 .Fn SSL_has_matching_session_id
 219 were introduced in OpenSSL 0.9.7.