-.\" $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>.
.\" 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
.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
.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.
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 .
-.\" $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
.\" 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
.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
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
.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
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.
.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 .
projects / openbsd / commitdiff