diff options
Diffstat (limited to 'lib/liboqs/include/oqs/sha3x4.h')
| -rw-r--r-- | lib/liboqs/include/oqs/sha3x4.h | 263 |
1 files changed, 263 insertions, 0 deletions
diff --git a/lib/liboqs/include/oqs/sha3x4.h b/lib/liboqs/include/oqs/sha3x4.h new file mode 100644 index 000000000..cef4e6750 --- /dev/null +++ b/lib/liboqs/include/oqs/sha3x4.h @@ -0,0 +1,263 @@ +/** + * \file shakex4.h + * \brief SHA3, SHAKE, and cSHAKE functions; not part of the OQS public API + * + * Contains the API and documentation for SHA3 digest and SHAKE implementations. + * + * <b>Note this is not part of the OQS public API: implementations within liboqs can use these + * functions, but external consumers of liboqs should not use these functions.</b> + * + * \author John Underhill, Douglas Stebila + * + * SPDX-License-Identifier: MIT + */ + +#ifndef OQS_SHA3X4_H +#define OQS_SHA3X4_H + +#include <stddef.h> +#include <stdint.h> + +#if defined(__cplusplus) +extern "C" { +#endif + +/** + * \brief Seed 4 parallel SHAKE-128 instances, and generate 4 arrays of pseudo-random bytes. + * + * \warning The output array length must not be zero. + * + * \param out0 The first output byte array + * \param out1 The second output byte array + * \param out2 The third output byte array + * \param out3 The fourth output byte array + * \param outlen The number of output bytes to generate in every output array + * \param in0 The first input seed byte array + * \param in1 The second input seed byte array + * \param in2 The third input seed byte array + * \param in3 The fourth input seed byte array + * \param inlen The number of seed bytes to process from every input array + */ +void OQS_SHA3_shake128_x4( + uint8_t *out0, + uint8_t *out1, + uint8_t *out2, + uint8_t *out3, + size_t outlen, + const uint8_t *in0, + const uint8_t *in1, + const uint8_t *in2, + const uint8_t *in3, + size_t inlen); + +/** Data structure for the state of the four-way parallel incremental SHAKE-128 API. */ +typedef struct { + /** Internal state. */ + void *ctx; +} OQS_SHA3_shake128_x4_inc_ctx; + +/** + * \brief Initialize the state for four-way parallel incremental SHAKE-128 API. + * + * \param state The function state to be initialized; must be allocated + */ +void OQS_SHA3_shake128_x4_inc_init(OQS_SHA3_shake128_x4_inc_ctx *state); + +/** + * \brief Four-way parallel SHAKE-128 absorb function. + * Absorb four input messages of the same length into four parallel states. + * + * \warning State must be initialized by the caller. + * + * \param state The function state; must be initialized + * \param in0 The input to be absorbed into first instance + * \param in1 The input to be absorbed into first instance + * \param in2 The input to be absorbed into first instance + * \param in3 The input to be absorbed into first instance + * \param inlen The number of bytes to process from each input array + */ +void OQS_SHA3_shake128_x4_inc_absorb( + OQS_SHA3_shake128_x4_inc_ctx *state, + const uint8_t *in0, + const uint8_t *in1, + const uint8_t *in2, + const uint8_t *in3, + size_t inlen); + +/** + * \brief Four-way parallel SHAKE-128 finalize function. + * Prepares the states for squeezing. + * + * \param state The function state; must be initialized + */ +void OQS_SHA3_shake128_x4_inc_finalize(OQS_SHA3_shake128_x4_inc_ctx *state); + +/** + * \brief Four-way parallel SHAKE-128 squeeze function. + * Extracts from four parallel states into four output buffers + * + * \param out0 output buffer for the first instance + * \param out1 output buffer for the second instance + * \param out2 output buffer for the third instance + * \param out3 output buffer for the fourth instance + * \param outlen bytes of outbut buffer + * \param state The function state; must be initialized and finalized. + */ +void OQS_SHA3_shake128_x4_inc_squeeze( + uint8_t *out0, + uint8_t *out1, + uint8_t *out2, + uint8_t *out3, + size_t outlen, + OQS_SHA3_shake128_x4_inc_ctx *state); + +/** + * \brief Frees the state for the four-way parallel incremental SHAKE-128 API. + * + * \param state The state to free + */ +void OQS_SHA3_shake128_x4_inc_ctx_release(OQS_SHA3_shake128_x4_inc_ctx *state); + +/** + * \brief Copies the state for the four-way parallel incremental SHAKE-128 API. + * + * \param dest The state to copy into; must be initialized + * \param src The state to copy from; must be initialized + */ +void OQS_SHA3_shake128_x4_inc_ctx_clone( + OQS_SHA3_shake128_x4_inc_ctx *dest, + const OQS_SHA3_shake128_x4_inc_ctx *src); + +/** + * \brief Resets the state for the four-way parallel incremental SHAKE-128 API. + * + * \param state The function state; must be initialized + */ +void OQS_SHA3_shake128_x4_inc_ctx_reset(OQS_SHA3_shake128_x4_inc_ctx *state); + +/* SHAKE256 */ + +/** + * \brief Seed 4 parallel SHAKE-256 instances, and generate 4 arrays of pseudo-random bytes. + * + * Uses a vectorized (AVX2) implementation of SHAKE-256 if available. + * + * \warning The output array length must not be zero. + * + * \param out0 The first output byte array + * \param out1 The second output byte array + * \param out2 The third output byte array + * \param out3 The fourth output byte array + * \param outlen The number of output bytes to generate in every output array + * \param in0 The first input seed byte array + * \param in1 The second input seed byte array + * \param in2 The third input seed byte array + * \param in3 The fourth input seed byte array + * \param inlen The number of seed bytes to process from every input array + */ +void OQS_SHA3_shake256_x4( + uint8_t *out0, + uint8_t *out1, + uint8_t *out2, + uint8_t *out3, + size_t outlen, + const uint8_t *in0, + const uint8_t *in1, + const uint8_t *in2, + const uint8_t *in3, + size_t inlen); + +/** Data structure for the state of the four-way parallel incremental SHAKE-256 API. */ +typedef struct { + /** Internal state. */ + void *ctx; +} OQS_SHA3_shake256_x4_inc_ctx; + +/** + * \brief Initialize the state for four-way parallel incremental SHAKE-256 API. + * + * \param state The function state to be initialized; must be allocated + */ +void OQS_SHA3_shake256_x4_inc_init(OQS_SHA3_shake256_x4_inc_ctx *state); + +/** + * \brief Four-way parallel SHAKE-256 absorb function. + * Absorb four input messages of the same length into four parallel states. + * + * \warning State must be initialized by the caller. + * + * \param state The function state; must be initialized + * \param in0 The input to be absorbed into first instance + * \param in1 The input to be absorbed into first instance + * \param in2 The input to be absorbed into first instance + * \param in3 The input to be absorbed into first instance + * \param inlen The number of bytes to process from each input array + */ +void OQS_SHA3_shake256_x4_inc_absorb( + OQS_SHA3_shake256_x4_inc_ctx *state, + const uint8_t *in0, + const uint8_t *in1, + const uint8_t *in2, + const uint8_t *in3, + size_t inlen); + +/** + * \brief Four-way parallel SHAKE-256 finalize function. + * + * \param state The function state; must be initialized + */ +void OQS_SHA3_shake256_x4_inc_finalize(OQS_SHA3_shake256_x4_inc_ctx *state); + +/** + * \brief Four-way parallel SHAKE-256 squeeze function. + * Extracts from four parallel states into four output buffers + * + * \param out0 output buffer for the first instance + * \param out1 output buffer for the second instance + * \param out2 output buffer for the third instance + * \param out3 output buffer for the fourth instance + * \param outlen bytes of outbut buffer + * \param state The function state; must be initialized and finalized + */ +void OQS_SHA3_shake256_x4_inc_squeeze( + uint8_t *out0, + uint8_t *out1, + uint8_t *out2, + uint8_t *out3, + size_t outlen, + OQS_SHA3_shake256_x4_inc_ctx *state); + +/** + * \brief Frees the state for the four-way parallel incremental SHAKE-256 API. + * + * \param state The state to free + */ +void OQS_SHA3_shake256_x4_inc_ctx_release(OQS_SHA3_shake256_x4_inc_ctx *state); + +/** + * \brief Copies the state for the four-way parallel incremental SHAKE-256 API. + * + * \warning dest must be allocated. dest must be freed by calling + * OQS_SHA3_shake256_inc_ctx_release. + * + * \param dest The state to copy into; must be initialized + * \param src The state to copy from; must be initialized + */ +void OQS_SHA3_shake256_x4_inc_ctx_clone( + OQS_SHA3_shake256_x4_inc_ctx *dest, + const OQS_SHA3_shake256_x4_inc_ctx *src); + +/** + * \brief Resets the state for the four-way parallel incremental SHAKE-256 API. + * Allows a context to be re-used without free and init calls. + * + * \param state The function state; must be initialized + */ +void OQS_SHA3_shake256_x4_inc_ctx_reset(OQS_SHA3_shake256_x4_inc_ctx *state); + + +#if defined(__cplusplus) +} // extern "C" +#endif + +#endif // OQS_SHA3_H |