diff options
author | Lutz Jänicke <jaenicke@openssl.org> | 2001-02-02 14:40:52 +0000 |
---|---|---|
committer | Lutz Jänicke <jaenicke@openssl.org> | 2001-02-02 14:40:52 +0000 |
commit | 8cbceba6106feb1110e7df6fbce9ab7ed2503b60 (patch) | |
tree | 554fbe87ef4b771b1f761b6df3aa2209066fca65 /doc | |
parent | 88ce56f8c19afca84548ce85bbc9b5dda3c724f9 (diff) |
Document session caching, first step.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ssl/SSL_CTX_sess_set_get_cb.pod | 80 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_set_session_cache_mode.pod | 101 | ||||
-rw-r--r-- | doc/ssl/SSL_set_session.pod | 3 | ||||
-rw-r--r-- | doc/ssl/d2i_SSL_SESSION.pod | 54 | ||||
-rw-r--r-- | doc/ssl/ssl.pod | 5 |
5 files changed, 241 insertions, 2 deletions
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 <openssl/ssl.h> + + 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_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>). +(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<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)> interface. + +The new_session_cb() is called, whenever a new session has been negotiated +and session caching is enabled (see +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>). +The new_session_cb() is passed the B<ssl> connection and the ssl session +B<sess>. 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<ctx> and the ssl session B<sess>. +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<ssl> connection, the session id of length B<length> at the memory location +B<data>. With the parameter B<copy> the callback can require the +SSL engine to increment the reference count of the SSL_SESSION object. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)> + +=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 <openssl/ssl.h> + + 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<ctx> to <mode>. + +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<ctx>, 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<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>). + +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<SSL_set_session(3)|SSL_set_session(3)> +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<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>, +L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>, +L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)> + +=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<ssl(3)|ssl(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> +L<ssl(3)|ssl(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)> =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 <openssl/ssl.h> + + 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<pp> with length B<length>, into +an SSL_SESSION object. + +i2d_SSL_SESSION() transforms the SSL_SESSION object B<in> into the ASN1 +representation and stores it into the memory location pointed to by B<pp>. +The length of the resulting ASN1 representation is returned. If B<pp> 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<pp> 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<pp=NULL>, 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<ssl(3)|ssl(3)>, +L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)> + +=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<SSL_CTX_get_ex_new_index(3)|SSL_CTX_get_ex_new_index(3)>, L<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>, L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> L<SSL_CTX_new(3)|SSL_CTX_new(3)>, +L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>, L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>, L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, @@ -679,7 +681,8 @@ L<SSL_set_fd(3)|SSL_set_fd(3)>, L<SSL_pending(3)|SSL_pending(3)>, L<SSL_set_session(3)|SSL_set_session(3)>, L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_write(3)|SSL_write(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, -L<SSL_SESSION_get_ex_new_index(3)|SSL_SESSION_get_ex_new_index(3)> +L<SSL_SESSION_get_ex_new_index(3)|SSL_SESSION_get_ex_new_index(3)>, +L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)> =head1 HISTORY |