diff options
Diffstat (limited to 'doc/man3/SSL_shutdown.pod')
| -rw-r--r-- | doc/man3/SSL_shutdown.pod | 24 |
1 files changed, 18 insertions, 6 deletions
diff --git a/doc/man3/SSL_shutdown.pod b/doc/man3/SSL_shutdown.pod index 732e5ada04ae..a77721c85269 100644 --- a/doc/man3/SSL_shutdown.pod +++ b/doc/man3/SSL_shutdown.pod @@ -95,13 +95,13 @@ 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<non-blocking>, SSL_shutdown() will also return +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 non-blocking socket, +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. @@ -116,6 +116,16 @@ 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 @@ -128,8 +138,10 @@ The following return values can occur: The shutdown is not yet finished: the close_notify was sent but the peer did not send it back yet. Call SSL_read() to do a bidirectional shutdown. -The output of L<SSL_get_error(3)> may be misleading, as an -erroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred. + +Unlike most other function, returning 0 does not indicate an error. +L<SSL_get_error(3)> should not get called, it may misleadingly +indicate an error even though no error occurred. =item Z<>1 @@ -140,7 +152,7 @@ and the peer's close_notify alert was received. The shutdown was not successful. Call L<SSL_get_error(3)> with the return value B<ret> to find out the reason. -It can occur if an action is needed to continue the operation for non-blocking +It can occur if an action is needed to continue the operation for nonblocking BIOs. It can also occur when not all data was read using SSL_read(). @@ -157,7 +169,7 @@ L<ssl(7)>, L<bio(7)> =head1 COPYRIGHT -Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy |