secure/lib/libssl/man/SSL_CTX_set_session_id_context.3

   1 .\" Automatically generated by Pod::Man version 1.15
   2 .\" Wed Feb 19 16:47:42 2003
   3 .\"
   4 .\" Standard preamble:
   5 .\" ======================================================================
   6 .de Sh \" Subsection heading
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp \" Vertical space (when we can't use .PP)
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip \" List item
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb \" Begin verbatim text
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve \" End verbatim text
  30 .ft R
  31
  32 .fi
  33 ..
  34 .\" Set up some character translations and predefined strings.  \*(-- will
  35 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  36 .\" double quote, and \*(R" will give a right double quote.  | will give a
  37 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
  38 .\" to do unbreakable dashes and therefore won't be available.  \*(C` and
  39 .\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
  40 .tr \(*W-|\(bv\*(Tr
  41 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  42 .ie n \{\
  43 .    ds -- \(*W-
  44 .    ds PI pi
  45 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  46 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  47 .    ds L" ""
  48 .    ds R" ""
  49 .    ds C` ""
  50 .    ds C' ""
  51 'br\}
  52 .el\{\
  53 .    ds -- \|\(em\|
  54 .    ds PI \(*p
  55 .    ds L" ``
  56 .    ds R" ''
  57 'br\}
  58 .\"
  59 .\" If the F register is turned on, we'll generate index entries on stderr
  60 .\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
  61 .\" index entries marked with X<> in POD.  Of course, you'll have to process
  62 .\" the output yourself in some meaningful fashion.
  63 .if \nF \{\
  64 .    de IX
  65 .    tm Index:\\$1\t\\n%\t"\\$2"
  66 ..
  67 .    nr % 0
  68 .    rr F
  69 .\}
  70 .\"
  71 .\" For nroff, turn off justification.  Always turn off hyphenation; it
  72 .\" makes way too many mistakes in technical documents.
  73 .hy 0
  74 .if n .na
  75 .\"
  76 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  77 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  78 .bd B 3
  79 .    \" fudge factors for nroff and troff
  80 .if n \{\
  81 .    ds #H 0
  82 .    ds #V .8m
  83 .    ds #F .3m
  84 .    ds #[ \f1
  85 .    ds #] \fP
  86 .\}
  87 .if t \{\
  88 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  89 .    ds #V .6m
  90 .    ds #F 0
  91 .    ds #[ \&
  92 .    ds #] \&
  93 .\}
  94 .    \" simple accents for nroff and troff
  95 .if n \{\
  96 .    ds ' \&
  97 .    ds ` \&
  98 .    ds ^ \&
  99 .    ds , \&
 100 .    ds ~ ~
 101 .    ds /
 102 .\}
 103 .if t \{\
 104 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 105 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 106 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 107 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 108 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 109 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 110 .\}
 111 .    \" troff and (daisy-wheel) nroff accents
 112 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 113 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 114 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 115 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 116 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 117 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 118 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 119 .ds ae a\h'-(\w'a'u*4/10)'e
 120 .ds Ae A\h'-(\w'A'u*4/10)'E
 121 .    \" corrections for vroff
 122 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 123 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 124 .    \" for low resolution devices (crt and lpr)
 125 .if \n(.H>23 .if \n(.V>19 \
 126 \{\
 127 .    ds : e
 128 .    ds 8 ss
 129 .    ds o a
 130 .    ds d- d\h'-1'\(ga
 131 .    ds D- D\h'-1'\(hy
 132 .    ds th \o'bp'
 133 .    ds Th \o'LP'
 134 .    ds ae ae
 135 .    ds Ae AE
 136 .\}
 137 .rm #[ #] #H #V #F C
 138 .\" ======================================================================
 139 .\"
 140 .IX Title "SSL_CTX_set_session_id_context 3"
 141 .TH SSL_CTX_set_session_id_context 3 "0.9.7a" "2003-02-19" "OpenSSL"
 142 .UC
 143 .SH "NAME"
 144 SSL_CTX_set_session_id_context, SSL_set_session_id_context \- set context within which session can be reused (server side only)
 145 .SH "SYNOPSIS"
 146 .IX Header "SYNOPSIS"
 147 .Vb 1
 148 \& #include <openssl/ssl.h>
 149 .Ve
 150 .Vb 4
 151 \& int SSL_CTX_set_session_id_context(SSL_CTX *ctx, const unsigned char *sid_ctx,
 152 \&                                    unsigned int sid_ctx_len);
 153 \& int SSL_set_session_id_context(SSL *ssl, const unsigned char *sid_ctx,
 154 \&                                unsigned int sid_ctx_len);
 155 .Ve
 156 .SH "DESCRIPTION"
 157 .IX Header "DESCRIPTION"
 158 \&\fISSL_CTX_set_session_id_context()\fR sets the context \fBsid_ctx\fR of length
 159 \&\fBsid_ctx_len\fR within which a session can be reused for the \fBctx\fR object.
 160 .PP
 161 \&\fISSL_set_session_id_context()\fR sets the context \fBsid_ctx\fR of length
 162 \&\fBsid_ctx_len\fR within which a session can be reused for the \fBssl\fR object.
 163 .SH "NOTES"
 164 .IX Header "NOTES"
 165 Sessions are generated within a certain context. When exporting/importing
 166 sessions with \fBi2d_SSL_SESSION\fR/\fBd2i_SSL_SESSION\fR it would be possible,
 167 to re-import a session generated from another context (e.g. another
 168 application), which might lead to malfunctions. Therefore each application
 169 must set its own session id context \fBsid_ctx\fR which is used to distinguish
 170 the contexts and is stored in exported sessions. The \fBsid_ctx\fR can be
 171 any kind of binary data with a given length, it is therefore possible
 172 to use e.g. the name of the application and/or the hostname and/or service
 173 name ...
 174 .PP
 175 The session id context becomes part of the session. The session id context
 176 is set by the \s-1SSL/TLS\s0 server. The \fISSL_CTX_set_session_id_context()\fR and
 177 \&\fISSL_set_session_id_context()\fR functions are therefore only useful on the
 178 server side.
 179 .PP
 180 OpenSSL clients will check the session id context returned by the server
 181 when reusing a session.
 182 .PP
 183 The maximum length of the \fBsid_ctx\fR is limited to
 184 \&\fB\s-1SSL_MAX_SSL_SESSION_ID_LENGTH\s0\fR.
 185 .SH "WARNINGS"
 186 .IX Header "WARNINGS"
 187 If the session id context is not set on an \s-1SSL/TLS\s0 server, stored sessions
 188 will not be reused but a fatal error will be flagged and the handshake
 189 will fail.
 190 .PP
 191 If a server returns a different session id context to an OpenSSL client
 192 when reusing a session, an error will be flagged and the handshake will
 193 fail. OpenSSL servers will always return the correct session id context,
 194 as an OpenSSL server checks the session id context itself before reusing
 195 a session as described above.
 196 .SH "RETURN VALUES"
 197 .IX Header "RETURN VALUES"
 198 \&\fISSL_CTX_set_session_id_context()\fR and \fISSL_set_session_id_context()\fR
 199 return the following values:
 200 .Ip "0" 4
 201 The length \fBsid_ctx_len\fR of the session id context \fBsid_ctx\fR exceeded
 202 the maximum allowed length of \fB\s-1SSL_MAX_SSL_SESSION_ID_LENGTH\s0\fR. The error
 203 is logged to the error stack.
 204 .Ip "1" 4
 205 .IX Item "1"
 206 The operation succeeded.
 207 .SH "SEE ALSO"
 208 .IX Header "SEE ALSO"
 209 ssl(3)