From 82b7f378b6907ab315a6e50322d2a0a8794a0aa9 Mon Sep 17 00:00:00 2001 From: bentley <> Date: Sun, 12 Oct 2014 09:33:04 +0000 Subject: Convert libssl manpages from pod to mdoc(7). libcrypto has not been started yet. ok schwarze@ miod@ --- .../libssl/doc/SSL_CTX_set_generate_session_id.3 | 193 +++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 src/lib/libssl/doc/SSL_CTX_set_generate_session_id.3 (limited to 'src/lib/libssl/doc/SSL_CTX_set_generate_session_id.3') diff --git a/src/lib/libssl/doc/SSL_CTX_set_generate_session_id.3 b/src/lib/libssl/doc/SSL_CTX_set_generate_session_id.3 new file mode 100644 index 0000000000..e2e2a70362 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_generate_session_id.3 @@ -0,0 +1,193 @@ +.Dd $Mdocdate: October 12 2014 $ +.Dt SSL_CTX_SET_GENERATE_SESSION_ID 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_generate_session_id , +.Nm SSL_set_generate_session_id , +.Nm SSL_has_matching_session_id +.Nd manipulate generation of SSL session IDs (server only) +.Sh SYNOPSIS +.In openssl/ssl.h +.Bd -literal + typedef int (*GEN_SESSION_CB)(const SSL *ssl, unsigned char *id, + unsigned int *id_len); +.Ed +.Ft int +.Fn SSL_CTX_set_generate_session_id "SSL_CTX *ctx" "GEN_SESSION_CB cb" +.Ft int +.Fn SSL_set_generate_session_id "SSL *ssl" "GEN_SESSION_CB" "cb);" +.Ft int +.Fo SSL_has_matching_session_id +.Fa "const SSL *ssl" "const unsigned char *id" "unsigned int id_len" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_set_generate_session_id +sets the callback function for generating new session ids for SSL/TLS sessions +for +.Fa ctx +to be +.Fa cb . +.Pp +.Fn SSL_set_generate_session_id +sets the callback function for generating new session ids for SSL/TLS sessions +for +.Fa ssl +to be +.Fa cb . +.Pp +.Fn SSL_has_matching_session_id +checks, whether a session with id +.Fa id +(of length +.Fa id_len ) +is already contained in the internal session cache +of the parent context of +.Fa ssl . +.Sh NOTES +When a new session is established between client and server, +the server generates a session id. +The session id is an arbitrary sequence of bytes. +The length of the session id is 16 bytes for SSLv2 sessions and between 1 and +32 bytes for SSLv3/TLSv1. +The session id is not security critical but must be unique for the server. +Additionally, the session id is transmitted in the clear when reusing the +session so it must not contain sensitive information. +.Pp +Without a callback being set, an OpenSSL server will generate a unique session +id from pseudo random numbers of the maximum possible length. +Using the callback function, the session id can be changed to contain +additional information like, e.g., a host id in order to improve load balancing +or external caching techniques. +.Pp +The callback function receives a pointer to the memory location to put +.Fa id +into and a pointer to the maximum allowed length +.Fa id_len . +The buffer at location +.Fa id +is only guaranteed to have the size +.Fa id_len . +The callback is only allowed to generate a shorter id and reduce +.Fa id_len ; +the callback +.Em must never +increase +.Fa id_len +or write to the location +.Fa id +exceeding the given limit. +.Pp +If a SSLv2 session id is generated and +.Fa id_len +is reduced, it will be restored after the callback has finished and the session +id will be padded with 0x00. +It is not recommended to change the +.Fa id_len +for SSLv2 sessions. +The callback can use the +.Xr SSL_get_version 3 +function to check whether the session is of type SSLv2. +.Pp +The location +.Fa id +is filled with 0x00 before the callback is called, +so the callback may only fill part of the possible length and leave +.Fa id_len +untouched while maintaining reproducibility. +.Pp +Since the sessions must be distinguished, session ids must be unique. +Without the callback a random number is used, +so that the probability of generating the same session id is extremely small +(2^128 possible ids for an SSLv2 session, 2^256 for SSLv3/TLSv1). +In order to ensure the uniqueness of the generated session id, +the callback must call +.Fn SSL_has_matching_session_id +and generate another id if a conflict occurs. +If an id conflict is not resolved, the handshake will fail. +If the application codes, e.g., a unique host id, a unique process number, and +a unique sequence number into the session id, uniqueness could easily be +achieved without randomness added (it should however be taken care that +no confidential information is leaked this way). +If the application cannot guarantee uniqueness, +it is recommended to use the maximum +.Fa id_len +and fill in the bytes not used to code special information with random data to +avoid collisions. +.Pp +.Fn SSL_has_matching_session_id +will only query the internal session cache, not the external one. +Since the session id is generated before the handshake is completed, +it is not immediately added to the cache. +If another thread is using the same internal session cache, +a race condition can occur in that another thread generates the same session id. +Collisions can also occur when using an external session cache, +since the external cache is not tested with +.Fn SSL_has_matching_session_id +and the same race condition applies. +.Pp +When calling +.Fn SSL_has_matching_session_id +for an SSLv2 session with reduced +.Fa id_len Ns , +the match operation will be performed using the fixed length required and with +a 0x00 padded id. +.Pp +The callback must return 0 if it cannot generate a session id for whatever +reason and return 1 on success. +.Sh RETURN VALUES +.Fn SSL_CTX_set_generate_session_id +and +.Fn SSL_set_generate_session_id +always return 1. +.Pp +.Fn SSL_has_matching_session_id +returns 1 if another session with the same id is already in the cache. +.Sh EXAMPLES +The callback function listed will generate a session id with the server id +given, and will fill the rest with pseudo random bytes: +.Bd -literal +const char session_id_prefix = "www-18"; + +#define MAX_SESSION_ID_ATTEMPTS 10 +static int +generate_session_id(const SSL *ssl, unsigned char *id, + unsigned int *id_len) +{ + unsigned int count = 0; + const char *version; + + version = SSL_get_version(ssl); + if (!strcmp(version, "SSLv2")) { + /* we must not change id_len */ + ; + } + + do { + RAND_pseudo_bytes(id, *id_len); + /* + * Prefix the session_id with the required prefix. NB: If + * our prefix is too long, clip it \(en but there will be + * worse effects anyway, e.g., the server could only + * possibly create one session ID (the prefix!) so all + * future session negotiations will fail due to conflicts. + */ + memcpy(id, session_id_prefix, + (strlen(session_id_prefix) < *id_len) ? + strlen(session_id_prefix) : *id_len); + } while (SSL_has_matching_session_id(ssl, id, *id_len) && + (++count < MAX_SESSION_ID_ATTEMPTS)); + + if (count >= MAX_SESSION_ID_ATTEMPTS) + return 0; + return 1; +} +.Ed +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_get_version 3 +.Sh HISTORY +.Fn SSL_CTX_set_generate_session_id , +.Fn SSL_set_generate_session_id +and +.Fn SSL_has_matching_session_id +were introduced in OpenSSL 0.9.7. -- cgit v1.2.3-55-g6feb