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

2 files changed, 130 insertions, 61 deletions

diff --git a/src/lib/libssl/man/SSL_read.3 b/src/lib/libssl/man/SSL_read.3
index ea181ce15c..bb72a8ed82 100644
--- a/src/lib/libssl/man/SSL_read.3
+++ b/src/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 .
diff --git a/src/lib/libssl/man/SSL_write.3 b/src/lib/libssl/man/SSL_write.3
index 16be55f259..2c6fbcef08 100644
--- a/src/lib/libssl/man/SSL_write.3
+++ b/src/lib/libssl/man/SSL_write.3
@@ -1,8 +1,11 @@
-.\"     $OpenBSD: SSL_write.3,v 1.6 2020/10/08 16:02:38 tb Exp $
-.\"     OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
+.\" $OpenBSD: SSL_write.3,v 1.7 2021/10/24 15:10:13 schwarze Exp $
+.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
+.\" partial merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
-.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
-.\" Copyright (c) 2000, 2001, 2002 The OpenSSL Project.  All rights reserved.
+.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>
+.\" and Matt Caswell <matt@openssl.org>.
+.\" Copyright (c) 2000, 2001, 2002, 2016 The OpenSSL Project.
+.\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -48,59 +51,67 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: October 8 2020 $
+.Dd $Mdocdate: October 24 2021 $
 .Dt SSL_WRITE 3
 .Os
 .Sh NAME
+.Nm SSL_write_ex ,
 .Nm SSL_write
-.Nd write bytes to a TLS/SSL connection
+.Nd write bytes to a TLS connection
 .Sh SYNOPSIS
 .In openssl/ssl.h
 .Ft int
+.Fn SSL_write_ex "SSL *ssl" "const void *buf" "size_t num" "size_t *written"
+.Ft int
 .Fn SSL_write "SSL *ssl" "const void *buf" "int num"
 .Sh DESCRIPTION
+.Fn SSL_write_ex
+and
 .Fn SSL_write
-writes
+write
 .Fa num
 bytes from the buffer
 .Fa buf
 into the specified
 .Fa ssl
 connection.
+On success
+.Fn SSL_write_ex
+stores the number of bytes written in
+.Pf * Fa written .
 .Pp
-If necessary,
+In the following,
+.Fn SSL_write_ex
+and
 .Fn SSL_write
-will negotiate a TLS/SSL session, if not already explicitly performed by
+are called
+.Dq write functions .
+.Pp
+If necessary, a write function negotiates a TLS session,
+if not already explicitly performed by
 .Xr SSL_connect 3
 or
 .Xr SSL_accept 3 .
 If the peer requests a re-negotiation,
 it will be performed transparently during the
-.Fn SSL_write
-operation.
-The behaviour of
-.Fn SSL_write
-depends on the underlying
+write function operation.
+The behaviour of the write functions depends on the underlying
 .Vt BIO .
 .Pp
 For the transparent negotiation to succeed, the
 .Fa ssl
 must have been initialized to client or server mode.
-This is being done by calling
+This is done by calling
 .Xr SSL_set_connect_state 3
 or
 .Xr SSL_set_accept_state 3
-before the first call to an
-.Xr SSL_read 3
-or
-.Fn SSL_write
-function.
+before the first call to a write function.
 .Pp
 If the underlying
 .Vt BIO
 is
 .Em blocking ,
-.Fn SSL_write
+the write function
 will only return once the write operation has been finished or an error
 occurred, except when a renegotiation takes place, in which case a
 .Dv SSL_ERROR_WANT_READ
@@ -115,26 +126,19 @@ If the underlying
 .Vt BIO
 is
 .Em non-blocking ,
-.Fn SSL_write
-will also return when the underlying
+the write function will also return when the underlying
 .Vt BIO
-could not satisfy the needs of
-.Fn SSL_write
-to continue the operation.
+could not satisfy the needs of the function to continue the operation.
 In this case a call to
 .Xr SSL_get_error 3
-with the return value of
-.Fn SSL_write
-will yield
+with the return value of the write function will yield
 .Dv SSL_ERROR_WANT_READ
 or
 .Dv SSL_ERROR_WANT_WRITE .
 As at any time a re-negotiation is possible, a call to
-.Fn SSL_write
-can also cause read operations!
+a write function can also cause read operations.
 The calling process then must repeat the call after taking appropriate action
-to satisfy the needs of
-.Fn SSL_write .
+to satisfy the needs of the write function.
 The action depends on the underlying
 .Vt BIO .
 When using a non-blocking socket, nothing is to be done, but
@@ -147,7 +151,7 @@ like a
 pair, data must be written into or retrieved out of the BIO before being able
 to continue.
 .Pp
-.Fn SSL_write
+The write functions
 will only return with success when the complete contents of
 .Fa buf
 of length
@@ -157,23 +161,15 @@ This default behaviour can be changed with the
 .Dv SSL_MODE_ENABLE_PARTIAL_WRITE
 option of
 .Xr SSL_CTX_set_mode 3 .
-When this flag is set,
-.Fn SSL_write
-will also return with success when a partial write has been successfully
-completed.
-In this case the
-.Fn SSL_write
-operation is considered completed.
-The bytes are sent and a new
-.Fn SSL_write
-operation with a new buffer (with the already sent bytes removed) must be
-started.
+When this flag is set, the write functions will also return with
+success when a partial write has been successfully completed.
+In this case the write function operation is considered completed.
+The bytes are sent and a new write call with a new buffer (with the
+already sent bytes removed) must be started.
 A partial write is performed with the size of a message block,
 which is 16kB.
 .Pp
-When an
-.Fn SSL_write
-operation has to be repeated because
+When a write function call has to be repeated because
 .Xr SSL_get_error 3
 returned
 .Dv SSL_ERROR_WANT_READ
@@ -186,12 +182,37 @@ When calling
 with
 .Fa num Ns =0
 bytes to be sent, the behaviour is undefined.
+.Fn SSL_write_ex
+can be called with
+.Fa num Ns =0 ,
+but will not send application data to the peer.
 .Sh RETURN VALUES
-The following return values can occur:
+.Fn SSL_write_ex
+returns 1 for success or 0 for failure.
+Success means that all requested application data bytes have been
+written to the TLS connection or, if
+.Dv SSL_MODE_ENABLE_PARTIAL_WRITE
+is in use, at least one application data byte has been written
+to the TLS connection.
+Failure means that not all the requested bytes have been written yet (if
+.Dv SSL_MODE_ENABLE_PARTIAL_WRITE
+is not in use) or no bytes could be written to the TLS connection (if
+.Dv SSL_MODE_ENABLE_PARTIAL_WRITE
+is in use).
+Failures can be retryable (e.g. the network write buffer has temporarily
+filled up) 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_write ,
+the following return values can occur:
 .Bl -tag -width Ds
 .It >0
 The write operation was successful.
-The return value is the number of bytes actually written to the TLS/SSL
+The return value is the number of bytes actually written to the TLS
 connection.
 .It 0
 The write operation was not successful.
@@ -222,3 +243,7 @@ with the return value to find out the reason.
 .Fn SSL_write
 appeared in SSLeay 0.4 or earlier and has been available since
 .Ox 2.4 .
+.Pp
+.Fn SSL_write_ex
+first appeared in OpenSSL 1.1.1 and has been available since
+.Ox 7.1 .