Documenting session caching, 2nd step.

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

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

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

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

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

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

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

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

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