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_write.3 | 125 ++++++++++++++++++++++++----------------- 1 file changed, 75 insertions(+), 50 deletions(-) (limited to 'src/lib/libssl/man/SSL_write.3') 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