wbrawner/openssl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Documenting session caching, 2nd step.

Browse source
This commit is contained in:
Lutz Jänicke 2001-02-04 18:05:27 +00:00
parent 2b916952a8
commit 0bc6597d4d
9 changed files with 303 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

65
doc/ssl/SSL_CTX_add_session.pod Normal file
View file

@ -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

49
doc/ssl/SSL_CTX_flush_sessions.pod Normal file
View file

@ -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

50
doc/ssl/SSL_CTX_sess_set_cache_size.pod Normal file
View file

@ -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

9
doc/ssl/SSL_CTX_sess_set_get_cb.pod
View file

@ -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

13
doc/ssl/SSL_CTX_set_session_cache_mode.pod
View file

@ -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

55
doc/ssl/SSL_CTX_set_timeout.pod Normal file
View file

@ -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

2
doc/ssl/SSL_SESSION_free.pod
View file

@ -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

63
doc/ssl/SSL_SESSION_get_time.pod Normal file
View file

@ -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

5
doc/ssl/ssl.pod
View file

@ -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