diff options
author | Ingo Schwarze <schwarze@cvs.openbsd.org> | 2021-10-24 15:10:14 +0000 |
---|---|---|
committer | Ingo Schwarze <schwarze@cvs.openbsd.org> | 2021-10-24 15:10:14 +0000 |
commit | 52ddd3f732e761cf64e8ed545f0f31374734d955 (patch) | |
tree | 3fef6b574a05d879c1fb760ddc1910ffa1bbe296 /lib/libssl/man/SSL_read.3 | |
parent | bfb08069538b0c18730e583fbcbcea4be1d05207 (diff) |
merge documentation for SSL_read_ex(3), SSL_peek_ex(3), and SSL_write_ex(3)
from the OpenSSL 1.1.1 branch, which is still under a free license
Diffstat (limited to 'lib/libssl/man/SSL_read.3')
-rw-r--r-- | lib/libssl/man/SSL_read.3 | 66 |
1 files changed, 55 insertions, 11 deletions
diff --git a/lib/libssl/man/SSL_read.3 b/lib/libssl/man/SSL_read.3 index ea181ce15c5..bb72a8ed824 100644 --- a/lib/libssl/man/SSL_read.3 +++ b/lib/libssl/man/SSL_read.3 @@ -1,6 +1,6 @@ -.\" $OpenBSD: SSL_read.3,v 1.7 2020/05/26 19:45:58 schwarze Exp $ -.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 -.\" partial merge up to: OpenSSL 18bad535 Apr 9 15:13:55 2019 +0100 +.\" $OpenBSD: SSL_read.3,v 1.8 2021/10/24 15:10:13 schwarze Exp $ +.\" full merge up to: OpenSSL 5a2443ae Nov 14 11:37:36 2016 +0000 +.\" partial merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 .\" .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org> and .\" Matt Caswell <matt@openssl.org>. @@ -51,38 +51,59 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: May 26 2020 $ +.Dd $Mdocdate: October 24 2021 $ .Dt SSL_READ 3 .Os .Sh NAME +.Nm SSL_read_ex , .Nm SSL_read , +.Nm SSL_peek_ex , .Nm SSL_peek .Nd read bytes from a TLS connection .Sh SYNOPSIS .In openssl/ssl.h .Ft int +.Fn SSL_read_ex "SSL *ssl" "void *buf" "size_t num" "size_t *readbytes" +.Ft int .Fn SSL_read "SSL *ssl" "void *buf" "int num" .Ft int +.Fn SSL_peek_ex "SSL *ssl" "void *buf" "size_t num" "size_t *readbytes" +.Ft int .Fn SSL_peek "SSL *ssl" "void *buf" "int num" .Sh DESCRIPTION +.Fn SSL_read_ex +and .Fn SSL_read -tries to read +try to read .Fa num bytes from the specified .Fa ssl into the buffer .Fa buf . +On success +.Fn SSL_read_ex +stores the number of bytes actually read in +.Pf * Fa readbytes . .Pp +.Fn SSL_peek_ex +and .Fn SSL_peek -is identical to -.Fn SSL_read +are identical to +.Fn SSL_read_ex +and +.Fn SSL_read , +respectively, except that no bytes are removed from the underlying BIO during the read, such that a subsequent call to +.Fn SSL_read_ex +or .Fn SSL_read will yield at least the same bytes once again. .Pp In the following, -.Fn SSL_read +.Fn SSL_read_ex , +.Fn SSL_read , +.Fn SSL_peek_ex , and .Fn SSL_peek are called @@ -107,11 +128,11 @@ or .Xr SSL_set_accept_state 3 before the first call to a read function. .Pp -The read functions works based on the TLS records. +The read functions work based on the TLS records. The data are received in records (with a maximum record size of 16kB). Only when a record has been completely received, it can be processed (decrypted and checked for integrity). -Therefore data that was not retrieved at the last read call can +Therefore, data that was not retrieved at the last read call can still be buffered inside the TLS layer and will be retrieved on the next read call. If @@ -182,7 +203,24 @@ or .Dv SSL_ERROR_WANT_WRITE , it must be repeated with the same arguments. .Sh RETURN VALUES -The following return values can occur: +.Fn SSL_read_ex +and +.Fn SSL_peek_ex +return 1 for success or 0 for failure. +Success means that one or more application data bytes +have been read from the SSL connection. +Failure means that no bytes could be read from the SSL connection. +Failures can be retryable (e.g. we are waiting for more bytes to be +delivered by the network) or non-retryable (e.g. a fatal network error). +In the event of a failure, call +.Xr SSL_get_error 3 +to find out the reason which indicates whether the call is retryable or not. +.Pp +For +.Fn SSL_read +and +.Fn SSL_peek , +the following return values can occur: .Bl -tag -width Ds .It >0 The read operation was successful. @@ -232,3 +270,9 @@ appeared in SSLeay 0.4 or earlier. first appeared in SSLeay 0.6.6. Both functions have been available since .Ox 2.4 . +.Pp +.Fn SSL_read_ex +and +.Fn SSL_peek_ex +first appeared in OpenSSL 1.1.1 and have been available since +.Ox 7.1 . |