From 8cbceba6106feb1110e7df6fbce9ab7ed2503b60 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Lutz=20J=C3=A4nicke?= Date: Fri, 2 Feb 2001 14:40:52 +0000 Subject: [PATCH] Document session caching, first step. --- doc/ssl/SSL_CTX_sess_set_get_cb.pod | 80 ++++++++++++++++ doc/ssl/SSL_CTX_set_session_cache_mode.pod | 101 +++++++++++++++++++++ doc/ssl/SSL_set_session.pod | 3 +- doc/ssl/d2i_SSL_SESSION.pod | 54 +++++++++++ doc/ssl/ssl.pod | 5 +- 5 files changed, 241 insertions(+), 2 deletions(-) create mode 100644 doc/ssl/SSL_CTX_sess_set_get_cb.pod create mode 100644 doc/ssl/SSL_CTX_set_session_cache_mode.pod create mode 100644 doc/ssl/d2i_SSL_SESSION.pod diff --git a/doc/ssl/SSL_CTX_sess_set_get_cb.pod b/doc/ssl/SSL_CTX_sess_set_get_cb.pod new file mode 100644 index 0000000000..4f3c93a859 --- /dev/null +++ b/doc/ssl/SSL_CTX_sess_set_get_cb.pod @@ -0,0 +1,80 @@ +=pod + +=head1 NAME + +SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb - provide callback functions for server side external session caching + +=head1 SYNOPSIS + + #include + + void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx, + int (*new_session_cb)(SSL *, SSL_SESSION *)); + void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx, + void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *)); + void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx, + SSL_SESSION (*get_session-cb)(SSL *, unsigned char *, int, int *)); + + int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, SSL_SESSION *sess); + void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, SSL_SESSION *sess); + SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, unsigned char *data, int len, int *copy); + + int (*new_session_cb)(struct ssl_st *ssl, SSL_SESSION *sess); + void (*remove_session_cb)(struct ssl_ctx_st *ctx, SSL_SESSION *sess); + SSL_SESSION *(*get_session_cb)(struct ssl_st *ssl, unsigned char *data, + int len, int *copy); + +=head1 DESCRIPTION + +SSL_CTX_sess_set_new_cb() sets the callback function, which is automatically +called whenever a new session was negotiated. + +SSL_CTX_sess_set_remove_cb() sets the callback function, which is +automatically called whenever a session is removed by the SSL engine, +because it is considered faulty or the session has become obsolete because +of exceeding the timeout value. + +SSL_CTX_sess_set_get_cb() sets the callback function which is called, +whenever a SSL/TLS client proposed to resume a session but the session +could not be found in the internal session cache (see +L). +(SSL/TLS server only.) + +SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and +SSL_CTX_sess_get_get_cb() allow to retrieve the funtion pointers of the +provided callback functions. If a callback function has not been set, +the NULL pointer is returned. + +=head1 NOTES + +In order to allow external session caching, synchronization with the internal +session cache is realized via callback functions. Inside these callback +functions, session can be saved to disk or put into a database using the +L interface. + +The new_session_cb() is called, whenever a new session has been negotiated +and session caching is enabled (see +L). +The new_session_cb() is passed the B connection and the ssl session +B. If the callback returns B<0>, the session will be immediatly +removed again. + +The remove_session_cb() is called, whenever the SSL engine removes a session +from the internal cache. This happens if the session is removed because +it is expired or when a connection was not shutdown cleanly. The +remove_session_cb() is passed the B and the ssl session B. +It does not provide any feedback. + +The get_session_cb() is only called on SSL/TLS servers with the session id +proposed by the client. The get_session_cb() is always called, also when +session caching was disabled. The get_session_cb() is passed the +B connection, the session id of length B at the memory location +B. With the parameter B the callback can require the +SSL engine to increment the reference count of the SSL_SESSION object. + +=head1 SEE ALSO + +L, L, +L + +=cut diff --git a/doc/ssl/SSL_CTX_set_session_cache_mode.pod b/doc/ssl/SSL_CTX_set_session_cache_mode.pod new file mode 100644 index 0000000000..8fead0c6ee --- /dev/null +++ b/doc/ssl/SSL_CTX_set_session_cache_mode.pod @@ -0,0 +1,101 @@ +=pod + +=head1 NAME + +SSL_CTX_set_session_cache_mode - enable/disable session caching + +=head1 SYNOPSIS + + #include + + long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode); + long SSL_CTX_get_session_cache_mode(SSL_CTX ctx); + +=head1 DESCRIPTION + +SSL_CTX_set_session_cache_mode() enables/disables session caching +by setting the operational mode for B to . + +SSL_CTX_get_session_cache_mode() returns the currently used cache mode. + +=head1 NOTES + +The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse. +The sessions can be held in memory for each B, if more than one +SSL_CTX object is being maintained, the sessions are unique for each SSL_CTX +object. + +In order to reuse a session, a client must send the session's id to the +server. It can only send exactly one id. The server then decides whether it +agrees in reusing the session or starts the handshake for a new session. + +A server will lookup up the session in its internal session storage. If +the session is not found in internal storage or internal storage is +deactivated, the server will try the external storage if available. + +Since a client may try to reuse a session intended for use in a different +context, the session id context must be set by the server (see +L). + +The following session cache modes and modifiers are available: + +=over 4 + +=item SSL_SESS_CACHE_OFF + +No session caching for client or server takes place. + +=item SSL_SESS_CACHE_CLIENT + +Client sessions are added to the session cache. As there is no reliable way +for the OpenSSL library to know whether a session should be reused or which +session to choose (due to the abstract BIO layer the SSL engine does not +have details about the connection), the application must select the session +to be reused by using the L +function. This option is not activated by default. + +=item SSL_SESS_CACHE_SERVER + +Server sessions are added to the session cache. When a client proposes a +session to be reused, the session is looked up in the internal session cache. +If the session is found, the server will try to reuse the session. +This is the default. + +=item SSL_SESS_CACHE_BOTH + +Enable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time. + +=item SSL_SESS_CACHE_NO_AUTO_CLEAR + +Normally the session cache is checked for expired sessions every +255 connections using the SSL_CTX_flush_sessions() function. Since +this may lead to a delay which cannot be controlled, the automatic +flushing may be disabled and SSL_CTX_flush_sessions() can be called +explicitly by the application. + +=item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP + +By setting this flag sessions are cached in the internal storage but +they are not looked up automatically. If an external session cache +is enabled, sessions are looked up in the external cache. As automatic +lookup only applies for SSL/TLS servers, the flag has no effect on +clients. + +=back + +The default mode is SSL_SESS_CACHE_SERVER. + +=head1 RETURN VALUES + +SSL_CTX_set_session_cache_mode() returns the previously set cache mode. + +SSL_CTX_get_session_cache_mode() returns the currently set cache mode. + + +=head1 SEE ALSO + +L, L, +L, +L + +=cut diff --git a/doc/ssl/SSL_set_session.pod b/doc/ssl/SSL_set_session.pod index 9f78d9e434..c4f7878579 100644 --- a/doc/ssl/SSL_set_session.pod +++ b/doc/ssl/SSL_set_session.pod @@ -40,6 +40,7 @@ The operation succeeded. =head1 SEE ALSO -L, L +L, L, +L =cut diff --git a/doc/ssl/d2i_SSL_SESSION.pod b/doc/ssl/d2i_SSL_SESSION.pod new file mode 100644 index 0000000000..feadad85c9 --- /dev/null +++ b/doc/ssl/d2i_SSL_SESSION.pod @@ -0,0 +1,54 @@ +=pod + +=head1 NAME +d2i_SSL_SESSION, i2d_SSL_SESSION - convert SSL_SESSION object from/to ASN1 representation + +=head1 SYNOPSIS + + #include + + SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a, unsigned char **pp, long length); int i2d_SSL_SESSION(SSL_SESSION *in, unsigned char **pp); + +=head1 DESCRIPTION + +d2i_SSL_SESSION() transforms the external ASN1 representation of an SSL/TLS +session, stored as binary data at location B with length B, into +an SSL_SESSION object. + +i2d_SSL_SESSION() transforms the SSL_SESSION object B into the ASN1 +representation and stores it into the memory location pointed to by B. +The length of the resulting ASN1 representation is returned. If B is +the NULL pointer, only the length is calculated and returned. + +=head1 NOTES + +The SSL_SESSION object is built from several malloc()ed parts, it can +therefore not be moved, copied or stored directly. In order to store +session data on disk or into a database, it must be transformed into +a binary ASN1 representation. + +When using d2i_SSL_SESSION(), the SSL_SESSION object is automatically +allocated. + +When using i2d_SSL_SESSION(), the memory location pointed to by B must be +large enough to hold the binary representation of the session. There is no +known limit on the size of the created ASN1 representation, so the necessary +amount of space should be obtained by first calling i2d_SSL_SESSION() with +B, and obtain the size needed, then allocate the memory and +call i2d_SSL_SESSION() again. + +=head1 RETURN VALUES + +d2i_SSL_SESSION() returns a pointer to the newly allocated SSL_SESSION +object. In case of failure the NULL-pointer is returned and the error message +can be retrieved from the error stack. + +i2d_SSL_SESSION() returns the size of the ASN1 representation in bytes. +When the session is not valid, B<0> is returned and no operation is performed. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod index 00e27ea8d3..33ee2d1e82 100644 --- a/doc/ssl/ssl.pod +++ b/doc/ssl/ssl.pod @@ -655,8 +655,10 @@ L, L, L L, +L, L, L, +L, L, L, L, @@ -679,7 +681,8 @@ L, L, L, L, L, L, -L +L, +L =head1 HISTORY -- 2.25.1