]>
Commit | Line | Data |
---|---|---|
f3f56c2a DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
c952780c | 5 | SSL_extension_supported, |
314aec07 | 6 | SSL_CTX_add_custom_ext, |
121677b4 RS |
7 | SSL_CTX_add_client_custom_ext, SSL_CTX_add_server_custom_ext, |
8 | custom_ext_add_cb, custom_ext_free_cb, custom_ext_parse_cb | |
c952780c | 9 | - custom TLS extension handling |
f3f56c2a DSH |
10 | |
11 | =head1 SYNOPSIS | |
12 | ||
13 | #include <openssl/ssl.h> | |
14 | ||
cd17bb19 MC |
15 | typedef int (*SSL_custom_ext_add_cb_ex) (SSL *s, unsigned int ext_type, |
16 | unsigned int context, | |
17 | const unsigned char **out, | |
18 | size_t *outlen, X509 *x, | |
19 | size_t chainidx, int *al, | |
20 | void *add_arg); | |
21 | ||
22 | typedef void (*SSL_custom_ext_free_cb_ex) (SSL *s, unsigned int ext_type, | |
23 | unsigned int context, | |
24 | const unsigned char *out, | |
25 | void *add_arg); | |
26 | ||
27 | typedef int (*SSL_custom_ext_parse_cb_ex) (SSL *s, unsigned int ext_type, | |
28 | unsigned int context, | |
29 | const unsigned char *in, | |
30 | size_t inlen, X509 *x, | |
31 | size_t chainidx, int *al, | |
32 | void *parse_arg); | |
314aec07 MC |
33 | |
34 | int SSL_CTX_add_custom_ext(SSL_CTX *ctx, unsigned int ext_type, | |
35 | unsigned int context, | |
cd17bb19 MC |
36 | SSL_custom_ext_add_cb_ex add_cb, |
37 | SSL_custom_ext_free_cb_ex free_cb, | |
314aec07 | 38 | void *add_arg, |
cd17bb19 MC |
39 | SSL_custom_ext_parse_cb_ex parse_cb, |
40 | void *parse_arg); | |
f3f56c2a DSH |
41 | |
42 | typedef int (*custom_ext_add_cb)(SSL *s, unsigned int ext_type, | |
1bc74519 RS |
43 | const unsigned char **out, |
44 | size_t *outlen, int *al, | |
45 | void *add_arg); | |
f3f56c2a DSH |
46 | |
47 | typedef void (*custom_ext_free_cb)(SSL *s, unsigned int ext_type, | |
1bc74519 RS |
48 | const unsigned char *out, |
49 | void *add_arg); | |
f3f56c2a DSH |
50 | |
51 | typedef int (*custom_ext_parse_cb)(SSL *s, unsigned int ext_type, | |
1bc74519 RS |
52 | const unsigned char *in, |
53 | size_t inlen, int *al, | |
54 | void *parse_arg); | |
f3f56c2a | 55 | |
314aec07 MC |
56 | int SSL_CTX_add_client_custom_ext(SSL_CTX *ctx, unsigned int ext_type, |
57 | custom_ext_add_cb add_cb, | |
58 | custom_ext_free_cb free_cb, void *add_arg, | |
59 | custom_ext_parse_cb parse_cb, | |
60 | void *parse_arg); | |
f3f56c2a | 61 | |
314aec07 MC |
62 | int SSL_CTX_add_server_custom_ext(SSL_CTX *ctx, unsigned int ext_type, |
63 | custom_ext_add_cb add_cb, | |
64 | custom_ext_free_cb free_cb, void *add_arg, | |
65 | custom_ext_parse_cb parse_cb, | |
66 | void *parse_arg); | |
f3f56c2a | 67 | |
314aec07 | 68 | int SSL_extension_supported(unsigned int ext_type); |
f3f56c2a | 69 | |
314aec07 | 70 | =head1 DESCRIPTION |
f3f56c2a | 71 | |
64350ab5 | 72 | SSL_CTX_add_custom_ext() adds a custom extension for a TLS/DTLS client or server |
314aec07 MC |
73 | for all supported protocol versions with extension type B<ext_type> and |
74 | callbacks B<add_cb>, B<free_cb> and B<parse_cb> (see the | |
75 | L</EXTENSION CALLBACKS> section below). The B<context> value determines | |
76 | which messages and under what conditions the extension will be added/parsed (see | |
77 | the L</EXTENSION CONTEXTS> section below). | |
78 | ||
64350ab5 MC |
79 | SSL_CTX_add_client_custom_ext() adds a custom extension for a TLS/DTLS client |
80 | with extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and | |
81 | B<parse_cb>. This function is similar to SSL_CTX_add_custom_ext() except it only | |
82 | applies to clients, uses the older style of callbacks, and implicitly sets the | |
314aec07 MC |
83 | B<context> value to: |
84 | ||
85 | SSL_EXT_TLS1_2_AND_BELOW_ONLY | SSL_EXT_CLIENT_HELLO | |
86 | | SSL_EXT_TLS1_2_SERVER_HELLO | SSL_EXT_IGNORE_ON_RESUMPTION | |
87 | ||
64350ab5 MC |
88 | SSL_CTX_add_server_custom_ext() adds a custom extension for a TLS/DTLS server |
89 | with extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and | |
314aec07 MC |
90 | B<parse_cb>. This function is similar to SSL_CTX_add_custom_ext() except it |
91 | only applies to servers, uses the older style of callbacks, and implicitly sets | |
92 | the B<context> value to the same as for SSL_CTX_add_client_custom_ext() above. | |
93 | ||
64350ab5 MC |
94 | The B<ext_type> parameter corresponds to the B<extension_type> field of |
95 | RFC5246 et al. It is B<not> a NID. In all cases the extension type must not be | |
96 | handled by OpenSSL internally or an error occurs. | |
f3f56c2a DSH |
97 | |
98 | SSL_extension_supported() returns 1 if the extension B<ext_type> is handled | |
99 | internally by OpenSSL and 0 otherwise. | |
100 | ||
101 | =head1 EXTENSION CALLBACKS | |
102 | ||
1bc74519 | 103 | The callback B<add_cb> is called to send custom extension data to be |
314aec07 MC |
104 | included in various TLS messages. The B<ext_type> parameter is set to the |
105 | extension type which will be added and B<add_arg> to the value set when the | |
106 | extension handler was added. When using the new style callbacks the B<context> | |
107 | parameter will indicate which message is currently being constructed e.g. for | |
108 | the ClientHello it will be set to B<SSL_EXT_CLIENT_HELLO>. | |
f3f56c2a DSH |
109 | |
110 | If the application wishes to include the extension B<ext_type> it should | |
111 | set B<*out> to the extension data, set B<*outlen> to the length of the | |
112 | extension data and return 1. | |
113 | ||
114 | If the B<add_cb> does not wish to include the extension it must return 0. | |
115 | ||
116 | If B<add_cb> returns -1 a fatal handshake error occurs using the TLS | |
117 | alert value specified in B<*al>. | |
118 | ||
64350ab5 | 119 | When constructing the ClientHello, if B<add_cb> is set to NULL a zero length |
314aec07 MC |
120 | extension is added for B<ext_type>. For all other messages if B<add_cb> is set |
121 | to NULL then no extension is added. | |
122 | ||
123 | When constructing a Certificate message the callback will be called for each | |
124 | certificate in the message. The B<x> parameter will indicate the | |
125 | current certificate and the B<chainidx> parameter will indicate the position | |
126 | of the certificate in the message. The first certificate is always the end | |
64350ab5 MC |
127 | entity certificate and has a B<chainidx> value of 0. The certificates are in the |
128 | order that they were received in the Certificate message. | |
f3f56c2a | 129 | |
314aec07 MC |
130 | For all messages except the ServerHello and EncryptedExtensions every |
131 | registered B<add_cb> is always called to see if the application wishes to add an | |
132 | extension (as long as all requirements of the specified B<context> are met). | |
f3f56c2a | 133 | |
314aec07 MC |
134 | For the ServerHello and EncryptedExtension messages every registered B<add_cb> |
135 | is called once if and only if the requirements of the specified B<context> are | |
136 | met and the corresponding extension was received in the ClientHello. That is, if | |
137 | no corresponding extension was received in the ClientHello then B<add_cb> will | |
138 | not be called. | |
f3f56c2a DSH |
139 | |
140 | If an extension is added (that is B<add_cb> returns 1) B<free_cb> is called | |
141 | (if it is set) with the value of B<out> set by the add callback. It can be | |
142 | used to free up any dynamic extension data set by B<add_cb>. Since B<out> is | |
143 | constant (to permit use of constant data in B<add_cb>) applications may need to | |
144 | cast away const to free the data. | |
145 | ||
314aec07 MC |
146 | The callback B<parse_cb> receives data for TLS extensions. The callback is only |
147 | called if the extension is present and relevant for the context (see | |
148 | L</EXTENSION CONTEXTS> below). | |
f3f56c2a DSH |
149 | |
150 | The extension data consists of B<inlen> bytes in the buffer B<in> for the | |
314aec07 MC |
151 | extension B<ext_type>. |
152 | ||
153 | If the message being parsed is a TLSv1.3 compatible Certificate message then | |
154 | B<parse_cb> will be called for each certificate contained within the message. | |
155 | The B<x> parameter will indicate the current certificate and the B<chainidx> | |
156 | parameter will indicate the position of the certificate in the message. The | |
157 | first certificate is always the end entity certificate and has a B<chainidx> | |
158 | value of 0. | |
f3f56c2a DSH |
159 | |
160 | If the B<parse_cb> considers the extension data acceptable it must return | |
161 | 1. If it returns 0 or a negative value a fatal handshake error occurs | |
162 | using the TLS alert value specified in B<*al>. | |
163 | ||
164 | The buffer B<in> is a temporary internal buffer which will not be valid after | |
165 | the callback returns. | |
166 | ||
314aec07 MC |
167 | =head1 EXTENSION CONTEXTS |
168 | ||
169 | An extension context defines which messages and under which conditions an | |
170 | extension should be added or expected. The context is built up by performing | |
171 | a bitwise OR of multiple pre-defined values together. The valid context values | |
172 | are: | |
173 | ||
174 | =over 4 | |
175 | ||
176 | =item SSL_EXT_TLS_ONLY | |
177 | ||
178 | The extension is only allowed in TLS | |
179 | ||
180 | =item SSL_EXT_DTLS_ONLY | |
181 | ||
182 | The extension is only allowed in DTLS | |
183 | ||
184 | =item SSL_EXT_TLS_IMPLEMENTATION_ONLY | |
185 | ||
186 | The extension is allowed in DTLS, but there is only a TLS implementation | |
187 | available (so it is ignored in DTLS). | |
188 | ||
189 | =item SSL_EXT_SSL3_ALLOWED | |
190 | ||
191 | Extensions are not typically defined for SSLv3. Setting this value will allow | |
192 | the extension in SSLv3. Applications will not typically need to use this. | |
193 | ||
194 | =item SSL_EXT_TLS1_2_AND_BELOW_ONLY | |
195 | ||
64350ab5 MC |
196 | The extension is only defined for TLSv1.2/DTLSv1.2 and below. Servers will |
197 | ignore this extension if it is present in the ClientHello and TLSv1.3 is | |
198 | negotiated. | |
314aec07 MC |
199 | |
200 | =item SSL_EXT_TLS1_3_ONLY | |
201 | ||
202 | The extension is only defined for TLS1.3 and above. Servers will ignore this | |
203 | extension if it is present in the ClientHello and TLSv1.2 or below is | |
204 | negotiated. | |
205 | ||
206 | =item SSL_EXT_IGNORE_ON_RESUMPTION | |
207 | ||
208 | The extension will be ignored during parsing if a previous session is being | |
209 | successfully resumed. | |
210 | ||
211 | =item SSL_EXT_CLIENT_HELLO | |
212 | ||
213 | The extension may be present in the ClientHello message. | |
214 | ||
215 | =item SSL_EXT_TLS1_2_SERVER_HELLO | |
216 | ||
217 | The extension may be present in a TLSv1.2 or below compatible ServerHello | |
218 | message. | |
219 | ||
220 | =item SSL_EXT_TLS1_3_SERVER_HELLO | |
221 | ||
222 | The extension may be present in a TLSv1.3 compatible ServerHello message. | |
223 | ||
224 | =item SSL_EXT_TLS1_3_ENCRYPTED_EXTENSIONS | |
225 | ||
226 | The extension may be present in an EncryptedExtensions message. | |
227 | ||
228 | =item SSL_EXT_TLS1_3_HELLO_RETRY_REQUEST | |
229 | ||
230 | The extension may be present in a HelloRetryRequest message. | |
231 | ||
232 | =item SSL_EXT_TLS1_3_CERTIFICATE | |
233 | ||
234 | The extension may be present in a TLSv1.3 compatible Certificate message. | |
235 | ||
236 | =item SSL_EXT_TLS1_3_NEW_SESSION_TICKET | |
237 | ||
238 | The extension may be present in a TLSv1.3 compatible NewSessionTicket message. | |
239 | ||
240 | =item SSL_EXT_TLS1_3_CERTIFICATE_REQUEST | |
241 | ||
242 | The extension may be present in a TLSv1.3 compatible CertificateRequest message. | |
243 | ||
244 | =back | |
245 | ||
246 | The context must include at least one message value (otherwise the extension | |
247 | will never be used). | |
248 | ||
f3f56c2a DSH |
249 | =head1 NOTES |
250 | ||
251 | The B<add_arg> and B<parse_arg> parameters can be set to arbitrary values | |
252 | which will be passed to the corresponding callbacks. They can, for example, | |
253 | be used to store the extension data received in a convenient structure or | |
254 | pass the extension data to be added or freed when adding extensions. | |
255 | ||
f3f56c2a DSH |
256 | If the same custom extension type is received multiple times a fatal |
257 | B<decode_error> alert is sent and the handshake aborts. If a custom extension | |
314aec07 MC |
258 | is received in a ServerHello/EncryptedExtensions message which was not sent in |
259 | the ClientHello a fatal B<unsupported_extension> alert is sent and the | |
260 | handshake is aborted. The ServerHello/EncryptedExtensions B<add_cb> callback is | |
261 | only called if the corresponding extension was received in the ClientHello. This | |
262 | is compliant with the TLS specifications. This behaviour ensures that each | |
263 | callback is called at most once and that an application can never send | |
264 | unsolicited extensions. | |
f3f56c2a DSH |
265 | |
266 | =head1 RETURN VALUES | |
267 | ||
314aec07 MC |
268 | SSL_CTX_add_custom_ext(), SSL_CTX_add_client_custom_ext() and |
269 | SSL_CTX_add_server_custom_ext() return 1 for success and 0 for failure. A | |
270 | failure can occur if an attempt is made to add the same B<ext_type> more than | |
271 | once, if an attempt is made to use an extension type handled internally by | |
272 | OpenSSL or if an internal error occurs (for example a memory allocation | |
273 | failure). | |
f3f56c2a DSH |
274 | |
275 | SSL_extension_supported() returns 1 if the extension B<ext_type> is handled | |
276 | internally by OpenSSL and 0 otherwise. | |
277 | ||
314aec07 MC |
278 | =head1 HISTORY |
279 | ||
fc5ecadd | 280 | The SSL_CTX_add_custom_ext() function was added in OpenSSL 1.1.1. |
314aec07 | 281 | |
e2f92610 RS |
282 | =head1 COPYRIGHT |
283 | ||
314aec07 | 284 | Copyright 2014-2017 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 285 | |
4746f25a | 286 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
287 | this file except in compliance with the License. You can obtain a copy |
288 | in the file LICENSE in the source distribution or at | |
289 | L<https://www.openssl.org/source/license.html>. | |
290 | ||
291 | =cut |