]>
Commit | Line | Data |
---|---|---|
fc1d88f0 RS |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
a76ce286 P |
5 | SSL_CTX_set_tlsext_ticket_key_evp_cb, |
6 | SSL_CTX_set_tlsext_ticket_key_cb | |
7 | - set a callback for session ticket processing | |
fc1d88f0 RS |
8 | |
9 | =head1 SYNOPSIS | |
10 | ||
11 | #include <openssl/tls1.h> | |
12 | ||
a76ce286 P |
13 | int SSL_CTX_set_tlsext_ticket_key_evp_cb(SSL_CTX sslctx, |
14 | int (*cb)(SSL *s, unsigned char key_name[16], | |
15 | unsigned char iv[EVP_MAX_IV_LENGTH], | |
16 | EVP_CIPHER_CTX *ctx, EVP_MAC_CTX *hctx, int enc)); | |
17 | ||
18 | Deprecated since OpenSSL 3.0, can be hidden entirely by defining | |
19 | B<OPENSSL_API_COMPAT> with a suitable version value, see | |
20 | L<openssl_user_macros(7)>: | |
21 | ||
22 | int SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx, | |
e9b77246 BB |
23 | int (*cb)(SSL *s, unsigned char key_name[16], |
24 | unsigned char iv[EVP_MAX_IV_LENGTH], | |
25 | EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)); | |
fc1d88f0 RS |
26 | |
27 | =head1 DESCRIPTION | |
28 | ||
a76ce286 | 29 | SSL_CTX_set_tlsext_ticket_key_evp_cb() sets a callback function I<cb> for handling |
1bc74519 | 30 | session tickets for the ssl context I<sslctx>. Session tickets, defined in |
fc1d88f0 RS |
31 | RFC5077 provide an enhanced session resumption capability where the server |
32 | implementation is not required to maintain per session state. It only applies | |
33 | to TLS and there is no SSLv3 implementation. | |
34 | ||
fc1d88f0 RS |
35 | The callback function I<cb> will be called for every client instigated TLS |
36 | session when session ticket extension is presented in the TLS hello | |
37 | message. It is the responsibility of this function to create or retrieve the | |
38 | cryptographic parameters and to maintain their state. | |
39 | ||
1bc74519 | 40 | The OpenSSL library uses your callback function to help implement a common TLS |
fc1d88f0 | 41 | ticket construction state according to RFC5077 Section 4 such that per session |
1bc74519 | 42 | state is unnecessary and a small set of cryptographic variables needs to be |
fc1d88f0 RS |
43 | maintained by the callback function implementation. |
44 | ||
45 | In order to reuse a session, a TLS client must send the a session ticket | |
46 | extension to the server. The client can only send exactly one session ticket. | |
47 | The server, through the callback function, either agrees to reuse the session | |
48 | ticket information or it starts a full TLS handshake to create a new session | |
49 | ticket. | |
50 | ||
5812e6f1 | 51 | Before the callback function is started I<ctx> and I<hctx> have been |
865adf97 | 52 | initialised with L<EVP_CIPHER_CTX_reset(3)> and L<EVP_MAC_CTX_new(3)> |
a76ce286 | 53 | respectively. |
fc1d88f0 RS |
54 | |
55 | For new sessions tickets, when the client doesn't present a session ticket, or | |
5812e6f1 | 56 | an attempted retrieval of the ticket failed, or a renew option was indicated, |
fc1d88f0 | 57 | the callback function will be called with I<enc> equal to 1. The OpenSSL |
5812e6f1 | 58 | library expects that the function will set an arbitrary I<name>, initialize |
fc1d88f0 RS |
59 | I<iv>, and set the cipher context I<ctx> and the hash context I<hctx>. |
60 | ||
a23a6e85 DSH |
61 | The I<name> is 16 characters long and is used as a key identifier. |
62 | ||
63 | The I<iv> length is the length of the IV of the corresponding cipher. The | |
879365e6 | 64 | maximum IV length is B<EVP_MAX_IV_LENGTH> bytes defined in F<< <openssl/evp.h> >>. |
fc1d88f0 | 65 | |
5812e6f1 AM |
66 | The initialization vector I<iv> should be a random value. The cipher context |
67 | I<ctx> should use the initialisation vector I<iv>. The cipher context can be | |
a76ce286 | 68 | set using L<EVP_EncryptInit_ex(3)>. The hmac context and digest can be set using |
865adf97 | 69 | L<EVP_MAC_CTX_set_params(3)> with the B<OSSL_MAC_PARAM_KEY> and |
a76ce286 | 70 | B<OSSL_MAC_PARAM_DIGEST> parameters respectively. |
fc1d88f0 | 71 | |
1bc74519 | 72 | When the client presents a session ticket, the callback function with be called |
5812e6f1 | 73 | with I<enc> set to 0 indicating that the I<cb> function should retrieve a set |
fc1d88f0 RS |
74 | of parameters. In this case I<name> and I<iv> have already been parsed out of |
75 | the session ticket. The OpenSSL library expects that the I<name> will be used | |
76 | to retrieve a cryptographic parameters and that the cryptographic context | |
5812e6f1 | 77 | I<ctx> will be set with the retrieved parameters and the initialization vector |
a76ce286 | 78 | I<iv>. using a function like L<EVP_DecryptInit_ex(3)>. The key material and |
865adf97 | 79 | digest for I<hctx> need to be set using L<EVP_MAC_CTX_set_params(3)> with the |
a76ce286 | 80 | B<OSSL_MAC_PARAM_KEY> and B<OSSL_MAC_PARAM_DIGEST> parameters respectively. |
fc1d88f0 RS |
81 | |
82 | If the I<name> is still valid but a renewal of the ticket is required the | |
83 | callback function should return 2. The library will call the callback again | |
5812e6f1 | 84 | with an argument of enc equal to 1 to set the new ticket. |
fc1d88f0 RS |
85 | |
86 | The return value of the I<cb> function is used by OpenSSL to determine what | |
87 | further processing will occur. The following return values have meaning: | |
88 | ||
89 | =over 4 | |
90 | ||
fd9e2443 | 91 | =item Z<>2 |
fc1d88f0 | 92 | |
1bc74519 | 93 | This indicates that the I<ctx> and I<hctx> have been set and the session can |
fc1d88f0 RS |
94 | continue on those parameters. Additionally it indicates that the session |
95 | ticket is in a renewal period and should be replaced. The OpenSSL library will | |
96 | call I<cb> again with an enc argument of 1 to set the new ticket (see RFC5077 | |
97 | 3.3 paragraph 2). | |
98 | ||
fd9e2443 | 99 | =item Z<>1 |
fc1d88f0 | 100 | |
1bc74519 | 101 | This indicates that the I<ctx> and I<hctx> have been set and the session can |
fc1d88f0 RS |
102 | continue on those parameters. |
103 | ||
fd9e2443 | 104 | =item Z<>0 |
fc1d88f0 | 105 | |
1bc74519 | 106 | This indicates that it was not possible to set/retrieve a session ticket and |
b9b6a7e5 | 107 | the SSL/TLS session will continue by negotiating a set of cryptographic |
fc1d88f0 RS |
108 | parameters or using the alternate SSL/TLS resumption mechanism, session ids. |
109 | ||
110 | If called with enc equal to 0 the library will call the I<cb> again to get | |
111 | a new set of parameters. | |
112 | ||
113 | =item less than 0 | |
114 | ||
115 | This indicates an error. | |
116 | ||
117 | =back | |
118 | ||
a76ce286 P |
119 | The SSL_CTX_set_tlsext_ticket_key_cb() function is identical to |
120 | SSL_CTX_set_tlsext_ticket_key_evp_cb() except that it takes a deprecated | |
121 | HMAC_CTX pointer instead of an EVP_MAC_CTX one. | |
122 | Before this callback function is started I<hctx> will have been | |
865adf97 MC |
123 | initialised with L<EVP_MAC_CTX_new(3)> and the digest set with |
124 | L<EVP_MAC_CTX_set_params(3)>. | |
a76ce286 P |
125 | The I<hctx> key material can be set using L<HMAC_Init_ex(3)>. |
126 | ||
fc1d88f0 RS |
127 | =head1 NOTES |
128 | ||
129 | Session resumption shortcuts the TLS so that the client certificate | |
5812e6f1 | 130 | negotiation don't occur. It makes up for this by storing client certificate |
fc1d88f0 RS |
131 | an all other negotiated state information encrypted within the ticket. In a |
132 | resumed session the applications will have all this state information available | |
5812e6f1 | 133 | exactly as if a full negotiation had occurred. |
fc1d88f0 | 134 | |
a23a6e85 DSH |
135 | If an attacker can obtain the key used to encrypt a session ticket, they can |
136 | obtain the master secret for any ticket using that key and decrypt any traffic | |
c4de074e | 137 | using that session: even if the cipher suite supports forward secrecy. As |
a23a6e85 DSH |
138 | a result applications may wish to use multiple keys and avoid using long term |
139 | keys stored in files. | |
140 | ||
141 | Applications can use longer keys to maintain a consistent level of security. | |
c4de074e | 142 | For example if a cipher suite uses 256 bit ciphers but only a 128 bit ticket key |
a23a6e85 DSH |
143 | the overall security is only 128 bits because breaking the ticket key will |
144 | enable an attacker to obtain the session keys. | |
145 | ||
4564e77a PY |
146 | =head1 RETURN VALUES |
147 | ||
148 | returns 0 to indicate the callback function was set. | |
149 | ||
fc1d88f0 RS |
150 | =head1 EXAMPLES |
151 | ||
5812e6f1 | 152 | Reference Implementation: |
fc1d88f0 | 153 | |
a76ce286 | 154 | SSL_CTX_set_tlsext_ticket_key_evp_cb(SSL, ssl_tlsext_ticket_key_cb); |
2947af32 BB |
155 | ... |
156 | ||
157 | static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16], | |
158 | unsigned char *iv, EVP_CIPHER_CTX *ctx, | |
a76ce286 | 159 | EVP_MAC_CTX *hctx, int enc) |
2947af32 | 160 | { |
a76ce286 | 161 | OSSL_PARAM params[3]; |
8c330e19 | 162 | your_type_t *key; /* something that you need to implement */ |
a76ce286 | 163 | |
2947af32 | 164 | if (enc) { /* create new session */ |
a12de2cb | 165 | if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) <= 0) |
2947af32 BB |
166 | return -1; /* insufficient random */ |
167 | ||
168 | key = currentkey(); /* something that you need to implement */ | |
169 | if (key == NULL) { | |
170 | /* current key doesn't exist or isn't valid */ | |
171 | key = createkey(); /* | |
172 | * Something that you need to implement. | |
173 | * createkey needs to initialise a name, | |
174 | * an aes_key, a hmac_key and optionally | |
175 | * an expire time. | |
176 | */ | |
177 | if (key == NULL) /* key couldn't be created */ | |
178 | return 0; | |
179 | } | |
180 | memcpy(key_name, key->name, 16); | |
181 | ||
8c330e19 | 182 | EVP_EncryptInit_ex(&ctx, EVP_aes_256_cbc(), NULL, key->aes_key, iv); |
a76ce286 P |
183 | |
184 | params[0] = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_KEY, | |
8c330e19 | 185 | key->hmac_key, 32); |
a76ce286 P |
186 | params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST, |
187 | "sha256", 0); | |
188 | params[2] = OSSL_PARAM_construct_end(); | |
865adf97 | 189 | EVP_MAC_CTX_set_params(hctx, params); |
2947af32 BB |
190 | |
191 | return 1; | |
192 | ||
193 | } else { /* retrieve session */ | |
8c330e19 GS |
194 | time_t t = time(NULL); |
195 | key = findkey(key_name); /* something that you need to implement */ | |
2947af32 | 196 | |
8c330e19 | 197 | if (key == NULL || key->expire < t) |
2947af32 BB |
198 | return 0; |
199 | ||
a76ce286 | 200 | params[0] = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, |
8c330e19 | 201 | key->hmac_key, 32); |
a76ce286 P |
202 | params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST, |
203 | "sha256", 0); | |
204 | params[2] = OSSL_PARAM_construct_end(); | |
865adf97 | 205 | EVP_MAC_CTX_set_params(hctx, params); |
a76ce286 | 206 | |
8c330e19 | 207 | EVP_DecryptInit_ex(&ctx, EVP_aes_256_cbc(), NULL, key->aes_key, iv); |
2947af32 | 208 | |
8c330e19 | 209 | if (key->expire < t - RENEW_TIME) { /* RENEW_TIME: implement */ |
2947af32 BB |
210 | /* |
211 | * return 2 - This session will get a new ticket even though the | |
212 | * current one is still valid. | |
213 | */ | |
214 | return 2; | |
215 | } | |
216 | return 1; | |
217 | } | |
218 | } | |
fc1d88f0 | 219 | |
fc1d88f0 RS |
220 | =head1 SEE ALSO |
221 | ||
b97fdb57 | 222 | L<ssl(7)>, L<SSL_set_session(3)>, |
9b86974e RS |
223 | L<SSL_session_reused(3)>, |
224 | L<SSL_CTX_add_session(3)>, | |
225 | L<SSL_CTX_sess_number(3)>, | |
226 | L<SSL_CTX_sess_set_get_cb(3)>, | |
227 | L<SSL_CTX_set_session_id_context(3)>, | |
fc1d88f0 | 228 | |
a76ce286 P |
229 | =head1 HISTORY |
230 | ||
231 | The SSL_CTX_set_tlsext_ticket_key_cb() function was deprecated in OpenSSL 3.0. | |
232 | ||
233 | The SSL_CTX_set_tlsext_ticket_key_evp_cb() function was introduced in | |
234 | OpenSSL 3.0. | |
235 | ||
e2f92610 RS |
236 | =head1 COPYRIGHT |
237 | ||
4333b89f | 238 | Copyright 2014-2021 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 239 | |
4746f25a | 240 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
241 | this file except in compliance with the License. You can obtain a copy |
242 | in the file LICENSE in the source distribution or at | |
243 | L<https://www.openssl.org/source/license.html>. | |
244 | ||
245 | =cut |