From: Dr. David von Oheimb Date: Fri, 11 Apr 2025 17:53:00 +0000 (+0200) Subject: SSL_CTX_set_tlsext_servername_callback.pod: improve doc of SSL_set_tlsext_host_name... X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=edec017c065983525e0f5c31af577d6c602dd2aa;p=thirdparty%2Fopenssl.git 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 Reviewed-by: Eugene Syromiatnikov 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 03d7cb860cf..285d7d57b03 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 +SSL_CTX_set_tlsext_servername_callback() sets the application callback I used by a server to perform any actions or configuration required based on -the servername extension received in the incoming connection. When B +the B extension received in the incoming connection. When I 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 parameter to the callback. By default this +the location pointed to by the I 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 parameter +of the alert should be stored in the location pointed to by the I 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 parameter) for this B. +passed into the callback (via the I parameter) for this B. 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. +is present. +The only type defined in RFC 3546 and supported here is B. -SSL_set_tlsext_host_name() sets the server name indication ClientHello extension -to contain the value B. The type of server name indication extension is set -to B (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 of type B. +If I 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 or +L 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 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 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, L, -L, L +L, L, +L, L, +L, L =head1 HISTORY diff --git a/ssl/s3_lib.c b/ssl/s3_lib.c index e30e56dfeb6..1e2b0523545 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;