|
Packit |
c4476c |
=pod
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 NAME
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable session caching
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SYNOPSIS
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
#include <openssl/ssl.h>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode);
|
|
Packit |
c4476c |
long SSL_CTX_get_session_cache_mode(SSL_CTX ctx);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 DESCRIPTION
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_CTX_set_session_cache_mode() enables/disables session caching
|
|
Packit |
c4476c |
by setting the operational mode for B<ctx> to <mode>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_CTX_get_session_cache_mode() returns the currently used cache mode.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 NOTES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse.
|
|
Packit |
c4476c |
The sessions can be held in memory for each B<ctx>, if more than one
|
|
Packit |
c4476c |
SSL_CTX object is being maintained, the sessions are unique for each SSL_CTX
|
|
Packit |
c4476c |
object.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
In order to reuse a session, a client must send the session's id to the
|
|
Packit |
c4476c |
server. It can only send exactly one id. The server then either
|
|
Packit |
c4476c |
agrees to reuse the session or it starts a full handshake (to create a new
|
|
Packit |
c4476c |
session).
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
A server will look up the session in its internal session storage. If the
|
|
Packit |
c4476c |
session is not found in internal storage or lookups for the internal storage
|
|
Packit |
c4476c |
have been deactivated (SSL_SESS_CACHE_NO_INTERNAL_LOOKUP), the server will try
|
|
Packit |
c4476c |
the external storage if available.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Since a client may try to reuse a session intended for use in a different
|
|
Packit |
c4476c |
context, the session id context must be set by the server (see
|
|
Packit |
c4476c |
L<SSL_CTX_set_session_id_context(3)>).
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The following session cache modes and modifiers are available:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=over 4
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item SSL_SESS_CACHE_OFF
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
No session caching for client or server takes place.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item SSL_SESS_CACHE_CLIENT
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Client sessions are added to the session cache. As there is no reliable way
|
|
Packit |
c4476c |
for the OpenSSL library to know whether a session should be reused or which
|
|
Packit |
c4476c |
session to choose (due to the abstract BIO layer the SSL engine does not
|
|
Packit |
c4476c |
have details about the connection), the application must select the session
|
|
Packit |
c4476c |
to be reused by using the L<SSL_set_session(3)>
|
|
Packit |
c4476c |
function. This option is not activated by default.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item SSL_SESS_CACHE_SERVER
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Server sessions are added to the session cache. When a client proposes a
|
|
Packit |
c4476c |
session to be reused, the server looks for the corresponding session in (first)
|
|
Packit |
c4476c |
the internal session cache (unless SSL_SESS_CACHE_NO_INTERNAL_LOOKUP is set),
|
|
Packit |
c4476c |
then (second) in the external cache if available. If the session is found, the
|
|
Packit |
c4476c |
server will try to reuse the session. This is the default.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item SSL_SESS_CACHE_BOTH
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Enable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item SSL_SESS_CACHE_NO_AUTO_CLEAR
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Normally the session cache is checked for expired sessions every
|
|
Packit |
c4476c |
255 connections using the
|
|
Packit |
c4476c |
L<SSL_CTX_flush_sessions(3)> function. Since
|
|
Packit |
c4476c |
this may lead to a delay which cannot be controlled, the automatic
|
|
Packit |
c4476c |
flushing may be disabled and
|
|
Packit |
c4476c |
L<SSL_CTX_flush_sessions(3)> can be called
|
|
Packit |
c4476c |
explicitly by the application.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
By setting this flag, session-resume operations in an SSL/TLS server will not
|
|
Packit |
c4476c |
automatically look up sessions in the internal cache, even if sessions are
|
|
Packit |
c4476c |
automatically stored there. If external session caching callbacks are in use,
|
|
Packit |
c4476c |
this flag guarantees that all lookups are directed to the external cache.
|
|
Packit |
c4476c |
As automatic lookup only applies for SSL/TLS servers, the flag has no effect on
|
|
Packit |
c4476c |
clients.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item SSL_SESS_CACHE_NO_INTERNAL_STORE
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Depending on the presence of SSL_SESS_CACHE_CLIENT and/or SSL_SESS_CACHE_SERVER,
|
|
Packit |
c4476c |
sessions negotiated in an SSL/TLS handshake may be cached for possible reuse.
|
|
Packit |
c4476c |
Normally a new session is added to the internal cache as well as any external
|
|
Packit |
c4476c |
session caching (callback) that is configured for the SSL_CTX. This flag will
|
|
Packit |
c4476c |
prevent sessions being stored in the internal cache (though the application can
|
|
Packit |
c4476c |
add them manually using L<SSL_CTX_add_session(3)>). Note:
|
|
Packit |
c4476c |
in any SSL/TLS servers where external caching is configured, any successful
|
|
Packit |
c4476c |
session lookups in the external cache (ie. for session-resume requests) would
|
|
Packit |
c4476c |
normally be copied into the local cache before processing continues - this flag
|
|
Packit |
c4476c |
prevents these additions to the internal cache as well.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item SSL_SESS_CACHE_NO_INTERNAL
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Enable both SSL_SESS_CACHE_NO_INTERNAL_LOOKUP and
|
|
Packit |
c4476c |
SSL_SESS_CACHE_NO_INTERNAL_STORE at the same time.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=back
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The default mode is SSL_SESS_CACHE_SERVER.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 RETURN VALUES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_CTX_set_session_cache_mode() returns the previously set cache mode.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_CTX_get_session_cache_mode() returns the currently set cache mode.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SEE ALSO
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
L<ssl(7)>, L<SSL_set_session(3)>,
|
|
Packit |
c4476c |
L<SSL_session_reused(3)>,
|
|
Packit |
c4476c |
L<SSL_CTX_add_session(3)>,
|
|
Packit |
c4476c |
L<SSL_CTX_sess_number(3)>,
|
|
Packit |
c4476c |
L<SSL_CTX_sess_set_cache_size(3)>,
|
|
Packit |
c4476c |
L<SSL_CTX_sess_set_get_cb(3)>,
|
|
Packit |
c4476c |
L<SSL_CTX_set_session_id_context(3)>,
|
|
Packit |
c4476c |
L<SSL_CTX_set_timeout(3)>,
|
|
Packit |
c4476c |
L<SSL_CTX_flush_sessions(3)>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 COPYRIGHT
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Licensed under the OpenSSL license (the "License"). You may not use
|
|
Packit |
c4476c |
this file except in compliance with the License. You can obtain a copy
|
|
Packit |
c4476c |
in the file LICENSE in the source distribution or at
|
|
Packit |
c4476c |
L<https://www.openssl.org/source/license.html>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=cut
|