aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPaul Duncan <pabs@pablotron.org>2023-10-14 11:09:36 -0400
committerPaul Duncan <pabs@pablotron.org>2023-10-14 11:09:36 -0400
commitc6f3716c64612981375fd8e8c1efa2cc380a2991 (patch)
tree167d4a5b87844f13b9b3e7a8ca1bfe62e7f46dfe
parent27d068ce203a7b1371dd28c1ce4bd8f3fad3d06f (diff)
downloadsha3-c6f3716c64612981375fd8e8c1efa2cc380a2991.tar.bz2
sha3-c6f3716c64612981375fd8e8c1efa2cc380a2991.zip
README.md: improve intro paragraph, shorten list of algorithms, add descriptions for each algorithm, add note about AVX-512 and test suite, add two more examples
-rw-r--r--README.md180
1 files changed, 154 insertions, 26 deletions
diff --git a/README.md b/README.md
index be9daf9..c10dbf5 100644
--- a/README.md
+++ b/README.md
@@ -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"