diff options
author | Lutz Jänicke <jaenicke@openssl.org> | 2001-02-04 18:05:27 +0000 |
---|---|---|
committer | Lutz Jänicke <jaenicke@openssl.org> | 2001-02-04 18:05:27 +0000 |
commit | 0bc6597d4d1402afd0c5df7855b72bdf93e98f9d (patch) | |
tree | cd85f9628d964de8de331e9c63591aad5ebfd7a6 /doc | |
parent | 2b916952a8de5b1197169801925dad74aa3360cd (diff) | |
download | openssl-0bc6597d4d1402afd0c5df7855b72bdf93e98f9d.tar.gz |
Documenting session caching, 2nd step.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ssl/SSL_CTX_add_session.pod | 65 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_flush_sessions.pod | 49 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_sess_set_cache_size.pod | 50 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_sess_set_get_cb.pod | 9 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_set_session_cache_mode.pod | 13 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_set_timeout.pod | 55 | ||||
-rw-r--r-- | doc/ssl/SSL_SESSION_free.pod | 2 | ||||
-rw-r--r-- | doc/ssl/SSL_SESSION_get_time.pod | 63 | ||||
-rw-r--r-- | doc/ssl/ssl.pod | 5 |
9 files changed, 303 insertions, 8 deletions
diff --git a/doc/ssl/SSL_CTX_add_session.pod b/doc/ssl/SSL_CTX_add_session.pod new file mode 100644 index 0000000000..af326c2f73 --- /dev/null +++ b/doc/ssl/SSL_CTX_add_session.pod @@ -0,0 +1,65 @@ +=pod + +=head1 NAME + +SSL_CTX_add_session, SSL_add_session, SSL_CTX_remove_session, SSL_remove_session - manipulate session cache + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_add_session(SSL_CTX *ctx, SSL_SESSION *c); + int SSL_add_session(SSL_CTX *ctx, SSL_SESSION *c); + + int SSL_CTX_remove_session(SSL_CTX *ctx, SSL_SESSION *c); + int SSL_remove_session(SSL_CTX *ctx, SSL_SESSION *c); + +=head1 DESCRIPTION + +SSL_CTX_add_session() adds the session B<c> to the context B<ctx>. The +reference count for session B<c> is incremented by 1. If a session with +the same session id already exists, the old session is removed by calling +L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>. + +SSL_CTX_remove_session() removes the session B<c> from the context B<ctx>. +L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> is called once for B<c>. + +SSL_add_session() and SSL_remove_session() are synonyms for their +SSL_CTX_*() counterparts. + +=head1 NOTES + +When adding a new session to the internal session cache, it is examined +whether a session with the same session id already exists. In this case +it is assumed that both sessions are identical. If the same session is +stored in a different SSL_SESSION object, The old session is +removed and replaced by the new session. If the session is actually +identical (the SSL_SESSION object is identical), SSL_CTX_add_session() +is a no-op, and the return value is 0. + + +=head1 RETURN VALUES + +The following values are returned by all functions: + +=over 4 + +=item 0 + + The operation failed. In case of the add operation, it was tried to add + the same (identical) session twice. In case of the remove operation, the + session was not found in the cache. + +=item 1 + + The operation succeeded. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, +L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_flush_sessions.pod b/doc/ssl/SSL_CTX_flush_sessions.pod new file mode 100644 index 0000000000..148c36c871 --- /dev/null +++ b/doc/ssl/SSL_CTX_flush_sessions.pod @@ -0,0 +1,49 @@ +=pod + +=head1 NAME + +SSL_CTX_flush_sessions, SSL_flush_sessions - remove expired sessions + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_flush_sessions(SSL_CTX *ctx, long tm); + void SSL_flush_sessions(SSL_CTX *ctx, long tm); + +=head1 DESCRIPTION + +SSL_CTX_flush_sessions() causes a run through the session cache of +B<ctx> to remove sessions expired at time B<tm>. + +SSL_flush_sessions() is a synonym for SSL_CTX_flush_sessions(). + +=head1 NOTES + +If enabled, the internal session cache will collect all sessions established +up to the specified maximum number (see SSL_CTX_sess_set_cache_size()). +As sessions will not be reused ones they are expired, they should be +removed from the cache to save resources. This can either be done + automatically whenever 255 new sessions were established (see +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>) +or manually by calling SSL_CTX_flush_sessions(). + +The parameter B<tm> specifies the time which should be used for the +expiration test, in most cases the actual time given by time(0) +will be used. + +SSL_CTX_flush_sessions() will only check sessions stored in the internal +cache. When a session is found and removed, the remove_session_cb is however +called to synchronize with the external cache (see +L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>). + +=head1 RETURN VALUES + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, +L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>, +L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_sess_set_cache_size.pod b/doc/ssl/SSL_CTX_sess_set_cache_size.pod new file mode 100644 index 0000000000..469933baf3 --- /dev/null +++ b/doc/ssl/SSL_CTX_sess_set_cache_size.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +SSL_CTX_sess_set_cache_size, SSL_CTX_sess_get_cache_size - manipulate session cache size + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_sess_set_cache_size(SSL_CTX *ctx, long t); + long SSL_CTX_sess_get_cache_size(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_sess_set_cache_size() sets the size of the internal session cache +of context B<ctx> to B<t>. + +SSL_CTX_sess_get_cache_size() returns the currently valid session cache size. + +=head1 NOTES + +The internal session cache size is SSL_SESSION_CACHE_MAX_SIZE_DEFAULT, +currently 1024*20, so that up to 20000 sessions can be held. This size +can be modified using the SSL_CTX_sess_set_cache_size() call. A special +case is the size 0, which is used for unlimited size. + +When the maximum number of sessions is reached, no more new sessions are +added to the cache. New space may be added by calling +L<SSL_CTX_flush_sessions(3)|<SSL_CTX_flush_sessions(3)> to remove +expired sessions. + +If the size of the session cache is reduced and more sessions are already +in the session cache, old session will be removed at the next time a +session shall be added. This removal is not synchronized with the +expiration of sessions. + +=head1 RETURN VALUES + +SSL_CTX_sess_set_cache_size() returns the previously valid size. + +SSL_CTX_sess_get_cache_size() returns the currently valid size. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, +L<SSL_CTX_flush_sessions(3)|<SSL_CTX_flush_sessions(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_sess_set_get_cb.pod b/doc/ssl/SSL_CTX_sess_set_get_cb.pod index 4f3c93a859..b6f15b4404 100644 --- a/doc/ssl/SSL_CTX_sess_set_get_cb.pod +++ b/doc/ssl/SSL_CTX_sess_set_get_cb.pod @@ -13,7 +13,7 @@ SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SS 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 *)); + 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); @@ -41,7 +41,7 @@ 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 +SSL_CTX_sess_get_get_cb() allow to retrieve the function pointers of the provided callback functions. If a callback function has not been set, the NULL pointer is returned. @@ -56,7 +56,7 @@ 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 +B<sess>. If the callback returns B<0>, the session will be immediately removed again. The remove_session_cb() is called, whenever the SSL engine removes a session @@ -75,6 +75,7 @@ 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)> +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, +L<SSL_CTX_flush_sessions(3)|<SSL_CTX_flush_sessions(3)> =cut diff --git a/doc/ssl/SSL_CTX_set_session_cache_mode.pod b/doc/ssl/SSL_CTX_set_session_cache_mode.pod index 8fead0c6ee..ba3502a0a4 100644 --- a/doc/ssl/SSL_CTX_set_session_cache_mode.pod +++ b/doc/ssl/SSL_CTX_set_session_cache_mode.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_CTX_set_session_cache_mode - enable/disable session caching +SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable session caching =head1 SYNOPSIS @@ -68,9 +68,11 @@ 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 +255 connections using the +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> 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 +flushing may be disabled and +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> can be called explicitly by the application. =item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP @@ -95,7 +97,10 @@ 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_cache_size(3)|SSL_CTX_sess_set_cache_size(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)> +L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>, +L<SSL_CTX_set_timeout.pod(3)|SSL_CTX_set_timeout.pod(3)>, +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> =cut diff --git a/doc/ssl/SSL_CTX_set_timeout.pod b/doc/ssl/SSL_CTX_set_timeout.pod new file mode 100644 index 0000000000..21faed12d4 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_timeout.pod @@ -0,0 +1,55 @@ +=pod + +=head1 NAME + +SSL_CTX_set_timeout, SSL_CTX_get_timeout - manipulate timeout values for session caching + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_set_timeout(SSL_CTX *ctx, long t); + long SSL_CTX_get_timeout(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_set_timeout() sets the timeout for newly created sessions for +B<ctx> to B<t>. The timeout value B<t> must be given in seconds. + +SSL_CTX_get_timeout() returns the currently set timeout value for B<ctx>. + +=head1 NOTES + +Whenever a new session is created, it is assigned a maximum lifetime. This +lifetime is specified by storing the creation time of the session and the +timeout value valid at this time. If the actual time is later than creation +time plus timeout, the session is not reused. + +Due to this realization, all sessions behave according to the timeout value +valid at the time of the session negotiation. Changes of the timeout value +do not affect already established sessions. + +The expiration time of a single session can be modified using the +L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)> family of functions. + +Expired sessions are removed from the internal session cache, whenever +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> is called, either +directly by the application or automatically (see +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>) + +The default value for session timeout is 300 seconds. + +=head1 RETURN VALUES + +SSL_CTX_set_timeout() returns the previously set timeout value. + +SSL_CTX_get_timeout() returns the currently set timeout value. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, +L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)>, +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> + +=cut diff --git a/doc/ssl/SSL_SESSION_free.pod b/doc/ssl/SSL_SESSION_free.pod index df30ccbb32..9275d88a40 100644 --- a/doc/ssl/SSL_SESSION_free.pod +++ b/doc/ssl/SSL_SESSION_free.pod @@ -20,6 +20,8 @@ memory, if the the reference count has reached 0. SSL_SESSION_free() does not provide diagnostic information. +=head1 SEE ALSO + L<ssl(3)|ssl(3)>, L<SSL_get_session(3)|SSL_get_session(3)> =cut diff --git a/doc/ssl/SSL_SESSION_get_time.pod b/doc/ssl/SSL_SESSION_get_time.pod new file mode 100644 index 0000000000..cd33b73aa3 --- /dev/null +++ b/doc/ssl/SSL_SESSION_get_time.pod @@ -0,0 +1,63 @@ +=pod + +=head1 NAME + +SSL_SESSION_get_time, SSL_SESSION_set_time, SSL_SESSION_get_timeout, SSL_SESSION_get_timeout - retrieve and manipulate session time and timeout settings + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_SESSION_get_time(SSL_SESSION *s); + long SSL_SESSION_set_time(SSL_SESSION *s, long tm); + long SSL_SESSION_get_timeout(SSL_SESSION *s); + long SSL_SESSION_set_timeout(SSL_SESSION *s, long tm); + + long SSL_get_time(SSL_SESSION *s); + long SSL_set_time(SSL_SESSION *s, long tm); + long SSL_get_timeout(SSL_SESSION *s); + long SSL_set_timeout(SSL_SESSION *s, long tm); + +=head1 DESCRIPTION + +SSL_SESSION_get_time() returns the time at which the session B<s> was +established. The time is given in seconds since the Epoch and therefore +compatible to the time delivered by the time() call. + +SSL_SESSION_set_time() replaces the creation time of the session B<s> with +the chosen value B<tm>. + +SSL_SESSION_get_timeout() returns the timeout value set for session B<s> +in seconds. + +SSL_SESSION_set_timeout() sets the timeout value for session B<s> in seconds +to B<tm>. + +The SSL_get_time(), SSL_set_time(), SSL_get_timeout(), and SSL_set_timeout() +functions are synonyms for the SSL_SESSION_*() counterparts. + +=head1 NOTES + +Sessions are expired by examining the creation time and the timeout value. +Both are set at creation time of the session to the actual time and the +default timeout value at creation, respectively, as set by +L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>. +Using these functions it is possible to extend or shorten the lifetime +of the session. + +=head1 RETURN VALUES + +SSL_SESSION_get_time() and SSL_SESSION_get_timeout() return the currently +valid values. + +SSL_SESSION_set_time() and SSL_SESSION_set_timeout() return 1 on success. + +If any of the function is passed the NULL pointer for the session B<s>, +0 is returned. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)> + +=cut diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod index 33ee2d1e82..c95b8dcc7d 100644 --- a/doc/ssl/ssl.pod +++ b/doc/ssl/ssl.pod @@ -651,16 +651,20 @@ L<SSL_accept(3)|SSL_accept(3)>, L<SSL_clear(3)|SSL_clear(3)>, L<SSL_connect(3)|SSL_connect(3)>, L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)>, L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>, +L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>, +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>, 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_cache_size(3)|SSL_CTX_sess_set_cache_size(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_timeout(3)|SSL_CTX_set_timeout(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, @@ -682,6 +686,7 @@ 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_time(3)|SSL_SESSION_get_time(3)>, L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)> =head1 HISTORY |