Home | History | Annotate | Line # | Download | only in man7 
      1 =pod
      2 
      3 =head1 NAME
      4 
      5 EVP_MD-SHAKE, EVP_MD-KECCAK-KMAC
      6 - The SHAKE / KECCAK family EVP_MD implementations
      7 
      8 =head1 DESCRIPTION
      9 
     10 Support for computing SHAKE or KECCAK-KMAC digests through the
     11 B<EVP_MD> API.
     12 
     13 KECCAK-KMAC is an Extendable Output Function (XOF), with a definition
     14 similar to SHAKE, used by the KMAC EVP_MAC implementation (see
     15 L<EVP_MAC-KMAC(7)>).
     16 
     17 =head2 Identities
     18 
     19 This implementation is available in the FIPS provider as well as the default
     20 provider, and includes the following varieties:
     21 
     22 =over 4
     23 
     24 =item KECCAK-KMAC-128
     25 
     26 Known names are "KECCAK-KMAC-128" and "KECCAK-KMAC128".  This is used
     27 by L<EVP_MAC-KMAC128(7)>.  Using the notation from NIST FIPS 202
     28 (Section 6.2), we have S<KECCAK-KMAC-128(M, d)> = S<KECCAK[256](M || 00, d)>
     29 (see the description of KMAC128 in Appendix A of NIST SP 800-185).
     30 
     31 =item KECCAK-KMAC-256
     32 
     33 Known names are "KECCAK-KMAC-256" and "KECCAK-KMAC256".  This is used
     34 by L<EVP_MAC-KMAC256(7)>.  Using the notation from NIST FIPS 202
     35 (Section 6.2), we have S<KECCAK-KMAC-256(M, d)> = S<KECCAK[512](M || 00, d)>
     36 (see the description of KMAC256 in Appendix A of NIST SP 800-185).
     37 
     38 =item SHAKE-128
     39 
     40 Known names are "SHAKE-128" and "SHAKE128".
     41 
     42 =item SHAKE-256
     43 
     44 Known names are "SHAKE-256" and "SHAKE256".
     45 
     46 =back
     47 
     48 =head2 Parameters
     49 
     50 This implementation supports the following L<OSSL_PARAM(3)> entries:
     51 
     52 =over 4
     53 
     54 =item "xoflen" (B<OSSL_DIGEST_PARAM_XOFLEN>) <unsigned integer>
     55 
     56 Sets or Gets the digest length for extendable output functions.
     57 The length of the "xoflen" parameter should not exceed that of a B<size_t>.
     58 
     59 The SHAKE-128 and SHAKE-256 implementations do not have any default digest
     60 length.
     61 
     62 This parameter must be set before calling either EVP_DigestFinal_ex() or
     63 EVP_DigestFinal(), since these functions were not designed to handle variable
     64 length output. It is recommended to either use EVP_DigestSqueeze() or
     65 EVP_DigestFinalXOF() instead.
     66 
     67 =item "size" (B<OSSL_DIGEST_PARAM_SIZE>) <unsigned integer>
     68 
     69 An alias of "xoflen".
     70 
     71 =back
     72 
     73 See L<EVP_DigestInit(3)/PARAMETERS> for further information related to parameters
     74 
     75 =head1 NOTES
     76 
     77 For SHAKE-128, to ensure the maximum security strength of 128 bits, the output
     78 length passed to EVP_DigestFinalXOF() should be at least 32.
     79 
     80 For SHAKE-256, to ensure the maximum security strength of 256 bits, the output
     81 length passed to EVP_DigestFinalXOF() should be at least 64.
     82 
     83 =head1 SEE ALSO
     84 
     85 L<EVP_MD_CTX_set_params(3)>, L<provider-digest(7)>, L<OSSL_PROVIDER-default(7)>
     86 
     87 =head1 HISTORY
     88 
     89 Since OpenSSL 3.4 the SHAKE-128 and SHAKE-256 implementations have no default
     90 digest length.
     91 
     92 =head1 COPYRIGHT
     93 
     94 Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved.
     95 
     96 Licensed under the Apache License 2.0 (the "License").  You may not use
     97 this file except in compliance with the License.  You can obtain a copy
     98 in the file LICENSE in the source distribution or at
     99 L<https://www.openssl.org/source/license.html>.
    100 
    101 =cut
    102