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

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"