From: James Muir <james@openssl.org>
Date: Mon, 13 Nov 2023 19:28:23 +0000 (-0500)
Subject: doc: better description of KECCAK-KMAC XOF
X-Git-Tag: openssl-3.3.0-alpha1~596
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f1bea887ef17802a2d83e9289e812c00fd0f0523;p=thirdparty%2Fopenssl.git

doc: better description of KECCAK-KMAC XOF

KECCAK-KMAC-128 and KECCAK-KMAC-256 are extendable output functions
that have been defined because they are convenient for implementing
KMAC.  Give definitions for them so that users aren't left to figure
that out themselves.  KECCAK-KMAC-128 is very similar to SHAKE-128,
and KECCAK-KMAC-256 is very similar to SHAKE-256.

Related to #22619.

Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/22755)
---

diff --git a/doc/man7/EVP_MD-SHAKE.pod b/doc/man7/EVP_MD-SHAKE.pod
index 6f1fe9cae64..e0395f887b4 100644
--- a/doc/man7/EVP_MD-SHAKE.pod
+++ b/doc/man7/EVP_MD-SHAKE.pod
@@ -10,8 +10,9 @@ EVP_MD-SHAKE, EVP_MD-KECCAK-KMAC
 Support for computing SHAKE or KECCAK-KMAC digests through the
 B<EVP_MD> API.
 
-KECCAK-KMAC is a special digest that's used by the KMAC EVP_MAC
-implementation (see L<EVP_MAC-KMAC(7)>).
+KECCAK-KMAC is an Extendable Output Function (XOF), with a definition
+similar to SHAKE, used by the KMAC EVP_MAC implementation (see
+L<EVP_MAC-KMAC(7)>).
 
 =head2 Identities
 
@@ -22,21 +23,25 @@ provider, and includes the following varieties:
 
 =item KECCAK-KMAC-128
 
-Known names are "KECCAK-KMAC-128" and "KECCAK-KMAC128"
-This is used by L<EVP_MAC-KMAC128(7)>
+Known names are "KECCAK-KMAC-128" and "KECCAK-KMAC128".  This is used
+by L<EVP_MAC-KMAC128(7)>.  Using the notation from NIST FIPS 202
+(Section 6.2), we have KECCAK-KMAC-128(M, d) = KECCAK[256](M || 00, d)
+(see the description of KMAC128 in Appendix A of NIST SP 800-185).
 
 =item KECCAK-KMAC-256
 
-Known names are "KECCAK-KMAC-256" and "KECCAK-KMAC256"
-This is used by L<EVP_MAC-KMAC256(7)>
+Known names are "KECCAK-KMAC-256" and "KECCAK-KMAC256".  This is used
+by L<EVP_MAC-KMAC256(7)>.  Using the notation from NIST FIPS 202
+(Section 6.2), we have KECCAK-KMAC-256(M, d) = KECCAK[512](M || 00, d)
+(see the description of KMAC256 in Appendix A of NIST SP 800-185).
 
 =item SHAKE-128
 
-Known names are "SHAKE-128" and "SHAKE128"
+Known names are "SHAKE-128" and "SHAKE128".
 
 =item SHAKE-256
 
-Known names are "SHAKE-256" and "SHAKE256"
+Known names are "SHAKE-256" and "SHAKE256".
 
 =back