diff options
author | Phus Lu <phus.lu@gmail.com> | 2021-10-25 18:47:00 +0800 |
---|---|---|
committer | Tomas Mraz <tomas@openssl.org> | 2022-02-03 13:45:41 +0100 |
commit | 13a53fbf13bc6fa09c95ad4bdc6ec70fa15aa16d (patch) | |
tree | 34c712b39eae57857d9b3b60abd7d8f59c9cdca5 /doc | |
parent | 27aca04e13ca8a9bead49de7bc380110ecb7064e (diff) |
add SSL_get0_iana_groups() & SSL_client_hello_get_extension_order()
The function/macro allow user get groups/extensions without memory allcations.
So we could calculate the ssl fignerprint(ja3) in low cost.
Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/16910)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/SSL_CTX_set1_curves.pod | 17 | ||||
-rw-r--r-- | doc/man3/SSL_CTX_set_client_hello_cb.pod | 22 |
2 files changed, 35 insertions, 4 deletions
diff --git a/doc/man3/SSL_CTX_set1_curves.pod b/doc/man3/SSL_CTX_set1_curves.pod index cbd8f71346..d24db8f812 100644 --- a/doc/man3/SSL_CTX_set1_curves.pod +++ b/doc/man3/SSL_CTX_set1_curves.pod @@ -3,9 +3,10 @@ =head1 NAME SSL_CTX_set1_groups, SSL_CTX_set1_groups_list, SSL_set1_groups, -SSL_set1_groups_list, SSL_get1_groups, SSL_get_shared_group, -SSL_get_negotiated_group, SSL_CTX_set1_curves, SSL_CTX_set1_curves_list, -SSL_set1_curves, SSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve +SSL_set1_groups_list, SSL_get1_groups, SSL_get0_iana_groups, +SSL_get_shared_group, SSL_get_negotiated_group, SSL_CTX_set1_curves, +SSL_CTX_set1_curves_list, SSL_set1_curves, SSL_set1_curves_list, +SSL_get1_curves, SSL_get_shared_curve - EC supported curve functions =head1 SYNOPSIS @@ -19,6 +20,7 @@ SSL_set1_curves, SSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve int SSL_set1_groups_list(SSL *ssl, char *list); int SSL_get1_groups(SSL *ssl, int *groups); + int SSL_get0_iana_groups(SSL *ssl, uint16_t **out); int SSL_get_shared_group(SSL *s, int n); int SSL_get_negotiated_group(SSL *s); @@ -68,6 +70,13 @@ order. It can return zero if the client did not send a supported groups extension. If a supported group NID is unknown then the value is set to the bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the group. +SSL_get0_iana_groups() retrieves the list of groups sent by the +client in the supported_groups extension. The B<*out> array of bytes +is populated with the host-byte-order representation of the uint16_t group +identifiers, as assigned by IANA. The group list is returned in the same order +that was received in the ClientHello. The return value is the number of groups, +not the number of bytes written. + SSL_get_shared_group() returns the NID of the shared group B<n> for a server-side SSL B<ssl>. If B<n> is -1 then the total number of shared groups is returned, which may be zero. Other than for diagnostic purposes, @@ -108,6 +117,8 @@ SSL_set1_groups_list(), return 1 for success and 0 for failure. SSL_get1_groups() returns the number of groups, which may be zero. +SSL_get0_iana_groups() returns the number of (uint16_t) groups, which may be zero. + SSL_get_shared_group() returns the NID of shared group B<n> or NID_undef if there is no shared group B<n>; or the total number of shared groups if B<n> is -1. diff --git a/doc/man3/SSL_CTX_set_client_hello_cb.pod b/doc/man3/SSL_CTX_set_client_hello_cb.pod index f324647abc..dc882a12e6 100644 --- a/doc/man3/SSL_CTX_set_client_hello_cb.pod +++ b/doc/man3/SSL_CTX_set_client_hello_cb.pod @@ -2,7 +2,7 @@ =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 +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_get_extension_order, SSL_client_hello_get0_ext - callback functions for early server-side ClientHello processing =head1 SYNOPSIS @@ -18,6 +18,8 @@ SSL_CTX_set_client_hello_cb, SSL_client_hello_cb_fn, SSL_client_hello_isv2, SSL_ const unsigned char **out); int SSL_client_hello_get1_extensions_present(SSL *s, int **out, size_t *outlen); + int SSL_client_hello_get_extension_order(SSL *s, uint16_t *exts, + size_t *num_exts); int SSL_client_hello_get0_ext(SSL *s, unsigned int type, const unsigned char **out, size_t *outlen); @@ -68,6 +70,20 @@ 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. +SSL_client_hello_get_extension_order() is similar to +SSL_client_hello_get1_extensions_present(), without internal memory allocation. +When called with B<exts> set to NULL, returns the number of extensions +(e.g., to allocate storage for a subsequent call). Otherwise, B<*exts> is populated +with the ExtensionType values in the order that the corresponding extensions +appeared in the ClientHello. B<*num_exts> is an input/output parameter, used +as input to supply the size of storage allocated by the caller, and as output to +indicate how many ExtensionType values were written. If the input B<*num_exts> +is smaller then the number of extensions in question, that is treated as an error. +A subsequent call with B<exts> set to NULL can retrieve the size of storage needed. +A ClientHello that contained no extensions is treated as success, with B<*num_exts> +set to 0. + + =head1 NOTES The ClientHello callback provides a vast window of possibilities for application @@ -107,6 +123,8 @@ SSL_client_hello_get0_ext() returns 1 if the extension of type 'type' is present SSL_client_hello_get1_extensions_present() returns 1 on success and 0 on failure. +SSL_client_hello_get_extension_order() returns 1 on success and 0 on failure. + =head1 SEE ALSO L<ssl(7)>, L<SSL_CTX_set_tlsext_servername_callback(3)>, @@ -119,6 +137,8 @@ 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. +SSL_client_hello_get_extension_order() +was added in OpenSSL 3.1.0. =head1 COPYRIGHT |