From: tb <tb@openbsd.org>
Date: Wed, 27 Jan 2021 17:59:57 +0000 (+0000)
Subject: Write SSL_get_finished() documentation from scratch.
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=20849070c40147b3b936113ad1c6bdc6aae4cf71;p=openbsd

Write SSL_get_finished() documentation from scratch.

ok beck
---

diff --git a/lib/libssl/man/SSL_get_finished.3 b/lib/libssl/man/SSL_get_finished.3
new file mode 100644
index 00000000000..596703223e5
--- /dev/null
+++ b/lib/libssl/man/SSL_get_finished.3
@@ -0,0 +1,77 @@
+.\" $OpenBSD: SSL_get_finished.3,v 1.1 2021/01/27 17:59:57 tb Exp $
+.\"
+.\" Copyright (c) 2020 Theo Buehler <tb@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: January 27 2021 $
+.Dt SSL_GET_FINISHED 3
+.Os
+.Sh NAME
+.Nm SSL_get_finished ,
+.Nm SSL_get_peer_finished
+.Nd get last sent or last expected finished message
+.Sh SYNOPSIS
+.In openssl/ssl.h
+.Ft size_t
+.Fn SSL_get_finished "const SSL *ssl" "void *buf" "size_t count"
+.Ft size_t
+.Fn SSL_get_peer_finished "const SSL *ssl" "void *buf" "size_t count"
+.Sh DESCRIPTION
+.Fn SSL_get_finished
+and
+.Fn SSL_get_peer_finished
+copy
+.Fa count
+bytes from the last finished message sent to the peer
+or expected from the peer into the
+caller-provided buffer
+.Fa buf .
+.Pp
+The finished message is computed from a checksum of the handshake records
+exchanged with the peer.
+Its length depends on the ciphersuite in use and is at most
+.Dv EVP_MAX_MD_SIZE ,
+i.e., 64 bytes.
+.\" In TLSv1.3 the length is equal to the length of the hash algorithm
+.\" used by the hash-based message authentication code (HMAC),
+.\" which is currently either 32 bytes for SHA-256 or 48 bytes for SHA-384.
+.\" In TLSv1.2 the length defaults to 12 bytes, but it can explicitly
+.\" specified by the ciphersuite to be longer.
+.\" In TLS versions 1.1 and 1.0, the finished message has a fixed length
+.\" of 12 bytes.
+.Sh RETURN VALUES
+.Fn SSL_get_finished
+and
+.Fn SSL_get_peer_finished
+return the number of bytes copied into
+.Fa buf .
+The return value is zero if the handshake has not reached the
+finished message.
+.Sh SEE ALSO
+.Xr ssl 3 ,
+.Xr SSL_get_session 3 ,
+.Xr SSL_set_session 3
+.Sh STANDARDS
+RFC 8446: The Transport Layer Security (TLS) Protocol Version 1.3,
+section 4.4.4: Finished.
+.Pp
+RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2,
+section 7.4.9: Finished.
+.Sh HISTORY
+.Fn SSL_get_finished
+and
+.Fn SSL_get_peer_finished
+first appeared in SSLeay 0.9.5
+and have been available since
+.Ox 2.7 .