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 77sets the callback function for generating new session ids for SSL/TLS sessions 78for 79.Fa ctx 80to be 81.Fa cb . 82.Pp 83.Fn SSL_set_generate_session_id 84sets the callback function for generating new session ids for SSL/TLS sessions 85for 86.Fa ssl 87to be 88.Fa cb . 89.Pp 90.Fn SSL_has_matching_session_id 91checks, whether a session with id 92.Fa id 93(of length 94.Fa id_len ) 95is already contained in the internal session cache 96of the parent context of 97.Fa ssl . 98.Pp 99When a new session is established between client and server, 100the server generates a session id. 101The session id is an arbitrary sequence of bytes. 102The length of the session id is between 1 and 32 bytes. 103The session id is not security critical but must be unique for the server. 104Additionally, the session id is transmitted in the clear when reusing the 105session so it must not contain sensitive information. 106.Pp 107Without a callback being set, an OpenSSL server will generate a unique session 108id from pseudo random numbers of the maximum possible length. 109Using the callback function, the session id can be changed to contain 110additional information like, e.g., a host id in order to improve load balancing 111or external caching techniques. 112.Pp 113The callback function receives a pointer to the memory location to put 114.Fa id 115into and a pointer to the maximum allowed length 116.Fa id_len . 117The buffer at location 118.Fa id 119is only guaranteed to have the size 120.Fa id_len . 121The callback is only allowed to generate a shorter id and reduce 122.Fa id_len ; 123the callback 124.Em must never 125increase 126.Fa id_len 127or write to the location 128.Fa id 129exceeding the given limit. 130.Pp 131The location 132.Fa id 133is filled with 0x00 before the callback is called, 134so the callback may only fill part of the possible length and leave 135.Fa id_len 136untouched while maintaining reproducibility. 137.Pp 138Since the sessions must be distinguished, session ids must be unique. 139Without the callback a random number is used, 140so that the probability of generating the same session id is extremely small 141(2^256 for TLSv1). 142In order to ensure the uniqueness of the generated session id, 143the callback must call 144.Fn SSL_has_matching_session_id 145and generate another id if a conflict occurs. 146If an id conflict is not resolved, the handshake will fail. 147If the application codes, e.g., a unique host id, a unique process number, and 148a unique sequence number into the session id, uniqueness could easily be 149achieved without randomness added (it should however be taken care that 150no confidential information is leaked this way). 151If the application cannot guarantee uniqueness, 152it is recommended to use the maximum 153.Fa id_len 154and fill in the bytes not used to code special information with random data to 155avoid collisions. 156.Pp 157.Fn SSL_has_matching_session_id 158will only query the internal session cache, not the external one. 159Since the session id is generated before the handshake is completed, 160it is not immediately added to the cache. 161If another thread is using the same internal session cache, 162a race condition can occur in that another thread generates the same session id. 163Collisions can also occur when using an external session cache, 164since the external cache is not tested with 165.Fn SSL_has_matching_session_id 166and the same race condition applies. 167.Pp 168The callback must return 0 if it cannot generate a session id for whatever 169reason and return 1 on success. 170.Sh RETURN VALUES 171.Fn SSL_CTX_set_generate_session_id 172and 173.Fn SSL_set_generate_session_id 174always return 1. 175.Pp 176.Fn SSL_has_matching_session_id 177returns 1 if another session with the same id is already in the cache. 178.Sh EXAMPLES 179The callback function listed will generate a session id with the server id 180given, and will fill the rest with pseudo random bytes: 181.Bd -literal 182const char session_id_prefix = "www-18"; 183 184#define MAX_SESSION_ID_ATTEMPTS 10 185static int 186generate_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 217and 218.Fn SSL_has_matching_session_id 219were introduced in OpenSSL 0.9.7. 220