1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5b077aed3SPierre ProncheryEVP_MD-SHAKE, EVP_MD-KECCAK-KMAC 6b077aed3SPierre Pronchery- The SHAKE / KECCAK family EVP_MD implementations 7b077aed3SPierre Pronchery 8b077aed3SPierre Pronchery=head1 DESCRIPTION 9b077aed3SPierre Pronchery 10b077aed3SPierre ProncherySupport for computing SHAKE or KECCAK-KMAC digests through the 11b077aed3SPierre ProncheryB<EVP_MD> API. 12b077aed3SPierre Pronchery 13*e0c4386eSCy SchubertKECCAK-KMAC is an Extendable Output Function (XOF), with a definition 14*e0c4386eSCy Schubertsimilar to SHAKE, used by the KMAC EVP_MAC implementation (see 15*e0c4386eSCy SchubertL<EVP_MAC-KMAC(7)>). 16b077aed3SPierre Pronchery 17b077aed3SPierre Pronchery=head2 Identities 18b077aed3SPierre Pronchery 19b077aed3SPierre ProncheryThis implementation is available in the FIPS provider as well as the default 20b077aed3SPierre Proncheryprovider, and includes the following varieties: 21b077aed3SPierre Pronchery 22b077aed3SPierre Pronchery=over 4 23b077aed3SPierre Pronchery 24b077aed3SPierre Pronchery=item KECCAK-KMAC-128 25b077aed3SPierre Pronchery 26*e0c4386eSCy SchubertKnown names are "KECCAK-KMAC-128" and "KECCAK-KMAC128". This is used 27*e0c4386eSCy Schubertby L<EVP_MAC-KMAC128(7)>. Using the notation from NIST FIPS 202 28*e0c4386eSCy Schubert(Section 6.2), we have S<KECCAK-KMAC-128(M, d)> = S<KECCAK[256](M || 00, d)> 29*e0c4386eSCy Schubert(see the description of KMAC128 in Appendix A of NIST SP 800-185). 30b077aed3SPierre Pronchery 31b077aed3SPierre Pronchery=item KECCAK-KMAC-256 32b077aed3SPierre Pronchery 33*e0c4386eSCy SchubertKnown names are "KECCAK-KMAC-256" and "KECCAK-KMAC256". This is used 34*e0c4386eSCy Schubertby L<EVP_MAC-KMAC256(7)>. Using the notation from NIST FIPS 202 35*e0c4386eSCy Schubert(Section 6.2), we have S<KECCAK-KMAC-256(M, d)> = S<KECCAK[512](M || 00, d)> 36*e0c4386eSCy Schubert(see the description of KMAC256 in Appendix A of NIST SP 800-185). 37b077aed3SPierre Pronchery 38b077aed3SPierre Pronchery=item SHAKE-128 39b077aed3SPierre Pronchery 40*e0c4386eSCy SchubertKnown names are "SHAKE-128" and "SHAKE128". 41b077aed3SPierre Pronchery 42b077aed3SPierre Pronchery=item SHAKE-256 43b077aed3SPierre Pronchery 44*e0c4386eSCy SchubertKnown names are "SHAKE-256" and "SHAKE256". 45b077aed3SPierre Pronchery 46b077aed3SPierre Pronchery=back 47b077aed3SPierre Pronchery 48b077aed3SPierre Pronchery=head2 Gettable Parameters 49b077aed3SPierre Pronchery 50b077aed3SPierre ProncheryThis implementation supports the common gettable parameters described 51b077aed3SPierre Proncheryin L<EVP_MD-common(7)>. 52b077aed3SPierre Pronchery 53b077aed3SPierre Pronchery=head2 Settable Context Parameters 54b077aed3SPierre Pronchery 55b077aed3SPierre ProncheryThese implementations support the following L<OSSL_PARAM(3)> entries, 56b077aed3SPierre Proncherysettable for an B<EVP_MD_CTX> with L<EVP_MD_CTX_set_params(3)>: 57b077aed3SPierre Pronchery 58b077aed3SPierre Pronchery=over 4 59b077aed3SPierre Pronchery 60b077aed3SPierre Pronchery=item "xoflen" (B<OSSL_DIGEST_PARAM_XOFLEN>) <unsigned integer> 61b077aed3SPierre Pronchery 62b077aed3SPierre ProncherySets the digest length for extendable output functions. 63b077aed3SPierre ProncheryThe length of the "xoflen" parameter should not exceed that of a B<size_t>. 64b077aed3SPierre Pronchery 65b077aed3SPierre ProncheryFor backwards compatibility reasons the default xoflen length for SHAKE-128 is 66b077aed3SPierre Pronchery16 (bytes) which results in a security strength of only 64 bits. To ensure the 67b077aed3SPierre Proncherymaximum security strength of 128 bits, the xoflen should be set to at least 32. 68b077aed3SPierre Pronchery 69b077aed3SPierre ProncheryFor backwards compatibility reasons the default xoflen length for SHAKE-256 is 70b077aed3SPierre Pronchery32 (bytes) which results in a security strength of only 128 bits. To ensure the 71b077aed3SPierre Proncherymaximum security strength of 256 bits, the xoflen should be set to at least 64. 72b077aed3SPierre Pronchery 73b077aed3SPierre Pronchery=back 74b077aed3SPierre Pronchery 75b077aed3SPierre Pronchery=head1 SEE ALSO 76b077aed3SPierre Pronchery 77b077aed3SPierre ProncheryL<EVP_MD_CTX_set_params(3)>, L<provider-digest(7)>, L<OSSL_PROVIDER-default(7)> 78b077aed3SPierre Pronchery 79b077aed3SPierre Pronchery=head1 COPYRIGHT 80b077aed3SPierre Pronchery 81b077aed3SPierre ProncheryCopyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved. 82b077aed3SPierre Pronchery 83b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 84b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 85b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 86b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 87b077aed3SPierre Pronchery 88b077aed3SPierre Pronchery=cut 89