From 3562e78743202e43aec8727005182a2558117eca Mon Sep 17 00:00:00 2001 From: marha Date: Sun, 28 Jun 2009 22:07:26 +0000 Subject: Checked in the following released items: xkeyboard-config-1.4.tar.gz ttf-bitstream-vera-1.10.tar.gz font-alias-1.0.1.tar.gz font-sun-misc-1.0.0.tar.gz font-sun-misc-1.0.0.tar.gz font-sony-misc-1.0.0.tar.gz font-schumacher-misc-1.0.0.tar.gz font-mutt-misc-1.0.0.tar.gz font-misc-misc-1.0.0.tar.gz font-misc-meltho-1.0.0.tar.gz font-micro-misc-1.0.0.tar.gz font-jis-misc-1.0.0.tar.gz font-isas-misc-1.0.0.tar.gz font-dec-misc-1.0.0.tar.gz font-daewoo-misc-1.0.0.tar.gz font-cursor-misc-1.0.0.tar.gz font-arabic-misc-1.0.0.tar.gz font-winitzki-cyrillic-1.0.0.tar.gz font-misc-cyrillic-1.0.0.tar.gz font-cronyx-cyrillic-1.0.0.tar.gz font-screen-cyrillic-1.0.1.tar.gz font-xfree86-type1-1.0.1.tar.gz font-adobe-utopia-type1-1.0.1.tar.gz font-ibm-type1-1.0.0.tar.gz font-bitstream-type1-1.0.0.tar.gz font-bitstream-speedo-1.0.0.tar.gz font-bh-ttf-1.0.0.tar.gz font-bh-type1-1.0.0.tar.gz font-bitstream-100dpi-1.0.0.tar.gz font-bh-lucidatypewriter-100dpi-1.0.0.tar.gz font-bh-100dpi-1.0.0.tar.gz font-adobe-utopia-100dpi-1.0.1.tar.gz font-adobe-100dpi-1.0.0.tar.gz font-util-1.0.1.tar.gz font-bitstream-75dpi-1.0.0.tar.gz font-bh-lucidatypewriter-75dpi-1.0.0.tar.gz font-adobe-utopia-75dpi-1.0.1.tar.gz font-bh-75dpi-1.0.0.tar.gz bdftopcf-1.0.1.tar.gz font-adobe-75dpi-1.0.0.tar.gz mkfontscale-1.0.6.tar.gz openssl-0.9.8k.tar.gz bigreqsproto-1.0.2.tar.gz xtrans-1.2.2.tar.gz resourceproto-1.0.2.tar.gz inputproto-1.4.4.tar.gz compositeproto-0.4.tar.gz damageproto-1.1.0.tar.gz zlib-1.2.3.tar.gz xkbcomp-1.0.5.tar.gz freetype-2.3.9.tar.gz pthreads-w32-2-8-0-release.tar.gz pixman-0.12.0.tar.gz kbproto-1.0.3.tar.gz evieext-1.0.2.tar.gz fixesproto-4.0.tar.gz recordproto-1.13.2.tar.gz randrproto-1.2.2.tar.gz scrnsaverproto-1.1.0.tar.gz renderproto-0.9.3.tar.gz xcmiscproto-1.1.2.tar.gz fontsproto-2.0.2.tar.gz xextproto-7.0.3.tar.gz xproto-7.0.14.tar.gz libXdmcp-1.0.2.tar.gz libxkbfile-1.0.5.tar.gz libfontenc-1.0.4.tar.gz libXfont-1.3.4.tar.gz libX11-1.1.5.tar.gz libXau-1.0.4.tar.gz libxcb-1.1.tar.gz xorg-server-1.5.3.tar.gz --- .../doc/ssl/SSL_CTX_set_generate_session_id.pod | 150 +++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 openssl/doc/ssl/SSL_CTX_set_generate_session_id.pod (limited to 'openssl/doc/ssl/SSL_CTX_set_generate_session_id.pod') diff --git a/openssl/doc/ssl/SSL_CTX_set_generate_session_id.pod b/openssl/doc/ssl/SSL_CTX_set_generate_session_id.pod new file mode 100644 index 000000000..798e8443a --- /dev/null +++ b/openssl/doc/ssl/SSL_CTX_set_generate_session_id.pod @@ -0,0 +1,150 @@ +=pod + +=head1 NAME + +SSL_CTX_set_generate_session_id, SSL_set_generate_session_id, SSL_has_matching_session_id - manipulate generation of SSL session IDs (server only) + +=head1 SYNOPSIS + + #include + + typedef int (*GEN_SESSION_CB)(const SSL *ssl, unsigned char *id, + unsigned int *id_len); + + int SSL_CTX_set_generate_session_id(SSL_CTX *ctx, GEN_SESSION_CB cb); + int SSL_set_generate_session_id(SSL *ssl, GEN_SESSION_CB, cb); + int SSL_has_matching_session_id(const SSL *ssl, const unsigned char *id, + unsigned int id_len); + +=head1 DESCRIPTION + +SSL_CTX_set_generate_session_id() sets the callback function for generating +new session ids for SSL/TLS sessions for B to be B. + +SSL_set_generate_session_id() sets the callback function for generating +new session ids for SSL/TLS sessions for B to be B. + +SSL_has_matching_session_id() checks, whether a session with id B +(of length B) is already contained in the internal session cache +of the parent context of B. + +=head1 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. + +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. + +The callback function receives a pointer to the memory location to put +B into and a pointer to the maximum allowed length B. The +buffer at location B is only guaranteed to have the size B. +The callback is only allowed to generate a shorter id and reduce B; +the callback B increase B or write to the location +B exceeding the given limit. + +If a SSLv2 session id is generated and B 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 B for SSLv2 sessions. +The callback can use the L function +to check, whether the session is of type SSLv2. + +The location B is filled with 0x00 before the callback is called, so the +callback may only fill part of the possible length and leave B +untouched while maintaining reproducibility. + +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 assure the +uniqueness of the generated session id, the callback must call +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 can not +guarantee uniqueness, it is recommended to use the maximum B and +fill in the bytes not used to code special information with random data +to avoid collisions. + +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 SSL_has_matching_session_id() +and the same race condition applies. + +When calling SSL_has_matching_session_id() for an SSLv2 session with +reduced B, the match operation will be performed using the +fixed length required and with a 0x00 padded id. + +The callback must return 0 if it cannot generate a session id for whatever +reason and return 1 on success. + +=head1 EXAMPLES + +The callback function listed will generate a session id with the +server id given, and will fill the rest with pseudo random bytes: + + 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 - but there will be worse effects + * anyway, eg. the server could only possibly create 1 session + * ID (ie. 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; + } + + +=head1 RETURN VALUES + +SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id() +always return 1. + +SSL_has_matching_session_id() returns 1 if another session with the +same id is already in the cache. + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +SSL_CTX_set_generate_session_id(), SSL_set_generate_session_id() +and SSL_has_matching_session_id() have been introduced in +OpenSSL 0.9.7. + +=cut -- cgit v1.2.3