Add Copyright and license.

Merge documentation of SSL_peek(3) from OpenSSL.
Stop taking about SSLv2.
Many wording improvements, most from OpenSSL.

1 files changed, 107 insertions, 76 deletions

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 <jaenicke@openssl.org> and
+.\" Matt Caswell <matt@openssl.org>.
+.\" 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.