diff options
author | Dmitry Belyavskiy <beldmit@gmail.com> | 2020-05-05 16:20:42 +0300 |
---|---|---|
committer | Dmitry Belyavskiy <beldmit@gmail.com> | 2020-05-19 19:04:11 +0300 |
commit | 09b90e0ed7915809fcd4ee1e250d881b77d06d45 (patch) | |
tree | 897a351d8f49b6f575bf54bba4dd486b00ad31f7 /doc | |
parent | fb420afc878fa38a5d8cf22e25cf7d438d39987a (diff) |
Introducing option SSL_OP_IGNORE_UNEXPECTED_EOF
Partially fixes #11209.
Before OpenSSL 3.0 in case when peer does not send close_notify,
the behaviour was to set SSL_ERROR_SYSCALL error with errno 0.
This behaviour has changed. The SSL_OP_IGNORE_UNEXPECTED_EOF restores
the old behaviour for compatibility's sake.
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Kurt Roeckx <kurt@roeckx.be>
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/11735)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man1/openssl-s_client.pod.in | 10 | ||||
-rw-r--r-- | doc/man1/openssl-s_server.pod.in | 10 | ||||
-rw-r--r-- | doc/man3/SSL_CTX_set_options.pod | 19 | ||||
-rw-r--r-- | doc/man3/SSL_get_error.pod | 12 | ||||
-rw-r--r-- | doc/man3/SSL_shutdown.pod | 8 |
5 files changed, 54 insertions, 5 deletions
diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in index 4d6b54a5e3..367e59e925 100644 --- a/doc/man1/openssl-s_client.pod.in +++ b/doc/man1/openssl-s_client.pod.in @@ -78,6 +78,7 @@ B<openssl> B<s_client> [B<-split_send_frag>] [B<-max_pipelines>] [B<-read_buf>] +[B<-ignore_unexpected_eof>] [B<-bugs>] [B<-comp>] [B<-no_comp>] @@ -578,6 +579,15 @@ effect if the buffer size is larger than the size that would otherwise be used and pipelining is in use (see L<SSL_CTX_set_default_read_buffer_len(3)> for further information). +=item B<-ignore_unexpected_eof> + +Some TLS implementations do not send the mandatory close_notify alert on +shutdown. If the application tries to wait for the close_notify alert but the +peer closes the connection without sending it, an error is generated. When this +option is enabled the peer does not need to send the close_notify alert and a +closed connection will be treated as if the close_notify alert was received. +For more information on shutting down a connection, see L<SSL_shutdown(3)>. + =item B<-bugs> There are several known bugs in SSL and TLS implementations. Adding this diff --git a/doc/man1/openssl-s_server.pod.in b/doc/man1/openssl-s_server.pod.in index 8e5da51c40..28ef15ea56 100644 --- a/doc/man1/openssl-s_server.pod.in +++ b/doc/man1/openssl-s_server.pod.in @@ -47,6 +47,7 @@ B<openssl> B<s_server> [B<-WWW>] [B<-http_server_binmode>] [B<-no_ca_names>] +[B<-ignore_unexpected_eof>] [B<-servername>] [B<-servername_fatal>] [B<-tlsextdebug>] @@ -420,6 +421,15 @@ Disable TLS Extension CA Names. You may want to disable it for security reasons or for compatibility with some Windows TLS implementations crashing when this extension is larger than 1024 bytes. +=item B<-ignore_unexpected_eof> + +Some TLS implementations do not send the mandatory close_notify alert on +shutdown. If the application tries to wait for the close_notify alert but the +peer closes the connection without sending it, an error is generated. When this +option is enabled the peer does not need to send the close_notify alert and a +closed connection will be treated as if the close_notify alert was received. +For more information on shutting down a connection, see L<SSL_shutdown(3)>. + =item B<-id_prefix> I<val> Generate SSL/TLS session IDs prefixed by I<val>. This is mostly useful diff --git a/doc/man3/SSL_CTX_set_options.pod b/doc/man3/SSL_CTX_set_options.pod index 39cb2ec30e..24bf66ad85 100644 --- a/doc/man3/SSL_CTX_set_options.pod +++ b/doc/man3/SSL_CTX_set_options.pod @@ -217,6 +217,20 @@ not propose, and servers will not accept the extension. Disable all renegotiation in TLSv1.2 and earlier. Do not send HelloRequest messages, and ignore renegotiation requests via ClientHello. +=item SSL_OP_IGNORE_UNEXPECTED_EOF + +Some TLS implementations do not send the mandatory close_notify alert on +shutdown. If the application tries to wait for the close_notify alert but the +peer closes the connection without sending it, an error is generated. When this +option is enabled the peer does not need to send the close_notify alert and a +closed connection will be treated as if the close_notify alert was received. + +You should only enable this option if the protocol running over TLS +can detect a truncation attack itself, and that the application is checking for +that truncation attack. + +For more information on shutting down a connection, see L<SSL_shutdown(3)>. + =item SSL_OP_ALLOW_NO_DHE_KEX In TLSv1.3 allow a non-(ec)dhe based key exchange mode on resumption. This means @@ -367,7 +381,7 @@ secure renegotiation and 0 if it does not. =head1 SEE ALSO -L<ssl(7)>, L<SSL_new(3)>, L<SSL_clear(3)>, +L<ssl(7)>, L<SSL_new(3)>, L<SSL_clear(3)>, L<SSL_shutdown(3)> L<SSL_CTX_set_tmp_dh_callback(3)>, L<SSL_CTX_set_min_proto_version(3)>, L<openssl-dhparam(1)> @@ -380,7 +394,8 @@ OpenSSL 0.9.8m. The B<SSL_OP_PRIORITIZE_CHACHA> and B<SSL_OP_NO_RENEGOTIATION> options were added in OpenSSL 1.1.1. -The B<SSL_OP_NO_EXTENDED_MASTER_SECRET> option was added in OpenSSL 3.0. +The B<SSL_OP_NO_EXTENDED_MASTER_SECRET> and B<SSL_OP_IGNORE_UNEXPECTED_EOF> +options were added in OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man3/SSL_get_error.pod b/doc/man3/SSL_get_error.pod index 8d081a5e0d..f13f3ea468 100644 --- a/doc/man3/SSL_get_error.pod +++ b/doc/man3/SSL_get_error.pod @@ -25,6 +25,15 @@ other OpenSSL function calls should appear in between. The current thread's error queue must be empty before the TLS/SSL I/O operation is attempted, or SSL_get_error() will not work reliably. +=head1 NOTES + +Some TLS implementations do not send a close_notify alert on shutdown. + +On an unexpected EOF, versions before OpenSSL 3.0 returned +B<SSL_ERROR_SYSCALL>, nothing was added to the error stack, and errno was 0. +Since OpenSSL 3.0 the returned error is B<SSL_ERROR_SSL> with a meaningful +error on the error stack. + =head1 RETURN VALUES The following return values can currently occur: @@ -44,6 +53,9 @@ No more data can be read. Note that B<SSL_ERROR_ZERO_RETURN> does not necessarily indicate that the underlying transport has been closed. +This error can also appear when the option B<SSL_OP_IGNORE_UNEXPECTED_EOF> +is set. See L<SSL_CTX_set_options(3)> for more details. + =item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE The operation did not complete and can be retried later. diff --git a/doc/man3/SSL_shutdown.pod b/doc/man3/SSL_shutdown.pod index 25191130ae..34469bae37 100644 --- a/doc/man3/SSL_shutdown.pod +++ b/doc/man3/SSL_shutdown.pod @@ -83,8 +83,10 @@ message, otherwise an unexpected EOF will be reported. There are implementations that do not send the required close_notify alert. If there is a need to communicate with such an implementation, and it's clear that all data has been received, do not wait for the peer's close_notify alert. -Waiting for the close_notify alert when the peer just closes the connection will -result in an error being generated. +Waiting for the close_notify alert when the peer just closes the connection +will result in an error being generated. +The error can be ignored using the B<SSL_OP_IGNORE_UNEXPECTED_EOF>. +For more information see L<SSL_CTX_set_options(3)>. =head2 First to close the connection @@ -159,7 +161,7 @@ It can also occur when not all data was read using SSL_read(). L<SSL_get_error(3)>, L<SSL_connect(3)>, L<SSL_accept(3)>, L<SSL_set_shutdown(3)>, -L<SSL_CTX_set_quiet_shutdown(3)>, +L<SSL_CTX_set_quiet_shutdown(3)>, L<SSL_CTX_set_options(3)> L<SSL_clear(3)>, L<SSL_free(3)>, L<ssl(7)>, L<bio(7)> |