examples: update examples for new shake{128,256} prototypes

3 files changed, 44 insertions, 80 deletions

diff --git a/examples/01-shake128/main.c b/examples/01-shake128/main.c
index f2a2347..54b8e3b 100644
--- a/examples/01-shake128/main.c
+++ b/examples/01-shake128/main.c
@@ -2,18 +2,18 @@
 // 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"
+#include <stdint.h> // uint8_t
+#include <stdio.h> // printf()
+#include "hex.h" // hex_write()
+#include "sha3.h" // shake128()
 
 // test data
 static const uint8_t DATA[] = "this is some test data";
 
-int main() {
+int main(void) {
   // hash data
   uint8_t buf[200] = { 0 };
-  shake128_xof_once(DATA, sizeof(DATA), buf, sizeof(buf));
+  shake128(DATA, sizeof(DATA), buf, sizeof(buf));
 
   // print result to stdout
   printf("SHAKE128 (200 bytes): ");
diff --git a/examples/05-python/sha3.py b/examples/05-python/sha3.py
index bd0e11b..1e66c59 100644
--- a/examples/05-python/sha3.py
+++ b/examples/05-python/sha3.py
@@ -17,10 +17,10 @@ sha3 = ctypes.CDLL('../../libsha3.so')
 # set function argument and return types
 # (note: this is not required, but it helps to prevent argument and type
 # oopsies)
-sha3.shake128_xof_once.argtypes = XOF_ARGS
-sha3.shake128_xof_once.rettype = None
-sha3.shake256_xof_once.argtypes = XOF_ARGS
-sha3.shake256_xof_once.rettype = None
+sha3.shake128.argtypes = XOF_ARGS
+sha3.shake128.rettype = None
+sha3.shake256.argtypes = XOF_ARGS
+sha3.shake256.rettype = None
 sha3.sha3_224.argtypes = HASH_ARGS
 sha3.sha3_224.rettype = None
 sha3.sha3_256.argtypes = HASH_ARGS
@@ -66,9 +66,9 @@ class Results:
     for r in self.rs:
       cw.writerow(r.to_row())
 
-def test_shake128_xof(rs: Results, data: bytes) -> None:
-  """append SHAKE128-XOF digest of data from hashlib and libsha3 to results"""
-  algo = 'shake128-xof' # algorithm name
+def test_shake128(rs: Results, data: bytes) -> None:
+  """append SHAKE128 digest of data from hashlib and libsha3 to results"""
+  algo = 'shake128' # algorithm name
   size = 32 # output size, in bytes
 
   # append hashlib digest
@@ -76,12 +76,12 @@ def test_shake128_xof(rs: Results, data: bytes) -> None:
 
   # append libsha3 digest
   buf = ctypes.create_string_buffer(size)
-  sha3.shake128_xof_once(data, len(data), buf, size)
+  sha3.shake128(data, len(data), buf, size)
   rs.append(algo, 'libsha3', buf.raw)
 
-def test_shake256_xof(rs: Results, data: bytes) -> None:
-  """append SHAKE256-XOF digest of data from hashlib and libsha3 to results"""
-  algo = 'shake256-xof' # algorithm name
+def test_shake256(rs: Results, data: bytes) -> None:
+  """append SHAKE256 digest of data from hashlib and libsha3 to results"""
+  algo = 'shake256' # algorithm name
   size = 32 # output size, in bytes
 
   # append hashlib digest
@@ -89,7 +89,7 @@ def test_shake256_xof(rs: Results, data: bytes) -> None:
 
   # append libsha3 digest
   buf = ctypes.create_string_buffer(size)
-  sha3.shake256_xof_once(data, len(data), buf, size)
+  sha3.shake256(data, len(data), buf, size)
   rs.append(algo, 'libsha3', buf.raw)
 
 def test_sha3_224(rs: Results, data: bytes) -> None:
@@ -145,8 +145,8 @@ DATA = b'foo bar'
 rs = Results()
 
 # run tests, add to results
-test_shake128_xof(rs, DATA)
-test_shake256_xof(rs, DATA)
+test_shake128(rs, DATA)
+test_shake256(rs, DATA)
 test_sha3_224(rs, DATA)
 test_sha3_256(rs, DATA)
 test_sha3_384(rs, DATA)
diff --git a/examples/06-all/all-fns.c b/examples/06-all/all-fns.c
index f494189..1aea4d6 100644
--- a/examples/06-all/all-fns.c
+++ b/examples/06-all/all-fns.c
@@ -186,27 +186,10 @@ static void shake128_example(void) {
   uint8_t buf[1024] = { 0 };
   rand_bytes(buf, sizeof(buf));
 
-  // absorb into shake128, write 16 byte result to `out`
-  uint8_t hash[16] = { 0 };
-  shake128(buf, sizeof(buf), hash);
-  ///! [shake128]
-
-  // print to stdout
-  printf("%s: ", __func__);
-  hex_write(stdout, hash, sizeof(hash));
-  fputs("\n", stdout);
-}
-
-static void shake128_xof_once_example(void) {
-  ///! [shake128_xof_once]
-  // get 1024 random bytes
-  uint8_t buf[1024] = { 0 };
-  rand_bytes(buf, sizeof(buf));
-
-  // absorb into shake128 xof context with 15 byte output, write result to `out`
+  // absorb into shake128 context with 15 byte output, write result to `out`
   uint8_t out[15] = { 0 };
-  shake128_xof_once(buf, sizeof(buf), out, sizeof(out));
-  ///! [shake128_xof_once]
+  shake128(buf, sizeof(buf), out, sizeof(out));
+  ///! [shake128]
 
   // print to stdout
   printf("%s: ", __func__);
@@ -214,19 +197,19 @@ static void shake128_xof_once_example(void) {
   fputs("\n", stdout);
 }
 
-static void shake128_xof_example(void) {
-  ///! [shake128_xof]
+static void shake128_ctx_example(void) {
+  ///! [shake128_ctx]
   // get 1024 random bytes
   uint8_t buf[1024] = { 0 };
   rand_bytes(buf, sizeof(buf));
 
-  // create shake128 xof context with arbitrary length output
+  // create shake128 context
   sha3_xof_t ctx = { 0 };
-  shake128_xof_init(&ctx);
+  shake128_init(&ctx);
 
   // absorb `buf` contents in 32 byte chunks
   for (size_t i = 0; i < sizeof(buf); i += 32) {
-    shake128_xof_absorb(&ctx, buf + i, 32);
+    shake128_absorb(&ctx, buf + i, 32);
   }
 
   // print result prefix to stdout
@@ -236,7 +219,7 @@ static void shake128_xof_example(void) {
   for (size_t i = 0; i < 128; i += 32) {
     // squeeze 32 bytes of result into `out`
     uint8_t out[32] = { 0 };
-    shake128_xof_squeeze(&ctx, out, sizeof(out));
+    shake128_squeeze(&ctx, out, sizeof(out));
 
     // encode as hex, print to stdout
     hex_write(stdout, out, sizeof(out));
@@ -244,7 +227,7 @@ static void shake128_xof_example(void) {
 
   // print result suffix to stdout
   fputs("\n", stdout);
-  ///! [shake128_xof]
+  ///! [shake128_ctx]
 }
 
 static void shake256_example(void) {
@@ -253,27 +236,10 @@ static void shake256_example(void) {
   uint8_t buf[1024] = { 0 };
   rand_bytes(buf, sizeof(buf));
 
-  // absorb into shake256, write 32 byte result to `out`
-  uint8_t hash[32] = { 0 };
-  shake256(buf, sizeof(buf), hash);
-  ///! [shake256]
-
-  // print to stdout
-  printf("%s: ", __func__);
-  hex_write(stdout, hash, sizeof(hash));
-  fputs("\n", stdout);
-}
-
-static void shake256_xof_once_example(void) {
-  ///! [shake256_xof_once]
-  // get 1024 random bytes
-  uint8_t buf[1024] = { 0 };
-  rand_bytes(buf, sizeof(buf));
-
-  // absorb `buf` into shake256 xof with 15 byte output, write result to `out`
+  // absorb `buf` into shake256 context with 15 byte output, write result to `out`
   uint8_t out[15] = { 0 };
-  shake256_xof_once(buf, sizeof(buf), out, sizeof(out));
-  ///! [shake256_xof_once]
+  shake256(buf, sizeof(buf), out, sizeof(out));
+  ///! [shake256]
 
   // print to stdout
   printf("%s: ", __func__);
@@ -281,19 +247,19 @@ static void shake256_xof_once_example(void) {
   fputs("\n", stdout);
 }
 
-static void shake256_xof_example(void) {
-  ///! [shake256_xof]
+static void shake256_ctx_example(void) {
+  ///! [shake256_ctx]
   // get 1024 random bytes
   uint8_t buf[1024] = { 0 };
   rand_bytes(buf, sizeof(buf));
 
-  // create shake256 xof context with arbitrary length output
+  // create shake256 context
   sha3_xof_t ctx = { 0 };
-  shake256_xof_init(&ctx);
+  shake256_init(&ctx);
 
   // absorb `buf` contents in 32 byte chunks
   for (size_t i = 0; i < sizeof(buf); i += 32) {
-    shake256_xof_absorb(&ctx, buf + i, 32);
+    shake256_absorb(&ctx, buf + i, 32);
   }
 
   // print result prefix to stdout
@@ -303,7 +269,7 @@ static void shake256_xof_example(void) {
   for (size_t i = 0; i < 128; i += 32) {
     // squeeze 32 bytes of result into `out`
     uint8_t out[32] = { 0 };
-    shake256_xof_squeeze(&ctx, out, sizeof(out));
+    shake256_squeeze(&ctx, out, sizeof(out));
 
     // encode as hex, print to stdout
     hex_write(stdout, out, sizeof(out));
@@ -311,7 +277,7 @@ static void shake256_xof_example(void) {
 
   // print result suffix to stdout
   fputs("\n", stdout);
-  ///! [shake256_xof]
+  ///! [shake256_ctx]
 }
 
 static void hmac_sha3_224_example(void) {
@@ -557,7 +523,7 @@ static void cshake128_xof_example(void) {
     .custom_len = sizeof(custom) - 1, // length, in bytes (w/o trailing NUL)
   };
 
-  // create cSHAKE128 XOF context from parameters
+  // create cSHAKE128 context from parameters
   sha3_xof_t ctx = { 0 };
   cshake128_xof_init(&ctx, params);
 
@@ -623,7 +589,7 @@ static void cshake256_xof_example(void) {
     .custom_len = sizeof(custom) - 1, // length, in bytes (w/o trailing NUL)
   };
 
-  // create cSHAKE256 XOF context from parameters
+  // create cSHAKE256 context from parameters
   sha3_xof_t ctx = { 0 };
   cshake256_xof_init(&ctx, params);
 
@@ -1533,11 +1499,9 @@ int main(void) {
   sha3_512_example();
   sha3_512_absorb_example();
   shake128_example();
-  shake128_xof_once_example();
-  shake128_xof_example();
+  shake128_ctx_example();
   shake256_example();
-  shake256_xof_once_example();
-  shake256_xof_example();
+  shake256_ctx_example();
   hmac_sha3_224_example();
   hmac_sha3_224_absorb_example();
   hmac_sha3_256_example();