secure/lib/libcrypto/man/SSL_CTX_set_tlsext_ticket_key_cb.3

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.39)
   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_TLSEXT_TICKET_KEY_CB 3"
 136 .TH SSL_CTX_SET_TLSEXT_TICKET_KEY_CB 3 "2019-09-10" "1.1.1d" "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_tlsext_ticket_key_cb \- set a callback for session ticket processing
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/tls1.h>
 147 \&
 148 \& long SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx,
 149 \&     int (*cb)(SSL *s, unsigned char key_name[16],
 150 \&               unsigned char iv[EVP_MAX_IV_LENGTH],
 151 \&               EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc));
 152 .Ve
 153 .SH "DESCRIPTION"
 154 .IX Header "DESCRIPTION"
 155 \&\fBSSL_CTX_set_tlsext_ticket_key_cb()\fR sets a callback function \fIcb\fR for handling
 156 session tickets for the ssl context \fIsslctx\fR. Session tickets, defined in
 157 \&\s-1RFC5077\s0 provide an enhanced session resumption capability where the server
 158 implementation is not required to maintain per session state. It only applies
 159 to \s-1TLS\s0 and there is no SSLv3 implementation.
 160 .PP
 161 The callback function \fIcb\fR will be called for every client instigated \s-1TLS\s0
 162 session when session ticket extension is presented in the \s-1TLS\s0 hello
 163 message. It is the responsibility of this function to create or retrieve the
 164 cryptographic parameters and to maintain their state.
 165 .PP
 166 The OpenSSL library uses your callback function to help implement a common \s-1TLS\s0
 167 ticket construction state according to \s-1RFC5077\s0 Section 4 such that per session
 168 state is unnecessary and a small set of cryptographic variables needs to be
 169 maintained by the callback function implementation.
 170 .PP
 171 In order to reuse a session, a \s-1TLS\s0 client must send the a session ticket
 172 extension to the server. The client can only send exactly one session ticket.
 173 The server, through the callback function, either agrees to reuse the session
 174 ticket information or it starts a full \s-1TLS\s0 handshake to create a new session
 175 ticket.
 176 .PP
 177 Before the callback function is started \fIctx\fR and \fIhctx\fR have been
 178 initialised with \fBEVP_CIPHER_CTX_reset\fR\|(3) and \fBHMAC_CTX_reset\fR\|(3) respectively.
 179 .PP
 180 For new sessions tickets, when the client doesn't present a session ticket, or
 181 an attempted retrieval of the ticket failed, or a renew option was indicated,
 182 the callback function will be called with \fIenc\fR equal to 1. The OpenSSL
 183 library expects that the function will set an arbitrary \fIname\fR, initialize
 184 \&\fIiv\fR, and set the cipher context \fIctx\fR and the hash context \fIhctx\fR.
 185 .PP
 186 The \fIname\fR is 16 characters long and is used as a key identifier.
 187 .PP
 188 The \fIiv\fR length is the length of the \s-1IV\s0 of the corresponding cipher. The
 189 maximum \s-1IV\s0 length is \fB\s-1EVP_MAX_IV_LENGTH\s0\fR bytes defined in \fBevp.h\fR.
 190 .PP
 191 The initialization vector \fIiv\fR should be a random value. The cipher context
 192 \&\fIctx\fR should use the initialisation vector \fIiv\fR. The cipher context can be
 193 set using \fBEVP_EncryptInit_ex\fR\|(3). The hmac context can be set using
 194 \&\fBHMAC_Init_ex\fR\|(3).
 195 .PP
 196 When the client presents a session ticket, the callback function with be called
 197 with \fIenc\fR set to 0 indicating that the \fIcb\fR function should retrieve a set
 198 of parameters. In this case \fIname\fR and \fIiv\fR have already been parsed out of
 199 the session ticket. The OpenSSL library expects that the \fIname\fR will be used
 200 to retrieve a cryptographic parameters and that the cryptographic context
 201 \&\fIctx\fR will be set with the retrieved parameters and the initialization vector
 202 \&\fIiv\fR. using a function like \fBEVP_DecryptInit_ex\fR\|(3). The \fIhctx\fR needs to be
 203 set using \fBHMAC_Init_ex\fR\|(3).
 204 .PP
 205 If the \fIname\fR is still valid but a renewal of the ticket is required the
 206 callback function should return 2. The library will call the callback again
 207 with an argument of enc equal to 1 to set the new ticket.
 208 .PP
 209 The return value of the \fIcb\fR function is used by OpenSSL to determine what
 210 further processing will occur. The following return values have meaning:
 211 .IP "2" 4
 212 .IX Item "2"
 213 This indicates that the \fIctx\fR and \fIhctx\fR have been set and the session can
 214 continue on those parameters. Additionally it indicates that the session
 215 ticket is in a renewal period and should be replaced. The OpenSSL library will
 216 call \fIcb\fR again with an enc argument of 1 to set the new ticket (see \s-1RFC5077
 217 3.3\s0 paragraph 2).
 218 .IP "1" 4
 219 .IX Item "1"
 220 This indicates that the \fIctx\fR and \fIhctx\fR have been set and the session can
 221 continue on those parameters.
 222 .IP "0" 4
 223 This indicates that it was not possible to set/retrieve a session ticket and
 224 the \s-1SSL/TLS\s0 session will continue by negotiating a set of cryptographic
 225 parameters or using the alternate \s-1SSL/TLS\s0 resumption mechanism, session ids.
 226 .Sp
 227 If called with enc equal to 0 the library will call the \fIcb\fR again to get
 228 a new set of parameters.
 229 .IP "less than 0" 4
 230 .IX Item "less than 0"
 231 This indicates an error.
 232 .SH "NOTES"
 233 .IX Header "NOTES"
 234 Session resumption shortcuts the \s-1TLS\s0 so that the client certificate
 235 negotiation don't occur. It makes up for this by storing client certificate
 236 an all other negotiated state information encrypted within the ticket. In a
 237 resumed session the applications will have all this state information available
 238 exactly as if a full negotiation had occurred.
 239 .PP
 240 If an attacker can obtain the key used to encrypt a session ticket, they can
 241 obtain the master secret for any ticket using that key and decrypt any traffic
 242 using that session: even if the cipher suite supports forward secrecy. As
 243 a result applications may wish to use multiple keys and avoid using long term
 244 keys stored in files.
 245 .PP
 246 Applications can use longer keys to maintain a consistent level of security.
 247 For example if a cipher suite uses 256 bit ciphers but only a 128 bit ticket key
 248 the overall security is only 128 bits because breaking the ticket key will
 249 enable an attacker to obtain the session keys.
 250 .SH "RETURN VALUES"
 251 .IX Header "RETURN VALUES"
 252 returns 0 to indicate the callback function was set.
 253 .SH "EXAMPLES"
 254 .IX Header "EXAMPLES"
 255 Reference Implementation:
 256 .PP
 257 .Vb 2
 258 \& SSL_CTX_set_tlsext_ticket_key_cb(SSL, ssl_tlsext_ticket_key_cb);
 259 \& ...
 260 \&
 261 \& static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16],
 262 \&                                     unsigned char *iv, EVP_CIPHER_CTX *ctx,
 263 \&                                     HMAC_CTX *hctx, int enc)
 264 \& {
 265 \&     if (enc) { /* create new session */
 266 \&         if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) <= 0)
 267 \&             return \-1; /* insufficient random */
 268 \&
 269 \&         key = currentkey(); /* something that you need to implement */
 270 \&         if (key == NULL) {
 271 \&             /* current key doesn\*(Aqt exist or isn\*(Aqt valid */
 272 \&             key = createkey(); /*
 273 \&                                 * Something that you need to implement.
 274 \&                                 * createkey needs to initialise a name,
 275 \&                                 * an aes_key, a hmac_key and optionally
 276 \&                                 * an expire time.
 277 \&                                 */
 278 \&             if (key == NULL) /* key couldn\*(Aqt be created */
 279 \&                 return 0;
 280 \&         }
 281 \&         memcpy(key_name, key\->name, 16);
 282 \&
 283 \&         EVP_EncryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key\->aes_key, iv);
 284 \&         HMAC_Init_ex(&hctx, key\->hmac_key, 16, EVP_sha256(), NULL);
 285 \&
 286 \&         return 1;
 287 \&
 288 \&     } else { /* retrieve session */
 289 \&         key = findkey(name);
 290 \&
 291 \&         if (key == NULL || key\->expire < now())
 292 \&             return 0;
 293 \&
 294 \&         HMAC_Init_ex(&hctx, key\->hmac_key, 16, EVP_sha256(), NULL);
 295 \&         EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key\->aes_key, iv);
 296 \&
 297 \&         if (key\->expire < now() \- RENEW_TIME) {
 298 \&             /*
 299 \&              * return 2 \- This session will get a new ticket even though the
 300 \&              * current one is still valid.
 301 \&              */
 302 \&             return 2;
 303 \&         }
 304 \&         return 1;
 305 \&     }
 306 \& }
 307 .Ve
 308 .SH "SEE ALSO"
 309 .IX Header "SEE ALSO"
 310 \&\fBssl\fR\|(7), \fBSSL_set_session\fR\|(3),
 311 \&\fBSSL_session_reused\fR\|(3),
 312 \&\fBSSL_CTX_add_session\fR\|(3),
 313 \&\fBSSL_CTX_sess_number\fR\|(3),
 314 \&\fBSSL_CTX_sess_set_get_cb\fR\|(3),
 315 \&\fBSSL_CTX_set_session_id_context\fR\|(3),
 316 .SH "COPYRIGHT"
 317 .IX Header "COPYRIGHT"
 318 Copyright 2014\-2019 The OpenSSL Project Authors. All Rights Reserved.
 319 .PP
 320 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 321 this file except in compliance with the License.  You can obtain a copy
 322 in the file \s-1LICENSE\s0 in the source distribution or at
 323 <https://www.openssl.org/source/license.html>.