SSL_CTX_set_tlsext_servername_callback.pod: improve doc of SSL_set_tlsext_host_name...

Add recommendation to use it for TLS clients, together with X509_VERIFY_PARAM_{set1,add1}_host()

Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Eugene Syromiatnikov <esyr@openssl.org>
MergeDate: Wed Jun 10 06:26:57 2026
(Merged from https://github.com/openssl/openssl/pull/27357)

diff --git a/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod b/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod
index 03d7cb860cf789fcfaf0d7fee0a1ed5bd067c0d8..285d7d57b0382ae1d3eba3934cfa53401295c1a1 100644 (file)
--- a/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod
+++ b/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod
@@ -26,9 +26,9 @@ the ClientHello callback, which can be set using SSL_CTX_set_client_hello_cb().
 However, even where the ClientHello callback is used, the servername callback is
 still necessary in order to acknowledge the servername requested by the client.
 
-SSL_CTX_set_tlsext_servername_callback() sets the application callback B<cb>
+SSL_CTX_set_tlsext_servername_callback() sets the application callback I<cb>
 used by a server to perform any actions or configuration required based on
-the servername extension received in the incoming connection. When B<cb>
+the B<servername> extension received in the incoming connection. When I<cb>
 is NULL, SNI is not used. Note that this callback occurs late in the processing
 of the ClientHello message. In particular it happens after session resumption
 has occurred, and so typically this callback should not call functions such
@@ -49,14 +49,14 @@ up a different configuration for the selected servername in this case.
 
 In this case the servername requested by the client is not accepted and the
 handshake will be aborted. The value of the alert to be used should be stored in
-the location pointed to by the B<al> parameter to the callback. By default this
+the location pointed to by the I<al> parameter to the callback. By default this
 value is initialised to SSL_AD_UNRECOGNIZED_NAME.
 
 =item SSL_TLSEXT_ERR_ALERT_WARNING
 
 If this value is returned then the servername is not accepted by the server.
 However, the handshake will continue and send a warning alert instead. The value
-of the alert should be stored in the location pointed to by the B<al> parameter
+of the alert should be stored in the location pointed to by the I<al> parameter
 as for SSL_TLSEXT_ERR_ALERT_FATAL above. Note that TLSv1.3 does not support
 warning alerts, so if TLSv1.3 has been negotiated then this return value is
 treated the same way as SSL_TLSEXT_ERR_NOACK.
@@ -69,7 +69,7 @@ No alerts are sent and the server will not acknowledge the requested servername.
 =back
 
 SSL_CTX_set_tlsext_servername_arg() sets a context-specific argument to be
-passed into the callback (via the B<arg> parameter) for this B<SSL_CTX>.
+passed into the callback (via the I<arg> parameter) for this B<SSL_CTX>.
 
 The behaviour of SSL_get_servername() depends on a number of different factors.
 In particular note that in TLSv1.3 the servername is negotiated in every
@@ -127,12 +127,21 @@ client is processed. The servername, certificate and ALPN callbacks occur after
 a servername extension from the client is processed.
 
 SSL_get_servername_type() returns the servername type or -1 if no servername
-is present. Currently the only supported type (defined in RFC3546) is
-B<TLSEXT_NAMETYPE_host_name>.
+is present.
+The only type defined in RFC 3546 and supported here is B<TLSEXT_NAMETYPE_host_name>.
 
-SSL_set_tlsext_host_name() sets the server name indication ClientHello extension
-to contain the value B<name>. The type of server name indication extension is set
-to B<TLSEXT_NAMETYPE_host_name> (defined in RFC3546).
+SSL_set_tlsext_host_name() sets the Server Name Indication (SNI)
+ClientHello extension defined in RFC 3546 section 3.1
+to contain the value I<name> of type B<TLSEXT_NAMETYPE_host_name>.
+If I<name> is NULL, it clears the SNI extension.
+
+Using this function may also be important for correct routing of connection requests.
+TLS clients should call this function alongside L<SSL_set1_dnsname(3)> or
+L<SSL_add1_dnsname(3)> to set the expected server hostname(s) for certificate validation.
+
+The SSL_set_tlsext_host_name() function should only be called on SSL objects
+that will act as clients; otherwise, the configured I<name> will be ignored.
+In the future, calling this function on the server side may result in an error.
 
 =head1 NOTES
 
@@ -140,9 +149,6 @@ Several callbacks are executed during ClientHello processing, including
 the ClientHello, ALPN, and servername callbacks.  The ClientHello callback is
 executed first, then the servername callback, followed by the ALPN callback.
 
-The SSL_set_tlsext_host_name() function should only be called on SSL objects
-that will act as clients; otherwise the configured B<name> will be ignored.
-
 =head1 RETURN VALUES
 
 SSL_CTX_set_tlsext_servername_callback() and
@@ -152,7 +158,9 @@ SSL_set_tlsext_host_name() returns 1 on success, 0 in case of error.
 =head1 SEE ALSO
 
 L<ssl(7)>, L<SSL_CTX_set_alpn_select_cb(3)>,
-L<SSL_get0_alpn_selected(3)>, L<SSL_CTX_set_client_hello_cb(3)>
+L<SSL_get0_alpn_selected(3)>, L<SSL_CTX_set_client_hello_cb(3)>,
+L<SSL_set1_dnsname(3)>, L<SSL_add1_dnsname(3)>,
+L<X509_VERIFY_PARAM_set1_host(3)>, L<X509_VERIFY_PARAM_add1_host(3)>
 
 =head1 HISTORY
 

diff --git a/ssl/s3_lib.c b/ssl/s3_lib.c
index e30e56dfeb6baf51cd8a9a4a18b4f52a92343f36..1e2b05235456f9f6a75981b7b6cdf1214e57ca5c 100644 (file)
--- a/ssl/s3_lib.c
+++ b/ssl/s3_lib.c
@@ -4025,8 +4025,7 @@ long ssl3_ctrl(SSL *s, int cmd, long larg, void *parg)
          * from the server, but we currently allow it to be used on servers
          * as well, which is a programming error.  Currently we just clear
          * the field in SSL_do_handshake() for server SSLs, but when we can
-         * make ABI-breaking changes, we may want to make use of this API
-         * an error on server SSLs.
+         * make ABI-breaking changes, we may want to return an error in this case.
          */
         if (larg == TLSEXT_NAMETYPE_host_name) {
             size_t len;