diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/SSL_CTX_set_tlsext_servername_callback.3')
-rw-r--r-- | secure/lib/libcrypto/man/man3/SSL_CTX_set_tlsext_servername_callback.3 | 103 |
1 files changed, 91 insertions, 12 deletions
diff --git a/secure/lib/libcrypto/man/man3/SSL_CTX_set_tlsext_servername_callback.3 b/secure/lib/libcrypto/man/man3/SSL_CTX_set_tlsext_servername_callback.3 index cd619b0f5a97..a95f0a2f9211 100644 --- a/secure/lib/libcrypto/man/man3/SSL_CTX_set_tlsext_servername_callback.3 +++ b/secure/lib/libcrypto/man/man3/SSL_CTX_set_tlsext_servername_callback.3 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.39) +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== @@ -133,7 +133,7 @@ .\" ======================================================================== .\" .IX Title "SSL_CTX_SET_TLSEXT_SERVERNAME_CALLBACK 3" -.TH SSL_CTX_SET_TLSEXT_SERVERNAME_CALLBACK 3 "2019-09-10" "1.1.1d" "OpenSSL" +.TH SSL_CTX_SET_TLSEXT_SERVERNAME_CALLBACK 3 "2020-03-17" "1.1.1e" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -146,7 +146,7 @@ SSL_CTX_set_tlsext_servername_callback, SSL_CTX_set_tlsext_servername_arg, SSL_g \& #include <openssl/ssl.h> \& \& long SSL_CTX_set_tlsext_servername_callback(SSL_CTX *ctx, -\& int (*cb)(SSL *, int *, void *)); +\& int (*cb)(SSL *s, int *al, void *arg)); \& long SSL_CTX_set_tlsext_servername_arg(SSL_CTX *ctx, void *arg); \& \& const char *SSL_get_servername(const SSL *s, const int type); @@ -156,21 +156,84 @@ SSL_CTX_set_tlsext_servername_callback, SSL_CTX_set_tlsext_servername_arg, SSL_g .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" -The functionality provided by the servername callback is superseded by the -ClientHello callback, which can be set using \fBSSL_CTX_set_client_hello_cb()\fR. -The servername callback is retained for historical compatibility. +The functionality provided by the servername callback is mostly superseded by +the ClientHello callback, which can be set using \fBSSL_CTX_set_client_hello_cb()\fR. +However, even where the ClientHello callback is used, the servername callback is +still necessary in order to acknowledge the servername requested by the client. .PP \&\fBSSL_CTX_set_tlsext_servername_callback()\fR sets the application callback \fBcb\fR used by a server to perform any actions or configuration required based on the servername extension received in the incoming connection. When \fBcb\fR -is \s-1NULL, SNI\s0 is not used. The \fBarg\fR value is a pointer which is passed to -the application callback. +is \s-1NULL, SNI\s0 is not used. +.PP +The servername callback should return one of the following values: +.IP "\s-1SSL_TLSEXT_ERR_OK\s0" 4 +.IX Item "SSL_TLSEXT_ERR_OK" +This is used to indicate that the servername requested by the client has been +accepted. Typically a server will call \fBSSL_set_SSL_CTX()\fR in the callback to set +up a different configuration for the selected servername in this case. +.IP "\s-1SSL_TLSEXT_ERR_ALERT_FATAL\s0" 4 +.IX Item "SSL_TLSEXT_ERR_ALERT_FATAL" +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 \fBal\fR parameter to the callback. By default this +value is initialised to \s-1SSL_AD_UNRECOGNIZED_NAME.\s0 +.IP "\s-1SSL_TLSEXT_ERR_ALERT_WARNING\s0" 4 +.IX 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 \fBal\fR parameter +as for \s-1SSL_TLSEXT_ERR_ALERT_FATAL\s0 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 \s-1SSL_TLSEXT_ERR_NOACK.\s0 +.IP "\s-1SSL_TLSEXT_ERR_NOACK\s0" 4 +.IX Item "SSL_TLSEXT_ERR_NOACK" +This return value indicates that the servername is not accepted by the server. +No alerts are sent and the server will not acknowledge the requested servername. .PP \&\fBSSL_CTX_set_tlsext_servername_arg()\fR sets a context-specific argument to be -passed into the callback for this \fB\s-1SSL_CTX\s0\fR. +passed into the callback (via the \fBarg\fR parameter) for this \fB\s-1SSL_CTX\s0\fR. +.PP +The behaviour of \fBSSL_get_servername()\fR depends on a number of different factors. +In particular note that in TLSv1.3 the servername is negotiated in every +handshake. In TLSv1.2 the servername is only negotiated on initial handshakes +and not on resumption handshakes. +.IP "On the client, before the handshake" 4 +.IX Item "On the client, before the handshake" +If a servername has been set via a call to \fBSSL_set_tlsext_host_name()\fR then it +will return that servername. +.Sp +If one has not been set, but a TLSv1.2 resumption is being attempted and the +session from the original handshake had a servername accepted by the server then +it will return that servername. +.Sp +Otherwise it returns \s-1NULL.\s0 +.IP "On the client, during or after the handshake and a TLSv1.2 (or below) resumption occurred" 4 +.IX Item "On the client, during or after the handshake and a TLSv1.2 (or below) resumption occurred" +If the session from the orignal handshake had a servername accepted by the +server then it will return that servername. +.Sp +Otherwise it returns the servername set via \fBSSL_set_tlsext_host_name()\fR or \s-1NULL\s0 +if it was not called. +.IP "On the client, during or after the handshake and a TLSv1.2 (or below) resumption did not occur" 4 +.IX Item "On the client, during or after the handshake and a TLSv1.2 (or below) resumption did not occur" +It will return the servername set via \fBSSL_set_tlsext_host_name()\fR or \s-1NULL\s0 if it +was not called. +.IP "On the server, before the handshake" 4 +.IX Item "On the server, before the handshake" +The function will always return \s-1NULL\s0 before the handshake +.IP "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption occurred" 4 +.IX Item "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption occurred" +If a servername was accepted by the server in the original handshake then it +will return that servername, or \s-1NULL\s0 otherwise. +.IP "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption did not occur" 4 +.IX Item "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption did not occur" +The function will return the servername requested by the client in this +handshake or \s-1NULL\s0 if none was requested. .PP -\&\fBSSL_get_servername()\fR returns a servername extension value of the specified -type if provided in the Client Hello or \s-1NULL.\s0 +Note that the ClientHello callback occurs before a servername extension from the +client is processed. The servername, certificate and \s-1ALPN\s0 callbacks occur after +a servername extension from the client is processed. .PP \&\fBSSL_get_servername_type()\fR returns the servername type or \-1 if no servername is present. Currently the only supported type (defined in \s-1RFC3546\s0) is @@ -196,9 +259,25 @@ that will act as clients; otherwise the configured \fBname\fR will be ignored. .IX Header "SEE ALSO" \&\fBssl\fR\|(7), \fBSSL_CTX_set_alpn_select_cb\fR\|(3), \&\fBSSL_get0_alpn_selected\fR\|(3), \fBSSL_CTX_set_client_hello_cb\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\fBSSL_get_servername()\fR historically provided some unexpected results in certain +corner cases. This has been fixed from OpenSSL 1.1.1e. +.PP +Prior to 1.1.1e, when the client requested a servername in an initial TLSv1.2 +handshake, the server accepted it, and then the client successfully resumed but +set a different explict servername in the second handshake then when called by +the client it returned the servername from the second handshake. This has now +been changed to return the servername requested in the original handshake. +.PP +Also prior to 1.1.1e, if the client sent a servername in the first handshake but +the server did not accept it, and then a second handshake occured where TLSv1.2 +resumption was successful then when called by the server it returned the +servername requested in the original handshake. This has now been changed to +\&\s-1NULL.\s0 .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved. .PP Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy |