aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPaul Duncan <pabs@pablotron.org>2023-09-04 11:32:34 -0400
committerPaul Duncan <pabs@pablotron.org>2023-09-04 11:32:34 -0400
commit4ad0ff5bf5aded277263515b7683fd9b610c1fe4 (patch)
treef498c78c2a822c911704f358bb2bd9155231d41e
parent03c206c98c0c8a65b8558b88d94770b3d55df850 (diff)
downloadsha3-4ad0ff5bf5aded277263515b7683fd9b610c1fe4.tar.bz2
sha3-4ad0ff5bf5aded277263515b7683fd9b610c1fe4.zip
sha3.h: document cshake{128,256}(), cshake{128,256}_xof_{init,absorb,squeeze}()
-rw-r--r--sha3.h141
1 files changed, 129 insertions, 12 deletions
diff --git a/sha3.h b/sha3.h
index 1545f25..5d574a1 100644
--- a/sha3.h
+++ b/sha3.h
@@ -17,11 +17,11 @@ typedef union {
uint64_t u64[25];
} sha3_state_t;
-// XOF state
+// Internal XOF state
typedef struct {
- size_t num_bytes;
- sha3_state_t a;
- _Bool squeezing;
+ size_t num_bytes; // number of bytes absorbed
+ sha3_state_t a; // internal state
+ _Bool squeezing; // mode (absorbing or squeezing)
} sha3_xof_t;
/**
@@ -102,7 +102,7 @@ void shake128_xof_init(sha3_xof_t * const xof);
* context `xof`. Can be called iteratively to absorb input data in
* chunks.
*
- * @param[in] xof SHAKE128 XOF context.
+ * @param[in/out] xof SHAKE128 XOF context.
* @param[in] m Input data.
* @param[in] len Input data length, in bytes.
*
@@ -115,7 +115,7 @@ _Bool shake128_xof_absorb(sha3_xof_t *xof, const uint8_t *m, const size_t len);
* XOF context `xof`. Can be called iteratively to squeeze output data
* in chunks.
*
- * @param[in] xof SHAKE128 XOF context.
+ * @param[in/out] xof SHAKE128 XOF context.
* @param[out] dst Destination buffer.
* @param[in] len Destination buffer length, in bytes.
*/
@@ -145,7 +145,7 @@ void shake256_xof_init(sha3_xof_t *xof);
* context `xof`. Can be called iteratively to absorb input data in
* chunks.
*
- * @param[in] xof SHAKE256 XOF context.
+ * @param[in/out] xof SHAKE256 XOF context.
* @param[in] m Input data.
* @param[in] len Input data length, in bytes.
*
@@ -158,7 +158,7 @@ _Bool shake256_xof_absorb(sha3_xof_t *xof, const uint8_t *m, const size_t len);
* XOF context `xof`. Can be called iteratively to squeeze output data
* in chunks.
*
- * @param[in] xof SHAKE256 XOF context.
+ * @param[in/out] xof SHAKE256 XOF context.
* @param[out] dst Destination buffer.
* @param[in] len Destination buffer length, in bytes.
*/
@@ -184,15 +184,132 @@ typedef struct {
const size_t custom_len; // length of customization string, in bytes
} cshake_params_t;
-void cshake128(const cshake_params_t params, const uint8_t *msg, const size_t msg_len, uint8_t *dst, const size_t dst_len);
-void cshake256(const cshake_params_t params, const uint8_t *msg, const size_t msg_len, uint8_t *dst, const size_t dst_len);
+/**
+ * Initialize internal cSHAKE128 (customizable SHAKE128, as defined in
+ * section 3 of NIST SP 800-185) context with customization parameters
+ * `params`, absorb data in buffer `src` of length `src_len` bytes into
+ * internal context, then squeeze `dst_len` bytes of output into
+ * destination buffer `dst`.
+ *
+ * Note: cSHAKE is used to implement the hash and extendable output
+ * functions (XOF) defined in NIST SP 800-185 and should generally not
+ * be used directly.
+ *
+ * @param[in] params cSHAKE customization parameters.
+ * @param[in] src Input data buffer.
+ * @param[in] src_len Input data buffer length, in bytes.
+ * @param[out] dst Destination buffer.
+ * @param[in] len Destination buffer length, in bytes.
+ */
+void cshake128(const cshake_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
+
+/**
+ * Initialize internal cSHAKE256 (customizable SHAKE256, as defined in
+ * section 3 of NIST SP 800-185) context with customization parameters
+ * `params`, absorb data in buffer `src` of length `src_len` bytes into
+ * internal context, then squeeze `dst_len` bytes of output into
+ * destination buffer `dst`.
+ *
+ * Note: cSHAKE is used to implement the hash and extendable output
+ * functions (XOF) defined in NIST SP 800-185 and should generally not
+ * be used directly.
+ *
+ * @param[in] params cSHAKE customization parameters.
+ * @param[in] src Input data buffer.
+ * @param[in] src_len Input data buffer length, in bytes.
+ * @param[out] dst Destination buffer.
+ * @param[in] len Destination buffer length, in bytes.
+ */
+void cshake256(const cshake_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
+/**
+ * Initialize cSHAKE128 (customizable SHAKE128, as defined in section 3 of
+ * NIST SP 800-185) XOF context with customization parameters `params`.
+ *
+ * Note: cSHAKE is used to implement the hash and extendable output
+ * functions (XOF) defined in NIST SP 800-185 and should generally not
+ * be used directly.
+ *
+ * @param[out] xof cSHAKE128 context.
+ * @param[in] params cSHAKE128 customization parameters.
+ */
void cshake128_xof_init(sha3_xof_t *xof, const cshake_params_t params);
-_Bool cshake128_xof_absorb(sha3_xof_t *xof, const uint8_t *msg, const size_t len);
+
+/**
+ * Absorb data in buffer `src` of length `len` bytes into cSHAKE128 XOF
+ * context `xof`. Can be called iteratively to absorb input data in
+ * chunks.
+ *
+ * Note: cSHAKE is used to implement the hash and extendable output
+ * functions (XOF) defined in NIST SP 800-185 and should generally not
+ * be used directly.
+ *
+ * @param[in/out] xof cSHAKE128 context.
+ * @param[in] msg Input data buffer.
+ * @param[in] len Input data buffer length, in bytes.
+ *
+ * @return True if data was absorbed, and false otherwise (e.g., if context has already been squeezed).
+ */
+_Bool cshake128_xof_absorb(sha3_xof_t *xof, const uint8_t *src, const size_t len);
+
+/**
+ * Squeeze `dst_len` bytes data into output buffer `dst` from cSHAKE128
+ * context XOF context `xof`. Can be called iteratively to squeeze
+ * output data in chunks.
+ *
+ * Note: cSHAKE is used to implement the hash and extendable output
+ * functions (XOF) defined in NIST SP 800-185 and should generally not
+ * be used directly.
+ *
+ * @param[in/out] xof cSHAKE128 context.
+ * @param[out] dst Destination buffer.
+ * @param[in] len Destination buffer length, in bytes.
+ */
void cshake128_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len);
+/**
+ * Initialize cSHAKE256 (customizable SHAKE256, as defined in section 3 of
+ * NIST SP 800-185) XOF context with customization parameters `params`.
+ *
+ * Note: cSHAKE is used to implement the hash and extendable output
+ * functions (XOF) defined in NIST SP 800-185 and should generally not
+ * be used directly.
+ *
+ * @param[out] xof cSHAKE256 context.
+ * @param[in] params cSHAKE256 customization parameters.
+ */
void cshake256_xof_init(sha3_xof_t *xof, const cshake_params_t params);
-_Bool cshake256_xof_absorb(sha3_xof_t *xof, const uint8_t *msg, const size_t len);
+
+/**
+ * Absorb data in buffer `src` of length `len` bytes into cSHAKE256 XOF
+ * context `xof`. Can be called iteratively to absorb input data in
+ * chunks.
+ *
+ * Note: cSHAKE is used to implement the hash and extendable output
+ * functions (XOF) defined in NIST SP 800-185 and should generally not
+ * be used directly.
+ *
+ * @param[in/out] xof cSHAKE256 context.
+ * @param[in] msg Input data buffer.
+ * @param[in] len Input data buffer length, in bytes.
+ *
+ * @return True if data was absorbed, and false otherwise (e.g., if context has already been squeezed).
+ */
+_Bool cshake256_xof_absorb(sha3_xof_t *xof, const uint8_t *src, const size_t len);
+
+/**
+ * Squeeze `dst_len` bytes data into output buffer `dst` from cSHAKE256
+ * context XOF context `xof`. Can be called iteratively to squeeze
+ * output data in chunks.
+ *
+ * Note: cSHAKE is used to implement the hash and extendable output
+ * functions (XOF) defined in NIST SP 800-185 and should generally not
+ * be used directly.
+ *
+ * @param[in/out] xof cSHAKE256 context.
+ * @param[out] dst Destination buffer.
+ * @param[in] len Destination buffer length, in bytes.
+ */
void cshake256_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len);
typedef struct {