sha3.c: move kmac128(), add missing kmac comments

1 files changed, 63 insertions, 53 deletions

diff --git a/sha3.c b/sha3.c
index ae33e82..1822851 100644
--- a/sha3.c
+++ b/sha3.c
@@ -1128,6 +1128,7 @@ static inline bytepad_t bytepad(const size_t data_len, const size_t width) {
 DEF_CSHAKE(128) // cshake128
 DEF_CSHAKE(256) // cshake256
 
+// one-shot kmac128
 void kmac128(
   const kmac_params_t params,
   const uint8_t * const msg, const size_t msg_len,
@@ -1184,15 +1185,27 @@ void kmac128(
   cshake128_xof_squeeze(&xof, dst, dst_len);
 }
 
-void kmac256(
-  const kmac_params_t params,
-  const uint8_t * const msg, const size_t msg_len,
-  uint8_t * const dst, const size_t dst_len
-) {
-  static const uint8_t PAD[SHAKE256_RATE] = { 0 };
+// absorb data into kmac128-xof context
+_Bool kmac128_xof_absorb(sha3_xof_t * const xof, const uint8_t * const msg, const size_t len) {
+  return cshake128_xof_absorb(xof, msg, len);
+}
+
+// squeeze data from kmac128-xof context
+void kmac128_xof_squeeze(sha3_xof_t * const xof, uint8_t * const dst, const size_t len) {
+  if (!xof->squeezing) {
+    // append XOF length suffix
+    const uint8_t SUFFIX[] = { 0, 1 };
+    (void) cshake128_xof_absorb(xof, SUFFIX, sizeof(SUFFIX));
+  }
+  cshake128_xof_squeeze(xof, dst, len);
+}
+
+// init kmac128-xof context
+void kmac128_xof_init(sha3_xof_t * const xof, const kmac_params_t params) {
+  static const uint8_t PAD[SHAKE128_RATE] = { 0 };
   static const uint8_t NAME[4] = { 'K', 'M', 'A', 'C' };
 
-  // build cshake256 params
+  // build cshake128 params
   const cshake_params_t cshake_params = {
     .name = NAME,
     .name_len = sizeof(NAME),
@@ -1205,59 +1218,45 @@ void kmac256(
   const size_t key_buf_len = encode_string_prefix(key_buf, params.key_len);
 
   // build bytepad prefix
-  const bytepad_t bp = bytepad(key_buf_len + params.key_len, SHAKE256_RATE);
+  const bytepad_t bp = bytepad(key_buf_len + params.key_len, SHAKE128_RATE);
 
   // init xof
-  sha3_xof_t xof;
-  cshake256_xof_init(&xof, cshake_params);
+  cshake128_xof_init(xof, cshake_params);
 
   // absorb bytepad prefix
-  (void) cshake256_xof_absorb(&xof, bp.prefix, bp.prefix_len);
+  (void) cshake128_xof_absorb(xof, bp.prefix, bp.prefix_len);
 
   // absorb key
-  (void) cshake256_xof_absorb(&xof, key_buf, key_buf_len);
+  (void) cshake128_xof_absorb(xof, key_buf, key_buf_len);
   if (params.key_len > 0) {
-    (void) cshake256_xof_absorb(&xof, params.key, params.key_len);
+    (void) cshake128_xof_absorb(xof, params.key, params.key_len);
   }
 
   // absorb padding
   for (size_t ofs = 0; ofs < bp.pad_len; ofs += sizeof(PAD)) {
     const size_t len = MIN(bp.pad_len - ofs, sizeof(PAD));
-    (void) cshake256_xof_absorb(&xof, PAD, len);
+    (void) cshake128_xof_absorb(xof, PAD, len);
   }
-
-  // absorb message
-  (void) cshake256_xof_absorb(&xof, msg, msg_len);
-
-  // build output length suffix
-  uint8_t suffix_buf[9] = { 0 };
-  const size_t suffix_buf_len = right_encode(suffix_buf, dst_len << 3);
-
-  // absorb output length suffix
-  (void) cshake256_xof_absorb(&xof, suffix_buf, suffix_buf_len);
-
-  // squeeze
-  cshake256_xof_squeeze(&xof, dst, dst_len);
-}
-
-_Bool kmac128_xof_absorb(sha3_xof_t * const xof, const uint8_t * const msg, const size_t len) {
-  return cshake128_xof_absorb(xof, msg, len);
 }
 
-void kmac128_xof_squeeze(sha3_xof_t * const xof, uint8_t * const dst, const size_t len) {
-  if (!xof->squeezing) {
-    // append XOF length suffix
-    const uint8_t SUFFIX[] = { 0, 1 };
-    (void) cshake128_xof_absorb(xof, SUFFIX, sizeof(SUFFIX));
-  }
-  cshake128_xof_squeeze(xof, dst, len);
+// one-shot kmac128-xof
+void kmac128_xof_once(const kmac_params_t params, const uint8_t * const src, const size_t src_len, uint8_t * const dst, const size_t dst_len) {
+  sha3_xof_t xof;
+  kmac128_xof_init(&xof, params);
+  kmac128_xof_absorb(&xof, src, src_len);
+  kmac128_xof_squeeze(&xof, dst, dst_len);
 }
 
-void kmac128_xof_init(sha3_xof_t * const xof, const kmac_params_t params) {
-  static const uint8_t PAD[SHAKE128_RATE] = { 0 };
+// one-shot kmac256
+void kmac256(
+  const kmac_params_t params,
+  const uint8_t * const msg, const size_t msg_len,
+  uint8_t * const dst, const size_t dst_len
+) {
+  static const uint8_t PAD[SHAKE256_RATE] = { 0 };
   static const uint8_t NAME[4] = { 'K', 'M', 'A', 'C' };
 
-  // build cshake128 params
+  // build cshake256 params
   const cshake_params_t cshake_params = {
     .name = NAME,
     .name_len = sizeof(NAME),
@@ -1270,38 +1269,47 @@ void kmac128_xof_init(sha3_xof_t * const xof, const kmac_params_t params) {
   const size_t key_buf_len = encode_string_prefix(key_buf, params.key_len);
 
   // build bytepad prefix
-  const bytepad_t bp = bytepad(key_buf_len + params.key_len, SHAKE128_RATE);
+  const bytepad_t bp = bytepad(key_buf_len + params.key_len, SHAKE256_RATE);
 
   // init xof
-  cshake128_xof_init(xof, cshake_params);
+  sha3_xof_t xof;
+  cshake256_xof_init(&xof, cshake_params);
 
   // absorb bytepad prefix
-  (void) cshake128_xof_absorb(xof, bp.prefix, bp.prefix_len);
+  (void) cshake256_xof_absorb(&xof, bp.prefix, bp.prefix_len);
 
   // absorb key
-  (void) cshake128_xof_absorb(xof, key_buf, key_buf_len);
+  (void) cshake256_xof_absorb(&xof, key_buf, key_buf_len);
   if (params.key_len > 0) {
-    (void) cshake128_xof_absorb(xof, params.key, params.key_len);
+    (void) cshake256_xof_absorb(&xof, params.key, params.key_len);
   }
 
   // absorb padding
   for (size_t ofs = 0; ofs < bp.pad_len; ofs += sizeof(PAD)) {
     const size_t len = MIN(bp.pad_len - ofs, sizeof(PAD));
-    (void) cshake128_xof_absorb(xof, PAD, len);
+    (void) cshake256_xof_absorb(&xof, PAD, len);
   }
-}
 
-void kmac128_xof_once(const kmac_params_t params, const uint8_t * const src, const size_t src_len, uint8_t * const dst, const size_t dst_len) {
-  sha3_xof_t xof;
-  kmac128_xof_init(&xof, params);
-  kmac128_xof_absorb(&xof, src, src_len);
-  kmac128_xof_squeeze(&xof, dst, dst_len);
+  // absorb message
+  (void) cshake256_xof_absorb(&xof, msg, msg_len);
+
+  // build output length suffix
+  uint8_t suffix_buf[9] = { 0 };
+  const size_t suffix_buf_len = right_encode(suffix_buf, dst_len << 3);
+
+  // absorb output length suffix
+  (void) cshake256_xof_absorb(&xof, suffix_buf, suffix_buf_len);
+
+  // squeeze
+  cshake256_xof_squeeze(&xof, dst, dst_len);
 }
 
+// absorb data into kmac256-xof context
 _Bool kmac256_xof_absorb(sha3_xof_t * const xof, const uint8_t * const msg, const size_t len) {
   return cshake256_xof_absorb(xof, msg, len);
 }
 
+// squeeze data from kmac256-xof context
 void kmac256_xof_squeeze(sha3_xof_t * const xof, uint8_t * const dst, const size_t len) {
   if (!xof->squeezing) {
     // append XOF length suffix
@@ -1311,6 +1319,7 @@ void kmac256_xof_squeeze(sha3_xof_t * const xof, uint8_t * const dst, const size
   cshake256_xof_squeeze(xof, dst, len);
 }
 
+// init kmac256-xof context
 void kmac256_xof_init(sha3_xof_t * const xof, const kmac_params_t params) {
   static const uint8_t PAD[SHAKE256_RATE] = { 0 };
   static const uint8_t NAME[4] = { 'K', 'M', 'A', 'C' };
@@ -1349,6 +1358,7 @@ void kmac256_xof_init(sha3_xof_t * const xof, const kmac_params_t params) {
   }
 }
 
+// one-shot kmac256-xof
 void kmac256_xof_once(const kmac_params_t params, const uint8_t * const src, const size_t src_len, uint8_t * const dst, const size_t dst_len) {
   sha3_xof_t xof;
   kmac256_xof_init(&xof, params);