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