NetBSD/lib/libcrypto/man/SSL_CTX_set_session_cache_mode.3

.\"	$NetBSD: SSL_CTX_set_session_cache_mode.3,v 1.2 2002/02/07 07:00:41 ross Exp $
.\"
.\" Automatically generated by Pod::Man version 1.02
.\" Thu Apr 12 19:27:22 2001
.\"
.\" Standard preamble:
.\" ======================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R

.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
.\" to do unbreakable dashes and therefore won't be available.  \*(C` and
.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` `
.    ds C' '
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
.\" index entries marked with X<> in POD.  Of course, you'll have to process
.\" the output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
.    .
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it
.\" makes way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.bd B 3
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ======================================================================
.\"
.IX Title "SSL_CTX_set_session_cache_mode 3"
.TH SSL_CTX_set_session_cache_mode 3 "0.9.6a" "2001-04-12" "OpenSSL"
.UC
.SH "NAME"
SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode \- enable/disable session caching
.SH "LIBRARY"
libcrypto, -lcrypto
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include \*[Lt]openssl/ssl.h\*[Gt]
.Ve
.Vb 2
\& long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode);
\& long SSL_CTX_get_session_cache_mode(SSL_CTX ctx);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fISSL_CTX_set_session_cache_mode()\fR enables/disables session caching
by setting the operational mode for \fBctx\fR to \*[Lt]mode\*[Gt].
.PP
\&\fISSL_CTX_get_session_cache_mode()\fR returns the currently used cache mode.
.SH "NOTES"
.IX Header "NOTES"
The OpenSSL library can store/retrieve \s-1SSL/TLS\s0 sessions for later reuse.
The sessions can be held in memory for each \fBctx\fR, if more than one
\&\s-1SSL_CTX\s0 object is being maintained, the sessions are unique for each \s-1SSL_CTX\s0
object.
.PP
In order to reuse a session, a client must send the session's id to the
server. It can only send exactly one id.  The server then decides whether it
agrees in reusing the session or starts the handshake for a new session.
.PP
A server will lookup up the session in its internal session storage. If
the session is not found in internal storage or internal storage is
deactivated, the server will try the external storage if available.
.PP
Since a client may try to reuse a session intended for use in a different
context, the session id context must be set by the server (see
SSL_CTX_set_session_id_context(3)).
.PP
The following session cache modes and modifiers are available:
.Ip "\s-1SSL_SESS_CACHE_OFF\s0" 4
.IX Item "SSL_SESS_CACHE_OFF"
No session caching for client or server takes place.
.Ip "\s-1SSL_SESS_CACHE_CLIENT\s0" 4
.IX Item "SSL_SESS_CACHE_CLIENT"
Client sessions are added to the session cache. As there is no reliable way
for the OpenSSL library to know whether a session should be reused or which
session to choose (due to the abstract \s-1BIO\s0 layer the \s-1SSL\s0 engine does not
have details about the connection), the application must select the session
to be reused by using the SSL_set_session(3)
function. This option is not activated by default.
.Ip "\s-1SSL_SESS_CACHE_SERVER\s0" 4
.IX Item "SSL_SESS_CACHE_SERVER"
Server sessions are added to the session cache. When a client proposes a
session to be reused, the session is looked up in the internal session cache.
If the session is found, the server will try to reuse the session.
This is the default.
.Ip "\s-1SSL_SESS_CACHE_BOTH\s0" 4
.IX Item "SSL_SESS_CACHE_BOTH"
Enable both \s-1SSL_SESS_CACHE_CLIENT\s0 and \s-1SSL_SESS_CACHE_SERVER\s0 at the same time.
.Ip "\s-1SSL_SESS_CACHE_NO_AUTO_CLEAR\s0" 4
.IX 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(3) function. Since
this may lead to a delay which cannot be controlled, the automatic
flushing may be disabled and
SSL_CTX_flush_sessions(3) can be called
explicitly by the application.
.Ip "\s-1SSL_SESS_CACHE_NO_INTERNAL_LOOKUP\s0" 4
.IX Item "SSL_SESS_CACHE_NO_INTERNAL_LOOKUP"
By setting this flag sessions are cached in the internal storage but
they are not looked up automatically. If an external session cache
is enabled, sessions are looked up in the external cache. As automatic
lookup only applies for \s-1SSL/TLS\s0 servers, the flag has no effect on
clients.
.PP
The default mode is \s-1SSL_SESS_CACHE_SERVER\s0.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fISSL_CTX_set_session_cache_mode()\fR returns the previously set cache mode.
.PP
\&\fISSL_CTX_get_session_cache_mode()\fR returns the currently set cache mode.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
ssl(3), SSL_set_session(3),
SSL_CTX_sess_number(3),
SSL_CTX_sess_set_cache_size(3),
SSL_CTX_sess_set_get_cb(3),
SSL_CTX_set_session_id_context(3),
SSL_CTX_set_timeout.pod(3),
SSL_CTX_flush_sessions(3)