diff options
| -rw-r--r-- | README.md | 180 |
1 files changed, 154 insertions, 26 deletions
@@ -1,34 +1,53 @@ # sha3 -[C11][] implementations of the following [SHA-3][] algorithms from [FIPS 202][] and -[SP 800-185][800-185]: - -* SHA3-224 -* SHA3-256 -* SHA3-384 -* SHA3-512 -* HMAC-SHA3-224 -* HMAC-SHA3-256 -* HMAC-SHA3-384 -* HMAC-SHA3-512 -* SHAKE128 and SHAKE128-XOF -* SHAKE256 and SHAKE256-XOF -* cSHAKE128 and cSHAKE128-XOF -* cSHAKE256 and cSHAKE256-XOF -* KMAC128 and KMAC128-XOF -* KMAC256 and KMAC256-XOF -* TupleHash128 and TupleHash128-XOF -* TupleHash256 and TupleHash256-XOF -* ParallelHash128 and ParallelHash128-XOF -* ParallelHash256 and ParallelHash256-XOF -* TurboSHAKE128 and TurboSHAKE256 -* KangarooTwelve +[C11][] implementation of the [SHA-3][] [cryptographic hash +functions][hash], [eXtendable Output Functions (XOF)][xof], and +[Hash-based Message Authentication Code functions (HMAC)][hmac] defined +in [FIPS 202][], [SP 800-185][800-185], and the [draft KangarooTwelve +and TurboSHAKE specification][turboshake-ietf]. + +Includes [AVX-512][] acceleration and a full test suite with test +vectors from the [NIST CSRC "Examples With Intermediate Values" +site][csrc-examples] and the [Test Vectors section of the draft +KangarooTwelve and TurboSHAKE specification][turboshake-ietf-test-vectors]. + +The following algorithms are implemented: + +* SHA3-224, SHA3-256, SHA3-384, and SHA3-512: [SHA-3][] [cryptographic + hash functions][hash] with fixed-length output defined in section 6.1 + of [FIPS 202][]. +* HMAC-SHA3-224, HMAC-SHA3-256, HMAC-SHA3-384, HMAC-SHA3-512: + [HMAC][hmac] instantiated with [SHA-3][] hash functions, as specified + in [RFC 2104][] and [FIPS 198-1][]. +* SHAKE128, SHAKE128-XOF, SHAKE256, and SHAKE256-XOF: [SHA-3][] + [XOFs][xof] defined in section 6.2 of [FIPS 202][]. +* cSHAKE128, cSHAKE128-XOF, cSHAKE256, and cSHAKE256-XOF: Fixed-length + and [XOF][] variants of the customizable-SHAKE primitive defined in + section 3 of [SP 800-185][800-185]. +* KMAC128, KMAC128-XOF, KMAC256 and KMAC256-XOF: Keccak [Message + Authentication Code (MAC)][mac] defined in section 4 of [SP + 800-185][800-185]. +* TupleHash128, TupleHash128-XOF, TupleHash256, and TupleHash256-XOF: + Misuse-resistant hash function and [XOF][] for hashing a [tuple][] of + byte strings, defined in section 5 of [SP 800-185][800-185]. +* ParallelHash128, ParallelHash128-XOF, ParallelHash256, and + ParallelHash256-XOF: Hash function and [XOF][] defined in section 6 + of [SP 800-185][800-185]. +* TurboSHAKE128 and TurboSHAKE256: Faster, reduced-round [XOFs][xof] + defined in the [draft KangarooTwelve and TurboSHAKE + specification][turboshake-ietf]. +* KangarooTwelve: Faster, reduced-round [XOF][] with customzation string + defined in the [draft KangarooTwelve and TurboSHAKE + specification][turboshake-ietf]. Use `make` to build a minimal sample application, and `make test` to run the test suite. ## Examples +Calculate the SHA3-256 hash of a test string and print the result to +standard output: + ```c // sha3-256-example: print sha3-256 hash of data to standard output. #include <stdint.h> @@ -39,8 +58,8 @@ the test suite. // test data static const uint8_t DATA[] = "this is some test data"; -int main() { - // hash data +int main(void) { + // hash `DATA` into `buf` uint8_t buf[32] = { 0 }; sha3_256(DATA, sizeof(DATA), buf); @@ -53,6 +72,97 @@ int main() { } ``` +Calculate the SHAKE128 hash of a test string and print the first 200 +bytes to standard output: + +```c +// +// shake128-example: hash contents of DATA with SHAKE128 and print first +// 200 bytes of SHAKE128 hash of data to standard output. +// +#include <stdint.h> +#include <stdio.h> +#include "hex.h" +#include "sha3.h" + +// test data +static const uint8_t DATA[] = "this is some test data"; + +int main(void) { + // hash data + uint8_t buf[200] = { 0 }; + shake128_xof_once(DATA, sizeof(DATA), buf, sizeof(buf)); + + // print result to stdout + printf("SHAKE128 (200 bytes): "); + hex_write(stdout, buf, sizeof(buf)); + printf("\n"); + + return 0; +} +``` + +TurboSHAKE128 example, using the iterative API: + +```c +// +// turboshake128-example: Absorb 4096 bytes of data from /dev/urandom in +// 1024 byte chunks, hash it with TurboShake128, then print 128 bytes of +// result in 32 byte chunks (hex-encoded) to standard output. +// output. +// +#include <stdint.h> +#include <stdio.h> +#include <err.h> +#include "hex.h" +#include "sha3.h" + +int main() { + // init turboshake + turboshake_t ts; + turboshake128_init(&ts); + + // open source + FILE *fh = fopen("/dev/urandom", "rb"); + if (!fh) { + err(-1, "fopen()"); + } + + { + // read and absorb + uint8_t buf[1024] = { 0 }; + for (size_t i = 0; i < 4096/sizeof(buf); i++) { + // read data + if (!fread(buf, sizeof(buf), 1, fh)) { + err(-1, "fread()"); + } + + // absorb + turboshake128_absorb(&ts, buf, sizeof(buf)); + } + } + + // close source + if (!fclose(fh)) { + warn("fclose()"); + } + + + printf("TurboShake128 output:\n"); + { + // squeeze in 32 byte chunks, write to stdout + uint8_t buf[32] = { 0 }; + for (size_t ofs = 0; ofs < 128; ofs += sizeof(buf)) { + turboshake128_squeeze(&ts, buf, sizeof(buf)); + hex_write(stdout, buf, sizeof(buf)); + } + } + printf("\n"); + + return 0; +} +``` + See the `examples/` directory for more examples. ## References @@ -68,15 +178,33 @@ See the `examples/` directory for more examples. "ISO/IEC 9899:2011" [SHA-3]: https://en.wikipedia.org/wiki/SHA-3 "Secure Hash Algorithm 3" +[hash]: https://en.wikipedia.org/wiki/Cryptographic_hash_function + "Cryptographic hash function" +[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" +[hmac]: https://en.wikipedia.org/wiki/HMAC + "Keyed Hash Message Authentication Code (HMAC)" +[tuple]: https://en.wikipedia.org/wiki/Tuple + "Ordered list of elements." [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions" [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" +[rfc 2104]: https://datatracker.ietf.org/doc/html/rfc2104 + "RFC 2104: HMAC: Keyed-Hashing for Message Authentication" [FIPS 198-1]: https://csrc.nist.gov/pubs/fips/198-1/final "The Keyed-Hash Message Authentication Code (HMAC)" +[csrc]: https://csrc.nist.gov/projects/cryptographic-standards-and-guidelines/ + "NIST Computer Security Resource Center" [csrc-examples]: https://csrc.nist.gov/projects/cryptographic-standards-and-guidelines/example-values "NIST CSRC: Cryptographic Standards and Guidelines: Examples with Intermediate Values" [turboshake]: https://eprint.iacr.org/2023/342.pdf "TurboSHAKE" -[turboshake-ietf]: https://www.ietf.org/archive/id/draft-irtf-cfrg-kangarootwelve-10.html#name-test-vectors +[turboshake-ietf]: https://www.ietf.org/archive/id/draft-irtf-cfrg-kangarootwelve-10.html "KangarooTwelve and TurboSHAKE" +[turboshake-ietf-test-vectors]: https://www.ietf.org/archive/id/draft-irtf-cfrg-kangarootwelve-10.html#name-test-vectors + "KangarooTwelve and TurboSHAKE test vectors" +[avx-512]: https://en.wikipedia.org/wiki/AVX-512 + "Advanced Vector Extensions 512 (AVX-512): 512-bit SIMD vector instruction set" |