1 files changed, 156 insertions, 0 deletions

diff --git a/src/lib/libssl/doc/SSL_CTX_sess_set_get_cb.3 b/src/lib/libssl/doc/SSL_CTX_sess_set_get_cb.3
new file mode 100644
index 0000000000..d5c506cec8
--- /dev/null
+++ b/src/lib/libssl/doc/SSL_CTX_sess_set_get_cb.3
@@ -0,0 +1,156 @@
+.Dd $Mdocdate: October 12 2014 $
+.Dt SSL_CTX_SESS_SET_GET_CB 3
+.Os
+.Sh NAME
+.Nm SSL_CTX_sess_set_new_cb ,
+.Nm SSL_CTX_sess_set_remove_cb ,
+.Nm SSL_CTX_sess_set_get_cb ,
+.Nm SSL_CTX_sess_get_new_cb ,
+.Nm SSL_CTX_sess_get_remove_cb ,
+.Nm SSL_CTX_sess_get_get_cb
+.Nd provide callback functions for server side external session caching
+.Sh SYNOPSIS
+.In openssl/ssl.h
+.Ft void
+.Fo SSL_CTX_sess_set_new_cb
+.Fa "SSL_CTX *ctx"
+.Fa "int (*new_session_cb)(SSL *, SSL_SESSION *)"
+.Fc
+.Ft void
+.Fo SSL_CTX_sess_set_remove_cb
+.Fa "SSL_CTX *ctx"
+.Fa "void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *)"
+.Fc
+.Ft void
+.Fo SSL_CTX_sess_set_get_cb
+.Fa "SSL_CTX *ctx"
+.Fa "SSL_SESSION (*get_session_cb)(SSL *, unsigned char *, int, int *)"
+.Fc
+.Ft int
+.Fo "(*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))"
+.Fa "struct ssl_st *ssl"
+.Fa "SSL_SESSION *sess"
+.Fc
+.Ft void
+.Fo "(*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))"
+.Fa "struct ssl_ctx_st *ctx"
+.Fa "SSL_SESSION *sess"
+.Fc
+.Ft SSL_SESSION *
+.Fo "(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))"
+.Fa "struct ssl_st *ssl"
+.Fa "unsigned char *data"
+.Fa "int len"
+.Fa "int *copy"
+.Fc
+.Ft int
+.Fo "(*new_session_cb)"
+.Fa "struct ssl_st *ssl"
+.Fa "SSL_SESSION *sess"
+.Fc
+.Ft void
+.Fo "(*remove_session_cb)"
+.Fa "struct ssl_ctx_st *ctx"
+.Fa "SSL_SESSION *sess"
+.Fc
+.Ft SSL_SESSION *
+.Fo "(*get_session_cb)"
+.Fa "struct ssl_st *ssl"
+.Fa "unsigned char *data"
+.Fa "int len"
+.Fa "int *copy"
+.Fc
+.Sh DESCRIPTION
+.Fn SSL_CTX_sess_set_new_cb
+sets the callback function which is automatically called whenever a new session
+was negotiated.
+.Pp
+.Fn SSL_CTX_sess_set_remove_cb
+sets the callback function which is automatically called whenever a session is
+removed by the SSL engine (because it is considered faulty or the session has
+become obsolete because of exceeding the timeout value).
+.Pp
+.Fn SSL_CTX_sess_set_get_cb
+sets the callback function which is called whenever a SSL/TLS client proposes
+to resume a session but the session cannot be found in the internal session
+cache (see
+.Xr SSL_CTX_set_session_cache_mode 3 ) .
+(SSL/TLS server only.)
+.Pp
+.Fn SSL_CTX_sess_get_new_cb ,
+.Fn SSL_CTX_sess_get_remove_cb ,
+and
+.Fn SSL_CTX_sess_get_get_cb
+retrieve the function pointers of the provided callback functions.
+If a callback function has not been set, the
+.Dv NULL
+pointer is returned.
+.Sh NOTES
+In order to allow external session caching, synchronization with the internal
+session cache is realized via callback functions.
+Inside these callback functions, session can be saved to disk or put into a
+database using the
+.Xr d2i_SSL_SESSION 3
+interface.
+.Pp
+The
+.Fn new_session_cb
+function is called whenever a new session has been negotiated and session
+caching is enabled (see
+.Xr SSL_CTX_set_session_cache_mode 3 ) .
+The
+.Fn new_session_cb
+is passed the
+.Fa ssl
+connection and the ssl session
+.Fa sess .
+If the callback returns 0, the session will be immediately removed again.
+.Pp
+The
+.Fn remove_session_cb
+is called whenever the SSL engine removes a session from the internal cache.
+This happens when the session is removed because it is expired or when a
+connection was not shut down cleanly.
+It also happens for all sessions in the internal session cache when
+.Xr SSL_CTX_free 3
+is called.
+The
+.Fn remove_session_cb
+function is passed the
+.Fa ctx
+and the
+.Vt ssl
+session
+.Fa sess .
+It does not provide any feedback.
+.Pp
+The
+.Fn get_session_cb
+function is only called on SSL/TLS servers with the session id proposed by the
+client.
+The
+.Fn get_session_cb
+function is always called, also when session caching was disabled.
+The
+.Fn get_session_cb
+is passed the
+.Fa ssl
+connection, the session id of length
+.Fa length
+at the memory location
+.Fa data .
+With the parameter
+.Fa copy
+the callback can require the SSL engine to increment the reference count of the
+.Vt SSL_SESSION
+object,
+Normally the reference count is not incremented and therefore the session must
+not be explicitly freed with
+.Xr SSL_SESSION_free 3 .
+.Sh SEE ALSO
+.Xr d2i_SSL_SESSION 3 ,
+.Xr ssl 3 ,
+.Xr SSL_CTX_flush_sessions 3 ,
+.Xr SSL_CTX_free 3 ,
+.Xr SSL_CTX_set_session_cache_mode 3 ,
+.Xr SSL_SESSION_free 3