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