Remove the dead store in EVP_DecryptFinal_ex

[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 6824b5b8d1a4c36b36d07b9dccda73c76c82bdd3..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,12 +137,14 @@ 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 OpenSSL license (the "License").  You may not use
+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
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.