diff options
author | Lutz Jänicke <jaenicke@openssl.org> | 2001-02-02 14:40:52 +0000 |
---|---|---|
committer | Lutz Jänicke <jaenicke@openssl.org> | 2001-02-02 14:40:52 +0000 |
commit | 8cbceba6106feb1110e7df6fbce9ab7ed2503b60 (patch) | |
tree | 554fbe87ef4b771b1f761b6df3aa2209066fca65 /doc/ssl/SSL_CTX_sess_set_get_cb.pod | |
parent | 88ce56f8c19afca84548ce85bbc9b5dda3c724f9 (diff) | |
download | openssl-8cbceba6106feb1110e7df6fbce9ab7ed2503b60.tar.gz |
Document session caching, first step.
Diffstat (limited to 'doc/ssl/SSL_CTX_sess_set_get_cb.pod')
-rw-r--r-- | doc/ssl/SSL_CTX_sess_set_get_cb.pod | 80 |
1 files changed, 80 insertions, 0 deletions
diff --git a/doc/ssl/SSL_CTX_sess_set_get_cb.pod b/doc/ssl/SSL_CTX_sess_set_get_cb.pod new file mode 100644 index 0000000000..4f3c93a859 --- /dev/null +++ b/doc/ssl/SSL_CTX_sess_set_get_cb.pod @@ -0,0 +1,80 @@ +=pod + +=head1 NAME + +SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb - provide callback functions for server side external session caching + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx, + int (*new_session_cb)(SSL *, SSL_SESSION *)); + 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 *)); + + 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_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, unsigned char *data, int len, int *copy); + + int (*new_session_cb)(struct ssl_st *ssl, SSL_SESSION *sess); + void (*remove_session_cb)(struct ssl_ctx_st *ctx, SSL_SESSION *sess); + SSL_SESSION *(*get_session_cb)(struct ssl_st *ssl, unsigned char *data, + int len, int *copy); + +=head1 DESCRIPTION + +SSL_CTX_sess_set_new_cb() sets the callback function, which is automatically +called whenever a new session was negotiated. + +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. + +SSL_CTX_sess_set_get_cb() sets the callback function which is called, +whenever a SSL/TLS client proposed to resume a session but the session +could not be found in the internal session cache (see +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 +provided callback functions. If a callback function has not been set, +the NULL pointer is returned. + +=head1 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 +L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)> interface. + +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 +removed again. + +The remove_session_cb() is called, whenever the SSL engine removes a session +from the internal cache. This happens if the session is removed because +it is expired or when a connection was not shutdown cleanly. The +remove_session_cb() is passed the B<ctx> and the ssl session B<sess>. +It does not provide any feedback. + +The get_session_cb() is only called on SSL/TLS servers with the session id +proposed by the client. The get_session_cb() is always called, also when +session caching was disabled. The get_session_cb() is passed the +B<ssl> connection, the session id of length B<length> at the memory location +B<data>. With the parameter B<copy> the callback can require the +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)> + +=cut |