secure/lib/libcrypto/man/man3/SSL_CTX_set_session_ticket_cb.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SSL_CTX_SET_SESSION_TICKET_CB 3"
 136 .TH SSL_CTX_SET_SESSION_TICKET_CB 3 "2022-05-03" "1.1.1o" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 SSL_CTX_set_session_ticket_cb, SSL_SESSION_get0_ticket_appdata, SSL_SESSION_set1_ticket_appdata, SSL_CTX_generate_session_ticket_fn, SSL_CTX_decrypt_session_ticket_fn \- manage session ticket application data
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& typedef int (*SSL_CTX_generate_session_ticket_fn)(SSL *s, void *arg);
 149 \& typedef SSL_TICKET_RETURN (*SSL_CTX_decrypt_session_ticket_fn)(SSL *s, SSL_SESSION *ss,
 150 \&                                                                const unsigned char *keyname,
 151 \&                                                                size_t keyname_len,
 152 \&                                                                SSL_TICKET_STATUS status,
 153 \&                                                                void *arg);
 154 \& int SSL_CTX_set_session_ticket_cb(SSL_CTX *ctx,
 155 \&                                   SSL_CTX_generate_session_ticket_fn gen_cb,
 156 \&                                   SSL_CTX_decrypt_session_ticket_fn dec_cb,
 157 \&                                   void *arg);
 158 \& int SSL_SESSION_set1_ticket_appdata(SSL_SESSION *ss, const void *data, size_t len);
 159 \& int SSL_SESSION_get0_ticket_appdata(SSL_SESSION *ss, void **data, size_t *len);
 160 .Ve
 161 .SH "DESCRIPTION"
 162 .IX Header "DESCRIPTION"
 163 \&\fBSSL_CTX_set_set_session_ticket_cb()\fR sets the application callbacks \fBgen_cb\fR
 164 and \fBdec_cb\fR that are used by a server to set and get application data stored
 165 with a session, and placed into a session ticket. Either callback function may
 166 be set to \s-1NULL.\s0 The value of \fBarg\fR is passed to the callbacks.
 167 .PP
 168 \&\fBgen_cb\fR is the application defined callback invoked when a session ticket is
 169 about to be created. The application can call \fBSSL_SESSION_set1_ticket_appdata()\fR
 170 at this time to add application data to the session ticket. The value of \fBarg\fR
 171 is the same as that given to \fBSSL_CTX_set_session_ticket_cb()\fR. The \fBgen_cb\fR
 172 callback is defined as type \fBSSL_CTX_generate_session_ticket_fn\fR.
 173 .PP
 174 \&\fBdec_cb\fR is the application defined callback invoked after session ticket
 175 decryption has been attempted and any session ticket application data is
 176 available. If ticket decryption was successful then the \fBss\fR argument contains
 177 the session data. The \fBkeyname\fR and \fBkeyname_len\fR arguments identify the key
 178 used to decrypt the session ticket. The \fBstatus\fR argument is the result of the
 179 ticket decryption. See the \s-1NOTES\s0 section below for further details. The value
 180 of \fBarg\fR is the same as that given to \fBSSL_CTX_set_session_ticket_cb()\fR. The
 181 \&\fBdec_cb\fR callback is defined as type \fBSSL_CTX_decrypt_session_ticket_fn\fR.
 182 .PP
 183 \&\fBSSL_SESSION_set1_ticket_appdata()\fR sets the application data specified by
 184 \&\fBdata\fR and \fBlen\fR into \fBss\fR which is then placed into any generated session
 185 tickets. It can be called at any time before a session ticket is created to
 186 update the data placed into the session ticket. However, given that sessions
 187 and tickets are created by the handshake, the \fBgen_cb\fR is provided to notify
 188 the application that a session ticket is about to be generated.
 189 .PP
 190 \&\fBSSL_SESSION_get0_ticket_appdata()\fR assigns \fBdata\fR to the session ticket
 191 application data and assigns \fBlen\fR to the length of the session ticket
 192 application data from \fBss\fR. The application data can be set via
 193 \&\fBSSL_SESSION_set1_ticket_appdata()\fR or by a session ticket. \s-1NULL\s0 will be assigned
 194 to \fBdata\fR and 0 will be assigned to \fBlen\fR if there is no session ticket
 195 application data. \fBSSL_SESSION_get0_ticket_appdata()\fR can be called any time
 196 after a session has been created. The \fBdec_cb\fR is provided to notify the
 197 application that a session ticket has just been decrypted.
 198 .SH "NOTES"
 199 .IX Header "NOTES"
 200 When the \fBdec_cb\fR callback is invoked, the \s-1SSL_SESSION\s0 \fBss\fR has not yet been
 201 assigned to the \s-1SSL\s0 \fBs\fR. The \fBstatus\fR indicates the result of the ticket
 202 decryption. The callback must check the \fBstatus\fR value before performing any
 203 action, as it is called even if ticket decryption fails.
 204 .PP
 205 The \fBkeyname\fR and \fBkeyname_len\fR arguments to \fBdec_cb\fR may be used to identify
 206 the key that was used to encrypt the session ticket.
 207 .PP
 208 The \fBstatus\fR argument can be any of these values:
 209 .IP "\s-1SSL_TICKET_EMPTY\s0" 4
 210 .IX Item "SSL_TICKET_EMPTY"
 211 Empty ticket present. No ticket data will be used and a new ticket should be
 212 sent to the client. This only occurs in TLSv1.2 or below. In TLSv1.3 it is not
 213 valid for a client to send an empty ticket.
 214 .IP "\s-1SSL_TICKET_NO_DECRYPT\s0" 4
 215 .IX Item "SSL_TICKET_NO_DECRYPT"
 216 The ticket couldn't be decrypted. No ticket data will be used and a new ticket
 217 should be sent to the client.
 218 .IP "\s-1SSL_TICKET_SUCCESS\s0" 4
 219 .IX Item "SSL_TICKET_SUCCESS"
 220 A ticket was successfully decrypted, any session ticket application data should
 221 be available. A new ticket should not be sent to the client.
 222 .IP "\s-1SSL_TICKET_SUCCESS_RENEW\s0" 4
 223 .IX Item "SSL_TICKET_SUCCESS_RENEW"
 224 Same as \fB\s-1SSL_TICKET_SUCCESS\s0\fR, but a new ticket should be sent to the client.
 225 .PP
 226 The return value can be any of these values:
 227 .IP "\s-1SSL_TICKET_RETURN_ABORT\s0" 4
 228 .IX Item "SSL_TICKET_RETURN_ABORT"
 229 The handshake should be aborted, either because of an error or because of some
 230 policy. Note that in TLSv1.3 a client may send more than one ticket in a single
 231 handshake. Therefore, just because one ticket is unacceptable it does not mean
 232 that all of them are. For this reason this option should be used with caution.
 233 .IP "\s-1SSL_TICKET_RETURN_IGNORE\s0" 4
 234 .IX Item "SSL_TICKET_RETURN_IGNORE"
 235 Do not use a ticket (if one was available). Do not send a renewed ticket to the
 236 client.
 237 .IP "\s-1SSL_TICKET_RETURN_IGNORE_RENEW\s0" 4
 238 .IX Item "SSL_TICKET_RETURN_IGNORE_RENEW"
 239 Do not use a ticket (if one was available). Send a renewed ticket to the client.
 240 .Sp
 241 If the callback does not wish to change the default ticket behaviour then it
 242 should return this value if \fBstatus\fR is \fB\s-1SSL_TICKET_EMPTY\s0\fR or
 243 \&\fB\s-1SSL_TICKET_NO_DECRYPT\s0\fR.
 244 .IP "\s-1SSL_TICKET_RETURN_USE\s0" 4
 245 .IX Item "SSL_TICKET_RETURN_USE"
 246 Use the ticket. Do not send a renewed ticket to the client. It is an error for
 247 the callback to return this value if \fBstatus\fR has a value other than
 248 \&\fB\s-1SSL_TICKET_SUCCESS\s0\fR or \fB\s-1SSL_TICKET_SUCCESS_RENEW\s0\fR.
 249 .Sp
 250 If the callback does not wish to change the default ticket behaviour then it
 251 should return this value if \fBstatus\fR is \fB\s-1SSL_TICKET_SUCCESS\s0\fR.
 252 .IP "\s-1SSL_TICKET_RETURN_USE_RENEW\s0" 4
 253 .IX Item "SSL_TICKET_RETURN_USE_RENEW"
 254 Use the ticket. Send a renewed ticket to the client. It is an error for the
 255 callback to return this value if \fBstatus\fR has a value other than
 256 \&\fB\s-1SSL_TICKET_SUCCESS\s0\fR or \fB\s-1SSL_TICKET_SUCCESS_RENEW\s0\fR.
 257 .Sp
 258 If the callback does not wish to change the default ticket behaviour then it
 259 should return this value if \fBstatus\fR is \fB\s-1SSL_TICKET_SUCCESS_RENEW\s0\fR.
 260 .PP
 261 If \fBstatus\fR has the value \fB\s-1SSL_TICKET_EMPTY\s0\fR or \fB\s-1SSL_TICKET_NO_DECRYPT\s0\fR then
 262 no session data will be available and the callback must not use the \fBss\fR
 263 argument. If \fBstatus\fR has the value \fB\s-1SSL_TICKET_SUCCESS\s0\fR or
 264 \&\fB\s-1SSL_TICKET_SUCCESS_RENEW\s0\fR then the application can call
 265 \&\fBSSL_SESSION_get0_ticket_appdata()\fR using the session provided in the \fBss\fR
 266 argument to retrieve the application data.
 267 .PP
 268 When the \fBgen_cb\fR callback is invoked, the \fBSSL_get_session()\fR function can be
 269 used to retrieve the \s-1SSL_SESSION\s0 for \fBSSL_SESSION_set1_ticket_appdata()\fR.
 270 .PP
 271 By default, in TLSv1.2 and below, a new session ticket is not issued on a
 272 successful resumption and therefore \fBgen_cb\fR will not be called. In TLSv1.3 the
 273 default behaviour is to always issue a new ticket on resumption. In both cases
 274 this behaviour can be changed if a ticket key callback is in use (see
 275 \&\fBSSL_CTX_set_tlsext_ticket_key_cb\fR\|(3)).
 276 .SH "RETURN VALUES"
 277 .IX Header "RETURN VALUES"
 278 The \fBSSL_CTX_set_session_ticket_cb()\fR, \fBSSL_SESSION_set1_ticket_appdata()\fR and
 279 \&\fBSSL_SESSION_get0_ticket_appdata()\fR functions return 1 on success and 0 on
 280 failure.
 281 .PP
 282 The \fBgen_cb\fR callback must return 1 to continue the connection. A return of 0
 283 will terminate the connection with an \s-1INTERNAL_ERROR\s0 alert.
 284 .PP
 285 The \fBdec_cb\fR callback must return a value as described in \s-1NOTES\s0 above.
 286 .SH "SEE ALSO"
 287 .IX Header "SEE ALSO"
 288 \&\fBssl\fR\|(7),
 289 \&\fBSSL_get_session\fR\|(3)
 290 .SH "HISTORY"
 291 .IX Header "HISTORY"
 292 The \fBSSL_CTX_set_session_ticket_cb()\fR, \fBSSL_SESSION_set1_ticket_appdata()\fR
 293 and \fBSSL_SESSION_get_ticket_appdata()\fR functions were added in OpenSSL 1.1.1.
 294 .SH "COPYRIGHT"
 295 .IX Header "COPYRIGHT"
 296 Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved.
 297 .PP
 298 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 299 this file except in compliance with the License.  You can obtain a copy
 300 in the file \s-1LICENSE\s0 in the source distribution or at
 301 <https://www.openssl.org/source/license.html>.