aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPaul Duncan <pabs@pablotron.org>2023-09-04 03:05:24 -0400
committerPaul Duncan <pabs@pablotron.org>2023-09-04 03:05:24 -0400
commit32197f7552185033ba75e41b7e3ce39543137233 (patch)
tree241759e050f85d37d73f972b3e77ef6b49ef250a
parent1ce1a4e379fff33afe8dbb53b7e2dc582ca79851 (diff)
downloadsha3-32197f7552185033ba75e41b7e3ce39543137233.tar.bz2
sha3-32197f7552185033ba75e41b7e3ce39543137233.zip
sha3.h: document sha3_*() and shake*()
-rw-r--r--sha3.h117
1 files changed, 117 insertions, 0 deletions
diff --git a/sha3.h b/sha3.h
index 76de7b0..9e4389c 100644
--- a/sha3.h
+++ b/sha3.h
@@ -1,3 +1,7 @@
+/**
+ * C11 implementations of SHA-3 algorithms from FIPS 202 and NIST SP
+ * 800-185.
+ */
#ifndef SHA3_H
#define SHA3_H
@@ -7,35 +11,148 @@ extern "C" {
#include <stdint.h>
+// sha3 state
typedef union {
uint8_t u8[200];
uint64_t u64[25];
} sha3_state_t;
+// XOF state
typedef struct {
size_t num_bytes;
sha3_state_t a;
_Bool squeezing;
} sha3_xof_t;
+/**
+ * SHA3-224, as specified in FIPS 202, section 6.1.
+ *
+ * @param[in] m Input message.
+ * @param[in] m_len Input message length, in bytes.
+ * @param[out] dst Destination array. Must be at least 28 bytes in length.
+ */
void sha3_224(const uint8_t *m, size_t m_len, uint8_t dst[static 28]);
+
+/**
+ * SHA3-256, as specified in FIPS 202, section 6.1.
+ *
+ * @param[in] m Input message.
+ * @param[in] m_len Input message length, in bytes.
+ * @param[out] dst Destination array. Must be at least 32 bytes in length.
+ */
void sha3_256(const uint8_t *m, size_t m_len, uint8_t dst[static 32]);
+
+/**
+ * SHA3-384, as specified in FIPS 202, section 6.1.
+ *
+ * @param[in] m Input message.
+ * @param[in] m_len Input message length, in bytes.
+ * @param[out] dst Destination array. Must be at least 48 bytes in length.
+ */
void sha3_384(const uint8_t *m, size_t m_len, uint8_t dst[static 48]);
+
+/**
+ * SHA3-512, as specified in FIPS 202, section 6.1.
+ *
+ * @param[in] m Input message.
+ * @param[in] m_len Input message length, in bytes.
+ * @param[out] dst Destination array. Must be at least 48 bytes in length.
+ */
void sha3_512(const uint8_t *m, size_t m_len, uint8_t dst[static 64]);
+/**
+ * SHAKE128, as specified in FIPS 202, section 6.2.
+ *
+ * @param[in] m Input message.
+ * @param[in] m_len Input message length, in bytes.
+ * @param[out] dst Destination array. Must be at least 16 bytes in length.
+ */
void shake128(const uint8_t *m, size_t m_len, uint8_t dst[static 16]);
+
+/**
+ * SHAKE256, as specified in FIPS 202, section 6.2.
+ *
+ * @param[in] m Input message.
+ * @param[in] m_len Input message length, in bytes.
+ * @param[out] dst Destination array. Must be at least 16 bytes in length.
+ */
void shake256(const uint8_t *m, size_t m_len, uint8_t dst[static 32]);
+/**
+ * Initialize SHAKE128 extendable-output function (XOF) context.
+ *
+ * @param[out] xof SHAKE128 XOF context.
+ */
void shake128_xof_init(sha3_xof_t * const xof);
+
+/**
+ * Absorb data into SHAKE128 XOF context.
+ *
+ * @param[in] xof SHAKE128 XOF context.
+ * @param[in] m Input data.
+ * @param[in] len Input data length, in bytes.
+ *
+ * @return True if data was absorbed, and false otherwise (e.g., if context has already been squeezed).
+ */
_Bool shake128_xof_absorb(sha3_xof_t * const xof, const uint8_t * const m, const size_t len);
+
+/**
+ * Squeeze data from SHAKE128 XOF context into output buffer.
+ *
+ * @param[in] xof SHAKE128 XOF context.
+ * @param[out] dst Destination buffer.
+ * @param[in] len Destination buffer length, in bytes.
+ */
void shake128_xof_squeeze(sha3_xof_t * const xof, uint8_t * const dst, const size_t dst_len);
+
+/**
+ * Absorb data into SHAKE128 XOF and then squeeze result into output buffer.
+ *
+ * @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 shake128_xof_once(const uint8_t * const src, const size_t src_len, uint8_t * const dst, const size_t dst_len);
+/**
+ * Initialize SHAKE256 extendable-output function (XOF) context.
+ *
+ * @param[out] xof SHAKE256 XOF context.
+ */
void shake256_xof_init(sha3_xof_t * const xof);
+
+/**
+ * Absorb data into SHAKE256 XOF context.
+ *
+ * @param[in] xof SHAKE256 XOF context.
+ * @param[in] m Input data.
+ * @param[in] len Input data length, in bytes.
+ *
+ * @return True if data was absorbed, and false otherwise (e.g., if context has already been squeezed).
+ */
_Bool shake256_xof_absorb(sha3_xof_t * const xof, const uint8_t * const m, const size_t len);
+
+/**
+ * Squeeze data from SHAKE256 XOF context into output buffer.
+ *
+ * @param[in] xof SHAKE256 XOF context.
+ * @param[out] dst Destination buffer.
+ * @param[in] len Destination buffer length, in bytes.
+ */
void shake256_xof_squeeze(sha3_xof_t * const xof, uint8_t * const dst, const size_t dst_len);
+
+/**
+ * Absorb data into SHAKE256 XOF and then squeeze result into output buffer.
+ *
+ * @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 shake256_xof_once(const uint8_t * const src, const size_t src_len, uint8_t * const dst, const size_t dst_len);
+// cSHAKE parameters.
typedef struct {
const uint8_t *name; // NIST function name
const size_t name_len; // length of NIST function name, in bytes