1 files changed, 193 insertions, 0 deletions

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.