This commit was manufactured by cvs2svn to create branch

=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

=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

=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

=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

=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