Commit edec017c06 for openssl.org
commit edec017c065983525e0f5c31af577d6c602dd2aa
Author: Dr. David von Oheimb <dev@ddvo.net>
Date: Fri Apr 11 19:53:00 2025 +0200
SSL_CTX_set_tlsext_servername_callback.pod: improve doc of SSL_set_tlsext_host_name(); update format
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 03d7cb860c..285d7d57b0 100644
--- 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 e30e56dfeb..1e2b052354 100644
--- 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;