| =pod |
| |
| =head1 NAME |
| |
| SSL_extension_supported, |
| SSL_custom_ext_add_cb_ex, |
| SSL_custom_ext_free_cb_ex, |
| SSL_custom_ext_parse_cb_ex, |
| SSL_CTX_add_custom_ext, |
| SSL_CTX_add_client_custom_ext, SSL_CTX_add_server_custom_ext, |
| custom_ext_add_cb, custom_ext_free_cb, custom_ext_parse_cb |
| - custom TLS extension handling |
| |
| =head1 SYNOPSIS |
| |
| #include <openssl/ssl.h> |
| |
| typedef int (*SSL_custom_ext_add_cb_ex)(SSL *s, unsigned int ext_type, |
| unsigned int context, |
| const unsigned char **out, |
| size_t *outlen, X509 *x, |
| size_t chainidx, int *al, |
| void *add_arg); |
| |
| typedef void (*SSL_custom_ext_free_cb_ex)(SSL *s, unsigned int ext_type, |
| unsigned int context, |
| const unsigned char *out, |
| void *add_arg); |
| |
| typedef int (*SSL_custom_ext_parse_cb_ex)(SSL *s, unsigned int ext_type, |
| unsigned int context, |
| const unsigned char *in, |
| size_t inlen, X509 *x, |
| size_t chainidx, int *al, |
| void *parse_arg); |
| |
| int SSL_CTX_add_custom_ext(SSL_CTX *ctx, unsigned int ext_type, |
| unsigned int context, |
| SSL_custom_ext_add_cb_ex add_cb, |
| SSL_custom_ext_free_cb_ex free_cb, |
| void *add_arg, |
| SSL_custom_ext_parse_cb_ex parse_cb, |
| void *parse_arg); |
| |
| typedef int (*custom_ext_add_cb)(SSL *s, unsigned int ext_type, |
| const unsigned char **out, |
| size_t *outlen, int *al, |
| void *add_arg); |
| |
| typedef void (*custom_ext_free_cb)(SSL *s, unsigned int ext_type, |
| const unsigned char *out, |
| void *add_arg); |
| |
| typedef int (*custom_ext_parse_cb)(SSL *s, unsigned int ext_type, |
| const unsigned char *in, |
| size_t inlen, int *al, |
| void *parse_arg); |
| |
| int SSL_CTX_add_client_custom_ext(SSL_CTX *ctx, unsigned int ext_type, |
| custom_ext_add_cb add_cb, |
| custom_ext_free_cb free_cb, void *add_arg, |
| custom_ext_parse_cb parse_cb, |
| void *parse_arg); |
| |
| int SSL_CTX_add_server_custom_ext(SSL_CTX *ctx, unsigned int ext_type, |
| custom_ext_add_cb add_cb, |
| custom_ext_free_cb free_cb, void *add_arg, |
| custom_ext_parse_cb parse_cb, |
| void *parse_arg); |
| |
| int SSL_extension_supported(unsigned int ext_type); |
| |
| =head1 DESCRIPTION |
| |
| SSL_CTX_add_custom_ext() adds a custom extension for a TLS/DTLS client or server |
| for all supported protocol versions with extension type B<ext_type> and |
| callbacks B<add_cb>, B<free_cb> and B<parse_cb> (see the |
| L</EXTENSION CALLBACKS> section below). The B<context> value determines |
| which messages and under what conditions the extension will be added/parsed (see |
| the L</EXTENSION CONTEXTS> section below). |
| |
| SSL_CTX_add_client_custom_ext() adds a custom extension for a TLS/DTLS client |
| with extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and |
| B<parse_cb>. This function is similar to SSL_CTX_add_custom_ext() except it only |
| applies to clients, uses the older style of callbacks, and implicitly sets the |
| B<context> value to: |
| |
| SSL_EXT_TLS1_2_AND_BELOW_ONLY | SSL_EXT_CLIENT_HELLO |
| | SSL_EXT_TLS1_2_SERVER_HELLO | SSL_EXT_IGNORE_ON_RESUMPTION |
| |
| SSL_CTX_add_server_custom_ext() adds a custom extension for a TLS/DTLS server |
| with extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and |
| B<parse_cb>. This function is similar to SSL_CTX_add_custom_ext() except it |
| only applies to servers, uses the older style of callbacks, and implicitly sets |
| the B<context> value to the same as for SSL_CTX_add_client_custom_ext() above. |
| |
| The B<ext_type> parameter corresponds to the B<extension_type> field of |
| RFC5246 et al. It is B<not> a NID. In all cases the extension type must not be |
| handled by OpenSSL internally or an error occurs. |
| |
| SSL_extension_supported() returns 1 if the extension B<ext_type> is handled |
| internally by OpenSSL and 0 otherwise. |
| |
| =head1 EXTENSION CALLBACKS |
| |
| The callback B<add_cb> is called to send custom extension data to be |
| included in various TLS messages. The B<ext_type> parameter is set to the |
| extension type which will be added and B<add_arg> to the value set when the |
| extension handler was added. When using the new style callbacks the B<context> |
| parameter will indicate which message is currently being constructed e.g. for |
| the ClientHello it will be set to B<SSL_EXT_CLIENT_HELLO>. |
| |
| If the application wishes to include the extension B<ext_type> it should |
| set B<*out> to the extension data, set B<*outlen> to the length of the |
| extension data and return 1. |
| |
| If the B<add_cb> does not wish to include the extension it must return 0. |
| |
| If B<add_cb> returns -1 a fatal handshake error occurs using the TLS |
| alert value specified in B<*al>. |
| |
| When constructing the ClientHello, if B<add_cb> is set to NULL a zero length |
| extension is added for B<ext_type>. For all other messages if B<add_cb> is set |
| to NULL then no extension is added. |
| |
| When constructing a Certificate message the callback will be called for each |
| certificate in the message. The B<x> parameter will indicate the |
| current certificate and the B<chainidx> parameter will indicate the position |
| of the certificate in the message. The first certificate is always the end |
| entity certificate and has a B<chainidx> value of 0. The certificates are in the |
| order that they were received in the Certificate message. |
| |
| For all messages except the ServerHello and EncryptedExtensions every |
| registered B<add_cb> is always called to see if the application wishes to add an |
| extension (as long as all requirements of the specified B<context> are met). |
| |
| For the ServerHello and EncryptedExtension messages every registered B<add_cb> |
| is called once if and only if the requirements of the specified B<context> are |
| met and the corresponding extension was received in the ClientHello. That is, if |
| no corresponding extension was received in the ClientHello then B<add_cb> will |
| not be called. |
| |
| If an extension is added (that is B<add_cb> returns 1) B<free_cb> is called |
| (if it is set) with the value of B<out> set by the add callback. It can be |
| used to free up any dynamic extension data set by B<add_cb>. Since B<out> is |
| constant (to permit use of constant data in B<add_cb>) applications may need to |
| cast away const to free the data. |
| |
| The callback B<parse_cb> receives data for TLS extensions. The callback is only |
| called if the extension is present and relevant for the context (see |
| L</EXTENSION CONTEXTS> below). |
| |
| The extension data consists of B<inlen> bytes in the buffer B<in> for the |
| extension B<ext_type>. |
| |
| If the message being parsed is a TLSv1.3 compatible Certificate message then |
| B<parse_cb> will be called for each certificate contained within the message. |
| The B<x> parameter will indicate the current certificate and the B<chainidx> |
| parameter will indicate the position of the certificate in the message. The |
| first certificate is always the end entity certificate and has a B<chainidx> |
| value of 0. |
| |
| If the B<parse_cb> considers the extension data acceptable it must return |
| 1. If it returns 0 or a negative value a fatal handshake error occurs |
| using the TLS alert value specified in B<*al>. |
| |
| The buffer B<in> is a temporary internal buffer which will not be valid after |
| the callback returns. |
| |
| =head1 EXTENSION CONTEXTS |
| |
| An extension context defines which messages and under which conditions an |
| extension should be added or expected. The context is built up by performing |
| a bitwise OR of multiple pre-defined values together. The valid context values |
| are: |
| |
| =over 4 |
| |
| =item SSL_EXT_TLS_ONLY |
| |
| The extension is only allowed in TLS |
| |
| =item SSL_EXT_DTLS_ONLY |
| |
| The extension is only allowed in DTLS |
| |
| =item SSL_EXT_TLS_IMPLEMENTATION_ONLY |
| |
| The extension is allowed in DTLS, but there is only a TLS implementation |
| available (so it is ignored in DTLS). |
| |
| =item SSL_EXT_SSL3_ALLOWED |
| |
| Extensions are not typically defined for SSLv3. Setting this value will allow |
| the extension in SSLv3. Applications will not typically need to use this. |
| |
| =item SSL_EXT_TLS1_2_AND_BELOW_ONLY |
| |
| The extension is only defined for TLSv1.2/DTLSv1.2 and below. Servers will |
| ignore this extension if it is present in the ClientHello and TLSv1.3 is |
| negotiated. |
| |
| =item SSL_EXT_TLS1_3_ONLY |
| |
| The extension is only defined for TLS1.3 and above. Servers will ignore this |
| extension if it is present in the ClientHello and TLSv1.2 or below is |
| negotiated. |
| |
| =item SSL_EXT_IGNORE_ON_RESUMPTION |
| |
| The extension will be ignored during parsing if a previous session is being |
| successfully resumed. |
| |
| =item SSL_EXT_CLIENT_HELLO |
| |
| The extension may be present in the ClientHello message. |
| |
| =item SSL_EXT_TLS1_2_SERVER_HELLO |
| |
| The extension may be present in a TLSv1.2 or below compatible ServerHello |
| message. |
| |
| =item SSL_EXT_TLS1_3_SERVER_HELLO |
| |
| The extension may be present in a TLSv1.3 compatible ServerHello message. |
| |
| =item SSL_EXT_TLS1_3_ENCRYPTED_EXTENSIONS |
| |
| The extension may be present in an EncryptedExtensions message. |
| |
| =item SSL_EXT_TLS1_3_HELLO_RETRY_REQUEST |
| |
| The extension may be present in a HelloRetryRequest message. |
| |
| =item SSL_EXT_TLS1_3_CERTIFICATE |
| |
| The extension may be present in a TLSv1.3 compatible Certificate message. |
| |
| =item SSL_EXT_TLS1_3_NEW_SESSION_TICKET |
| |
| The extension may be present in a TLSv1.3 compatible NewSessionTicket message. |
| |
| =item SSL_EXT_TLS1_3_CERTIFICATE_REQUEST |
| |
| The extension may be present in a TLSv1.3 compatible CertificateRequest message. |
| |
| =back |
| |
| The context must include at least one message value (otherwise the extension |
| will never be used). |
| |
| =head1 NOTES |
| |
| The B<add_arg> and B<parse_arg> parameters can be set to arbitrary values |
| which will be passed to the corresponding callbacks. They can, for example, |
| be used to store the extension data received in a convenient structure or |
| pass the extension data to be added or freed when adding extensions. |
| |
| If the same custom extension type is received multiple times a fatal |
| B<decode_error> alert is sent and the handshake aborts. If a custom extension |
| is received in a ServerHello/EncryptedExtensions message which was not sent in |
| the ClientHello a fatal B<unsupported_extension> alert is sent and the |
| handshake is aborted. The ServerHello/EncryptedExtensions B<add_cb> callback is |
| only called if the corresponding extension was received in the ClientHello. This |
| is compliant with the TLS specifications. This behaviour ensures that each |
| callback is called at most once and that an application can never send |
| unsolicited extensions. |
| |
| =head1 RETURN VALUES |
| |
| SSL_CTX_add_custom_ext(), SSL_CTX_add_client_custom_ext() and |
| SSL_CTX_add_server_custom_ext() return 1 for success and 0 for failure. A |
| failure can occur if an attempt is made to add the same B<ext_type> more than |
| once, if an attempt is made to use an extension type handled internally by |
| OpenSSL or if an internal error occurs (for example a memory allocation |
| failure). |
| |
| SSL_extension_supported() returns 1 if the extension B<ext_type> is handled |
| internally by OpenSSL and 0 otherwise. |
| |
| =head1 SEE ALSO |
| |
| L<ssl(7)> |
| |
| =head1 HISTORY |
| |
| The SSL_CTX_add_custom_ext() function was added in OpenSSL 1.1.1. |
| |
| =head1 COPYRIGHT |
| |
| Copyright 2014-2020 The OpenSSL Project Authors. All Rights Reserved. |
| |
| Licensed under the Apache License 2.0 (the "License"). You may not use |
| this file except in compliance with the License. You can obtain a copy |
| in the file LICENSE in the source distribution or at |
| L<https://www.openssl.org/source/license.html>. |
| |
| =cut |
