Fix potential memory leak in OSSL_IETF_ATTR_SYNTAX_add1_value()

[openssl.git] / doc / man3 / SSL_CTX_set_client_hello_cb.pod

diff --git a/doc/man3/SSL_CTX_set_client_hello_cb.pod b/doc/man3/SSL_CTX_set_client_hello_cb.pod
index b8dad37adabbe0d867720df72446ea49c0182e41..74468ab8ac15655ba918c72d3fabcf868d636007 100644 (file)
--- 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,7 +18,9 @@ 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_get0_ext(SSL *s, int type, const unsigned char **out,
+ 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);
 
 =head1 DESCRIPTION
@@ -26,7 +28,7 @@ SSL_CTX_set_client_hello_cb, SSL_client_hello_cb_fn, SSL_client_hello_isv2, SSL_
 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
+callback at run time.  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
@@ -65,6 +67,22 @@ 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.
+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
 
@@ -105,10 +123,12 @@ 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)>,
-L<SSL_bytes_to_cipher_list>
+L<SSL_bytes_to_cipher_list(3)>
 
 =head1 HISTORY
 
@@ -117,10 +137,12 @@ 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.2.0.
 
 =head1 COPYRIGHT
 
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2022 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy