From 0bc6597d4d1402afd0c5df7855b72bdf93e98f9d Mon Sep 17 00:00:00 2001 From: =?utf8?q?Lutz=20J=C3=A4nicke?= Date: Sun, 4 Feb 2001 18:05:27 +0000 Subject: [PATCH] Documenting session caching, 2nd step. --- doc/ssl/SSL_CTX_add_session.pod | 65 ++++++++++++++++++++++ doc/ssl/SSL_CTX_flush_sessions.pod | 49 ++++++++++++++++ doc/ssl/SSL_CTX_sess_set_cache_size.pod | 50 +++++++++++++++++ doc/ssl/SSL_CTX_sess_set_get_cb.pod | 9 +-- doc/ssl/SSL_CTX_set_session_cache_mode.pod | 13 +++-- doc/ssl/SSL_CTX_set_timeout.pod | 55 ++++++++++++++++++ doc/ssl/SSL_SESSION_free.pod | 2 + doc/ssl/SSL_SESSION_get_time.pod | 63 +++++++++++++++++++++ doc/ssl/ssl.pod | 5 ++ 9 files changed, 303 insertions(+), 8 deletions(-) create mode 100644 doc/ssl/SSL_CTX_add_session.pod create mode 100644 doc/ssl/SSL_CTX_flush_sessions.pod create mode 100644 doc/ssl/SSL_CTX_sess_set_cache_size.pod create mode 100644 doc/ssl/SSL_CTX_set_timeout.pod create mode 100644 doc/ssl/SSL_SESSION_get_time.pod 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 + + 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 to the context B. The +reference count for session B is incremented by 1. If a session with +the same session id already exists, the old session is removed by calling +L. + +SSL_CTX_remove_session() removes the session B from the context B. +L is called once for B. + +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, +L, +L + +=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 + + 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 to remove sessions expired at time B. + +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) +or manually by calling SSL_CTX_flush_sessions(). + +The parameter B 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). + +=head1 RETURN VALUES + +=head1 SEE ALSO + +L, +L, +L, +L + +=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 + + 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 to B. + +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 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, +L, +L + +=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/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). 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 +B. 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, L, -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 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 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 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, L, +L, L, -L +L, +L, +L =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 + + 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 to B. The timeout value B must be given in seconds. + +SSL_CTX_get_timeout() returns the currently set timeout value for B. + +=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 family of functions. + +Expired sessions are removed from the internal session cache, whenever +L is called, either +directly by the application or automatically (see +L) + +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, +L, +L, +L + +=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, L =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 + + 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 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 with +the chosen value B. + +SSL_SESSION_get_timeout() returns the timeout value set for session B +in seconds. + +SSL_SESSION_set_timeout() sets the timeout value for session B in seconds +to B. + +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. +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, +0 is returned. + +=head1 SEE ALSO + +L, +L + +=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, L, L, L, L, +L, +L, L, L, L L, +L, L, L, L, L, L, L, +L, L, L, L, @@ -682,6 +686,7 @@ L, L, L, L, L, +L, L =head1 HISTORY -- 2.25.1