Rename SSL_CTX_set_early_cb to SSL_CTX_set_client_hello_cb.

"Early callback" is a little ambiguous now that early data exists.
Perhaps "ClientHello callback"?

Reviewed-by: Rich Salz <rsalz@openssl.org>
Reviewed-by: Ben Kaduk <kaduk@mit.edu>
(Merged from https://github.com/openssl/openssl/pull/4349)

6 files changed, 149 insertions, 142 deletions

diff --git a/doc/man3/SSL_CIPHER_get_name.pod b/doc/man3/SSL_CIPHER_get_name.pod
index c82be8e4e2..b23a38ba6a 100644
--- a/doc/man3/SSL_CIPHER_get_name.pod
+++ b/doc/man3/SSL_CIPHER_get_name.pod
@@ -97,8 +97,9 @@ ChaCha20/Poly1305), and 0 if it is not AEAD.
 SSL_CIPHER_find() returns a B<SSL_CIPHER> structure which has the cipher ID stored
 in B<ptr>. The B<ptr> parameter is a two element array of B<char>, which stores the
 two-byte TLS cipher ID (as allocated by IANA) in network byte order. This parameter
-is usually retrieved from a TLS packet by using functions like L<SSL_early_get0_ciphers(3)>.
-SSL_CIPHER_find() returns NULL if an error occurs or the indicated cipher is not found.
+is usually retrieved from a TLS packet by using functions like
+L<SSL_client_hello_get0_ciphers(3)>.  SSL_CIPHER_find() returns NULL if an
+error occurs or the indicated cipher is not found.
 
 SSL_CIPHER_get_id() returns the OpenSSL-specific ID of the given cipher B<c>. That ID is
 not the same as the IANA-specific ID.
diff --git a/doc/man3/SSL_CTX_set_client_hello_cb.pod b/doc/man3/SSL_CTX_set_client_hello_cb.pod
new file mode 100644
index 0000000000..18bbc2938d
--- /dev/null
+++ b/doc/man3/SSL_CTX_set_client_hello_cb.pod
@@ -0,0 +1,129 @@
+=pod
+
+=head1 NAME
+
+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
+
+=head1 SYNOPSIS
+
+ typedef int (*SSL_client_hello_cb_fn)(SSL *s, int *al, void *arg);
+ void SSL_CTX_set_client_hello_cb(SSL_CTX *c, SSL_client_hello_cb_fn *f,
+                                  void *arg);
+ int SSL_client_hello_isv2(SSL *s);
+ unsigned int SSL_client_hello_get0_legacy_version(SSL *s);
+ size_t SSL_client_hello_get0_random(SSL *s, const unsigned char **out);
+ size_t SSL_client_hello_get0_session_id(SSL *s, const unsigned char **out);
+ size_t SSL_client_hello_get0_ciphers(SSL *s, const unsigned char **out);
+ size_t SSL_client_hello_get0_compression_methods(SSL *s,
+                                                  const unsigned char **out);
+ int SSL_client_hello_get1_extensions_present(SSL *s, int **out,
+                                              size_t *outlen);
+ int SSL_client_hello_get0_ext(SSL *s, int type, const unsigned char **out,
+                               size_t *outlen);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_client_hello_cb() sets the callback function, which is automatically
+called during the early stages of ClientHello processing on the server.
+The argument supplied when setting the callback is passed back to the
+callback at runtime.  A callback that returns failure (0) will cause the
+connection to terminate, and callbacks returning failure should indicate
+what alert value is to be sent in the B<al> parameter.  A callback may
+also return a negative value to suspend the handshake, and the handshake
+function will return immediately.  L<SSL_get_error(3)> will return
+SSL_ERROR_WANT_CLIENT_HELLO_CB to indicate that the handshake was suspended.
+It is the job of the ClientHello callback to store information about the state
+of the last call if needed to continue.  On the next call into the handshake
+function, the ClientHello callback will be called again, and, if it returns
+success, normal handshake processing will continue from that point.
+
+SSL_client_hello_isv2() indicates whether the ClientHello was carried in a
+SSLv2 record and is in the SSLv2 format.  The SSLv2 format has substantial
+differences from the normal SSLv3 format, including using three bytes per
+cipher suite, and not allowing extensions.  Additionally, the SSLv2 format
+'challenge' field is exposed via SSL_client_hello_get0_random(), padded to
+SSL3_RANDOM_SIZE bytes with zeros if needed.  For SSLv2 format ClientHellos,
+SSL_client_hello_get0_compression_methods() returns a dummy list that only includes
+the null compression method, since the SSLv2 format does not include a
+mechanism by which to negotiate compression.
+
+SSL_client_hello_get0_random(), SSL_client_hello_get0_session_id(),
+SSL_client_hello_get0_ciphers(), and
+SSL_client_hello_get0_compression_methods() provide access to the corresponding
+ClientHello fields, returning the field length and optionally setting an out
+pointer to the octets of that field.
+
+Similarly, SSL_client_hello_get0_ext() provides access to individual extensions
+from the ClientHello on a per-extension basis.  For the provided wire
+protocol extension type value, the extension value and length are returned
+in the output parameters (if present).
+
+SSL_client_hello_get1_extensions_present() can be used prior to
+SSL_client_hello_get0_ext(), to determine which extensions are present in the
+ClientHello before querying for them.  The B<out> and B<outlen> parameters are
+both required, and on success the caller must release the storage allocated for
+B<*out> using OPENSSL_free().  The contents of B<*out> is an array of integers
+holding the numerical value of the TLS extension types in the order they appear
+in the ClientHello.  B<*outlen> contains the number of elements in the array.
+
+=head1 NOTES
+
+The ClientHello callback provides a vast window of possibilities for application
+code to affect the TLS handshake.  A primary use of the callback is to
+allow the server to examine the server name indication extension provided
+by the client in order to select an appropriate certificate to present,
+and make other configuration adjustments relevant to that server name
+and its configuration.  Such configuration changes can include swapping out
+the associated SSL_CTX pointer, modifying the server's list of permitted TLS
+versions, changing the server's cipher list in response to the client's
+cipher list, etc.
+
+It is also recommended that applications utilize a ClientHello callback and
+not use a servername callback, in order to avoid unexpected behavior that
+occurs due to the relative order of processing between things like session
+resumption and the historical servername callback.
+
+The SSL_client_hello_* family of functions may only be called from code executing
+within a ClientHello callback.
+
+=head1 RETURN VALUES
+
+The application's supplied ClientHello callback returns 1 on success, 0 on failure,
+and a negative value to suspend processing.
+
+SSL_client_hello_isv2() returns 1 for SSLv2-format ClientHellos and 0 otherwise.
+
+SSL_client_hello_get0_random(), SSL_client_hello_get0_session_id(),
+SSL_client_hello_get0_ciphers(), and
+SSL_client_hello_get0_compression_methods() return the length of the
+corresponding ClientHello fields.  If zero is returned, the output pointer
+should not be assumed to be valid.
+
+SSL_client_hello_get0_ext() returns 1 if the extension of type 'type' is present, and
+0 otherwise.
+
+SSL_client_hello_get1_extensions_present() returns 1 on success and 0 on failure.
+
+=head1 SEE ALSO
+
+L<ssl(7)>, L<SSL_CTX_set_tlsext_servername_callback(3)>,
+L<SSL_bytes_to_cipher_list>
+
+=head1 HISTORY
+
+The SSL ClientHello callback, SSL_client_hello_isv2(),
+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_get0_ext(), and SSL_client_hello_get1_extensions_present()
+were added in OpenSSL 1.1.1.
+
+=head1 COPYRIGHT
+
+Copyright 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
diff --git a/doc/man3/SSL_CTX_set_early_cb.pod b/doc/man3/SSL_CTX_set_early_cb.pod
deleted file mode 100644
index c2b4650a06..0000000000
--- a/doc/man3/SSL_CTX_set_early_cb.pod
+++ /dev/null
@@ -1,123 +0,0 @@
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_early_cb, SSL_early_cb_fn, SSL_early_isv2, SSL_early_get0_legacy_version, SSL_early_get0_random, SSL_early_get0_session_id, SSL_early_get0_ciphers, SSL_early_get0_compression_methods, SSL_early_get1_extensions_present, SSL_early_get0_ext - callback functions for early server-side ClientHello processing
-
-=head1 SYNOPSIS
-
- typedef int (*SSL_early_cb_fn)(SSL *s, int *al, void *arg);
- void SSL_CTX_set_early_cb(SSL_CTX *c, SSL_early_cb_fn *f, void *arg);
- int SSL_early_isv2(SSL *s);
- unsigned int SSL_early_get0_legacy_version(SSL *s);
- size_t SSL_early_get0_random(SSL *s, const unsigned char **out);
- size_t SSL_early_get0_session_id(SSL *s, const unsigned char **out);
- size_t SSL_early_get0_ciphers(SSL *s, const unsigned char **out);
- size_t SSL_early_get0_compression_methods(SSL *s, const unsigned char **out);
- int SSL_early_get1_extensions_present(SSL *s, int **out, size_t *outlen);
- int SSL_early_get0_ext(SSL *s, int type, const unsigned char **out,
-                        size_t *outlen);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_early_cb() sets the callback function, which is automatically
-called during the early stages of ClientHello processing on the server.
-The argument supplied when setting the callback is passed back to the
-callback at runtime.  A callback that returns failure (0) will cause the
-connection to terminate, and callbacks returning failure should indicate
-what alert value is to be sent in the B<al> parameter.  A callback may
-also return a negative value to suspend the handshake, and the handshake
-function will return immediately.  L<SSL_get_error(3)> will return
-SSL_ERROR_WANT_EARLY to indicate that the handshake was suspended.
-It is the job of the early callback to store information about the state
-of the last call if needed to continue.  On the next call into the handshake
-function, the early callback will be called again, and, if it returns
-success, normal handshake processing will continue from that point.
-
-SSL_early_isv2() indicates whether the ClientHello was carried in a
-SSLv2 record and is in the SSLv2 format.  The SSLv2 format has substantial
-differences from the normal SSLv3 format, including using three bytes per
-cipher suite, and not allowing extensions.  Additionally, the SSLv2 format
-'challenge' field is exposed via SSL_early_get0_random(), padded to
-SSL3_RANDOM_SIZE bytes with zeros if needed.  For SSLv2 format ClientHellos,
-SSL_early_get0_compression_methods() returns a dummy list that only includes
-the null compression method, since the SSLv2 format does not include a
-mechanism by which to negotiate compression.
-
-SSL_early_get0_random(), SSL_early_get0_session_id(), SSL_early_get0_ciphers(),
-and SSL_early_get0_compression_methods() provide access to the corresponding
-ClientHello fields, returning the field length and optionally setting an
-out pointer to the octets of that field.
-
-Similarly, SSL_early_get0_ext() provides access to individual extensions
-from the ClientHello on a per-extension basis.  For the provided wire
-protocol extension type value, the extension value and length are returned
-in the output parameters (if present).
-
-SSL_early_get1_extensions_present() can be used prior to SSL_early_get0_ext(),
-to determine which extensions are present in the ClientHello before querying
-for them.  The B<out> and B<outlen> parameters are both required, and on
-success the caller must release the storage allocated for B<*out> using
-OPENSSL_free().  The contents of B<*out> is an array of integers holding the
-numerical value of the TLS extension types in the order they appear in the
-ClientHello.  B<*outlen> contains the number of elements in the array.
-
-=head1 NOTES
-
-The early callback provides a vast window of possibilities for application
-code to affect the TLS handshake.  A primary use of the callback is to
-allow the server to examine the server name indication extension provided
-by the client in order to select an appropriate certificate to present,
-and make other configuration adjustments relevant to that server name
-and its configuration.  Such configuration changes can include swapping out
-the associated SSL_CTX pointer, modifying the server's list of permitted TLS
-versions, changing the server's cipher list in response to the client's
-cipher list, etc.
-
-It is also recommended that applications utilize an early callback and
-not use a servername callback, in order to avoid unexpected behavior that
-occurs due to the relative order of processing between things like session
-resumption and the historical servername callback.
-
-The SSL_early_* family of functions may only be called from code executing
-within an early callback.
-
-=head1 RETURN VALUES
-
-The application's supplied early callback returns 1 on success, 0 on failure,
-and a negative value to suspend processing.
-
-SSL_early_isv2() returns 1 for SSLv2-format ClientHellos and 0 otherwise.
-
-SSL_early_get0_random(), SSL_early_get0_session_id(), SSL_early_get0_ciphers(),
-and SSL_early_get0_compression_methods() return the length of the corresponding
-ClientHello fields.  If zero is returned, the output pointer should not be
-assumed to be valid.
-
-SSL_early_get0_ext() returns 1 if the extension of type 'type' is present, and
-0 otherwise.
-
-SSL_early_get1_extensions_present() returns 1 on success and 0 on failure.
-
-=head1 SEE ALSO
-
-L<ssl(7)>, L<SSL_CTX_set_tlsext_servername_callback(3)>,
-L<SSL_bytes_to_cipher_list>
-
-=head1 HISTORY
-
-The SSL early callback, SSL_early_isv2(), SSL_early_get0_random(),
-SSL_early_get0_session_id(), SSL_early_get0_ciphers(),
-SSL_early_get0_compression_methods(), SSL_early_get0_ext(), and
-SSL_early_get1_extensions_present() were added in OpenSSL 1.1.1.
-
-=head1 COPYRIGHT
-
-Copyright 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
diff --git a/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod b/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod
index 151de16079..b1fb5ab7d9 100644
--- a/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod
+++ b/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod
@@ -21,8 +21,8 @@ SSL_set_tlsext_host_name - handle server name indication (SNI)
 
 =head1 DESCRIPTION
 
-The functionality provided by the servername callback is superseded by
-the early callback, which can be set using SSL_CTX_set_early_cb().
+The functionality provided by the servername callback is superseded by the
+ClientHello callback, which can be set using SSL_CTX_set_client_hello_cb().
 The servername callback is retained for historical compatibility.
 
 SSL_CTX_set_tlsext_servername_callback() sets the application callback B<cb>
@@ -48,8 +48,8 @@ to B<TLSEXT_NAMETYPE_host_name> (defined in RFC3546).
 =head1 NOTES
 
 Several callbacks are executed during ClientHello processing, including
-the early, ALPN, and servername callbacks.  The early callback is executed
-first, then the servername callback, followed by the ALPN callback.
+the ClientHello, ALPN, and servername callbacks.  The ClientHello callback is
+executed first, then the servername callback, followed by the ALPN callback.
 
 The SSL_set_tlsext_host_name() function should only be called on SSL objects
 that will act as clients; otherwise the configured B<name> will be ignored.
@@ -63,7 +63,7 @@ SSL_set_tlsext_host_name() returns 1 on success, 0 in case of error.
 =head1 SEE ALSO
 
 L<ssl(7)>, L<SSL_CTX_set_alpn_select_cb(3)>,
-L<SSL_get0_alpn_selected(3)>, L<SSL_CTX_set_early_cb(3)>
+L<SSL_get0_alpn_selected(3)>, L<SSL_CTX_set_client_hello_cb(3)>
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/SSL_get_error.pod b/doc/man3/SSL_get_error.pod
index efa78ef099..4e26514a22 100644
--- a/doc/man3/SSL_get_error.pod
+++ b/doc/man3/SSL_get_error.pod
@@ -110,10 +110,10 @@ through a call to L<ASYNC_init_thread(3)>. The application should retry the
 operation after a currently executing asynchronous operation for the current
 thread has completed.
 
-=item SSL_ERROR_WANT_EARLY
+=item SSL_ERROR_WANT_CLIENT_HELLO_CB
 
 The operation did not complete because an application callback set by
-SSL_CTX_set_early_cb() has asked to be called again.
+SSL_CTX_set_client_hello_cb() has asked to be called again.
 The TLS/SSL I/O function should be called again later.
 Details depend on the application.
 
@@ -137,7 +137,7 @@ L<ssl(7)>
 =head1 HISTORY
 
 SSL_ERROR_WANT_ASYNC was added in OpenSSL 1.1.0.
-SSL_ERROR_WANT_EARLY was added in OpenSSL 1.1.1.
+SSL_ERROR_WANT_CLIENT_HELLO_CB was added in OpenSSL 1.1.1.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/SSL_want.pod b/doc/man3/SSL_want.pod
index ce21f4790f..ef4b2183e0 100644
--- a/doc/man3/SSL_want.pod
+++ b/doc/man3/SSL_want.pod
@@ -3,8 +3,8 @@
 =head1 NAME
 
 SSL_want, SSL_want_nothing, SSL_want_read, SSL_want_write, SSL_want_x509_lookup,
-SSL_want_async, SSL_want_async_job, SSL_want_early - obtain state information
-TLS/SSL I/O operation
+SSL_want_async, SSL_want_async_job, SSL_want_client_hello_cb - obtain state
+information TLS/SSL I/O operation
 
 =head1 SYNOPSIS
 
@@ -17,7 +17,7 @@ TLS/SSL I/O operation
  int SSL_want_x509_lookup(const SSL *ssl);
  int SSL_want_async(const SSL *ssl);
  int SSL_want_async_job(const SSL *ssl);
- int SSL_want_early(const SSL *ssl);
+ int SSL_want_client_hello_cb(const SSL *ssl);
 
 =head1 DESCRIPTION
 
@@ -82,18 +82,18 @@ The asynchronous job could not be started because there were no async jobs
 available in the pool (see ASYNC_init_thread(3)). A call to L<SSL_get_error(3)>
 should return SSL_ERROR_WANT_ASYNC_JOB.
 
-=item SSL_EARLY_WORK
+=item SSL_CLIENT_HELLO_CB
 
 The operation did not complete because an application callback set by
-SSL_CTX_set_early_cb() has asked to be called again.
+SSL_CTX_set_client_hello_cb() has asked to be called again.
 A call to L<SSL_get_error(3)> should return
-SSL_ERROR_WANT_EARLY.
+SSL_ERROR_WANT_CLIENT_HELLO_CB.
 
 =back
 
 SSL_want_nothing(), SSL_want_read(), SSL_want_write(), SSL_want_x509_lookup(),
-SSL_want_async(), SSL_want_async_job(), and SSL_want_early() return 1, when
-the corresponding condition is true or 0 otherwise.
+SSL_want_async(), SSL_want_async_job(), and SSL_want_client_hello_cb() return
+1, when the corresponding condition is true or 0 otherwise.
 
 =head1 SEE ALSO
 
@@ -101,7 +101,7 @@ L<ssl(7)>, L<SSL_get_error(3)>
 
 =head1 HISTORY
 
-SSL_want_early() and SSL_EARLY_WORK were added in OpenSSL 1.1.1.
+SSL_want_client_hello_cb() and SSL_CLIENT_HELLO_CB were added in OpenSSL 1.1.1.
 
 =head1 COPYRIGHT