cd17bb190c
Reviewed-by: Rich Salz <rsalz@openssl.org> (Merged from https://github.com/openssl/openssl/pull/3139)
291 lines
12 KiB
Text
291 lines
12 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
SSL_extension_supported,
|
|
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 HISTORY
|
|
|
|
The function SSL_CTX_add_custom_ext() was added in OpenSSL version 1.1.1.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2014-2017 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
|
Licensed under the OpenSSL license (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
|