|
Packit |
c4476c |
=pod
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 NAME
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_CTX_set_client_hello_cb, SSL_client_hello_cb_fn, SSL_client_hello_isv2, SSL_client_hello_get0_legacy_version, SSL_client_hello_get0_random, SSL_client_hello_get0_session_id, SSL_client_hello_get0_ciphers, SSL_client_hello_get0_compression_methods, SSL_client_hello_get1_extensions_present, SSL_client_hello_get0_ext - callback functions for early server-side ClientHello processing
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SYNOPSIS
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
typedef int (*SSL_client_hello_cb_fn)(SSL *s, int *al, void *arg);
|
|
Packit |
c4476c |
void SSL_CTX_set_client_hello_cb(SSL_CTX *c, SSL_client_hello_cb_fn *f,
|
|
Packit |
c4476c |
void *arg);
|
|
Packit |
c4476c |
int SSL_client_hello_isv2(SSL *s);
|
|
Packit |
c4476c |
unsigned int SSL_client_hello_get0_legacy_version(SSL *s);
|
|
Packit |
c4476c |
size_t SSL_client_hello_get0_random(SSL *s, const unsigned char **out);
|
|
Packit |
c4476c |
size_t SSL_client_hello_get0_session_id(SSL *s, const unsigned char **out);
|
|
Packit |
c4476c |
size_t SSL_client_hello_get0_ciphers(SSL *s, const unsigned char **out);
|
|
Packit |
c4476c |
size_t SSL_client_hello_get0_compression_methods(SSL *s,
|
|
Packit |
c4476c |
const unsigned char **out);
|
|
Packit |
c4476c |
int SSL_client_hello_get1_extensions_present(SSL *s, int **out,
|
|
Packit |
c4476c |
size_t *outlen);
|
|
Packit |
c4476c |
int SSL_client_hello_get0_ext(SSL *s, int type, const unsigned char **out,
|
|
Packit |
c4476c |
size_t *outlen);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 DESCRIPTION
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_CTX_set_client_hello_cb() sets the callback function, which is automatically
|
|
Packit |
c4476c |
called during the early stages of ClientHello processing on the server.
|
|
Packit |
c4476c |
The argument supplied when setting the callback is passed back to the
|
|
Packit |
c4476c |
callback at runtime. A callback that returns failure (0) will cause the
|
|
Packit |
c4476c |
connection to terminate, and callbacks returning failure should indicate
|
|
Packit |
c4476c |
what alert value is to be sent in the B<al> parameter. A callback may
|
|
Packit |
c4476c |
also return a negative value to suspend the handshake, and the handshake
|
|
Packit |
c4476c |
function will return immediately. L<SSL_get_error(3)> will return
|
|
Packit |
c4476c |
SSL_ERROR_WANT_CLIENT_HELLO_CB to indicate that the handshake was suspended.
|
|
Packit |
c4476c |
It is the job of the ClientHello callback to store information about the state
|
|
Packit |
c4476c |
of the last call if needed to continue. On the next call into the handshake
|
|
Packit |
c4476c |
function, the ClientHello callback will be called again, and, if it returns
|
|
Packit |
c4476c |
success, normal handshake processing will continue from that point.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_client_hello_isv2() indicates whether the ClientHello was carried in a
|
|
Packit |
c4476c |
SSLv2 record and is in the SSLv2 format. The SSLv2 format has substantial
|
|
Packit |
c4476c |
differences from the normal SSLv3 format, including using three bytes per
|
|
Packit |
c4476c |
cipher suite, and not allowing extensions. Additionally, the SSLv2 format
|
|
Packit |
c4476c |
'challenge' field is exposed via SSL_client_hello_get0_random(), padded to
|
|
Packit |
c4476c |
SSL3_RANDOM_SIZE bytes with zeros if needed. For SSLv2 format ClientHellos,
|
|
Packit |
c4476c |
SSL_client_hello_get0_compression_methods() returns a dummy list that only includes
|
|
Packit |
c4476c |
the null compression method, since the SSLv2 format does not include a
|
|
Packit |
c4476c |
mechanism by which to negotiate compression.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_client_hello_get0_random(), SSL_client_hello_get0_session_id(),
|
|
Packit |
c4476c |
SSL_client_hello_get0_ciphers(), and
|
|
Packit |
c4476c |
SSL_client_hello_get0_compression_methods() provide access to the corresponding
|
|
Packit |
c4476c |
ClientHello fields, returning the field length and optionally setting an out
|
|
Packit |
c4476c |
pointer to the octets of that field.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Similarly, SSL_client_hello_get0_ext() provides access to individual extensions
|
|
Packit |
c4476c |
from the ClientHello on a per-extension basis. For the provided wire
|
|
Packit |
c4476c |
protocol extension type value, the extension value and length are returned
|
|
Packit |
c4476c |
in the output parameters (if present).
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_client_hello_get1_extensions_present() can be used prior to
|
|
Packit |
c4476c |
SSL_client_hello_get0_ext(), to determine which extensions are present in the
|
|
Packit |
c4476c |
ClientHello before querying for them. The B<out> and B<outlen> parameters are
|
|
Packit |
c4476c |
both required, and on success the caller must release the storage allocated for
|
|
Packit |
c4476c |
B<*out> using OPENSSL_free(). The contents of B<*out> is an array of integers
|
|
Packit |
c4476c |
holding the numerical value of the TLS extension types in the order they appear
|
|
Packit |
c4476c |
in the ClientHello. B<*outlen> contains the number of elements in the array.
|
|
Packit |
c4476c |
In situations when the ClientHello has no extensions, the function will return
|
|
Packit |
c4476c |
success with B<*out> set to NULL and B<*outlen> set to 0.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 NOTES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The ClientHello callback provides a vast window of possibilities for application
|
|
Packit |
c4476c |
code to affect the TLS handshake. A primary use of the callback is to
|
|
Packit |
c4476c |
allow the server to examine the server name indication extension provided
|
|
Packit |
c4476c |
by the client in order to select an appropriate certificate to present,
|
|
Packit |
c4476c |
and make other configuration adjustments relevant to that server name
|
|
Packit |
c4476c |
and its configuration. Such configuration changes can include swapping out
|
|
Packit |
c4476c |
the associated SSL_CTX pointer, modifying the server's list of permitted TLS
|
|
Packit |
c4476c |
versions, changing the server's cipher list in response to the client's
|
|
Packit |
c4476c |
cipher list, etc.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
It is also recommended that applications utilize a ClientHello callback and
|
|
Packit |
c4476c |
not use a servername callback, in order to avoid unexpected behavior that
|
|
Packit |
c4476c |
occurs due to the relative order of processing between things like session
|
|
Packit |
c4476c |
resumption and the historical servername callback.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The SSL_client_hello_* family of functions may only be called from code executing
|
|
Packit |
c4476c |
within a ClientHello callback.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 RETURN VALUES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The application's supplied ClientHello callback returns
|
|
Packit |
c4476c |
SSL_CLIENT_HELLO_SUCCESS on success, SSL_CLIENT_HELLO_ERROR on failure, and
|
|
Packit |
c4476c |
SSL_CLIENT_HELLO_RETRY to suspend processing.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_client_hello_isv2() returns 1 for SSLv2-format ClientHellos and 0 otherwise.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_client_hello_get0_random(), SSL_client_hello_get0_session_id(),
|
|
Packit |
c4476c |
SSL_client_hello_get0_ciphers(), and
|
|
Packit |
c4476c |
SSL_client_hello_get0_compression_methods() return the length of the
|
|
Packit |
c4476c |
corresponding ClientHello fields. If zero is returned, the output pointer
|
|
Packit |
c4476c |
should not be assumed to be valid.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_client_hello_get0_ext() returns 1 if the extension of type 'type' is present, and
|
|
Packit |
c4476c |
0 otherwise.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_client_hello_get1_extensions_present() returns 1 on success and 0 on failure.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SEE ALSO
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
L<ssl(7)>, L<SSL_CTX_set_tlsext_servername_callback(3)>,
|
|
Packit |
c4476c |
L<SSL_bytes_to_cipher_list>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 HISTORY
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The SSL ClientHello callback, SSL_client_hello_isv2(),
|
|
Packit |
c4476c |
SSL_client_hello_get0_random(), SSL_client_hello_get0_session_id(),
|
|
Packit |
c4476c |
SSL_client_hello_get0_ciphers(), SSL_client_hello_get0_compression_methods(),
|
|
Packit |
c4476c |
SSL_client_hello_get0_ext(), and SSL_client_hello_get1_extensions_present()
|
|
Packit |
c4476c |
were added in OpenSSL 1.1.1.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 COPYRIGHT
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Licensed under the OpenSSL license (the "License"). You may not use
|
|
Packit |
c4476c |
this file except in compliance with the License. You can obtain a copy
|
|
Packit |
c4476c |
in the file LICENSE in the source distribution or at
|
|
Packit |
c4476c |
L<https://www.openssl.org/source/license.html>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=cut
|