1*1dcdf01fSchristos=pod 2*1dcdf01fSchristos 3*1dcdf01fSchristos=head1 NAME 4*1dcdf01fSchristos 5*1dcdf01fSchristosSSL_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 6*1dcdf01fSchristos 7*1dcdf01fSchristos=head1 SYNOPSIS 8*1dcdf01fSchristos 9*1dcdf01fSchristos typedef int (*SSL_client_hello_cb_fn)(SSL *s, int *al, void *arg); 10*1dcdf01fSchristos void SSL_CTX_set_client_hello_cb(SSL_CTX *c, SSL_client_hello_cb_fn *f, 11*1dcdf01fSchristos void *arg); 12*1dcdf01fSchristos int SSL_client_hello_isv2(SSL *s); 13*1dcdf01fSchristos unsigned int SSL_client_hello_get0_legacy_version(SSL *s); 14*1dcdf01fSchristos size_t SSL_client_hello_get0_random(SSL *s, const unsigned char **out); 15*1dcdf01fSchristos size_t SSL_client_hello_get0_session_id(SSL *s, const unsigned char **out); 16*1dcdf01fSchristos size_t SSL_client_hello_get0_ciphers(SSL *s, const unsigned char **out); 17*1dcdf01fSchristos size_t SSL_client_hello_get0_compression_methods(SSL *s, 18*1dcdf01fSchristos const unsigned char **out); 19*1dcdf01fSchristos int SSL_client_hello_get1_extensions_present(SSL *s, int **out, 20*1dcdf01fSchristos size_t *outlen); 21*1dcdf01fSchristos int SSL_client_hello_get0_ext(SSL *s, int type, const unsigned char **out, 22*1dcdf01fSchristos size_t *outlen); 23*1dcdf01fSchristos 24*1dcdf01fSchristos=head1 DESCRIPTION 25*1dcdf01fSchristos 26*1dcdf01fSchristosSSL_CTX_set_client_hello_cb() sets the callback function, which is automatically 27*1dcdf01fSchristoscalled during the early stages of ClientHello processing on the server. 28*1dcdf01fSchristosThe argument supplied when setting the callback is passed back to the 29*1dcdf01fSchristoscallback at runtime. A callback that returns failure (0) will cause the 30*1dcdf01fSchristosconnection to terminate, and callbacks returning failure should indicate 31*1dcdf01fSchristoswhat alert value is to be sent in the B<al> parameter. A callback may 32*1dcdf01fSchristosalso return a negative value to suspend the handshake, and the handshake 33*1dcdf01fSchristosfunction will return immediately. L<SSL_get_error(3)> will return 34*1dcdf01fSchristosSSL_ERROR_WANT_CLIENT_HELLO_CB to indicate that the handshake was suspended. 35*1dcdf01fSchristosIt is the job of the ClientHello callback to store information about the state 36*1dcdf01fSchristosof the last call if needed to continue. On the next call into the handshake 37*1dcdf01fSchristosfunction, the ClientHello callback will be called again, and, if it returns 38*1dcdf01fSchristossuccess, normal handshake processing will continue from that point. 39*1dcdf01fSchristos 40*1dcdf01fSchristosSSL_client_hello_isv2() indicates whether the ClientHello was carried in a 41*1dcdf01fSchristosSSLv2 record and is in the SSLv2 format. The SSLv2 format has substantial 42*1dcdf01fSchristosdifferences from the normal SSLv3 format, including using three bytes per 43*1dcdf01fSchristoscipher suite, and not allowing extensions. Additionally, the SSLv2 format 44*1dcdf01fSchristos'challenge' field is exposed via SSL_client_hello_get0_random(), padded to 45*1dcdf01fSchristosSSL3_RANDOM_SIZE bytes with zeros if needed. For SSLv2 format ClientHellos, 46*1dcdf01fSchristosSSL_client_hello_get0_compression_methods() returns a dummy list that only includes 47*1dcdf01fSchristosthe null compression method, since the SSLv2 format does not include a 48*1dcdf01fSchristosmechanism by which to negotiate compression. 49*1dcdf01fSchristos 50*1dcdf01fSchristosSSL_client_hello_get0_random(), SSL_client_hello_get0_session_id(), 51*1dcdf01fSchristosSSL_client_hello_get0_ciphers(), and 52*1dcdf01fSchristosSSL_client_hello_get0_compression_methods() provide access to the corresponding 53*1dcdf01fSchristosClientHello fields, returning the field length and optionally setting an out 54*1dcdf01fSchristospointer to the octets of that field. 55*1dcdf01fSchristos 56*1dcdf01fSchristosSimilarly, SSL_client_hello_get0_ext() provides access to individual extensions 57*1dcdf01fSchristosfrom the ClientHello on a per-extension basis. For the provided wire 58*1dcdf01fSchristosprotocol extension type value, the extension value and length are returned 59*1dcdf01fSchristosin the output parameters (if present). 60*1dcdf01fSchristos 61*1dcdf01fSchristosSSL_client_hello_get1_extensions_present() can be used prior to 62*1dcdf01fSchristosSSL_client_hello_get0_ext(), to determine which extensions are present in the 63*1dcdf01fSchristosClientHello before querying for them. The B<out> and B<outlen> parameters are 64*1dcdf01fSchristosboth required, and on success the caller must release the storage allocated for 65*1dcdf01fSchristosB<*out> using OPENSSL_free(). The contents of B<*out> is an array of integers 66*1dcdf01fSchristosholding the numerical value of the TLS extension types in the order they appear 67*1dcdf01fSchristosin the ClientHello. B<*outlen> contains the number of elements in the array. 68*1dcdf01fSchristosIn situations when the ClientHello has no extensions, the function will return 69*1dcdf01fSchristossuccess with B<*out> set to NULL and B<*outlen> set to 0. 70*1dcdf01fSchristos 71*1dcdf01fSchristos=head1 NOTES 72*1dcdf01fSchristos 73*1dcdf01fSchristosThe ClientHello callback provides a vast window of possibilities for application 74*1dcdf01fSchristoscode to affect the TLS handshake. A primary use of the callback is to 75*1dcdf01fSchristosallow the server to examine the server name indication extension provided 76*1dcdf01fSchristosby the client in order to select an appropriate certificate to present, 77*1dcdf01fSchristosand make other configuration adjustments relevant to that server name 78*1dcdf01fSchristosand its configuration. Such configuration changes can include swapping out 79*1dcdf01fSchristosthe associated SSL_CTX pointer, modifying the server's list of permitted TLS 80*1dcdf01fSchristosversions, changing the server's cipher list in response to the client's 81*1dcdf01fSchristoscipher list, etc. 82*1dcdf01fSchristos 83*1dcdf01fSchristosIt is also recommended that applications utilize a ClientHello callback and 84*1dcdf01fSchristosnot use a servername callback, in order to avoid unexpected behavior that 85*1dcdf01fSchristosoccurs due to the relative order of processing between things like session 86*1dcdf01fSchristosresumption and the historical servername callback. 87*1dcdf01fSchristos 88*1dcdf01fSchristosThe SSL_client_hello_* family of functions may only be called from code executing 89*1dcdf01fSchristoswithin a ClientHello callback. 90*1dcdf01fSchristos 91*1dcdf01fSchristos=head1 RETURN VALUES 92*1dcdf01fSchristos 93*1dcdf01fSchristosThe application's supplied ClientHello callback returns 94*1dcdf01fSchristosSSL_CLIENT_HELLO_SUCCESS on success, SSL_CLIENT_HELLO_ERROR on failure, and 95*1dcdf01fSchristosSSL_CLIENT_HELLO_RETRY to suspend processing. 96*1dcdf01fSchristos 97*1dcdf01fSchristosSSL_client_hello_isv2() returns 1 for SSLv2-format ClientHellos and 0 otherwise. 98*1dcdf01fSchristos 99*1dcdf01fSchristosSSL_client_hello_get0_random(), SSL_client_hello_get0_session_id(), 100*1dcdf01fSchristosSSL_client_hello_get0_ciphers(), and 101*1dcdf01fSchristosSSL_client_hello_get0_compression_methods() return the length of the 102*1dcdf01fSchristoscorresponding ClientHello fields. If zero is returned, the output pointer 103*1dcdf01fSchristosshould not be assumed to be valid. 104*1dcdf01fSchristos 105*1dcdf01fSchristosSSL_client_hello_get0_ext() returns 1 if the extension of type 'type' is present, and 106*1dcdf01fSchristos0 otherwise. 107*1dcdf01fSchristos 108*1dcdf01fSchristosSSL_client_hello_get1_extensions_present() returns 1 on success and 0 on failure. 109*1dcdf01fSchristos 110*1dcdf01fSchristos=head1 SEE ALSO 111*1dcdf01fSchristos 112*1dcdf01fSchristosL<ssl(7)>, L<SSL_CTX_set_tlsext_servername_callback(3)>, 113*1dcdf01fSchristosL<SSL_bytes_to_cipher_list> 114*1dcdf01fSchristos 115*1dcdf01fSchristos=head1 HISTORY 116*1dcdf01fSchristos 117*1dcdf01fSchristosThe SSL ClientHello callback, SSL_client_hello_isv2(), 118*1dcdf01fSchristosSSL_client_hello_get0_random(), SSL_client_hello_get0_session_id(), 119*1dcdf01fSchristosSSL_client_hello_get0_ciphers(), SSL_client_hello_get0_compression_methods(), 120*1dcdf01fSchristosSSL_client_hello_get0_ext(), and SSL_client_hello_get1_extensions_present() 121*1dcdf01fSchristoswere added in OpenSSL 1.1.1. 122*1dcdf01fSchristos 123*1dcdf01fSchristos=head1 COPYRIGHT 124*1dcdf01fSchristos 125*1dcdf01fSchristosCopyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved. 126*1dcdf01fSchristos 127*1dcdf01fSchristosLicensed under the OpenSSL license (the "License"). You may not use 128*1dcdf01fSchristosthis file except in compliance with the License. You can obtain a copy 129*1dcdf01fSchristosin the file LICENSE in the source distribution or at 130*1dcdf01fSchristosL<https://www.openssl.org/source/license.html>. 131*1dcdf01fSchristos 132*1dcdf01fSchristos=cut 133