From eb8dd9dca1228af0cd132f515509051ecfabf6f6 Mon Sep 17 00:00:00 2001 From: cvs2svn Date: Mon, 14 Apr 2025 17:32:06 +0000 Subject: This commit was manufactured by cvs2git to create tag 'tb_20250414'. --- src/lib/libssl/man/SSL_read.3 | 278 ------------------------------------------ 1 file changed, 278 deletions(-) delete mode 100644 src/lib/libssl/man/SSL_read.3 (limited to 'src/lib/libssl/man/SSL_read.3') diff --git a/src/lib/libssl/man/SSL_read.3 b/src/lib/libssl/man/SSL_read.3 deleted file mode 100644 index bb72a8ed82..0000000000 --- a/src/lib/libssl/man/SSL_read.3 +++ /dev/null @@ -1,278 +0,0 @@ -.\" $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 . -.\" Copyright (c) 2000, 2001, 2008, 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 -.\" are met: -.\" -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in -.\" the documentation and/or other materials provided with the -.\" distribution. -.\" -.\" 3. All advertising materials mentioning features or use of this -.\" software must display the following acknowledgment: -.\" "This product includes software developed by the OpenSSL Project -.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" -.\" -.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to -.\" endorse or promote products derived from this software without -.\" prior written permission. For written permission, please contact -.\" openssl-core@openssl.org. -.\" -.\" 5. Products derived from this software may not be called "OpenSSL" -.\" nor may "OpenSSL" appear in their names without prior written -.\" permission of the OpenSSL Project. -.\" -.\" 6. Redistributions of any form whatsoever must retain the following -.\" acknowledgment: -.\" "This product includes software developed by the OpenSSL Project -.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY -.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR -.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT -.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, -.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED -.\" OF THE POSSIBILITY OF SUCH DAMAGE. -.\" -.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 -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 -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_ex , -.Fn SSL_read , -.Fn SSL_peek_ex , -and -.Fn SSL_peek -are called -.Dq read functions . -.Pp -If necessary, a read function will negotiate 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 read function operation. -The behaviour of the read 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 done by calling -.Xr SSL_set_connect_state 3 -or -.Xr SSL_set_accept_state 3 -before the first call to a read function. -.Pp -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 -still be buffered inside the TLS layer and will be retrieved on the -next read call. -If -.Fa num -is higher than the number of bytes buffered, the read functions -will return with the bytes buffered. -If no more bytes are in the buffer, the read functions will trigger -the processing of the next record. -Only when the record has been received and processed completely -will the read functions return reporting success. -At most the contents of the record will be returned. -As the size of a TLS record may exceed the maximum packet size -of the underlying transport (e.g., TCP), it may be necessary to -read several packets from the transport layer before the record is -complete and the read call can succeed. -.Pp -If the underlying -.Vt BIO -is blocking, -a read function will only return once the read operation has been -finished or an error occurred, except when a renegotiation takes -place, in which case an -.Dv SSL_ERROR_WANT_READ -may occur. -This behavior can be controlled with the -.Dv SSL_MODE_AUTO_RETRY -flag of the -.Xr SSL_CTX_set_mode 3 -call. -.Pp -If the underlying -.Vt BIO -is non-blocking, a read function will also return when the underlying -.Vt BIO -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 the read function will yield -.Dv SSL_ERROR_WANT_READ -or -.Dv SSL_ERROR_WANT_WRITE . -As at any time a re-negotiation is possible, a read function may -also cause write operations. -The calling process must then repeat the call after taking appropriate -action to satisfy the needs of the read function. -The action depends on the underlying -.Vt BIO . -When using a non-blocking socket, nothing is to be done, but -.Xr select 2 -can be used to check for the required condition. -When using a buffering -.Vt BIO , -like a -.Vt BIO -pair, data must be written into or retrieved out of the -.Vt BIO -before being able to continue. -.Pp -.Xr SSL_pending 3 -can be used to find out whether there are buffered bytes available for -immediate retrieval. -In this case a read function can be called without blocking or -actually receiving new data from the underlying socket. -.Pp -When a read function operation has to be repeated because of -.Dv SSL_ERROR_WANT_READ -or -.Dv SSL_ERROR_WANT_WRITE , -it must be repeated with the same arguments. -.Sh RETURN VALUES -.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. -The return value is the number of bytes actually read from the -TLS connection. -.It 0 -The read operation was not successful. -The reason may either be a clean shutdown due to a -.Dq close notify -alert sent by the peer (in which case the -.Dv SSL_RECEIVED_SHUTDOWN -flag in the ssl shutdown state is set (see -.Xr SSL_shutdown 3 -and -.Xr SSL_set_shutdown 3 ) . -It is also possible that the peer simply shut down the underlying transport and -the shutdown is incomplete. -Call -.Xr SSL_get_error 3 -with the return value to find out whether an error occurred or the connection -was shut down cleanly -.Pq Dv SSL_ERROR_ZERO_RETURN . -.It <0 -The read operation was not successful, because either an error occurred or -action must be taken by the calling process. -Call -.Xr SSL_get_error 3 -with the return value to find out the reason. -.El -.Sh SEE ALSO -.Xr BIO_new 3 , -.Xr ssl 3 , -.Xr SSL_accept 3 , -.Xr SSL_connect 3 , -.Xr SSL_CTX_new 3 , -.Xr SSL_CTX_set_mode 3 , -.Xr SSL_get_error 3 , -.Xr SSL_pending 3 , -.Xr SSL_set_connect_state 3 , -.Xr SSL_set_shutdown 3 , -.Xr SSL_shutdown 3 , -.Xr SSL_write 3 -.Sh HISTORY -.Fn SSL_read -appeared in SSLeay 0.4 or earlier. -.Fn SSL_peek -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 . -- cgit v1.2.3-55-g6feb