GH-71 Expose rest of SSL_CTX_set_client_hello_cb family of functions.

Also update tests in 48_client_hello_callback.t and documentation in
SSLeay.pod.

Author: h-vn

Changes

@@ -30,6 +30,29 @@ Revision history for Perl extension Net::SSLeay.
 	  Update the previous minor releases to their latest versions. Add
 	  NetBSD to BSDs job and update the other BSDs and Alpine Linux jobs to
 	  cover additional and latest releases. Use the latest MacOS runners.
+	- Expose SSL_CTX_set_client_hello_cb for setting a callback
+	  the server calls when it processes a ClientHello. Expose the
+	  following functions that can be called only from the
+	  callback.
+	  - 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_get_extension_order
+	  - SSL_client_hello_get0_ext
+	- Expose constants used by SSL_CTX_set_client_hello_cb related
+          functions:
+	  - AD_ prefixed constants naming TLS alert codes for
+	    returning from a ClientHello callback or where alert types
+	    are used
+	  - CLIENT_HELLO_ERROR, CLIENT_HELLO_RETRY and
+	    CLIENT_HELLO_SUCCESS for returning from a ClientHello
+	    callback
+	  - TLSEXT_TYPE_ prefixed contants for naming TLS extension
+	    types
 
 1.93_02 2023-02-22
 	- Update ppport.h to version 3.68. This eliminates thousands of

SSLeay.xs

@@ -5896,6 +5896,112 @@ SSL_CTX_set_client_hello_cb(SSL_CTX *ctx, SV *callback, SV *arg=&PL_sv_undef)
 int
 SSL_client_hello_isv2(SSL *s)
 
+unsigned int
+SSL_client_hello_get0_legacy_version(SSL *s)
+
+void
+SSL_client_hello_get0_random(SSL *s)
+    PREINIT:
+	const unsigned char *out = NULL;
+	size_t outlen;
+    CODE:
+	outlen = SSL_client_hello_get0_random(s, &out);
+	if (outlen == 0) XSRETURN_PV("");
+	ST(0) = sv_newmortal();
+	sv_setpvn(ST(0), (const char *)out, (STRLEN)outlen);
+
+void
+SSL_client_hello_get0_session_id(SSL *s)
+    PREINIT:
+	const unsigned char *out = NULL;
+	size_t outlen;
+    CODE:
+	outlen = SSL_client_hello_get0_session_id(s, &out);
+	if (outlen == 0) XSRETURN_PV("");
+	ST(0) = sv_newmortal();
+	sv_setpvn(ST(0), (const char *)out, (STRLEN)outlen);
+
+void
+SSL_client_hello_get0_ciphers(SSL *s)
+    PREINIT:
+	const unsigned char *out = NULL;
+	size_t outlen;
+    CODE:
+	outlen = SSL_client_hello_get0_ciphers(s, &out);
+	if (outlen == 0) XSRETURN_PV("");
+	ST(0) = sv_newmortal();
+	sv_setpvn(ST(0), (const char *)out, (STRLEN)outlen);
+
+void
+SSL_client_hello_get0_compression_methods(SSL *s)
+    PREINIT:
+	const unsigned char *out = NULL;
+	size_t outlen;
+    CODE:
+	outlen = SSL_client_hello_get0_compression_methods(s, &out);
+	if (outlen == 0) XSRETURN_PV("");
+	ST(0) = sv_newmortal();
+	sv_setpvn(ST(0), (const char *)out, (STRLEN)outlen);
+
+void
+SSL_client_hello_get1_extensions_present(SSL *s)
+    PREINIT:
+	int ret, *out = NULL, i;
+	size_t outlen;
+	AV *av;
+    PPCODE:
+	ret = SSL_client_hello_get1_extensions_present(s, &out, &outlen);
+	if (ret != 1) XSRETURN_UNDEF;
+
+	av = newAV();
+	mXPUSHs(newRV_noinc((SV*)av));
+	for (i=0; i < outlen; i++) {
+	    av_push(av, newSViv(*(out + i)));
+	}
+	OPENSSL_free(out);
+
+#if OPENSSL_VERSION_NUMBER >= 0x30200000L && !defined(LIBRESSL_VERSION_NUMBER)
+
+void
+SSL_client_hello_get_extension_order(SSL *s)
+    PREINIT:
+	int ret, i;
+	uint16_t *exts;
+	size_t num_exts;
+	AV *av;
+    PPCODE:
+	ret = SSL_client_hello_get_extension_order(s, NULL, &num_exts);
+	if (ret != 1) XSRETURN_UNDEF;
+
+	Newx(exts, num_exts, uint16_t);
+	ret = SSL_client_hello_get_extension_order(s, exts, &num_exts);
+	if (ret != 1) {
+	    Safefree(exts);
+	    XSRETURN_UNDEF;
+	}
+
+	av = newAV();
+	mXPUSHs(newRV_noinc((SV*)av));
+	for (i=0; i < num_exts; i++) {
+	    av_push(av, newSViv(*(exts + i)));
+	}
+	Safefree(exts);
+
+#endif
+
+void
+SSL_client_hello_get0_ext(SSL *s, unsigned int type)
+    PREINIT:
+	int ret;
+	const unsigned char *out = NULL;
+	size_t outlen;
+    CODE:
+	ret = SSL_client_hello_get0_ext(s, type, &out, &outlen);
+	if (ret != 1) XSRETURN_UNDEF;
+
+	ST(0) = sv_newmortal();
+	sv_setpvn(ST(0), (const char *)out, (STRLEN)outlen);
+
 #endif
 
 int

lib/Net/SSLeay.pod

@@ -5510,6 +5510,91 @@ Indicate if the ClientHello was carried in a SSLv2 record and is in the SSLv2 fo
 
 Check openssl doc L<https://www.openssl.org/docs/manmaster/man3/SSL_client_hello_isv2.html>
 
+=item * client_hello_get0_legacy_version
+
+B<COMPATIBILITY:> not available in Net-SSLeay-1.92 and before; requires at least OpenSSL 1.1.1pre1, not in LibreSSL
+
+B<NOTE:> to be used only from a callback set with L<CTX_set_client_hello_cb>.
+
+Returns legacy_version, also known as client_version, field from the ClientHello.
+
+ my $rv = client_hello_get0_legacy_version($s);
+ # $s - value corresponding to openssl's SSL structure
+ #
+ # returns: unsigned integer, for example 0x0303 (TLS v1.2) with TLS 1.3
+
+Check openssl doc L<https://www.openssl.org/docs/manmaster/man3/SSL_client_hello_get0_legacy_version.html>
+
+=item * client_hello_get0_random, client_hello_get0_session_id, client_hello_get0_ciphers and client_hello_get0_compression_methods
+
+B<COMPATIBILITY:> not available in Net-SSLeay-1.92 and before; requires at least OpenSSL 1.1.1pre1, not in LibreSSL
+
+B<NOTE:> to be used only from a callback set with L<CTX_set_client_hello_cb>.
+
+These functions return random, session_id, cipher_suites and compression_methods fields from the ClientHello, respectively.
+
+ my $random = client_hello_get0_random($s);
+ my $session_id = client_hello_get0_session_id($s);
+ my $ciphers = client_hello_get0_ciphers($s);
+ my $compression_methods = client_hello_get0_compression_methods($s);
+ # $s - value corresponding to openssl's SSL structure
+ #
+ # returns: raw octet data where data length, zero or more, depends on the field definition
+
+Check openssl doc L<https://www.openssl.org/docs/manmaster/man3/SSL_client_hello_get0_random.html>
+
+=item * client_hello_get1_extensions_present and client_hello_get_extension_order
+
+B<COMPATIBILITY:> not available in Net-SSLeay-1.92 and before; requires at least OpenSSL 1.1.1pre1, not in LibreSSL
+
+B<NOTE:> to be used only from a callback set with L<CTX_set_client_hello_cb>.
+
+Returns a reference to an array holding the numerical value of the TLS extension types in the order they appear in the ClientHello. client_hello_get_extension_order is similar and requires at least OpenSSL 3.2.0, not in LibreSSL.
+
+ my $ref = client_hello_get1_extensions_present($s);
+ # $s - value corresponding to openssl's SSL structure
+ #
+ # returns: an array reference of zero or more extension types or undef on failure
+
+Example from a TLS 1.3 ClientHello:
+
+ sub client_hello_cb {
+    my ($ssl, $arg) = @_;
+    my $ref = client_hello_get1_extensions_present($ssl);
+    print join(' ', @$ref), "\n" if $ref;
+  }
+
+Prints: C<11 10 35 22 23 13 43 45 51>
+
+Check openssl doc L<https://www.openssl.org/docs/manmaster/man3/SSL_client_hello_get1_extensions_present.html>
+
+
+=item * client_hello_get0_ext
+
+B<COMPATIBILITY:> not available in Net-SSLeay-1.92 and before; requires at least OpenSSL 1.1.1pre1, not in LibreSSL
+
+B<NOTE:> to be used only from a callback set with L<CTX_set_client_hello_cb>.
+
+Returns an extension by type number from the ClientHello.
+
+ my $ref = client_hello_get1_extensions_present($s, $type);
+ # $s - value corresponding to openssl's SSL structure
+ # $type - (integer) extension type number
+ #
+ # returns: zero or more octets of extension contents including extension length, undef if the extension is not present
+
+Example: Get the value of TLS extension C<supported_versions>. You can use constant C<TLSEXT_TYPE_supported_versions> or 43 directly.
+
+ sub client_hello_cb {
+    my ($ssl, $arg) = @_;
+    my $ext_ver = Net::SSLeay::client_hello_get0_ext($ssl, Net::SSLeay::TLSEXT_TYPE_supported_versions());
+    print unpack('H*', $ext_ver), "\n" if defined $ext_ver;
+  }
+
+Prints: C<080304030303020301> where the first octet 0x08 is the extension length and the following four 16bit values correspond to TLS versions 1.3, 1.2, 1.1 and 1.0.
+
+Check openssl doc L<https://www.openssl.org/docs/manmaster/man3/SSL_client_hello_get0_ext.html>
+
 =back
 
 =head3 Low level API: RAND_* related functions