]>
Commit | Line | Data |
---|---|---|
df0fed9a TS |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_CTX_set_session_ticket_cb, | |
6 | SSL_SESSION_get0_ticket_appdata, | |
7 | SSL_SESSION_set1_ticket_appdata, | |
8 | SSL_CTX_generate_session_ticket_fn, | |
9 | SSL_CTX_decrypt_session_ticket_fn - manage session ticket application data | |
10 | ||
11 | =head1 SYNOPSIS | |
12 | ||
13 | #include <openssl/ssl.h> | |
14 | ||
15 | typedef int (*SSL_CTX_generate_session_ticket_fn)(SSL *s, void *arg); | |
16 | typedef SSL_TICKET_RETURN (*SSL_CTX_decrypt_session_ticket_fn)(SSL *s, SSL_SESSION *ss, | |
17 | const unsigned char *keyname, | |
18 | size_t keyname_len, | |
61fb5923 | 19 | SSL_TICKET_STATUS status, |
df0fed9a TS |
20 | void *arg); |
21 | int SSL_CTX_set_session_ticket_cb(SSL_CTX *ctx, | |
22 | SSL_CTX_generate_session_ticket_fn gen_cb, | |
23 | SSL_CTX_decrypt_session_ticket_fn dec_cb, | |
24 | void *arg); | |
25 | int SSL_SESSION_set1_ticket_appdata(SSL_SESSION *ss, const void *data, size_t len); | |
26 | int SSL_SESSION_get0_ticket_appdata(SSL_SESSION *ss, void **data, size_t *len); | |
27 | ||
28 | =head1 DESCRIPTION | |
29 | ||
30 | SSL_CTX_set_set_session_ticket_cb() sets the application callbacks B<gen_cb> | |
31 | and B<dec_cb> that are used by a server to set and get application data stored | |
32 | with a session, and placed into a session ticket. Either callback function may | |
33 | be set to NULL. The value of B<arg> is passed to the callbacks. | |
34 | ||
35 | B<gen_cb> is the application defined callback invoked when a session ticket is | |
36 | about to be created. The application can call SSL_SESSION_set1_ticket_appdata() | |
37 | at this time to add application data to the session ticket. The value of B<arg> | |
38 | is the same as that given to SSL_CTX_set_session_ticket_cb(). The B<gen_cb> | |
39 | callback is defined as type B<SSL_CTX_generate_session_ticket_fn>. | |
40 | ||
41 | B<dec_cb> is the application defined callback invoked after session ticket | |
61fb5923 MC |
42 | decryption has been attempted and any session ticket application data is |
43 | available. If ticket decryption was successful then the B<ss> argument contains | |
44 | the session data. The B<keyname> and B<keyname_len> arguments identify the key | |
45 | used to decrypt the session ticket. The B<status> argument is the result of the | |
46 | ticket decryption. See the L<NOTES> section below for further details. The value | |
47 | of B<arg> is the same as that given to SSL_CTX_set_session_ticket_cb(). The | |
48 | B<dec_cb> callback is defined as type B<SSL_CTX_decrypt_session_ticket_fn>. | |
df0fed9a TS |
49 | |
50 | SSL_SESSION_set1_ticket_appdata() sets the application data specified by | |
51 | B<data> and B<len> into B<ss> which is then placed into any generated session | |
52 | tickets. It can be called at any time before a session ticket is created to | |
53 | update the data placed into the session ticket. However, given that sessions | |
54 | and tickets are created by the handshake, the B<gen_cb> is provided to notify | |
55 | the application that a session ticket is about to be generated. | |
56 | ||
57 | SSL_SESSION_get0_ticket_appdata() assigns B<data> to the session ticket | |
58 | application data and assigns B<len> to the length of the session ticket | |
59 | application data from B<ss>. The application data can be set via | |
60 | SSL_SESSION_set1_ticket_appdata() or by a session ticket. NULL will be assigned | |
61 | to B<data> and 0 will be assigned to B<len> if there is no session ticket | |
62 | application data. SSL_SESSION_get0_ticket_appdata() can be called any time | |
63 | after a session has been created. The B<dec_cb> is provided to notify the | |
64 | application that a session ticket has just been decrypted. | |
65 | ||
66 | =head1 NOTES | |
67 | ||
68 | When the B<dec_cb> callback is invoked, the SSL_SESSION B<ss> has not yet been | |
61fb5923 MC |
69 | assigned to the SSL B<s>. The B<status> indicates the result of the ticket |
70 | decryption. The callback must check the B<status> value before performing any | |
71 | action, as it is called even if ticket decryption fails. | |
df0fed9a TS |
72 | |
73 | The B<keyname> and B<keyname_len> arguments to B<dec_cb> may be used to identify | |
74 | the key that was used to encrypt the session ticket. | |
75 | ||
61fb5923 | 76 | The B<status> argument can be any of these values: |
df0fed9a | 77 | |
61fb5923 | 78 | =over 4 |
2448bb8c | 79 | |
61fb5923 | 80 | =item SSL_TICKET_EMPTY |
df0fed9a | 81 | |
61fb5923 MC |
82 | Empty ticket present. No ticket data will be used and a new ticket should be |
83 | sent to the client. This only occurs in TLSv1.2 or below. In TLSv1.3 it is not | |
84 | valid for a client to send an empty ticket. | |
df0fed9a | 85 | |
61fb5923 | 86 | =item SSL_TICKET_NO_DECRYPT |
df0fed9a | 87 | |
61fb5923 MC |
88 | The ticket couldn't be decrypted. No ticket data will be used and a new ticket |
89 | should be sent to the client. | |
df0fed9a | 90 | |
61fb5923 | 91 | =item SSL_TICKET_SUCCESS |
df0fed9a | 92 | |
61fb5923 MC |
93 | A ticket was successfully decrypted, any session ticket application data should |
94 | be available. A new ticket should not be sent to the client. | |
df0fed9a | 95 | |
61fb5923 | 96 | =item SSL_TICKET_SUCCESS_RENEW |
df0fed9a | 97 | |
61fb5923 | 98 | Same as B<SSL_TICKET_SUCCESS>, but a new ticket should be sent to the client. |
df0fed9a | 99 | |
61fb5923 | 100 | =back |
df0fed9a | 101 | |
61fb5923 | 102 | The return value can be any of these values: |
df0fed9a | 103 | |
61fb5923 | 104 | =over 4 |
df0fed9a | 105 | |
61fb5923 | 106 | =item SSL_TICKET_RETURN_ABORT |
df0fed9a | 107 | |
61fb5923 MC |
108 | The handshake should be aborted, either because of an error or because of some |
109 | policy. Note that in TLSv1.3 a client may send more than one ticket in a single | |
110 | handshake. Therefore just because one ticket is unacceptable it does not mean | |
111 | that all of them are. For this reason this option should be used with caution. | |
df0fed9a | 112 | |
61fb5923 | 113 | =item SSL_TICKET_RETURN_IGNORE |
df0fed9a | 114 | |
61fb5923 MC |
115 | Do not use a ticket (if one was available). Do not send a renewed ticket to the |
116 | client. | |
df0fed9a | 117 | |
61fb5923 | 118 | =item SSL_TICKET_RETURN_IGNORE_RENEW |
df0fed9a | 119 | |
61fb5923 | 120 | Do not use a ticket (if one was available). Send a renewed ticket to the client. |
df0fed9a | 121 | |
61fb5923 MC |
122 | If the callback does not wish to change the default ticket behaviour then it |
123 | should return this value if B<status> is B<SSL_TICKET_EMPTY> or | |
124 | B<SSL_TICKET_NO_DECRYPT>. | |
df0fed9a | 125 | |
61fb5923 | 126 | =item SSL_TICKET_RETURN_USE |
df0fed9a | 127 | |
61fb5923 MC |
128 | Use the ticket. Do not send a renewed ticket to the client. It is an error for |
129 | the callback to return this value if B<status> has a value other than | |
130 | B<SSL_TICKET_SUCCESS> or B<SSL_TICKET_SUCCESS_RENEW>. | |
131 | ||
132 | If the callback does not wish to change the default ticket behaviour then it | |
133 | should return this value if B<status> is B<SSL_TICKET_SUCCESS>. | |
134 | ||
135 | =item SSL_TICKET_RETURN_USE_RENEW | |
136 | ||
137 | Use the ticket. Send a renewed ticket to the client. It is an error for the | |
138 | callback to return this value if B<status> has a value other than | |
139 | B<SSL_TICKET_SUCCESS> or B<SSL_TICKET_SUCCESS_RENEW>. | |
140 | ||
141 | If the callback does not wish to change the default ticket behaviour then it | |
142 | should return this value if B<status> is B<SSL_TICKET_SUCCESS_RENEW>. | |
df0fed9a TS |
143 | |
144 | =back | |
145 | ||
61fb5923 MC |
146 | If B<status> has the value B<SSL_TICKET_EMPTY> or B<SSL_TICKET_NO_DECRYPT> then |
147 | no session data will be available and the callback must not use the B<ss> | |
148 | argument. If B<status> has the value B<SSL_TICKET_SUCCESS> or | |
149 | B<SSL_TICKET_SUCCESS_RENEW> then the application can call | |
150 | SSL_SESSION_get0_ticket_appdata() using the session provided in the B<ss> | |
151 | argument to retrieve the application data. | |
152 | ||
153 | When the B<gen_cb> callback is invoked, the SSL_get_session() function can be | |
154 | used to retrieve the SSL_SESSION for SSL_SESSION_set1_ticket_appdata(). | |
155 | ||
156 | By default, in TLSv1.2 and below, a new session ticket is not issued on a | |
157 | successful resumption and therefore B<gen_cb> will not be called. In TLSv1.3 the | |
158 | default behaviour is to always issue a new ticket on resumption. In both cases | |
159 | this behaviour can be changed if a ticket key callback is in use (see | |
160 | L<SSL_CTX_set_tlsext_ticket_key_cb(3)>). | |
161 | ||
162 | =head1 RETURN VALUES | |
163 | ||
164 | The SSL_CTX_set_session_ticket_cb(), SSL_SESSION_set1_ticket_appdata() and | |
165 | SSL_SESSION_get0_ticket_appdata() functions return 1 on success and 0 on | |
166 | failure. | |
167 | ||
168 | The B<gen_cb> callback must return 1 to continue the connection. A return of 0 | |
169 | will terminate the connection with an INTERNAL_ERROR alert. | |
170 | ||
171 | The B<dec_cb> callback must return a value as described in L<NOTES> above. | |
172 | ||
df0fed9a TS |
173 | =head1 SEE ALSO |
174 | ||
175 | L<ssl(7)>, | |
176 | L<SSL_get_session(3)> | |
177 | ||
178 | =head1 HISTORY | |
179 | ||
fc5ecadd DMSP |
180 | The SSL_CTX_set_session_ticket_cb(), SSSL_SESSION_set1_ticket_appdata() |
181 | and SSL_SESSION_get_ticket_appdata() functions were added in OpenSSL 1.1.1. | |
df0fed9a TS |
182 | |
183 | =head1 COPYRIGHT | |
184 | ||
b0edda11 | 185 | Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. |
df0fed9a | 186 | |
4746f25a | 187 | Licensed under the Apache License 2.0 (the "License"). You may not use |
df0fed9a TS |
188 | this file except in compliance with the License. You can obtain a copy |
189 | in the file LICENSE in the source distribution or at | |
190 | L<https://www.openssl.org/source/license.html>. | |
191 | ||
192 | =cut |