From 86484520bb9fdf67e7e47b29f0fed6ff22b63378 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sun, 24 Oct 2021 15:10:13 +0000 Subject: 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 --- src/lib/libssl/man/SSL_read.3 | 66 ++++++++++++++++++---- src/lib/libssl/man/SSL_write.3 | 125 ++++++++++++++++++++++++----------------- 2 files changed, 130 insertions(+), 61 deletions(-) (limited to 'src/lib/libssl/man') 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 and .\" Matt Caswell . @@ -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 . -.\" Copyright (c) 2000, 2001, 2002 The OpenSSL Project. All rights reserved. +.\" This file was written by Lutz Jaenicke +.\" and Matt Caswell . +.\" 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 . -- cgit v1.2.3-55-g6feb