diff options
Diffstat (limited to 'doc/man3/SSL_shutdown.pod')
| -rw-r--r-- | doc/man3/SSL_shutdown.pod | 82 |
1 files changed, 40 insertions, 42 deletions
diff --git a/doc/man3/SSL_shutdown.pod b/doc/man3/SSL_shutdown.pod index a77721c85269..6797006a283e 100644 --- a/doc/man3/SSL_shutdown.pod +++ b/doc/man3/SSL_shutdown.pod @@ -15,8 +15,6 @@ SSL_shutdown - shut down a TLS/SSL connection SSL_shutdown() shuts down an active TLS/SSL connection. It sends the close_notify shutdown alert to the peer. -=head1 NOTES - SSL_shutdown() tries to send the close_notify shutdown alert to the peer. Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and a currently open session is considered closed and good and will be kept in the @@ -52,6 +50,44 @@ SSL_shutdown() only closes the write direction. It is not possible to call SSL_write() after calling SSL_shutdown(). The read direction is closed by the peer. +The behaviour of SSL_shutdown() additionally depends on the underlying BIO. +If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the +handshake step has been finished or an error occurred. + +If the underlying BIO is B<nonblocking>, SSL_shutdown() will also return +when the underlying BIO could not satisfy the needs of SSL_shutdown() +to continue the handshake. In this case a call to SSL_get_error() with the +return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or +B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after +taking appropriate action to satisfy the needs of SSL_shutdown(). +The action depends on the underlying BIO. When using a nonblocking socket, +nothing is to be done, but select() can be used to check for the required +condition. When using a buffering BIO, like a BIO pair, data must be written +into or retrieved out of the BIO before being able to continue. + +After SSL_shutdown() returned 0, it is possible to call SSL_shutdown() again +to wait for the peer's close_notify alert. +SSL_shutdown() will return 1 in that case. +However, it is recommended to wait for it using SSL_read() instead. + +SSL_shutdown() can be modified to only set the connection to "shutdown" +state but not actually send the close_notify alert messages, +see L<SSL_CTX_set_quiet_shutdown(3)>. +When "quiet shutdown" is enabled, SSL_shutdown() will always succeed +and return 1. +Note that this is not standard compliant behaviour. +It should only be done when the peer has a way to make sure all +data has been received and doesn't wait for the close_notify alert +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. +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 When the application is the first party to send the close_notify @@ -89,44 +125,6 @@ If successful, SSL_shutdown() will return 1. Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the SSL_get_shutdown() (see also L<SSL_set_shutdown(3)> call. -=head1 NOTES - -The behaviour of SSL_shutdown() additionally depends on the underlying BIO. -If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the -handshake step has been finished or an error occurred. - -If the underlying BIO is B<nonblocking>, SSL_shutdown() will also return -when the underlying BIO could not satisfy the needs of SSL_shutdown() -to continue the handshake. In this case a call to SSL_get_error() with the -return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or -B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after -taking appropriate action to satisfy the needs of SSL_shutdown(). -The action depends on the underlying BIO. When using a nonblocking socket, -nothing is to be done, but select() can be used to check for the required -condition. When using a buffering BIO, like a BIO pair, data must be written -into or retrieved out of the BIO before being able to continue. - -After SSL_shutdown() returned 0, it is possible to call SSL_shutdown() again -to wait for the peer's close_notify alert. -SSL_shutdown() will return 1 in that case. -However, it is recommended to wait for it using SSL_read() instead. - -SSL_shutdown() can be modified to only set the connection to "shutdown" -state but not actually send the close_notify alert messages, -see L<SSL_CTX_set_quiet_shutdown(3)>. -When "quiet shutdown" is enabled, SSL_shutdown() will always succeed -and return 1. -Note that this is not standard compliant behaviour. -It should only be done when the peer has a way to make sure all -data has been received and doesn't wait for the close_notify alert -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. - =head1 RETURN VALUES The following return values can occur: @@ -163,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)> @@ -171,7 +169,7 @@ L<ssl(7)>, L<bio(7)> Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. -Licensed under the OpenSSL license (the "License"). You may not use +Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at L<https://www.openssl.org/source/license.html>. |