From a9c2a9fc0155b518edbd41a398ffa986e0d855eb Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sun, 4 Dec 2016 12:17:34 +0000 Subject: Add Copyright and license. Merge documentation of SSL_peek(3) from OpenSSL. Stop taking about SSLv2. Many wording improvements, most from OpenSSL. --- src/lib/libssl/man/SSL_read.3 | 183 ++++++++++++++++++++++++------------------ 1 file changed, 107 insertions(+), 76 deletions(-) (limited to 'src') diff --git a/src/lib/libssl/man/SSL_read.3 b/src/lib/libssl/man/SSL_read.3 index 662aed4daa..eb598a63b4 100644 --- a/src/lib/libssl/man/SSL_read.3 +++ b/src/lib/libssl/man/SSL_read.3 @@ -1,7 +1,55 @@ +.\" $OpenBSD: SSL_read.3,v 1.2 2016/12/04 12:17:34 schwarze Exp $ +.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" -.\" $OpenBSD: SSL_read.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" This file was written by Lutz Jaenicke and +.\" Matt Caswell . +.\" Copyright (c) 2000, 2001, 2008, 2016 The OpenSSL Project. All rights reserved. .\" -.Dd $Mdocdate: November 5 2016 $ +.\" 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: December 4 2016 $ .Dt SSL_READ 3 .Os .Sh NAME @@ -11,6 +59,8 @@ .In openssl/ssl.h .Ft int .Fn SSL_read "SSL *ssl" "void *buf" "int num" +.Ft int +.Fn SSL_peek "SSL *ssl" "void *buf" "int num" .Sh DESCRIPTION .Fn SSL_read tries to read @@ -19,70 +69,68 @@ bytes from the specified .Fa ssl into the buffer .Fa buf . -.Sh NOTES -If necessary, +.Pp +.Fn SSL_peek +is identical to +.Fn SSL_read +except that no bytes are removed from the underlying BIO during +the read, such that a subsequent call to +.Fn SSL_read +will yield at least the same bytes once again. +.Pp +In the following, .Fn SSL_read -will negotiate a TLS/SSL session, if not already explicitly performed by +and +.Fn SSL_peek +are called +.Dq read functions . +.Pp +If necessary, a read function will negotiate a TLS/SSL 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_read -operation. -The behaviour of -.Fn SSL_read -depends on the underlying +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 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 -.Fn SSL_read -or -.Xr SSL_write 3 . +before the first call to a read function. .Pp -.Fn SSL_read -works based on the SSL/TLS records. -The data are received in records (with a maximum record size of 16kB for -SSLv3/TLSv1). -Only after a record has been completely received can it be processed +The read functions works based on the SSL/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 not retrieved at the last call of -.Fn SSL_read -can still be buffered inside the SSL layer and will be retrieved on the next -call to -.Fn SSL_read . +Therefore data that was not retrieved at the last read call can +still be buffered inside the SSL layer and will be retrieved on the +next read call. If .Fa num -is higher than the number of bytes buffered, -.Fn SSL_read +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, -.Fn SSL_read -will trigger the processing of the next record. -Only when the record has been received and processed completely will -.Fn SSL_read -return reporting success. +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 an SSL/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 -.Fn SSL_read -can succeed. +As the size of an SSL/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 -.Em blocking , -.Fn SSL_read -will only return once the read operation has been finished or an error -has occurred, except when a renegotiation take place, in which case a +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 @@ -93,28 +141,19 @@ call. .Pp If the underlying .Vt BIO -is -.Em non-blocking , -.Fn SSL_read -will also return when the underlying +is non-blocking, a read function will also return when the underlying .Vt BIO -could not satisfy the needs of -.Fn SSL_read -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_read -will yield +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 call to -.Fn SSL_read -can also cause write operations! -The calling process then must repeat the call after taking appropriate action -to satisfy the needs of -.Fn SSL_read . +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 @@ -131,14 +170,10 @@ before being able to continue. .Xr SSL_pending 3 can be used to find out whether there are buffered bytes available for immediate retrieval. -In this case -.Fn SSL_read -can be called without blocking or actually receiving new data from the -underlying socket. -.Sh WARNING -When an -.Fn SSL_read -operation has to be repeated because of +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 , @@ -147,8 +182,9 @@ it must be repeated with the same arguments. 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/SSL connection. +The read operation was successful. +The return value is the number of bytes actually read from the +TLS/SSL connection. .It 0 The read operation was not successful. The reason may either be a clean shutdown due to a @@ -166,11 +202,6 @@ Call with the return value to find out whether an error occurred or the connection was shut down cleanly .Pq Dv SSL_ERROR_ZERO_RETURN . -.Pp -SSLv2 (deprecated) does not support a shutdown alert protocol, so it can only -be detected whether the underlying connection was closed. -It cannot be checked whether the closure was initiated by the peer or by -something else. .It <0 The read operation was not successful, because either an error occurred or action must be taken by the calling process. -- cgit v1.2.3-55-g6feb