Note about different exclusion of GREASE extensions

Different SSL_client_hello_* functions have different behavior
in regards to GREASE extensions.

Fixes #27580

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/29066)

(cherry picked from commit 657b01241feeb23a53378920bf33d59505532ba8)

diff --git a/doc/man3/SSL_CTX_set_client_hello_cb.pod b/doc/man3/SSL_CTX_set_client_hello_cb.pod
index 74468ab8ac15655ba918c72d3fabcf868d636007..6367c68a62502cb7a491777000991ef0847b6265 100644 (file)
--- a/doc/man3/SSL_CTX_set_client_hello_cb.pod
+++ b/doc/man3/SSL_CTX_set_client_hello_cb.pod
@@ -69,6 +69,9 @@ 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.
 In situations when the ClientHello has no extensions, the function will return
 success with B<*out> set to NULL and B<*outlen> set to 0.
+Note that SSL_client_hello_get1_extensions_present() returns only recognised
+extensions; therefore, unrecognised (including GREASE) extensions will not
+appear in the output.
 
 SSL_client_hello_get_extension_order() is similar to
 SSL_client_hello_get1_extensions_present(), without internal memory allocation.
@@ -101,8 +104,12 @@ 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.
+The SSL_client_hello_* family of functions may only be called from code
+executing within a ClientHello callback.
+
+The SSL_client_hello_get0_*() functions return raw ClientHello data, whereas
+SSL_client_hello_get1_extensions_present() returns only recognized extensions
+(so unknown/GREASE-extensions are not included).
 
 =head1 RETURN VALUES