Documenting session caching, 2nd step.

=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

 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);

(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.

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

=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

=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

=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

=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