From a9696116c81c5794429e6b91e26704b11dd836b5 Mon Sep 17 00:00:00 2001 From: Paul Duncan Date: Mon, 16 Oct 2023 17:25:17 -0400 Subject: sha3.h: add @author, @copyright, @brief to file header, add examples for all functions, improve documentation links --- sha3.h | 1593 +++++++++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 1123 insertions(+), 470 deletions(-) diff --git a/sha3.h b/sha3.h index 6dc7546..589c44f 100644 --- a/sha3.h +++ b/sha3.h @@ -1,12 +1,17 @@ /** * @file sha3.h + * @author Paul Duncan + * @copyright MIT No Attribution (MIT-0) + * @brief C11 implementation of FIPS 202, NIST SP 800-185, and the draft KangarooTwelve and TurboSHAKE specification. + * * sha3 * https://pablotron.org/sha3 * * Copyright (c) 2023 Paul Duncan * SPDX-License-Identifier: MIT-0 * - * C11 implementations of the following SHA-3 algorithms: + * Embeddable, dependency-free, MIT-0-licensed C11 implementation of the + * following SHA-3 hash functions, XOFs, and HMACs: * * - SHA3-224, SHA3-256, SHA3-384, and SHA3-512 * - HMAC-SHA3-224, HMAC-SHA3-256, HMAC-SHA3-384, and HMAC-SHA3-512 @@ -18,7 +23,6 @@ * - TurboSHAKE128 and TurboSHAKE256 * - KangarooTwelve */ - #ifndef SHA3_H #define SHA3_H @@ -55,8 +59,11 @@ extern "C" { */ /** - * @brief Internal SHA-3 state (all members are private). + * @brief Internal [SHA-3][] state (all members are private). * @ingroup sha3 + * + * [SHA-3]: https://en.wikipedia.org/wiki/SHA-3 + * "Secure Hash Algorithm 3" */ typedef union { uint8_t u8[200]; /**< 8-bit unsigned integers. */ @@ -64,8 +71,11 @@ typedef union { } sha3_state_t; /** - * @brief Iterative SHA-3 context (all members are private). + * @brief Iterative [SHA-3][] context (all members are private). * @ingroup sha3 + * + * [SHA-3]: https://en.wikipedia.org/wiki/SHA-3 + * "Secure Hash Algorithm 3" */ typedef struct { size_t num_bytes; /**< number of bytes absorbed */ @@ -74,8 +84,11 @@ typedef struct { } sha3_t; /** - * @brief Iterative XOF context (all members are private). + * @brief Iterative [XOF][] context (all members are private). * @ingroup shake + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ typedef struct { size_t num_bytes; /**< number of bytes absorbed */ @@ -88,12 +101,18 @@ typedef struct { * @ingroup sha3 * * Hash `len` bytes of input data from source buffer `src` with SHA3-224 - * (FIPS 202, section 6.1), then write 28 bytes of output to destination - * buffer `dst`. + * ([FIPS 202][], section 6.1), then write 28 bytes of output to + * destination buffer `dst`. * * @param[in] src Source buffer. * @param[in] len Source buffer length, in bytes. - * @param[out] dst Destination array. Must be at least 28 bytes in length. + * @param[out] dst Destination buffer. Must be at least 28 bytes in length. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c sha3_224 + * + * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final + * "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions" */ void sha3_224(const uint8_t *src, size_t len, uint8_t dst[static 28]); @@ -102,6 +121,9 @@ void sha3_224(const uint8_t *src, size_t len, uint8_t dst[static 28]); * @ingroup sha3 * * @param[out] hash SHA3-224 hash context. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c sha3_224_absorb */ void sha3_224_init(sha3_t *hash); @@ -118,6 +140,9 @@ void sha3_224_init(sha3_t *hash); * @param[in] len Source buffer length, in bytes. * * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized). + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c sha3_224_absorb */ _Bool sha3_224_absorb(sha3_t *hash, const uint8_t *src, const size_t len); @@ -128,6 +153,9 @@ _Bool sha3_224_absorb(sha3_t *hash, const uint8_t *src, const size_t len); * * @param[in,out] hash SHA3-224 hash context. * @param[out] dst Destination buffer. Must be at least 28 bytes in length. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c sha3_224_absorb */ void sha3_224_final(sha3_t *hash, uint8_t dst[28]); @@ -136,12 +164,18 @@ void sha3_224_final(sha3_t *hash, uint8_t dst[28]); * @ingroup sha3 * * Hash `len` bytes of input data from source buffer `src` with SHA3-256 - * (FIPS 202, section 6.1), then write 32 bytes of output to destination - * buffer `dst`. + * ([FIPS 202][], section 6.1), then write 32 bytes of output to + * destination buffer `dst`. * * @param[in] src Source buffer. * @param[in] len Source buffer length, in bytes. - * @param[out] dst Destination array. Must be at least 32 bytes in length. + * @param[out] dst Destination buffer. Must be at least 32 bytes in length. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c sha3_256 + * + * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final + * "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions" */ void sha3_256(const uint8_t *src, size_t len, uint8_t dst[static 32]); @@ -150,6 +184,9 @@ void sha3_256(const uint8_t *src, size_t len, uint8_t dst[static 32]); * @ingroup sha3 * * @param[out] hash SHA3-256 hash context. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c sha3_256_absorb */ void sha3_256_init(sha3_t *hash); @@ -166,6 +203,9 @@ void sha3_256_init(sha3_t *hash); * @param[in] len Source buffer length, in bytes. * * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized). + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c sha3_256_absorb */ _Bool sha3_256_absorb(sha3_t *hash, const uint8_t *src, const size_t len); @@ -176,6 +216,9 @@ _Bool sha3_256_absorb(sha3_t *hash, const uint8_t *src, const size_t len); * * @param[in,out] hash SHA3-256 hash context. * @param[out] dst Destination buffer. Must be at least 32 bytes in length. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c sha3_256_absorb */ void sha3_256_final(sha3_t *hash, uint8_t dst[32]); @@ -184,12 +227,18 @@ void sha3_256_final(sha3_t *hash, uint8_t dst[32]); * @ingroup sha3 * * Hash `len` bytes of input data from source buffer `src` with SHA3-384 - * (FIPS 202, section 6.1), then write 48 bytes of output to destination - * buffer `dst`. + * ([FIPS 202][], section 6.1), then write 48 bytes of output to + * destination buffer `dst`. * * @param[in] src Source buffer. * @param[in] len Source buffer length, in bytes. - * @param[out] dst Destination array. Must be at least 48 bytes in length. + * @param[out] dst Destination buffer. Must be at least 48 bytes in length. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c sha3_384 + * + * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final + * "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions" */ void sha3_384(const uint8_t *src, size_t len, uint8_t dst[static 48]); @@ -198,6 +247,9 @@ void sha3_384(const uint8_t *src, size_t len, uint8_t dst[static 48]); * @ingroup sha3 * * @param[out] hash SHA3-384 hash context. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c sha3_384_absorb */ void sha3_384_init(sha3_t *hash); @@ -214,6 +266,9 @@ void sha3_384_init(sha3_t *hash); * @param[in] len Source buffer length, in bytes. * * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized). + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c sha3_384_absorb */ _Bool sha3_384_absorb(sha3_t *hash, const uint8_t *src, const size_t len); @@ -224,6 +279,9 @@ _Bool sha3_384_absorb(sha3_t *hash, const uint8_t *src, const size_t len); * * @param[in,out] hash SHA3-384 hash context. * @param[out] dst Destination buffer. Must be at least 48 bytes in length. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c sha3_384_absorb */ void sha3_384_final(sha3_t *hash, uint8_t dst[48]); @@ -232,12 +290,18 @@ void sha3_384_final(sha3_t *hash, uint8_t dst[48]); * @ingroup sha3 * * Hash `len` bytes of input data from source buffer `src` with SHA3-512 - * (FIPS 202, section 6.1), then write 64 bytes of output to destination - * buffer `dst`. + * ([FIPS 202][], section 6.1), then write 64 bytes of output to + * destination buffer `dst`. * * @param[in] src Source buffer. * @param[in] len Source buffer length, in bytes. - * @param[out] dst Destination array. Must be at least 64 bytes in length. + * @param[out] dst Destination buffer. Must be at least 64 bytes in length. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c sha3_512 + * + * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final + * "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions" */ void sha3_512(const uint8_t *src, size_t len, uint8_t dst[static 64]); @@ -246,6 +310,9 @@ void sha3_512(const uint8_t *src, size_t len, uint8_t dst[static 64]); * @ingroup sha3 * * @param[out] hash SHA3-512 hash context. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c sha3_512_absorb */ void sha3_512_init(sha3_t *hash); @@ -262,6 +329,9 @@ void sha3_512_init(sha3_t *hash); * @param[in] len Source buffer length, in bytes. * * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized). + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c sha3_512_absorb */ _Bool sha3_512_absorb(sha3_t *hash, const uint8_t *src, const size_t len); @@ -272,6 +342,9 @@ _Bool sha3_512_absorb(sha3_t *hash, const uint8_t *src, const size_t len); * * @param[in,out] hash SHA3-512 hash context. * @param[out] dst Destination buffer. Must be at least 64 bytes in length. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c sha3_512_absorb */ void sha3_512_final(sha3_t *hash, uint8_t dst[64]); @@ -298,69 +371,109 @@ void sha3_512_final(sha3_t *hash, uint8_t dst[64]); * @brief Calculat HMAC-SHA3-224 of given key and data. * @ingroup hmac * - * Calculate HMAC-SHA3-224 (FIPS 202, Section 7) of key in buffer `k` of - * length `k_len` and input message in buffer `m` of length `m_len` - * bytes and write 28 bytes of output to destination buffer `dst`. + * Calculate HMAC-SHA3-224 ([FIPS 202][], Section 7) of key in buffer + * `key` of length `key_len` and input message in buffer `msg` of length + * `msg_len` bytes and write 28 byte [message authentication code + * (MAC)][] to destination buffer `mac`. + * + * @param[in] key Key. + * @param[in] key_len Key length, in bytes. + * @param[in] msg Input message. + * @param[in] msg_len Input message length, in bytes. + * @param[out] mac [MAC][] destination buffer. Must be at least 28 bytes in length. * - * @param[in] k Key. - * @param[in] k_len Key length, in bytes. - * @param[in] m Input message. - * @param[in] m_len Input message length, in bytes. - * @param[out] dst Destination array. Must be at least 28 bytes in length. + * Example: + * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_224 + * + * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final + * "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions" + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code (MAC)" */ -void hmac_sha3_224(const uint8_t *k, const size_t k_len, const uint8_t *m, const size_t m_len, uint8_t dst[28]); +void hmac_sha3_224(const uint8_t *key, const size_t key_len, const uint8_t *msg, const size_t msg_len, uint8_t mac[28]); /** * @brief Calculate HMAC-SHA3-256 given key and data. * @ingroup hmac * - * Calculate HMAC-SHA3-256 (FIPS 202, Section 7) of key in buffer `k` of - * length `k_len` and input message in buffer `m` of length `m_len` - * bytes and write 32 bytes of output to destination buffer `dst`. + * Calculate HMAC-SHA3-256 ([FIPS 202][], Section 7) of key in buffer + * `key` of length `key_len` and input message in buffer `msg` of length + * `msg_len` bytes and write 32 byte [message authentication code + * (MAC)][mac] destination buffer `mac`. * - * @param[in] k Key. - * @param[in] k_len Key length, in bytes. - * @param[in] m Input message. - * @param[in] m_len Input message length, in bytes. - * @param[out] dst Destination array. Must be at least 32 bytes in length. + * @param[in] key Key. + * @param[in] key_len Key length, in bytes. + * @param[in] msg Input message. + * @param[in] msg_len Input message length, in bytes. + * @param[out] mac [MAC][] destination buffer. Must be at least 32 bytes in length. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_256 + * + * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final + * "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions" + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code (MAC)" */ -void hmac_sha3_256(const uint8_t *k, const size_t k_len, const uint8_t *m, const size_t m_len, uint8_t dst[32]); +void hmac_sha3_256(const uint8_t *key, const size_t key_len, const uint8_t *msg, const size_t msg_len, uint8_t mac[32]); /** - * Calculate HMAC-SHA3-384 of given key and data. + * @brief Calculate HMAC-SHA3-384 of given key and data. * @ingroup hmac * - * Calculate HMAC-SHA3-384 (FIPS 202, Section 7) of key in buffer `k` of - * length `k_len` and input message in buffer `m` of length `m_len` - * bytes and write 48 bytes of output to destination buffer `dst`. + * Calculate HMAC-SHA3-384 ([FIPS 202][], Section 7) of key in buffer + * `key` of length `key_len` and input message in buffer `msg` of length + * `msg_len` bytes and write 48 byte [message authentication code + * (MAC)][mac] destination buffer `mac`. + * + * @param[in] key Key. + * @param[in] key_len Key length, in bytes. + * @param[in] msg Input message. + * @param[in] msg_len Input message length, in bytes. + * @param[out] mac [MAC][] destination buffer. Must be at least 48 bytes in length. * - * @param[in] k Key. - * @param[in] k_len Key length, in bytes. - * @param[in] m Input message. - * @param[in] m_len Input message length, in bytes. - * @param[out] dst Destination array. Must be at least 48 bytes in length. + * Example: + * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_384 + * + * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final + * "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions" + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code (MAC)" */ -void hmac_sha3_384(const uint8_t *k, const size_t k_len, const uint8_t *m, const size_t m_len, uint8_t dst[48]); +void hmac_sha3_384(const uint8_t *key, const size_t key_len, const uint8_t *msg, const size_t msg_len, uint8_t mac[48]); /** * @brief Calculate HMAC-SHA3-512 of given key and data. * @ingroup hmac * - * Calculate HMAC-SHA3-512 (FIPS 202, Section 7) of key in buffer `k` of - * length `k_len` and input message in buffer `m` of length `m_len` - * bytes and write 64 bytes of output to destination buffer `dst`. + * Calculate HMAC-SHA3-512 ([FIPS 202][], Section 7) of key in buffer + * `key` of length `key_len` and input message in buffer `msg` of length + * `msg_len` bytes and write 64 byte [message authentication code + * (MAC)][mac] destination buffer `mac`. + * + * @param[in] key Key. + * @param[in] key_len Key length, in bytes. + * @param[in] msg Input message. + * @param[in] msg_len Input message length, in bytes. + * @param[out] mac [MAC][] destination buffer. Must be at least 64 bytes in length. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_512 * - * @param[in] k Key. - * @param[in] k_len Key length, in bytes. - * @param[in] m Input message. - * @param[in] m_len Input message length, in bytes. - * @param[out] dst Destination array. Must be at least 64 bytes in length. + * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final + * "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions" + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code (MAC)" */ -void hmac_sha3_512(const uint8_t *k, const size_t k_len, const uint8_t *m, const size_t m_len, uint8_t dst[64]); +void hmac_sha3_512(const uint8_t *key, const size_t key_len, const uint8_t *msg, const size_t msg_len, uint8_t mac[64]); /** - * @brief HMAC-SHA3 (Hash-based Message Authentication Code) context. + * @brief HMAC-SHA3 (Hash-based [Message Authentication Code][MAC]) + * context (all members are private). * @ingroup hmac + * + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code (MAC)" */ typedef struct { sha3_t inner, /**< Inner hash context (private) */ @@ -369,14 +482,20 @@ typedef struct { } hmac_sha3_t; /** - * @brief Initialize HMAC-SHA3-224 (FIPS 202, Section 7) context. + * @brief Initialize HMAC-SHA3-224 ([FIPS 202][], Section 7) context. * @ingroup hmac * - * @param[out] hmac HMAC-SHA3-224 context. - * @param[in] k Key. - * @param[in] k_len Key length, in bytes. + * @param[out] ctx HMAC-SHA3-224 context. + * @param[in] key Key. + * @param[in] key_len Key length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_224_absorb + * + * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final + * "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions" */ -void hmac_sha3_224_init(hmac_sha3_t *hmac, const uint8_t *k, const size_t k_len); +void hmac_sha3_224_init(hmac_sha3_t *ctx, const uint8_t *key, const size_t key_len); /** * @brief Absorb data into HMAC-SHA3-224 context. @@ -386,137 +505,192 @@ void hmac_sha3_224_init(hmac_sha3_t *hmac, const uint8_t *k, const size_t k_len) * context `hmac`. Can be called iteratively to absorb input data in * chunks. * - * @param[in,out] hmac HMAC-SHA3-224 context. + * @param[in,out] ctx HMAC-SHA3-224 context. * @param[in] src Input data. * @param[in] len Input data length, in bytes. * * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized). + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_224_absorb */ -_Bool hmac_sha3_224_absorb(hmac_sha3_t *hmac, const uint8_t *src, const size_t len); +_Bool hmac_sha3_224_absorb(hmac_sha3_t *ctx, const uint8_t *src, const size_t len); /** - * @brief Finalize HMAC-SHA3-224 hash context and write 28 bytes of - * output to destination buffer `dst`. + * @brief Finalize HMAC-SHA3-224 context and write 28 byte [MAC][] + * to destination buffer. * @ingroup hmac * - * @param[in,out] hmac HMAC-SHA3-224 hash context. - * @param[out] dst Destination buffer. Must be at least 28 bytes in length. + * @param[in,out] ctx HMAC-SHA3-224 context. + * @param[out] mac [MAC][] destination buffer. Must be at least 28 bytes in length. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_224_absorb + * + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code (MAC)" */ -void hmac_sha3_224_final(hmac_sha3_t *hmac, uint8_t dst[28]); +void hmac_sha3_224_final(hmac_sha3_t *ctx, uint8_t mac[28]); /** - * @brief Initialize HMAC-SHA3-256 (FIPS 202, Section 7) context. + * @brief Initialize HMAC-SHA3-256 ([FIPS 202][], Section 7) context. * @ingroup hmac * - * @param[out] hmac HMAC-SHA3-256 context. - * @param[in] k Key. - * @param[in] k_len Key length, in bytes. + * @param[out] ctx HMAC-SHA3-256 context. + * @param[in] key Key. + * @param[in] key_len Key length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_256_absorb + * + * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final + * "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions" */ -void hmac_sha3_256_init(hmac_sha3_t *hmac, const uint8_t *k, const size_t k_len); +void hmac_sha3_256_init(hmac_sha3_t *ctx, const uint8_t *key, const size_t key_len); /** * @brief Absorb data into HMAC-SHA3-256 context. * @ingroup hmac * * Absorb input data in `src` of length `len` bytes into HMAC-SHA3-256 - * context `hmac`. Can be called iteratively to absorb input data in + * context `ctx`. Can be called iteratively to absorb input data in * chunks. * - * @param[in,out] hmac HMAC-SHA3-256 context. + * @param[in,out] ctx HMAC-SHA3-256 context. * @param[in] src Input data. * @param[in] len Input data length, in bytes. * * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized). + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_256_absorb */ -_Bool hmac_sha3_256_absorb(hmac_sha3_t *hmac, const uint8_t *src, const size_t len); +_Bool hmac_sha3_256_absorb(hmac_sha3_t *ctx, const uint8_t *src, const size_t len); /** - * @brief Finalize HMAC-SHA3-256 hash context and write 32 bytes of - * output to destination buffer `dst`. + * @brief Finalize HMAC-SHA3-256 context and write 32 byte [MAC][] to + * destination buffer. * @ingroup hmac * - * @param[in,out] hmac HMAC-SHA3-256 hash context. - * @param[out] dst Destination buffer. Must be at least 32 bytes in length. + * @param[in,out] ctx HMAC-SHA3-256 context. + * @param[out] mac [MAC][] destination buffer. Must be at least 32 bytes in length. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_256_absorb + * + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code (MAC)" */ -void hmac_sha3_256_final(hmac_sha3_t *hmac, uint8_t dst[32]); +void hmac_sha3_256_final(hmac_sha3_t *ctx, uint8_t mac[32]); /** - * @brief Initialize HMAC-SHA3-384 (FIPS 202, Section 7) context. + * @brief Initialize HMAC-SHA3-384 ([FIPS 202][], Section 7) context. * @ingroup hmac * - * @param[out] hmac HMAC-SHA3-384 context. - * @param[in] k Key. - * @param[in] k_len Key length, in bytes. + * @param[out] ctx HMAC-SHA3-384 context. + * @param[in] key Key. + * @param[in] key_len Key length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_384_absorb + * + * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final + * "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions" */ -void hmac_sha3_384_init(hmac_sha3_t *hmac, const uint8_t *k, const size_t k_len); +void hmac_sha3_384_init(hmac_sha3_t *ctx, const uint8_t *key, const size_t key_len); /** * @brief Absorb data into HMAC-SHA3-384 context. * @ingroup hmac * * Absorb input data in `src` of length `len` bytes into HMAC-SHA3-384 - * context `hmac`. Can be called iteratively to absorb input data in + * context `ctx`. Can be called iteratively to absorb input data in * chunks. * - * @param[in,out] hmac HMAC-SHA3-384 context. + * @param[in,out] ctx HMAC-SHA3-384 context. * @param[in] src Input data. * @param[in] len Input data length, in bytes. * * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized). + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_384_absorb */ -_Bool hmac_sha3_384_absorb(hmac_sha3_t *hmac, const uint8_t *src, const size_t len); +_Bool hmac_sha3_384_absorb(hmac_sha3_t *ctx, const uint8_t *src, const size_t len); /** - * @brief Finalize HMAC-SHA3-384 hash context and write 48 bytes of - * output to destination buffer `dst`. + * @brief Finalize HMAC-SHA3-384 context and write 48 byte [MAC][] to + * destination buffer. * @ingroup hmac * - * @param[in,out] hmac HMAC-SHA3-384 hash context. - * @param[out] dst Destination buffer. Must be at least 48 bytes in length. + * @param[in,out] ctx HMAC-SHA3-384 context. + * @param[out] mac [MAC][] destination buffer. Must be at least 48 bytes in length. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_512_absorb + * + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code (MAC)" */ -void hmac_sha3_384_final(hmac_sha3_t *hmac, uint8_t dst[48]); +void hmac_sha3_384_final(hmac_sha3_t *ctx, uint8_t mac[48]); /** - * @brief Initialize HMAC-SHA3-512 (FIPS 202, Section 7) context. + * @brief Initialize HMAC-SHA3-512 ([FIPS 202][], Section 7) context. * @ingroup hmac * - * @param[out] hmac HMAC-SHA3-512 context. - * @param[in] k Key. - * @param[in] k_len Key length, in bytes. + * @param[out] ctx HMAC-SHA3-512 context. + * @param[in] key Key. + * @param[in] key_len Key length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_512_absorb + * + * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final + * "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions" */ -void hmac_sha3_512_init(hmac_sha3_t *hmac, const uint8_t *k, const size_t k_len); +void hmac_sha3_512_init(hmac_sha3_t *ctx, const uint8_t *key, const size_t key_len); /** * @brief Absorb data into HMAC-SHA3-512 context. * @ingroup hmac * * Absorb input data in `src` of length `len` bytes into HMAC-SHA3-512 - * context `hmac`. Can be called iteratively to absorb input data in + * context `ctx`. Can be called iteratively to absorb input data in * chunks. * - * @param[in,out] hmac HMAC-SHA3-512 context. + * @param[in,out] ctx HMAC-SHA3-512 context. * @param[in] src Input data. * @param[in] len Input data length, in bytes. * + * Example: + * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_512_absorb + * * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized). */ -_Bool hmac_sha3_512_absorb(hmac_sha3_t *hmac, const uint8_t *src, const size_t len); +_Bool hmac_sha3_512_absorb(hmac_sha3_t *ctx, const uint8_t *src, const size_t len); /** - * @brief Finalize HMAC-SHA3-512 hash context and write 64 bytes of - * output to destination buffer `dst`. + * @brief Finalize HMAC-SHA3-512 context and write 64 byte [MAC][] + * to destination buffer. * @ingroup hmac * - * @param[in,out] hmac HMAC-SHA3-512 hash context. - * @param[out] dst Destination buffer. Must be at least 64 bytes in length. + * @param[in,out] ctx HMAC-SHA3-512 hash context. + * @param[out] mac [MAC][] destination buffer. Must be at least 64 bytes in length. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_512_absorb + * + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code (MAC)" */ -void hmac_sha3_512_final(hmac_sha3_t *hmac, uint8_t dst[64]); +void hmac_sha3_512_final(hmac_sha3_t *ctx, uint8_t mac[64]); /** * @defgroup shake SHAKE * - * @brief [SHA-3][] [XOFs][xof] with both fixed-length output and - * arbitrary-length output, as defined in section 6.2 of [FIPS 202][]. + * @brief [SHA-3][] [Extendable-output functions (XOFs)][xof] with + * fixed-length and arbitrary-length output, as defined in section 6.2 + * of [FIPS 202][]. * * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final * "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions" @@ -530,141 +704,210 @@ void hmac_sha3_512_final(hmac_sha3_t *hmac, uint8_t dst[64]); * @brief Hash data with SHAKE128. * @ingroup shake * - * Hash input message in buffer `m` of length `m_len` bytes with - * SHAKE128 (FIPS 202, section 6.2) and write 16 bytes of output to + * Hash input message in buffer `msg` of length `len` bytes with + * SHAKE128 ([FIPS 202][], section 6.2) and write 16 bytes of output to * destination buffer `dst`. * - * @param[in] m Input message. - * @param[in] m_len Input message length, in bytes. - * @param[out] dst Destination array. Must be at least 16 bytes in length. + * @param[in] msg Input message. + * @param[in] len Input message length, in bytes. + * @param[out] dst Destination buffer. Must be at least 16 bytes in length. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c shake128 + * + * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final + * "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions" */ -void shake128(const uint8_t *m, size_t m_len, uint8_t dst[static 16]); +void shake128(const uint8_t *msg, size_t len, uint8_t dst[static 16]); /** * @brief Hash data with SHAKE256. * @ingroup shake * - * Hash input message in buffer `m` of length `m_len` bytes with - * SHAKE256 (FIPS 202, section 6.2) and write the result to output - * buffer `dst`. + * Hash input message in buffer `msg` of length `len` bytes with + * SHAKE256 ([FIPS 202][], section 6.2) and write 32 bytes of output to + * destination buffer `dst`. + * + * @param[in] msg Input message. + * @param[in] len Input message length, in bytes. + * @param[out] dst Destination buffer. Must be at least 32 bytes in length. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c shake256 * - * @param[in] m Input message. - * @param[in] m_len Input message length, in bytes. - * @param[out] dst Destination array. Must be at least 16 bytes in length. + * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final + * "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions" */ -void shake256(const uint8_t *m, size_t m_len, uint8_t dst[static 32]); +void shake256(const uint8_t *msg, size_t len, uint8_t dst[static 32]); /** - * @brief Initialize SHAKE128 extendable-output function (XOF) context. + * @brief Initialize SHAKE128 [extendable-output function (XOF)][xof] context. * @ingroup shake * - * @param[out] xof SHAKE128 XOF context. + * @param[out] xof SHAKE128 [XOF][] context. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c shake128_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void shake128_xof_init(sha3_xof_t * const xof); /** - * @brief Absorb data into SHAKE128 XOF context. + * @brief Absorb data into SHAKE128 [XOF][] context. * @ingroup shake * - * Absorb input data in `m` of length `len` bytes into SHAKE128 XOF - * context `xof`. Can be called iteratively to absorb input data in - * chunks. + * Absorb input data in `msg` of length `len` bytes into SHAKE128 + * [XOF][] context `xof`. Can be called iteratively to absorb input + * data in chunks. * - * @param[in,out] xof SHAKE128 XOF context. - * @param[in] m Input data. + * @param[in,out] xof SHAKE128 [XOF][] context. + * @param[in] msg Input data. * @param[in] len Input data length, in bytes. * * @return True if data was absorbed, and false otherwise (e.g., if context has already been squeezed). + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c shake128_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ -_Bool shake128_xof_absorb(sha3_xof_t *xof, const uint8_t *m, const size_t len); +_Bool shake128_xof_absorb(sha3_xof_t *xof, const uint8_t *msg, const size_t len); /** - * @brief Squeeze bytes from SHAKE128 XOF context. + * @brief Squeeze bytes from SHAKE128 [XOF][] context. * @ingroup shake * - * Squeeze `dst_len` bytes of output into destination buffer `dst` from + * Squeeze `len` bytes of output into destination buffer `dst` from * SHAKE128 XOF context `xof`. Can be called iteratively to squeeze * output data in chunks. * - * @param[in,out] xof SHAKE128 XOF context. + * @param[in,out] xof SHAKE128 [XOF][] context. * @param[out] dst Destination buffer. - * @param[in] dst_len Destination buffer length, in bytes. + * @param[in] len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c shake128_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ -void shake128_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t dst_len); +void shake128_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len); /** - * @brief Absorb data into SHAKE128 XOF, then squeeze bytes out. + * @brief Absorb data into SHAKE128 [XOF][], then squeeze bytes out. * @ingroup shake * * Absorb data in buffer `src` of length `src_len` bytes into SHAKE128 - * XOF context, then squeeze `dst_len` bytes of output into destination - * buffer `dst`. + * [XOF][] context, then squeeze `dst_len` bytes of output into + * destination buffer `dst`. + * + * @note This function will produce different output than shake128(), + * because shake128() produces fixed-length output and this function + * produces arbitrary-length output. * * @param[in] src Source buffer. * @param[in] src_len Source buffer length, in bytes. * @param[out] dst Destination buffer. * @param[in] dst_len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c shake128_xof_once + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void shake128_xof_once(const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len); /** - * @brief Initialize SHAKE256 extendable-output function (XOF) context. + * @brief Initialize SHAKE256 [extendable-output function (XOF)][xof] + * context. * @ingroup shake * - * @param[out] xof SHAKE256 XOF context. + * @param[out] xof SHAKE256 [XOF][] context. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c shake256_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void shake256_xof_init(sha3_xof_t *xof); /** - * @brief Absorb data into SHAKE256 XOF context. + * @brief Absorb data into SHAKE256 [XOF][] context. * @ingroup shake * - * Absorb input data in `m` of length `len` bytes into SHAKE256 XOF - * context `xof`. Can be called iteratively to absorb input data in - * chunks. + * Absorb input data in `msg` of length `len` bytes into SHAKE256 + * [XOF][] context `xof`. Can be called iteratively to absorb input + * data in chunks. * - * @param[in,out] xof SHAKE256 XOF context. - * @param[in] m Input data. + * @param[in,out] xof SHAKE256 [XOF][] context. + * @param[in] msg Input data. * @param[in] len Input data length, in bytes. * * @return True if data was absorbed, and false otherwise (e.g., if context has already been squeezed). + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c shake256_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ -_Bool shake256_xof_absorb(sha3_xof_t *xof, const uint8_t *m, const size_t len); +_Bool shake256_xof_absorb(sha3_xof_t *xof, const uint8_t *msg, const size_t len); /** - * @brief Squeeze bytes from SHAKE256 XOF context. + * @brief Squeeze bytes from SHAKE256 [XOF][] context. * @ingroup shake * - * Squeeze `dst_len` bytes of output into destination buffer `dst` from - * SHAKE256 XOF context `xof`. Can be called iteratively to squeeze + * Squeeze `len` bytes of output into destination buffer `dst` from + * SHAKE256 [XOF][] context `xof`. Can be called iteratively to squeeze * output data in chunks. * - * @param[in,out] xof SHAKE256 XOF context. + * @param[in,out] xof SHAKE256 [XOF][] context. * @param[out] dst Destination buffer. - * @param[in] dst_len Destination buffer length, in bytes. + * @param[in] len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c shake256_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ -void shake256_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t dst_len); +void shake256_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len); /** - * @brief Absorb data into SHAKE256 XOF, then squeeze bytes out. + * @brief Absorb data into SHAKE256 [XOF][], then squeeze bytes out. * @ingroup shake * * Absorb data in buffer `src` of length `src_len` bytes into SHAKE256 - * XOF context, then squeeze `dst_len` bytes of output into destination - * buffer `dst`. + * [XOF][] context, then squeeze `dst_len` bytes of output into + * destination buffer `dst`. + * + * @note This function will produce different output than shake256(), + * because shake256() produces fixed-length output and this function + * produces arbitrary-length output. * * @param[in] src Source buffer. * @param[in] src_len Source buffer length, in bytes. * @param[out] dst Destination buffer. * @param[in] dst_len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c shake256_xof_once + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void shake256_xof_once(const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len); /** * @defgroup cshake cSHAKE * - * @brief Fixed-length and [XOF][] variants of the customizable-SHAKE - * primitive, as defined in section 3 of [SP 800-185][800-185]. + * @brief Customizable SHAKE (cSHAKE) [extendable-output function + * (XOF)][xof], as defined in section 3 of [SP 800-185][800-185]. * * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function * "Extendable-Output Function (XOF)" @@ -688,20 +931,28 @@ typedef struct { * @ingroup cshake * * Initialize internal cSHAKE128 (customizable SHAKE128, as defined in - * section 3 of NIST SP 800-185) context with customization parameters - * `params`, absorb data in buffer `src` of length `src_len` bytes into - * internal context, then squeeze `dst_len` bytes of output into - * destination buffer `dst`. + * section 3 of [NIST SP 800-185][800-185]) context with customization + * parameters `params`, absorb data in buffer `src` of length `src_len` + * bytes into internal context, then squeeze `dst_len` bytes of output + * into destination buffer `dst`. * - * Note: cSHAKE is used to implement the hash and extendable output - * functions (XOF) defined in NIST SP 800-185 and should generally not - * be used directly. + * @note cSHAKE is used to implement the [extendable output functions + * (XOFs)][xof] defined in [NIST SP 800-185][800-185] and should + * generally not be used directly. * * @param[in] params cSHAKE customization parameters. * @param[in] src Source buffer. * @param[in] src_len Source buffer length, in bytes. * @param[out] dst Destination buffer. * @param[in] dst_len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c cshake128 + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" */ void cshake128(const cshake_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len); @@ -710,130 +961,188 @@ void cshake128(const cshake_params_t params, const uint8_t *src, const size_t sr * @ingroup cshake * * Initialize internal cSHAKE256 (customizable SHAKE256, as defined in - * section 3 of NIST SP 800-185) context with customization parameters - * `params`, absorb data in buffer `src` of length `src_len` bytes into - * internal context, then squeeze `dst_len` bytes of output into - * destination buffer `dst`. + * section 3 of [NIST SP 800-185][800-185]) context with customization + * parameters `params`, absorb data in buffer `src` of length `src_len` + * bytes into internal context, then squeeze `dst_len` bytes of output + * into destination buffer `dst`. * - * Note: cSHAKE is used to implement the hash and extendable output - * functions (XOF) defined in NIST SP 800-185 and should generally not - * be used directly. + * @note cSHAKE is used to implement the [extendable output functions + * (XOFs)][xof] defined in [NIST SP 800-185][800-185] and should + * generally not be used directly. * * @param[in] params cSHAKE customization parameters. * @param[in] src Source buffer. * @param[in] src_len Source buffer length, in bytes. * @param[out] dst Destination buffer. * @param[in] dst_len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c cshake256 + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" */ void cshake256(const cshake_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len); /** - * @brief Initialize cSHAKE128 XOF context. + * @brief Initialize cSHAKE128 [XOF][] context. * @ingroup cshake * * Initialize cSHAKE128 (customizable SHAKE128, as defined in section 3 of - * NIST SP 800-185) XOF context with customization parameters `params`. + * [NIST SP 800-185][800-185]) [XOF][] context with customization + * parameters `params`. * - * Note: cSHAKE is used to implement the hash and extendable output - * functions (XOF) defined in NIST SP 800-185 and should generally not - * be used directly. + * @note cSHAKE is used to implement the [extendable output functions + * (XOFs)][xof] defined in [NIST SP 800-185][800-185] and should + * generally not be used directly. * - * @param[out] xof cSHAKE128 context. + * @param[out] xof cSHAKE128 [XOF][] context. * @param[in] params cSHAKE128 customization parameters. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c cshake128_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" */ void cshake128_xof_init(sha3_xof_t *xof, const cshake_params_t params); /** - * @brief Absorb data into cSHAKE128 XOF context. + * @brief Absorb data into cSHAKE128 [XOF][] context. * @ingroup cshake * - * Absorb data in buffer `src` of length `len` bytes into cSHAKE128 XOF - * context `xof`. Can be called iteratively to absorb input data in - * chunks. + * Absorb data in buffer `src` of length `len` bytes into cSHAKE128 + * [XOF][] context `xof`. Can be called iteratively to absorb input + * data in chunks. * - * Note: cSHAKE is used to implement the hash and extendable output - * functions (XOF) defined in NIST SP 800-185 and should generally not - * be used directly. + * @note cSHAKE is used to implement the [extendable output functions + * (XOFs)][xof] defined in [NIST SP 800-185][800-185] and should + * generally not be used directly. * - * @param[in,out] xof cSHAKE128 context. + * @param[in,out] xof cSHAKE128 [XOF][] context. * @param[in] src Source buffer. * @param[in] len Source buffer length, in bytes. * * @return True if data was absorbed, and false otherwise (e.g., if context has already been squeezed). + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c cshake128_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" */ _Bool cshake128_xof_absorb(sha3_xof_t *xof, const uint8_t *src, const size_t len); /** - * @brief Squeeze bytes from cSHAKE128 XOF context. + * @brief Squeeze bytes from cSHAKE128 [XOF][] context. * @ingroup cshake * * Squeeze `dst_len` bytes of output into destination buffer `dst` from - * cSHAKE128 XOF context `xof`. Can be called iteratively to squeeze - * output data in chunks. + * cSHAKE128 [XOF][] context `xof`. Can be called iteratively to + * squeeze output data in chunks. * - * Note: cSHAKE is used to implement the hash and extendable output - * functions (XOF) defined in NIST SP 800-185 and should generally not - * be used directly. + * @note cSHAKE is used to implement the [extendable output functions + * (XOFs)][xof] defined in [NIST SP 800-185][800-185] and should + * generally not be used directly. * - * @param[in,out] xof cSHAKE128 context. + * @param[in,out] xof cSHAKE128 [XOF][] context. * @param[out] dst Destination buffer. * @param[in] len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c cshake128_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" */ void cshake128_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len); /** - * @brief Initialize cSHAKE256 XOF context. + * @brief Initialize cSHAKE256 [XOF][] context. * @ingroup cshake * - * Initialize cSHAKE256 (customizable SHAKE256, as defined in section 3 of - * NIST SP 800-185) XOF context with customization parameters `params`. + * Initialize cSHAKE256 (customizable SHAKE256, as defined in section 3 + * of [NIST SP 800-185][800-185]) [XOF][] context with customization + * parameters `params`. * - * Note: cSHAKE is used to implement the hash and extendable output - * functions (XOF) defined in NIST SP 800-185 and should generally not - * be used directly. + * @note cSHAKE is used to implement the [extendable output functions + * (XOFs)][xof] defined in [NIST SP 800-185][800-185] and should + * generally not be used directly. * * @ingroup cshake * - * @param[out] xof cSHAKE256 context. + * @param[out] xof cSHAKE256 [XOF][] context. * @param[in] params cSHAKE256 customization parameters. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c cshake256_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" */ void cshake256_xof_init(sha3_xof_t *xof, const cshake_params_t params); /** - * @brief Absorb data into cSHAKE256 XOF context. + * @brief Absorb data into cSHAKE256 [XOF][] context. * @ingroup cshake * - * Absorb data in buffer `src` of length `len` bytes into cSHAKE256 XOF - * context `xof`. Can be called iteratively to absorb input data in - * chunks. + * Absorb data in buffer `src` of length `len` bytes into cSHAKE256 + * [XOF][] context `xof`. Can be called iteratively to absorb input + * data in chunks. * - * Note: cSHAKE is used to implement the hash and extendable output - * functions (XOF) defined in NIST SP 800-185 and should generally not - * be used directly. + * @note cSHAKE is used to implement the hash and [extendable output + * functions (XOFs)][xof] defined in [NIST SP 800-185][800-185] and + * should generally not be used directly. * - * @param[in,out] xof cSHAKE256 context. + * @param[in,out] xof cSHAKE256 [XOF][] context. * @param[in] src Source buffer. * @param[in] len Source buffer length, in bytes. * * @return True if data was absorbed, and false otherwise (e.g., if context has already been squeezed). + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c cshake256_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" */ _Bool cshake256_xof_absorb(sha3_xof_t *xof, const uint8_t *src, const size_t len); /** - * @brief Squeeze bytes from cSHAKE256 XOF context. + * @brief Squeeze bytes from cSHAKE256 [XOF][] context. * @ingroup cshake * * Squeeze `dst_len` bytes of output into destination buffer `dst` from - * cSHAKE256 XOF context `xof`. Can be called iteratively to squeeze - * output data in chunks. + * cSHAKE256 [XOF][] context `xof`. Can be called iteratively to + * squeeze output data in chunks. * - * Note: cSHAKE is used to implement the hash and extendable output - * functions (XOF) defined in NIST SP 800-185 and should generally not - * be used directly. + * @note cSHAKE is used to implement the hash and [extendable output + * functions (XOFs)][xof] defined in [NIST SP 800-185][800-185] and + * should generally not be used directly. * - * @param[in,out] xof cSHAKE256 context. + * @param[in,out] xof cSHAKE256 [XOF][] context. * @param[out] dst Destination buffer. * @param[in] len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c cshake256_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" */ void cshake256_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len); @@ -865,16 +1174,26 @@ typedef struct { * @ingroup kmac * * Initialize internal KMAC128 (Keccak Message Authentication Code, as - * defined in section 4 of NIST SP 800-185) context with configuration - * parameters `params`, absorb data in buffer `src` of length `src_len` - * bytes into internal context, then squeeze `dst_len` bytes of output - * into destination buffer `dst`. + * defined in section 4 of [NIST SP 800-185][800-185]) context with + * configuration parameters `params`, absorb data in buffer `src` of + * length `src_len` bytes into internal context, then squeeze `dst_len` + * bytes of output into destination buffer `dst`. * * @param[in] params KMAC configuration parameters. * @param[in] src Source buffer. * @param[in] src_len Source buffer length, in bytes. * @param[out] dst Destination buffer. * @param[in] dst_len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c kmac128 + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code" */ void kmac128(const kmac_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len); @@ -883,7 +1202,7 @@ void kmac128(const kmac_params_t params, const uint8_t *src, const size_t src_le * @ingroup kmac * * Initialize internal KMAC256 (Keccak Message Authentication Code, as - * defined in section 4 of NIST SP 800-185) XOF context with + * defined in section 4 of [NIST SP 800-185][800-185]) context with * configuration parameters `params`, absorb data in buffer `src` of * length `src_len` bytes into internal context, then squeeze `dst_len` * bytes of output into destination buffer `dst`. @@ -893,24 +1212,44 @@ void kmac128(const kmac_params_t params, const uint8_t *src, const size_t src_le * @param[in] src_len Source buffer length, in bytes. * @param[out] dst Destination buffer. * @param[in] dst_len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c kmac256 + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code" */ void kmac256(const kmac_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len); /** - * @brief Initialize KMAC128 XOF context. + * @brief Initialize KMAC128 [XOF][] context. * @ingroup kmac * - * Initialize KMAC128 XOF (Keccak Message Authentication Code eXtendable - * Output Function, as defined in section 4.3.1 of NIST SP 800-185) - * context with configuration parameters `params`. + * Initialize KMAC128 [XOF][] (Keccak Message Authentication Code eXtendable + * Output Function, as defined in section 4.3.1 of [NIST SP + * 800-185][800-185]) context with configuration parameters `params`. * - * Note: KMAC128 and KMAC128 XOF produce different output, because + * @note KMAC128 and KMAC128 [XOF][] produce different output, because * KMAC128 encodes the fixed output size as part of the input while - * KMAC128 XOF does not. See section 4.3.1 of NIST SP 800-185 for - * details. + * KMAC128 [XOF][] does not. See section 4.3.1 of [NIST SP + * 800-185][800-185] for details. * - * @param[out] xof KMAC128 XOF context. + * @param[out] xof KMAC128 [XOF][] context. * @param[in] params KMAC configuration parameters. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c kmac128_xof + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code" */ void kmac128_xof_init(sha3_xof_t *xof, const kmac_params_t params); @@ -918,133 +1257,207 @@ void kmac128_xof_init(sha3_xof_t *xof, const kmac_params_t params); * @brief Absorb data into KMAC128 XOF context. * @ingroup kmac * - * Absorb data in buffer `src` of length `len` bytes into KMAC128 XOF - * context. Can be called iteratively to absorb input data in chunks. + * Absorb data in buffer `src` of length `len` bytes into KMAC128 + * [XOF][] context. Can be called iteratively to absorb input data in + * chunks. * - * @param[in,out] xof KMAC128 XOF context. + * @param[in,out] xof KMAC128 [XOF][] context. * @param[in] src Source buffer. * @param[in] len Source buffer length, in bytes. * * @return True if data was absorbed, and false otherwise (e.g., if context has already been squeezed). + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c kmac128_xof + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code" */ _Bool kmac128_xof_absorb(sha3_xof_t *xof, const uint8_t *src, const size_t len); /** - * @brief Squeeze data from KMAC128 XOF context. + * @brief Squeeze data from KMAC128 [XOF][] context. * @ingroup kmac * * Squeeze `len` bytes of output into destination buffer `dst` from - * KMAC128 XOF context `xof`. Can be called iteratively to squeeze + * KMAC128 [XOF][] context `xof`. Can be called iteratively to squeeze * output data in chunks. * - * Note: KMAC128 and KMAC128 XOF produce different output, because + * @note KMAC128 and KMAC128 [XOF][] produce different output, because * KMAC128 encodes the fixed output size as part of the input while - * KMAC128 XOF does not. See section 4.3.1 of NIST SP 800-185 for - * details. + * KMAC128 [XOF][] does not. See section 4.3.1 of [NIST SP + * 800-185][800-185] for details. * - * @param[in,out] xof KMAC128 XOF context. + * @param[in,out] xof KMAC128 [XOF][] context. * @param[out] dst Destination buffer. * @param[in] len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c kmac128_xof + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code" */ void kmac128_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len); /** - * @brief Absorb data into KMAC128 XOF context, then squeeze bytes out. + * @brief Absorb data into KMAC128 [XOF][] context, then squeeze bytes out. * @ingroup kmac * - * Initialize internal KMAC128 XOF (Keccak Message Authentication Code - * eXtendable Output Function, as defined in section 4 of NIST SP - * 800-185) context with configuration parameters `params`, absorb data - * in buffer `src` of length `src_len` bytes into internal context, then - * squeeze `dst_len` bytes of output into destination buffer `dst`. + * Initialize internal KMAC128 [XOF][] (Keccak Message Authentication + * Code eXtendable Output Function, as defined in section 4 of [NIST SP + * 800-185][800-185]) context with configuration parameters `params`, + * absorb data in buffer `src` of length `src_len` bytes into internal + * context, then squeeze `dst_len` bytes of output into destination + * buffer `dst`. * - * Note: KMAC128 and KMAC128 XOF produce different output, because + * @note KMAC128 and KMAC128 [XOF][] produce different output, because * KMAC128 encodes the fixed output size as part of the input while - * KMAC128 XOF does not. See section 4.3.1 of NIST SP 800-185 for - * details. + * KMAC128 [XOF][] does not. See section 4.3.1 of [NIST SP + * 800-185][800-185] for details. * * @param[in] params KMAC configuration parameters. * @param[in] src Source buffer. * @param[in] src_len Source buffer length, in bytes. * @param[out] dst Destination buffer. * @param[in] dst_len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c kmac256_xof_once + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code" */ void kmac128_xof_once(const kmac_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len); /** - * @brief Initialize KMAC256 XOF context. + * @brief Initialize KMAC256 [XOF][] context. * @ingroup kmac * - * Initialize KMAC256 XOF (Keccak Message Authentication Code eXtendable - * Output Function, as defined in section 4.3.1 of NIST SP 800-185) - * context with configuration parameters `params`. + * Initialize KMAC256 [XOF][] (Keccak Message Authentication Code + * eXtendable Output Function, as defined in section 4.3.1 of [NIST SP + * 800-185][800-185]) context with configuration parameters `params`. * - * Note: KMAC256 and KMAC256 XOF produce different output, because + * @note KMAC256 and KMAC256 [XOF][] produce different output, because * KMAC256 encodes the fixed output size as part of the input while - * KMAC256 XOF does not. See section 4.3.1 of NIST SP 800-185 for - * details. + * KMAC256 [XOF][] does not. See section 4.3.1 of [NIST SP + * 800-185][800-185] for details. * - * @param[out] xof KMAC256 XOF context. + * @param[out] xof KMAC256 [XOF][] context. * @param[in] params KMAC configuration parameters. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c kmac256_xof + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code" */ void kmac256_xof_init(sha3_xof_t *xof, const kmac_params_t params); /** - * @brief Absorb data into KMAC256 XOF context. + * @brief Absorb data into KMAC256 [XOF][] context. * @ingroup kmac * - * Absorb data in buffer `src` of length `len` bytes into KMAC256 XOF - * context. Can be called iteratively to absorb input data in chunks. + * Absorb data in buffer `src` of length `len` bytes into KMAC256 + * [XOF][] context. Can be called iteratively to absorb input data in + * chunks. * - * @param[in,out] xof KMAC256 XOF context. + * @param[in,out] xof KMAC256 [XOF][] context. * @param[in] src Source buffer. * @param[in] len Source buffer length, in bytes. * * @return True if data was absorbed, and false otherwise (e.g., if context has already been squeezed). + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c kmac256_xof + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code" */ _Bool kmac256_xof_absorb(sha3_xof_t *xof, const uint8_t *src, const size_t len); /** - * @brief Squeeze data from KMAC256 XOF context. + * @brief Squeeze data from KMAC256 [XOF][] context. * @ingroup kmac * * Squeeze `len` bytes of output into destination buffer `dst` from - * KMAC256 XOF context `xof`. Can be called iteratively to squeeze + * KMAC256 [XOF][] context `xof`. Can be called iteratively to squeeze * output data in chunks. * - * Note: KMAC256 and KMAC256 XOF produce different output, because + * @note KMAC256 and KMAC256 [XOF][] produce different output, because * KMAC256 encodes the fixed output size as part of the input while - * KMAC256 XOF does not. See section 4.3.1 of NIST SP 800-185 for - * details. + * KMAC256 [XOF][] does not. See section 4.3.1 of [NIST SP + * 800-185][800-185] for details. * * @ingroup kmac * - * @param[in,out] xof KMAC256 XOF context. + * @param[in,out] xof KMAC256 [XOF] context. * @param[out] dst Destination buffer. * @param[in] len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c kmac256_xof + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code" */ void kmac256_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len); /** - * @brief Absorb data into KMAC256 XOF context, then squeeze bytes out. + * @brief Absorb data into KMAC256 [XOF][] context, then squeeze bytes out. * @ingroup kmac * - * Initialize internal KMAC256 XOF (Keccak Message Authentication Code - * eXtendable Output Function, as defined in section 4 of NIST SP - * 800-185) context with configuration parameters `params`, absorb data - * in buffer `src` of length `src_len` bytes into internal context, then - * squeeze `dst_len` bytes of output into destination buffer `dst`. + * Initialize internal KMAC256 [XOF][] (Keccak Message Authentication + * Code eXtendable Output Function, as defined in section 4 of [NIST SP + * 800-185][800-185]) context with configuration parameters `params`, + * absorb data in buffer `src` of length `src_len` bytes into internal + * context, then squeeze `dst_len` bytes of output into destination + * buffer `dst`. * - * Note: KMAC256 and KMAC256 XOF produce different output, because + * @note KMAC256 and KMAC256 [XOF][] produce different output, because * KMAC256 encodes the fixed output size as part of the input while - * KMAC256 XOF does not. See section 4.3.1 of NIST SP 800-185 for - * details. + * KMAC256 [XOF][] does not. See section 4.3.1 of [NIST SP + * 800-185][800-185] for details. * * @param[in] params KMAC configuration parameters. * @param[in] src Source buffer. * @param[in] src_len Source buffer length, in bytes. * @param[out] dst Destination buffer. * @param[in] dst_len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c kmac256_xof_once + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" + * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code + * "Message authentication code" */ void kmac256_xof_once(const kmac_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len); @@ -1063,8 +1476,11 @@ void kmac256_xof_once(const kmac_params_t params, const uint8_t *src, const size */ /** - * @brief TupleHash tuple element. + * @brief Individual element of TupleHash [tuple][]. * @ingroup tuplehash + * + * [tuple]: https://en.wikipedia.org/wiki/Tuple + * "Ordered list of elements." */ typedef struct { const uint8_t *ptr; /**< Pointer to byte string. */ @@ -1083,146 +1499,224 @@ typedef struct { } tuplehash_params_t; /** - * @brief Absorb data into TupleHash128, then squeeze bytes out. + * @brief Absorb [tuple][] and customization string into TupleHash128, + * then squeeze bytes out. * @ingroup tuplehash * - * Initialize internal TupleHash128 (NIST SP 800-185, section 5) context - * with configuration parameters `params`, then squeeze `dst_len` bytes - * of output from internal context into destination buffer `dst`. + * Initialize internal TupleHash128 ([NIST SP 800-185][800-185], section + * 5) context with configuration parameters `params`, then squeeze `len` + * bytes of output from internal context into destination buffer `dst`. * * @param[in] params TupleHash128 configuration parameters. * @param[out] dst Destination buffer. - * @param[in] dst_len Destination buffer length, in bytes. + * @param[in] len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c tuplehash128 + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [tuple]: https://en.wikipedia.org/wiki/Tuple + * "Ordered list of elements." */ -void tuplehash128(const tuplehash_params_t params, uint8_t *dst, const size_t dst_len); +void tuplehash128(const tuplehash_params_t params, uint8_t *dst, const size_t len); /** - * @brief Absorb data into TupleHash256, then squeeze bytes out. + * @brief Absorb [tuple][] and customization string into TupleHash256, + * then squeeze bytes out. * @ingroup tuplehash * - * Initialize internal TupleHash256 (NIST SP 800-185, section 5) context - * with configuration parameters `params`, then squeeze `dst_len` bytes - * of output from internal context into destination buffer `dst`. + * Initialize internal TupleHash256 ([NIST SP 800-185][800-185], section + * 5) context with configuration parameters `params`, then squeeze `len` + * bytes of output from internal context into destination buffer `dst`. * * @ingroup tuplehash * * @param[in] params TupleHash256 configuration parameters. * @param[out] dst Destination buffer. - * @param[in] dst_len Destination buffer length, in bytes. + * @param[in] len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c tuplehash256 + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [tuple]: https://en.wikipedia.org/wiki/Tuple + * "Ordered list of elements." */ -void tuplehash256(const tuplehash_params_t params, uint8_t *dst, const size_t dst_len); +void tuplehash256(const tuplehash_params_t params, uint8_t *dst, const size_t len); /** - * @brief Initialize a TupleHash128 XOF context. + * @brief Initialize a TupleHash128 [XOF][] context. * @ingroup tuplehash * - * Initialize TupleHash128 XOF (TupleHash eXtendable Output Function, as - * defined in section 5.3.1 of NIST SP 800-185) context with - * configuration parameters `params`. + * Initialize TupleHash128 [XOF][] (TupleHash eXtendable Output + * Function, as defined in section 5.3.1 of [NIST SP 800-185][800-185]) + * context with configuration parameters `params`. * - * Note: TupleHash128 and TupleHash128 XOF produce different output, + * @note TupleHash128 and TupleHash128 [XOF][] produce different output, * because TupleHash128 encodes the fixed output size as part of the - * input while TupleHash128 XOF does not. See section 5.3.1 of NIST SP - * 800-185 for details. + * input while TupleHash128 [XOF][] does not. See section 5.3.1 of + * [NIST SP 800-185][800-185] for details. * - * @param[out] xof TupleHash128 XOF context. + * @param[out] xof TupleHash128 [XOF][] context. * @param[in] params TupleHash configuration parameters. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c tuplehash128_xof + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [tuple]: https://en.wikipedia.org/wiki/Tuple + * "Ordered list of elements." + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void tuplehash128_xof_init(sha3_xof_t *xof, const tuplehash_params_t params); /** - * @brief Squeeze data from TupleHash128 XOF context. + * @brief Squeeze data from TupleHash128 [XOF][] context. * @ingroup tuplehash * * Squeeze `len` bytes of output into destination buffer `dst` from - * TupleHash128 XOF context `xof`. Can be called iteratively to squeeze - * output data in chunks. + * TupleHash128 [XOF][] context `xof`. Can be called iteratively to + * squeeze output data in chunks. * - * Note: TupleHash128 and TupleHash128 XOF produce different output, + * @note TupleHash128 and TupleHash128 [XOF][] produce different output, * because TupleHash128 encodes the fixed output size as part of the - * input while TupleHash128 XOF does not. See section 5.3.1 of NIST SP - * 800-185 for details. + * input while TupleHash128 [XOF][] does not. See section 5.3.1 of + * [NIST SP 800-185][800-185] for details. * - * @param[in,out] xof TupleHash128 XOF context. + * @param[in,out] xof TupleHash128 [XOF][] context. * @param[out] dst Destination buffer. * @param[in] len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c tuplehash128_xof + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [tuple]: https://en.wikipedia.org/wiki/Tuple + * "Ordered list of elements." + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void tuplehash128_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len); /** - * @brief Absorb data into TupleHash128 XOF, then squeeze bytes out. + * @brief Absorb data into TupleHash128 [XOF][], then squeeze bytes out. * @ingroup tuplehash * - * Initialize internal TupleHash128 XOF (TupleHash eXtendable Output - * Function, as defined in section 5 of NIST SP 800-185) context with - * configuration parameters `params`, then squeeze `dst_len` bytes of - * output into destination buffer `dst`. + * Initialize internal TupleHash128 [XOF][] (TupleHash eXtendable Output + * Function, as defined in section 5 of [NIST SP 800-185][800-185]) + * context with configuration parameters `params`, then squeeze + * `len` bytes of output into destination buffer `dst`. * - * Note: TupleHash128 and TupleHash128 XOF produce different output, + * @note TupleHash128 and TupleHash128 [XOF][] produce different output, * because TupleHash128 encodes the fixed output size as part of the - * input while TupleHash128 XOF does not. See section 5.3.1 of NIST SP - * 800-185 for details. + * input while TupleHash128 [XOF][] does not. See section 5.3.1 of + * [NIST SP 800-185][800-185] for details. * * @param[in] params TupleHash128 configuration parameters. * @param[out] dst Destination buffer. - * @param[in] dst_len Destination buffer length, in bytes. + * @param[in] len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c tuplehash128_xof_once + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [tuple]: https://en.wikipedia.org/wiki/Tuple + * "Ordered list of elements." + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ -void tuplehash128_xof_once(const tuplehash_params_t params, uint8_t *dst, const size_t dst_len); +void tuplehash128_xof_once(const tuplehash_params_t params, uint8_t *dst, const size_t len); /** - * @brief Initialize a TupleHash256 XOF context. + * @brief Initialize a TupleHash256 [XOF][] context. * @ingroup tuplehash * - * Initialize TupleHash256 XOF (TupleHash eXtendable Output Function, as - * defined in section 5.3.1 of NIST SP 800-185) context with - * configuration parameters `params`. + * Initialize TupleHash256 [XOF][] (TupleHash eXtendable Output + * Function, as defined in section 5.3.1 of [NIST SP 800-185][800-185]) + * context with configuration parameters `params`. * - * Note: TupleHash256 and TupleHash256 XOF produce different output, + * @note TupleHash256 and TupleHash256 [XOF][] produce different output, * because TupleHash256 encodes the fixed output size as part of the - * input while TupleHash256 XOF does not. See section 5.3.1 of NIST SP - * 800-185 for details. + * input while TupleHash256 [XOF][] does not. See section 5.3.1 of + * [NIST SP 800-185][800-185] for details. * - * @param[out] xof TupleHash256 XOF context. + * @param[out] xof TupleHash256 [XOF][] context. * @param[in] params TupleHash configuration parameters. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c tuplehash256_xof + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [tuple]: https://en.wikipedia.org/wiki/Tuple + * "Ordered list of elements." + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void tuplehash256_xof_init(sha3_xof_t *xof, const tuplehash_params_t params); /** - * @brief Squeeze bytes from a TupleHash256 XOF context. + * @brief Squeeze bytes from a TupleHash256 [XOF][] context. * @ingroup tuplehash * * Squeeze `len` bytes of output into destination buffer `dst` from - * TupleHash256 XOF context `xof`. Can be called iteratively to squeeze - * output data in chunks. + * TupleHash256 [XOF][] context `xof`. Can be called iteratively to + * squeeze output data in chunks. * - * Note: TupleHash256 and TupleHash256 XOF produce different output, + * @note TupleHash256 and TupleHash256 [XOF][] produce different output, * because TupleHash256 encodes the fixed output size as part of the - * input while TupleHash256 XOF does not. See section 5.3.1 of NIST SP - * 800-185 for details. + * input while TupleHash256 [XOF][] does not. See section 5.3.1 of + * [NIST SP 800-185][800-185] for details. * - * @param[in,out] xof TupleHash256 XOF context. + * @param[in,out] xof TupleHash256 [XOF][] context. * @param[out] dst Destination buffer. * @param[in] len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c tuplehash256_xof + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [tuple]: https://en.wikipedia.org/wiki/Tuple + * "Ordered list of elements." + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void tuplehash256_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len); /** - * @brief Absorb data into TupleHash256 XOF, then squeeze bytes out. + * @brief Absorb data into TupleHash256 [XOF][], then squeeze bytes out. * @ingroup tuplehash * - * Initialize internal TupleHash256 XOF (TupleHash eXtendable Output - * Function, as defined in section 5 of NIST SP 800-185) context with - * configuration parameters `params`, then squeeze `dst_len` bytes of - * output into destination buffer `dst`. + * Initialize internal TupleHash256 [XOF][] (TupleHash eXtendable Output + * Function, as defined in section 5 of [NIST SP 800-185][800-185]) + * context with configuration parameters `params`, then squeeze `len` + * bytes of output into destination buffer `dst`. * - * Note: TupleHash256 and TupleHash256 XOF produce different output, + * Note: TupleHash256 and TupleHash256 [XOF][] produce different output, * because TupleHash256 encodes the fixed output size as part of the - * input while TupleHash256 XOF does not. See section 5.3.1 of NIST SP - * 800-185 for details. + * input while TupleHash256 [XOF][] does not. See section 5.3.1 of + * [NIST SP 800-185][800-185] for details. * * @param[in] params TupleHash256 configuration parameters. * @param[out] dst Destination buffer. * @param[in] len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c tuplehash256_xof_once + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [tuple]: https://en.wikipedia.org/wiki/Tuple + * "Ordered list of elements." + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void tuplehash256_xof_once(const tuplehash_params_t params, uint8_t *dst, const size_t len); @@ -1264,20 +1758,26 @@ typedef struct { * @brief Absorb data into ParallelHash128, then squeeze bytes out. * @ingroup parallelhash * - * Initialize internal ParallelHash128 (NIST SP 800-185, section 6) - * context with configuration parameters `params`, then squeeze - * `dst_len` bytes of output from internal context into destination - * buffer `dst`. + * Initialize internal ParallelHash128 ([NIST SP 800-185][800-185], + * section 6) context with configuration parameters `params`, then + * squeeze `dst_len` bytes of output from internal context into + * destination buffer `dst`. * - * Note: This implementation of ParallelHash128 is sequential, not - * parallel. + * @note This ParallelHash implementation is sequential, not parallel. * - * Note: This implementation of ParallelHash128 is sequential, not - * @param[in] params ParallelHash128 configuration parameters. + * @param[in] params ParallelHash configuration parameters. * @param[in] src Source buffer. * @param[in] src_len Source buffer length, in bytes. * @param[out] dst Destination buffer. * @param[in] dst_len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c parallelhash128 + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void parallelhash128(const parallelhash_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len); @@ -1285,193 +1785,256 @@ void parallelhash128(const parallelhash_params_t params, const uint8_t *src, con * @brief Absorb data into ParallelHash256, then squeeze bytes out. * @ingroup parallelhash * - * Initialize internal ParallelHash256 (NIST SP 800-185, section 6) - * context with configuration parameters `params`, then squeeze - * `dst_len` bytes of output from internal context into destination - * buffer `dst`. + * Initialize internal ParallelHash256 ([NIST SP 800-185][800-185], + * section 6) context with configuration parameters `params`, then + * squeeze `dst_len` bytes of output from internal context into + * destination buffer `dst`. * - * Note: This implementation of ParallelHash256 is sequential, not - * parallel. + * @note This ParallelHash implementation is sequential, not parallel. * * @ingroup parallelhash * - * @param[in] params ParallelHash256 configuration parameters. + * @param[in] params ParallelHash configuration parameters. * @param[in] src Source buffer. * @param[in] src_len Source buffer length, in bytes. * @param[out] dst Destination buffer. * @param[in] dst_len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c parallelhash256 + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void parallelhash256(const parallelhash_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len); /** - * @brief Initialize a ParallelHash128 XOF context. + * @brief Initialize a ParallelHash128 [XOF][] context. * @ingroup parallelhash * - * Initialize ParallelHash128 XOF (ParallelHash eXtendable Output - * Function, as defined in section 6.3.1 of NIST SP 800-185) context - * with configuration parameters `params`. + * Initialize ParallelHash128 [XOF][] (ParallelHash eXtendable Output + * Function, as defined in section 6.3.1 of [NIST SP 800-185][800-185]) + * context with configuration parameters `params`. * - * Note: ParallelHash128 and ParallelHash128 XOF produce different + * @note ParallelHash128 and ParallelHash128 [XOF][] produce different * output, because ParallelHash128 encodes the fixed output size as part * of the input while ParallelHash128 XOF does not. See section 6.3.1 - * of NIST SP 800-185 for details. + * of [NIST SP 800-185][800-185] for details. * - * Note: This implementation of ParallelHash128 is sequential, not - * parallel. + * @note This ParallelHash implementation is sequential, not parallel. * - * @param[out] xof ParallelHash128 XOF context. + * @param[out] xof ParallelHash128 [XOF][] context. * @param[in] params ParallelHash configuration parameters. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c parallelhash128_xof + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void parallelhash128_xof_init(parallelhash_t *xof, const parallelhash_params_t params); /** - * @brief Absorb data into a ParallelHash128 XOF context. + * @brief Absorb data into a ParallelHash128 [XOF][] context. * @ingroup parallelhash * * Absorb data in buffer `src` of length `len` bytes into - * ParallelHash128 XOF context. Can be called iteratively to absorb + * ParallelHash128 [XOF][] context. Can be called iteratively to absorb * input data in chunks. * - * Note: This implementation of ParallelHash128 is sequential, not - * parallel. + * @note This ParallelHash implementation is sequential, not parallel. * - * @param[in,out] hash ParallelHash128 XOF context. + * @param[in,out] hash ParallelHash128 [XOF][] context. * @param[in] src Source buffer. * @param[in] len Source buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c parallelhash128_xof + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void parallelhash128_xof_absorb(parallelhash_t *hash, const uint8_t *src, const size_t len); /** - * @brief Squeeze bytes from a ParallelHash128 XOF context. + * @brief Squeeze bytes from a ParallelHash128 [XOF][] context. * @ingroup parallelhash * * Squeeze `len` bytes of output into destination buffer `dst` from - * ParallelHash128 XOF context `xof`. Can be called iteratively to + * ParallelHash128 [XOF][] context `xof`. Can be called iteratively to * squeeze output data in chunks. * - * Note: ParallelHash128 and ParallelHash128 XOF produce different + * @note ParallelHash128 and ParallelHash128 [XOF][] produce different * output, because ParallelHash128 encodes the fixed output size as part - * of the input while ParallelHash128 XOF does not. See section 6.3.1 - * of NIST SP 800-185 for details. + * of the input while ParallelHash128 [XOF][] does not. See section + * 6.3.1 of [NIST SP 800-185][800-185] for details. * - * Note: This implementation of ParallelHash128 is sequential, not - * parallel. + * @note This ParallelHash implementation is sequential, not parallel. * * @param[in,out] xof ParallelHash128 XOF context. * @param[out] dst Destination buffer. * @param[in] len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c parallelhash128_xof + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void parallelhash128_xof_squeeze(parallelhash_t *xof, uint8_t *dst, const size_t len); /** - * @brief Absorb bytes into ParallelHash128 XOF, then squeeze bytes out. + * @brief Absorb bytes into ParallelHash128 [XOF][], then squeeze bytes out. * @ingroup parallelhash * - * Initialize internal ParallelHash128 XOF (ParallelHash eXtendable - * Output Function, as defined in section 6.3.1 of NIST SP 800-185) - * context with configuration parameters `params`, absorb data in buffer - * `src` of length `src_len` bytes into context, then squeeze `dst_len` - * bytes of output into destination buffer `dst`. + * Initialize internal ParallelHash128 [XOF][] (ParallelHash eXtendable + * Output Function, as defined in section 6.3.1 of [NIST SP + * 800-185][800-185]) context with configuration parameters `params`, + * absorb data in buffer `src` of length `src_len` bytes into context, + * then squeeze `dst_len` bytes of output into destination buffer `dst`. * - * Note: ParallelHash128 and ParallelHash128 XOF produce different + * @note ParallelHash128 and ParallelHash128 [XOF][] produce different * output, because ParallelHash128 encodes the fixed output size as part - * of the input while ParallelHash128 XOF does not. See section 6.3.1 - * of NIST SP 800-185 for details. + * of the input while ParallelHash128 [XOF][] does not. See section 6.3.1 + * of [NIST SP 800-185][800-185] for details. * - * Note: This implementation of ParallelHash128 is sequential, not - * parallel. + * @note This ParallelHash implementation is sequential, not parallel. * * @param[in] params ParallelHash configuration parameters. * @param[in] src Source buffer. * @param[in] src_len Source buffer length, in bytes. * @param[out] dst Destination buffer. * @param[in] dst_len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c parallelhash128_xof_once + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void parallelhash128_xof_once(const parallelhash_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len); /** - * @brief Initialize a ParallelHash256 XOF context. + * @brief Initialize a ParallelHash256 [XOF][] context. * @ingroup parallelhash * - * Initialize ParallelHash256 XOF (ParallelHash eXtendable Output - * Function, as defined in section 6.3.1 of NIST SP 800-185) context - * with configuration parameters `params`. + * Initialize ParallelHash256 [XOF][] (ParallelHash eXtendable Output + * Function, as defined in section 6.3.1 of [NIST SP 800-185][800-185]) + * context with configuration parameters `params`. * - * Note: ParallelHash256 and ParallelHash256 XOF produce different + * @note ParallelHash256 and ParallelHash256 [XOF][] produce different * output, because ParallelHash256 encodes the fixed output size as part - * of the input while ParallelHash256 XOF does not. See section 6.3.1 - * of NIST SP 800-185 for details. + * of the input while ParallelHash256 [XOF][] does not. See section 6.3.1 + * of [NIST SP 800-185][800-185] for details. * - * Note: This implementation of ParallelHash256 is sequential, not - * parallel. + * Note: This ParallelHash implementation is sequential, not parallel. * - * @param[out] xof ParallelHash256 XOF context. + * @param[out] xof ParallelHash256 [XOF][] context. * @param[in] params ParallelHash configuration parameters. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c parallelhash256_xof + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void parallelhash256_xof_init(parallelhash_t *xof, const parallelhash_params_t params); /** - * @brief Absorb data into a ParallelHash256 XOF context. + * @brief Absorb data into a ParallelHash256 [XOF][] context. * @ingroup parallelhash * * Absorb data in buffer `src` of length `len` bytes into - * ParallelHash256 XOF context. Can be called iteratively to absorb + * ParallelHash256 [XOF][] context. Can be called iteratively to absorb * input data in chunks. * - * Note: This implementation of ParallelHash256 is sequential, not - * parallel. + * @note This ParallelHash implementation is sequential, not parallel. * - * @param[in,out] hash ParallelHash256 XOF context. + * @param[in,out] xof ParallelHash256 [XOF][] context. * @param[in] src Source buffer. * @param[in] len Source buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c parallelhash256_xof + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ -void parallelhash256_xof_absorb(parallelhash_t *hash, const uint8_t *src, const size_t len); +void parallelhash256_xof_absorb(parallelhash_t *xof, const uint8_t *src, const size_t len); /** - * @brief Squeeze bytes from a ParallelHash256 XOF context. + * @brief Squeeze bytes from a ParallelHash256 [XOF][] context. * @ingroup parallelhash * * Squeeze `len` bytes of output into destination buffer `dst` from - * ParallelHash256 XOF context `xof`. Can be called iteratively to + * ParallelHash256 [XOF][] context `xof`. Can be called iteratively to * squeeze output data in chunks. * - * Note: ParallelHash256 and ParallelHash256 XOF produce different + * @note ParallelHash256 and ParallelHash256 [XOF][] produce different * output, because ParallelHash256 encodes the fixed output size as part - * of the input while ParallelHash256 XOF does not. See section 6.3.1 - * of NIST SP 800-185 for details. + * of the input while ParallelHash256 [XOF][] does not. See section 6.3.1 + * of [NIST SP 800-185][800-185] for details. * - * Note: This implementation of ParallelHash256 is sequential, not - * parallel. + * Note: This ParallelHash implementation is sequential, not parallel. * - * @param[in,out] xof ParallelHash256 XOF context. + * @param[in,out] xof ParallelHash256 [XOF][] context. * @param[out] dst Destination buffer. * @param[in] len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c parallelhash256_xof + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void parallelhash256_xof_squeeze(parallelhash_t *xof, uint8_t *dst, const size_t len); /** - * @brief Absorb bytes into ParallelHash256 XOF, then squeeze bytes out. + * @brief Absorb bytes into ParallelHash256 [XOF][], then squeeze bytes out. * @ingroup parallelhash * - * Initialize internal ParallelHash256 XOF (ParallelHash eXtendable - * Output Function, as defined in section 6.3.1 of NIST SP 800-185) - * context with configuration parameters `params`, absorb `src_len` - * bytes if input from source buffer `src`, then squeeze `dst_len` - * bytes of output into destination buffer `dst`. + * Initialize internal ParallelHash256 [XOF][] (ParallelHash eXtendable + * Output Function, as defined in section 6.3.1 of [NIST SP + * 800-185][800-185]) context with configuration parameters `params`, + * absorb `src_len` bytes if input from source buffer `src`, then + * squeeze `dst_len` bytes of output into destination buffer `dst`. * - * Note: ParallelHash256 and ParallelHash256 XOF produce different + * @note ParallelHash256 and ParallelHash256 [XOF][] produce different * output, because ParallelHash256 encodes the fixed output size as part - * of the input while ParallelHash256 XOF does not. See section 6.3.1 - * of NIST SP 800-185 for details. + * of the input while ParallelHash256 [XOF][] does not. See section + * 6.3.1 of [NIST SP 800-185][800-185] for details. * - * Note: This implementation of ParallelHash256 is sequential, not - * parallel. + * Note: This ParallelHash implementation is sequential, not parallel. * * @param[in] params ParallelHash configuration parameters. * @param[in] src Source buffer. * @param[in] src_len Source buffer length, in bytes. * @param[out] dst Destination buffer. * @param[in] dst_len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c parallelhash256_xof_once + * + * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final + * "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void parallelhash256_xof_once(const parallelhash_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len); @@ -1487,29 +2050,36 @@ void parallelhash256_xof_once(const parallelhash_params_t params, const uint8_t */ /** - * @brief Absorb bytes into TurboSHAKE128, then squeeze bytes out. + * @brief Absorb bytes into TurboSHAKE128 [XOF][], then squeeze bytes out. * @ingroup turboshake * - * Initialize internal TurboSHAKE128 context, absorb `src_len` bytes of - * input from source buffer `src`, then squeeze `dst_len` bytes of - * output into destination buffer `dst`. + * Initialize internal TurboSHAKE128 [XOF][] context, absorb `src_len` + * bytes of input from source buffer `src`, then squeeze `dst_len` bytes + * of output into destination buffer `dst`. * * @param[in] src Source buffer. * @param[in] src_len Source buffer length, in bytes. * @param[out] dst Destination buffer. * @param[in] dst_len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c turboshake128 + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void turboshake128(const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len); /** - * @brief Absorb bytes into TurboSHAKE128 with custom padding byte, then squeeze bytes out. + * @brief Absorb bytes into TurboSHAKE128 [XOF][] with custom padding + * byte, then squeeze bytes out. * @ingroup turboshake * - * Initialize internal TurboSHAKE128 context with custom padding byte - * `pad`, absorb `src_len` bytes of input from source buffer `src`, then - * squeeze `dst_len` bytes of output into destination buffer `dst`. + * Initialize internal TurboSHAKE128 [XOF][] context with custom padding + * byte `pad`, absorb `src_len` bytes of input from source buffer `src`, + * then squeeze `dst_len` bytes of output into destination buffer `dst`. * - * Note: The padding byte value must be in the range [0x01, 0x7F] and + * @note The padding byte value must be in the range [0x01, 0x7F] and * can be used for domain separation. * * @ingroup turboshake @@ -1519,33 +2089,46 @@ void turboshake128(const uint8_t *src, const size_t src_len, uint8_t *dst, const * @param[in] src_len Source buffer length, in bytes. * @param[out] dst Destination buffer. * @param[in] dst_len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c turboshake128_custom + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void turboshake128_custom(const uint8_t pad, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len); /** - * @brief Absorb bytes into TurboSHAKE256, then squeeze bytes out. + * @brief Absorb bytes into TurboSHAKE256 [XOF][], then squeeze bytes out. * @ingroup turboshake * - * Initialize internal TurboSHAKE256 context, absorb `src_len` bytes of - * input from source buffer `src`, then squeeze `dst_len` bytes of - * output into destination buffer `dst`. + * Initialize internal TurboSHAKE256 [XOF][] context, absorb `src_len` + * bytes of input from source buffer `src`, then squeeze `dst_len` bytes + * of output into destination buffer `dst`. * * @param[in] src Source buffer. * @param[in] src_len Source buffer length, in bytes. * @param[out] dst Destination buffer. * @param[in] dst_len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c turboshake256 + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void turboshake256(const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len); /** - * @brief Absorb bytes into TurboSHAKE256 with custom padding byte, then squeeze bytes out. + * @brief Absorb bytes into TurboSHAKE256 [XOF][] with custom padding + * byte, then squeeze bytes out. * @ingroup turboshake * - * Initialize internal TurboSHAKE256 context with custom padding byte - * `pad`, absorb `src_len` bytes of input from source buffer `src`, then - * squeeze `dst_len` bytes of output into destination buffer `dst`. + * Initialize internal TurboSHAKE256 [XOF][] context with custom padding + * byte `pad`, absorb `src_len` bytes of input from source buffer `src`, + * then squeeze `dst_len` bytes of output into destination buffer `dst`. * - * Note: The padding byte value must be in the range [0x01, 0x7F] and + * @note The padding byte value must be in the range [0x01, 0x7F] and * can be used for domain separation. * * @param[in] pad Padding byte. @@ -1553,12 +2136,21 @@ void turboshake256(const uint8_t *src, const size_t src_len, uint8_t *dst, const * @param[in] src_len Source buffer length, in bytes. * @param[out] dst Destination buffer. * @param[in] dst_len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c turboshake256_custom + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void turboshake256_custom(const uint8_t pad, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len); /** - * @brief TurboShake XOF context. + * @brief TurboShake [XOF][] context (all members are private). * @ingroup turboshake + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ typedef struct { sha3_xof_t xof; /**< XOF context (private) */ @@ -1566,108 +2158,156 @@ typedef struct { } turboshake_t; /** - * @brief Initialize TurboSHAKE128 context. + * @brief Initialize TurboSHAKE128 [XOF][] context. * @ingroup turboshake * - * @param[out] ts TurboSHAKE128 context. + * @param[out] ts TurboSHAKE128 [XOF][] context. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c turboshake128_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void turboshake128_init(turboshake_t *ts); /** - * @brief Initialize TurboSHAKE128 context with custom padding byte. + * @brief Initialize TurboSHAKE128 [XOF][] context with custom padding byte. * @ingroup turboshake * - * Initialize TurboSHAKE128 context with custom padding byte. The + * Initialize TurboSHAKE128 [XOF][] context with custom padding byte. The * custom padding byte can be used as a domain separator and must be in * the range [0x01, 0x7f]. * - * @param[out] ts TurboSHAKE128 context. + * @param[out] ts TurboSHAKE128 [XOF][] context. * @param[in] pad Padding byte (used for domain separation). * * @return False if the padding byte is out of range and true otherwise. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c turboshake128_custom_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ _Bool turboshake128_init_custom(turboshake_t *ts, const uint8_t pad); /** - * @brief Absorb data into TurboSHAKE128 context. + * @brief Absorb data into TurboSHAKE128 [XOF][] context. * @ingroup turboshake * * Absorb `src_len` bytes of input from source buffer `src` into - * TurboSHAKE128 context `ts`. Can be called iteratively to absorb - * input data in chunks. + * TurboSHAKE128 [XOF][] context `ts`. Can be called iteratively to + * absorb input data in chunks. * - * @param[in,out] ts TurboSHAKE128 context. + * @param[in,out] ts TurboSHAKE128 [XOF][] context. * @param[in] src Source buffer. * @param[in] len Source buffer length, in bytes. * * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized). + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c turboshake128_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ _Bool turboshake128_absorb(turboshake_t *ts, const uint8_t *src, const size_t len); /** - * @brief Squeeze bytes from TurboSHAKE128 context. + * @brief Squeeze bytes from TurboSHAKE128 [XOF][] context. * @ingroup turboshake * * Squeeze `dst_len` bytes of output into destination buffer `dst` from - * TurboSHAKE128 context `ts`. Can be called iteratively to squeeze - * output data in chunks. + * TurboSHAKE128 [XOF][] context `ts`. Can be called iteratively to + * squeeze output data in chunks. * - * @param[in,out] ts TurboSHAKE128 context. + * @param[in,out] ts TurboSHAKE128 [XOF][] context. * @param[out] dst Destination buffer. * @param[in] len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c turboshake128_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void turboshake128_squeeze(turboshake_t *ts, uint8_t *dst, const size_t len); /** - * @brief Initialize TurboSHAKE256 context. + * @brief Initialize TurboSHAKE256 [XOF][] context. * @ingroup turboshake * - * @param[out] ts TurboSHAKE256 context. + * @param[out] ts TurboSHAKE256 [XOF][] context. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c turboshake256_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void turboshake256_init(turboshake_t *ts); /** - * @brief Initialize TurboSHAKE256 context with custom padding byte. + * @brief Initialize TurboSHAKE256 [XOF] context with custom padding byte. * @ingroup turboshake * - * Initialize TurboSHAKE256 context with custom padding byte. The - * custom padding byte can be used as a domain separator and must be in - * the range [0x01, 0x7f]. + * Initialize TurboSHAKE256 [XOF][] context with custom padding byte. + * The custom padding byte can be used as a domain separator and must be + * in the range [0x01, 0x7f]. * - * @param[out] ts TurboSHAKE256 context. + * @param[out] ts TurboSHAKE256 [XOF][] context. * @param[in] pad Padding byte (used for domain separation). * * @return False if the padding byte is out of range and true otherwise. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c turboshake256_custom_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ _Bool turboshake256_init_custom(turboshake_t *ts, const uint8_t pad); /** - * @brief Absorb data into TurboSHAKE256 context. + * @brief Absorb data into TurboSHAKE256 [XOF][] context. * @ingroup turboshake * - * Absorb `src_len` bytes of input from source buffer `src` into - * TurboSHAKE256 context `ts`. Can be called iteratively to absorb - * input data in chunks. + * Absorb `len` bytes of input from source buffer `src` into + * TurboSHAKE256 [XOF][] context `ts`. Can be called iteratively to + * absorb input data in chunks. * - * @param[in,out] ts TurboSHAKE256 context. + * @param[in,out] ts TurboSHAKE256 [XOF][] context. * @param[in] src Source buffer. * @param[in] len Source buffer length, in bytes. * * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized). + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c turboshake256_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ _Bool turboshake256_absorb(turboshake_t *ts, const uint8_t *src, const size_t len); /** - * @brief Squeeze bytes from TurboSHAKE256 context. + * @brief Squeeze bytes from TurboSHAKE256 [XOF][] context. * @ingroup turboshake * - * Squeeze `dst_len` bytes of output into destination buffer `dst` from + * Squeeze `len` bytes of output into destination buffer `dst` from * TurboSHAKE256 context `ts`. Can be called iteratively to squeeze * output data in chunks. * - * @param[in,out] ts TurboSHAKE256 context. + * @param[in,out] ts TurboSHAKE256 [XOF][] context. * @param[out] dst Destination buffer. * @param[in] len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c turboshake256_xof + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ void turboshake256_squeeze(turboshake_t *ts, uint8_t *dst, const size_t len); @@ -1684,8 +2324,11 @@ void turboshake256_squeeze(turboshake_t *ts, uint8_t *dst, const size_t len); */ /** - * @brief KangarooTwelve context. + * @brief KangarooTwelve [XOF][] context (all members are private). * @ingroup k12 + * + * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function + * "Extendable-Output Function (XOF)" */ typedef struct { turboshake_t ts; /**< Internal turboshake context (private) */ @@ -1703,6 +2346,9 @@ typedef struct { * @param[in] src_len Source buffer length, in bytes. * @param[out] dst Destination buffer. * @param[in] dst_len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c k12_once */ void k12_once(const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len); @@ -1721,6 +2367,9 @@ void k12_once(const uint8_t *src, const size_t src_len, uint8_t *dst, const size * @param[in] custom_len Custom string length, in bytes. * @param[out] dst Destination buffer. * @param[in] dst_len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c k12_custom_once */ void k12_custom_once(const uint8_t *src, const size_t src_len, const uint8_t *custom, const size_t custom_len, uint8_t *dst, const size_t dst_len); @@ -1732,14 +2381,16 @@ void k12_custom_once(const uint8_t *src, const size_t src_len, const uint8_t *cu * `src_len` bytes and custom string `custom` of length `custom_len` * bytes. * - * Note: This implementation of KangarooTwelve is sequential, not - * parallel. + * @note This KangarooTwelve implementation is sequential, not parallel. * * @param[out] k12 KangarooTwelve context. * @param[in] src Source buffer. * @param[in] src_len Source buffer length, in bytes. * @param[in] custom Custom string buffer. * @param[in] custom_len Custom string length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c k12_xof */ void k12_init(k12_t *k12, const uint8_t *src, const size_t src_len, const uint8_t *custom, const size_t custom_len); @@ -1751,14 +2402,16 @@ void k12_init(k12_t *k12, const uint8_t *src, const size_t src_len, const uint8_ * KangarooTwelve context `k12`. Can be called iteratively to squeeze * output data in chunks. * - * Note: This implementation of KangarooTwelve is sequential, not - * parallel. + * @note This KangarooTwelve implementation is sequential, not parallel. * * @param[in,out] k12 KangarooTwelve context. * @param[out] dst Destination buffer. - * @param[in] dst_len Destination buffer length, in bytes. + * @param[in] len Destination buffer length, in bytes. + * + * Example: + * @snippet{trimleft} 06-all/all-fns.c k12_xof */ -void k12_squeeze(k12_t *k12, uint8_t *dst, const size_t dst_len); +void k12_squeeze(k12_t *k12, uint8_t *dst, const size_t len); #ifdef __cplusplus } -- cgit v1.2.3