lib/libssl/man/SSL_CTX_set_generate_session_id.3

   1 .\"     $OpenBSD: SSL_CTX_set_generate_session_id.3,v 1.4 2017/08/01 14:57:03 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: August 1 2017 $
  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 .Nm GEN_SESSION_CB
  59 .Nd manipulate generation of SSL session IDs (server only)
  60 .Sh SYNOPSIS
  61 .In openssl/ssl.h
  62 .Ft typedef int
  63 .Fo (*GEN_SESSION_CB)
  64 .Fa "const SSL *ssl"
  65 .Fa "unsigned char *id"
  66 .Fa "unsigned int *id_len"
  67 .Fc
  68 .Ft int
  69 .Fn SSL_CTX_set_generate_session_id "SSL_CTX *ctx" "GEN_SESSION_CB cb"
  70 .Ft int
  71 .Fn SSL_set_generate_session_id "SSL *ssl" "GEN_SESSION_CB cb"
  72 .Ft int
  73 .Fo SSL_has_matching_session_id
  74 .Fa "const SSL *ssl" "const unsigned char *id" "unsigned int id_len"
  75 .Fc
  76 .Sh DESCRIPTION
  77 .Fn SSL_CTX_set_generate_session_id
  78 sets the callback function for generating new session ids for SSL/TLS sessions
  79 for
  80 .Fa ctx
  81 to be
  82 .Fa cb .
  83 .Pp
  84 .Fn SSL_set_generate_session_id
  85 sets the callback function for generating new session ids for SSL/TLS sessions
  86 for
  87 .Fa ssl
  88 to be
  89 .Fa cb .
  90 .Pp
  91 .Fn SSL_has_matching_session_id
  92 checks, whether a session with id
  93 .Fa id
  94 (of length
  95 .Fa id_len )
  96 is already contained in the internal session cache
  97 of the parent context of
  98 .Fa ssl .
  99 .Pp
 100 When a new session is established between client and server,
 101 the server generates a session id.
 102 The session id is an arbitrary sequence of bytes.
 103 The length of the session id is between 1 and 32 bytes.
 104 The session id is not security critical but must be unique for the server.
 105 Additionally, the session id is transmitted in the clear when reusing the
 106 session so it must not contain sensitive information.
 107 .Pp
 108 Without a callback being set, an OpenSSL server will generate a unique session
 109 id from pseudo random numbers of the maximum possible length.
 110 Using the callback function, the session id can be changed to contain
 111 additional information like, e.g., a host id in order to improve load balancing
 112 or external caching techniques.
 113 .Pp
 114 The callback function receives a pointer to the memory location to put
 115 .Fa id
 116 into and a pointer to the maximum allowed length
 117 .Fa id_len .
 118 The buffer at location
 119 .Fa id
 120 is only guaranteed to have the size
 121 .Fa id_len .
 122 The callback is only allowed to generate a shorter id and reduce
 123 .Fa id_len ;
 124 the callback
 125 .Em must never
 126 increase
 127 .Fa id_len
 128 or write to the location
 129 .Fa id
 130 exceeding the given limit.
 131 .Pp
 132 The location
 133 .Fa id
 134 is filled with 0x00 before the callback is called,
 135 so the callback may only fill part of the possible length and leave
 136 .Fa id_len
 137 untouched while maintaining reproducibility.
 138 .Pp
 139 Since the sessions must be distinguished, session ids must be unique.
 140 Without the callback a random number is used,
 141 so that the probability of generating the same session id is extremely small
 142 (2^256 for TLSv1).
 143 In order to ensure the uniqueness of the generated session id,
 144 the callback must call
 145 .Fn SSL_has_matching_session_id
 146 and generate another id if a conflict occurs.
 147 If an id conflict is not resolved, the handshake will fail.
 148 If the application codes, e.g., a unique host id, a unique process number, and
 149 a unique sequence number into the session id, uniqueness could easily be
 150 achieved without randomness added (it should however be taken care that
 151 no confidential information is leaked this way).
 152 If the application cannot guarantee uniqueness,
 153 it is recommended to use the maximum
 154 .Fa id_len
 155 and fill in the bytes not used to code special information with random data to
 156 avoid collisions.
 157 .Pp
 158 .Fn SSL_has_matching_session_id
 159 will only query the internal session cache, not the external one.
 160 Since the session id is generated before the handshake is completed,
 161 it is not immediately added to the cache.
 162 If another thread is using the same internal session cache,
 163 a race condition can occur in that another thread generates the same session id.
 164 Collisions can also occur when using an external session cache,
 165 since the external cache is not tested with
 166 .Fn SSL_has_matching_session_id
 167 and the same race condition applies.
 168 .Pp
 169 The callback must return 0 if it cannot generate a session id for whatever
 170 reason and return 1 on success.
 171 .Sh RETURN VALUES
 172 .Fn SSL_CTX_set_generate_session_id
 173 and
 174 .Fn SSL_set_generate_session_id
 175 always return 1.
 176 .Pp
 177 .Fn SSL_has_matching_session_id
 178 returns 1 if another session with the same id is already in the cache.
 179 .Sh EXAMPLES
 180 The callback function listed will generate a session id with the server id
 181 given, and will fill the rest with pseudo random bytes:
 182 .Bd -literal
 183 const char session_id_prefix = "www-18";
 184
 185 #define MAX_SESSION_ID_ATTEMPTS 10
 186 static int
 187 generate_session_id(const SSL *ssl, unsigned char *id,
 188     unsigned int *id_len)
 189 {
 190         unsigned int count = 0;
 191
 192         do {
 193                 RAND_pseudo_bytes(id, *id_len);
 194                 /*
 195                  * Prefix the session_id with the required prefix. NB: If
 196                  * our prefix is too long, clip it \(en but there will be
 197                  * worse effects anyway, e.g., the server could only
 198                  * possibly create one session ID (the prefix!) so all
 199                  * future session negotiations will fail due to conflicts.
 200                  */
 201                 memcpy(id, session_id_prefix,
 202                     (strlen(session_id_prefix) < *id_len) ?
 203                     strlen(session_id_prefix) : *id_len);
 204         } while (SSL_has_matching_session_id(ssl, id, *id_len) &&
 205             (++count < MAX_SESSION_ID_ATTEMPTS));
 206
 207         if (count >= MAX_SESSION_ID_ATTEMPTS)
 208                 return 0;
 209         return 1;
 210 }
 211 .Ed
 212 .Sh SEE ALSO
 213 .Xr ssl 3 ,
 214 .Xr SSL_get_version 3
 215 .Sh HISTORY
 216 .Fn SSL_CTX_set_generate_session_id ,
 217 .Fn SSL_set_generate_session_id
 218 and
 219 .Fn SSL_has_matching_session_id
 220 were introduced in OpenSSL 0.9.7.