From 6071ac1fe215c8681ffc7fa5f72c54b4ace69a0d Mon Sep 17 00:00:00 2001
From: tb <tb@openbsd.org>
Date: Sun, 14 Jul 2024 15:48:24 +0000
Subject: [PATCH] Document SSL_CIPHER_get_handshake_digest(3)

---
 lib/libssl/man/SSL_CIPHER_get_name.3 | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/lib/libssl/man/SSL_CIPHER_get_name.3 b/lib/libssl/man/SSL_CIPHER_get_name.3
index 235ff1408e9..633ee3ff643 100644
--- a/lib/libssl/man/SSL_CIPHER_get_name.3
+++ b/lib/libssl/man/SSL_CIPHER_get_name.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: SSL_CIPHER_get_name.3,v 1.14 2022/07/17 08:51:07 jsg Exp $
+.\" $OpenBSD: SSL_CIPHER_get_name.3,v 1.15 2024/07/14 15:48:24 tb Exp $
 .\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
 .\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800
 .\"
@@ -52,7 +52,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 17 2022 $
+.Dd $Mdocdate: July 14 2024 $
 .Dt SSL_CIPHER_GET_NAME 3
 .Os
 .Sh NAME
@@ -61,6 +61,7 @@
 .Nm SSL_CIPHER_get_version ,
 .Nm SSL_CIPHER_get_cipher_nid ,
 .Nm SSL_CIPHER_get_digest_nid ,
+.Nm SSL_CIPHER_get_handshake_digest ,
 .Nm SSL_CIPHER_get_kx_nid ,
 .Nm SSL_CIPHER_get_auth_nid ,
 .Nm SSL_CIPHER_is_aead ,
@@ -80,6 +81,8 @@
 .Fn SSL_CIPHER_get_cipher_nid "const SSL_CIPHER *cipher"
 .Ft int
 .Fn SSL_CIPHER_get_digest_nid "const SSL_CIPHER *cipher"
+.Ft "const EVP_MD *"
+.Fn SSL_CIPHER_get_handshake_digest "const SSL_CIPHER *cipher"
 .Ft int
 .Fn SSL_CIPHER_get_kx_nid "const SSL_CIPHER *cipher"
 .Ft int
@@ -132,6 +135,14 @@ If there is no digest (e.g. for AEAD cipher suites), then
 .Dv NID_undef
 is returned.
 .Pp
+.Fn SSL_CIPHER_get_handshake_digest
+returns the
+.Vt EVP_MD
+object representing the digest used during a TLS handshake with the cipher
+.Fa c ,
+which may be different to the digest used in the message authentication code
+for encrypted records.
+.Pp
 .Fn SSL_CIPHER_get_kx_nid
 returns the key exchange NID corresponding to the method used by the
 .Fa cipher .
@@ -307,6 +318,12 @@ and
 return an NID constant or
 .Dv NID_undef
 if an error occurred.
+.Fn SSL_CIPHER_get_handshake_digest
+returns a valid
+.Vt EVP_MD
+object or
+.Dv NULL
+if an error ocurred.
 .Pp
 .Fn SSL_CIPHER_is_aead
 returns 1 if the
@@ -369,6 +386,9 @@ first appeared in OpenSSL 1.1.0 and have been available since
 .Fn SSL_CIPHER_find
 first appeared in OpenSSL 1.1.0 and has been available since
 .Ox 7.0 .
+.Fn SSL_CIPHER_get_handshake_digest
+first appeared in OpenSSL 1.1.1 and has been available since
+.Ox 7.5 .
 .Sh BUGS
 If
 .Fn SSL_CIPHER_description
-- 
2.20.1