1 /** 2 * \file sha3.h 3 * \brief SHA3 and SHAKE functions; not part of the OQS public API 4 * 5 * Contains the API and documentation for SHA3 digest and SHAKE implementations. 6 * 7 * <b>Note this is not part of the OQS public API: implementations within liboqs can use these 8 * functions, but external consumers of liboqs should not use these functions.</b> 9 * 10 * \author John Underhill, Douglas Stebila 11 * 12 * SPDX-License-Identifier: MIT 13 */ 14 15 #ifndef OQS_SHA3_H 16 #define OQS_SHA3_H 17 18 #include <stddef.h> 19 #include <stdint.h> 20 21 #if defined(__cplusplus) 22 extern "C" { 23 #endif 24 25 /* SHA3 */ 26 27 /** The SHA-256 byte absorption rate */ 28 #define OQS_SHA3_SHA3_256_RATE 136 29 30 /** 31 * \brief Process a message with SHA3-256 and return the digest in the output byte array. 32 * 33 * \warning The output array must be at least 32 bytes in length. 34 * 35 * \param output The output byte array 36 * \param input The message input byte array 37 * \param inplen The number of message bytes to process 38 */ 39 void OQS_SHA3_sha3_256(uint8_t *output, const uint8_t *input, size_t inplen); 40 41 /** Data structure for the state of the incremental SHA3-256 API. */ 42 typedef struct { 43 /** Internal state. */ 44 void *ctx; 45 } OQS_SHA3_sha3_256_inc_ctx; 46 47 /** 48 * \brief Initialize the state for the incremental SHA3-256 API. 49 * 50 * \warning Caller is responsible for releasing state by calling 51 * OQS_SHA3_sha3_256_inc_ctx_release. 52 * 53 * \param state The function state to be allocated and initialized. 54 */ 55 void OQS_SHA3_sha3_256_inc_init(OQS_SHA3_sha3_256_inc_ctx *state); 56 57 /** 58 * \brief The SHA3-256 absorb function. 59 * Absorb an input into the state. 60 * 61 * \param state The function state; must be initialized 62 * \param input The input array 63 * \param inlen The length of the input 64 */ 65 void OQS_SHA3_sha3_256_inc_absorb(OQS_SHA3_sha3_256_inc_ctx *state, const uint8_t *input, size_t inlen); 66 67 /** 68 * \brief The SHA3-256 finalize-and-squeeze function. 69 * Finalizes the state and squeezes a 32 byte digest. 70 * 71 * \warning Output array must be at least 32 bytes. 72 * State cannot be used after this without calling OQS_SHA3_sha3_256_inc_reset. 73 * 74 * \param output The output byte array 75 * \param state The function state; must be initialized 76 */ 77 void OQS_SHA3_sha3_256_inc_finalize(uint8_t *output, OQS_SHA3_sha3_256_inc_ctx *state); 78 79 /** 80 * \brief Release the state for the SHA3-256 incremental API. 81 * 82 * \param state The function state; must be initialized 83 */ 84 void OQS_SHA3_sha3_256_inc_ctx_release(OQS_SHA3_sha3_256_inc_ctx *state); 85 86 /** 87 * \brief Resets the state for the SHA3-256 incremental API. 88 * Alternative to freeing and reinitializing the state. 89 * 90 * \param state The function state; must be initialized 91 */ 92 void OQS_SHA3_sha3_256_inc_ctx_reset(OQS_SHA3_sha3_256_inc_ctx *state); 93 94 /** 95 * \brief Clone the state for the SHA3-256 incremental API. 96 * 97 * \param dest The function state to copy into; must be initialized 98 * \param src The function state to copy; must be initialized 99 */ 100 void OQS_SHA3_sha3_256_inc_ctx_clone(OQS_SHA3_sha3_256_inc_ctx *dest, const OQS_SHA3_sha3_256_inc_ctx *src); 101 102 /** The SHA-384 byte absorption rate */ 103 #define OQS_SHA3_SHA3_384_RATE 104 104 105 /** 106 * \brief Process a message with SHA3-384 and return the digest in the output byte array. 107 * 108 * \warning The output array must be at least 48 bytes in length. 109 * 110 * \param output The output byte array 111 * \param input The message input byte array 112 * \param inplen The number of message bytes to process 113 */ 114 void OQS_SHA3_sha3_384(uint8_t *output, const uint8_t *input, size_t inplen); 115 116 /** Data structure for the state of the incremental SHA3-384 API. */ 117 typedef struct { 118 /** Internal state. */ 119 void *ctx; 120 } OQS_SHA3_sha3_384_inc_ctx; 121 122 /** 123 * \brief Initialize the state for the incremental SHA3-384 API. 124 * 125 * \warning Caller is responsible for releasing state by calling 126 * OQS_SHA3_sha3_384_inc_ctx_release. 127 * 128 * \param state The function state to be allocated and initialized. 129 */ 130 void OQS_SHA3_sha3_384_inc_init(OQS_SHA3_sha3_384_inc_ctx *state); 131 132 /** 133 * \brief The SHA3-384 absorb function. 134 * Absorb an input into the state. 135 * 136 * \param state The function state; must be initialized 137 * \param input The input array 138 * \param inlen The length of the input 139 */ 140 void OQS_SHA3_sha3_384_inc_absorb(OQS_SHA3_sha3_384_inc_ctx *state, const uint8_t *input, size_t inlen); 141 142 /** 143 * \brief The SHA3-384 finalize-and-squeeze function. 144 * Finalizes the state and squeezes a 48 byte digest. 145 * 146 * \warning Output array must be at least 48 bytes. 147 * State cannot be used after this without calling OQS_SHA3_sha3_384_inc_reset. 148 * 149 * \param output The output byte array 150 * \param state The function state; must be initialized 151 */ 152 void OQS_SHA3_sha3_384_inc_finalize(uint8_t *output, OQS_SHA3_sha3_384_inc_ctx *state); 153 154 /** 155 * \brief Release the state for the SHA3-384 incremental API. 156 * 157 * \param state The function state; must be initialized 158 */ 159 void OQS_SHA3_sha3_384_inc_ctx_release(OQS_SHA3_sha3_384_inc_ctx *state); 160 161 /** 162 * \brief Resets the state for the SHA3-384 incremental API. 163 * Alternative to freeing and reinitializing the state. 164 * 165 * \param state The function state; must be initialized 166 */ 167 void OQS_SHA3_sha3_384_inc_ctx_reset(OQS_SHA3_sha3_384_inc_ctx *state); 168 169 /** 170 * \brief Clone the state for the SHA3-384 incremental API. 171 * 172 * \param dest The function state to copy into; must be initialized 173 * \param src The function state to copy; must be initialized 174 */ 175 void OQS_SHA3_sha3_384_inc_ctx_clone(OQS_SHA3_sha3_384_inc_ctx *dest, const OQS_SHA3_sha3_384_inc_ctx *src); 176 177 /** The SHA-512 byte absorption rate */ 178 #define OQS_SHA3_SHA3_512_RATE 72 179 180 /** 181 * \brief Process a message with SHA3-512 and return the digest in the output byte array. 182 * 183 * \warning The output array must be at least 64 bytes in length. 184 * 185 * \param output The output byte array 186 * \param input The message input byte array 187 * \param inplen The number of message bytes to process 188 */ 189 void OQS_SHA3_sha3_512(uint8_t *output, const uint8_t *input, size_t inplen); 190 191 /** Data structure for the state of the incremental SHA3-512 API. */ 192 typedef struct { 193 /** Internal state. */ 194 void *ctx; 195 } OQS_SHA3_sha3_512_inc_ctx; 196 197 /** 198 * \brief Initialize the state for the incremental SHA3-512 API. 199 * 200 * \warning Caller is responsible for releasing state by calling 201 * OQS_SHA3_sha3_512_inc_ctx_release. 202 * 203 * \param state The function state to be allocated and initialized. 204 */ 205 void OQS_SHA3_sha3_512_inc_init(OQS_SHA3_sha3_512_inc_ctx *state); 206 207 /** 208 * \brief The SHA3-512 absorb function. 209 * Absorb an input into the state. 210 * 211 * \param state The function state; must be initialized 212 * \param input The input array 213 * \param inlen The length of the input 214 */ 215 void OQS_SHA3_sha3_512_inc_absorb(OQS_SHA3_sha3_512_inc_ctx *state, const uint8_t *input, size_t inlen); 216 217 /** 218 * \brief The SHA3-512 finalize-and-squeeze function. 219 * Finalizes the state and squeezes a 64 byte digest. 220 * 221 * \warning Output array must be at least 64 bytes. 222 * State cannot be used after this without calling OQS_SHA3_sha3_512_inc_reset. 223 * 224 * \param output The output byte array 225 * \param state The function state; must be initialized 226 */ 227 void OQS_SHA3_sha3_512_inc_finalize(uint8_t *output, OQS_SHA3_sha3_512_inc_ctx *state); 228 229 /** 230 * \brief Release the state for the SHA3-512 incremental API. 231 * 232 * \param state The function state; must be initialized 233 */ 234 void OQS_SHA3_sha3_512_inc_ctx_release(OQS_SHA3_sha3_512_inc_ctx *state); 235 236 /** 237 * \brief Resets the state for the SHA3-512 incremental API. 238 * Alternative to freeing and reinitializing the state. 239 * 240 * \param state The function state; must be initialized 241 */ 242 void OQS_SHA3_sha3_512_inc_ctx_reset(OQS_SHA3_sha3_512_inc_ctx *state); 243 244 /** 245 * \brief Clone the state for the SHA3-512 incremental API. 246 * 247 * \param dest The function state to copy into; must be initialized 248 * \param src The function state to copy; must be initialized 249 */ 250 void OQS_SHA3_sha3_512_inc_ctx_clone(OQS_SHA3_sha3_512_inc_ctx *dest, const OQS_SHA3_sha3_512_inc_ctx *src); 251 252 /* SHAKE */ 253 254 /** The SHAKE-128 byte absorption rate */ 255 #define OQS_SHA3_SHAKE128_RATE 168 256 257 /** 258 * \brief Seed a SHAKE-128 instance, and generate an array of pseudo-random bytes. 259 * 260 * \warning The output array length must not be zero. 261 * 262 * \param output The output byte array 263 * \param outlen The number of output bytes to generate 264 * \param input The input seed byte array 265 * \param inplen The number of seed bytes to process 266 */ 267 void OQS_SHA3_shake128(uint8_t *output, size_t outlen, const uint8_t *input, size_t inplen); 268 269 /** Data structure for the state of the incremental SHAKE-128 API. */ 270 typedef struct { 271 /** Internal state. */ 272 void *ctx; 273 } OQS_SHA3_shake128_inc_ctx; 274 275 /** 276 * \brief Initialize the state for the incremental SHAKE-128 API. 277 * 278 * \warning Caller is responsible for releasing state by calling 279 * OQS_SHA3_shake128_inc_ctx_release. 280 * 281 * \param state The function state to be initialized; must be allocated 282 */ 283 void OQS_SHA3_shake128_inc_init(OQS_SHA3_shake128_inc_ctx *state); 284 285 /** 286 * \brief The SHAKE-128 absorb function. 287 * Absorb an input into the state. 288 * 289 * \warning State must be initialized. 290 * 291 * \param state The function state; must be initialized 292 * \param input input buffer 293 * \param inlen length of input buffer 294 */ 295 void OQS_SHA3_shake128_inc_absorb(OQS_SHA3_shake128_inc_ctx *state, const uint8_t *input, size_t inlen); 296 297 /** 298 * \brief The SHAKE-128 finalize function. 299 * Prepares the state for squeezing. 300 * 301 * \param state The function state; must be initialized 302 */ 303 void OQS_SHA3_shake128_inc_finalize(OQS_SHA3_shake128_inc_ctx *state); 304 305 /** 306 * \brief The SHAKE-128 squeeze function. 307 * Extracts to an output byte array. 308 * 309 * \param output output buffer 310 * \param outlen bytes of outbut buffer 311 * \param state The function state; must be initialized and finalized 312 */ 313 void OQS_SHA3_shake128_inc_squeeze(uint8_t *output, size_t outlen, OQS_SHA3_shake128_inc_ctx *state); 314 315 /** 316 * \brief Frees the state for the incremental SHAKE-128 API. 317 * 318 * \param state The state to free 319 */ 320 void OQS_SHA3_shake128_inc_ctx_release(OQS_SHA3_shake128_inc_ctx *state); 321 322 /** 323 * \brief Copies the state for the SHAKE-128 incremental API. 324 * 325 * \warning Caller is responsible for releasing dest by calling 326 * OQS_SHA3_shake128_inc_ctx_release. 327 * 328 * \param dest The function state to copy into; must be initialized 329 * \param src The function state to copy; must be initialized 330 */ 331 void OQS_SHA3_shake128_inc_ctx_clone(OQS_SHA3_shake128_inc_ctx *dest, const OQS_SHA3_shake128_inc_ctx *src); 332 333 /** 334 * \brief Resets the state for the SHAKE-128 incremental API. Allows a context 335 * to be re-used without free and init calls. 336 * 337 * \param state The function state; must be initialized 338 */ 339 void OQS_SHA3_shake128_inc_ctx_reset(OQS_SHA3_shake128_inc_ctx *state); 340 341 /** The SHAKE-256 byte absorption rate */ 342 #define OQS_SHA3_SHAKE256_RATE 136 343 344 /** 345 * \brief Seed a SHAKE-256 instance, and generate an array of pseudo-random bytes. 346 * 347 * \warning The output array length must not be zero. 348 * 349 * \param output The output byte array 350 * \param outlen The number of output bytes to generate 351 * \param input The input seed byte array 352 * \param inplen The number of seed bytes to process 353 */ 354 void OQS_SHA3_shake256(uint8_t *output, size_t outlen, const uint8_t *input, size_t inplen); 355 356 /** Data structure for the state of the incremental SHAKE-256 API. */ 357 typedef struct { 358 /** Internal state. */ 359 void *ctx; 360 } OQS_SHA3_shake256_inc_ctx; 361 362 /** 363 * \brief Initialize the state for the incremental SHAKE-256 API. 364 * 365 * \param state The function state to be initialized; must be allocated 366 */ 367 void OQS_SHA3_shake256_inc_init(OQS_SHA3_shake256_inc_ctx *state); 368 369 /** 370 * \brief The SHAKE-256 absorb function. 371 * Absorb an input message array directly into the state. 372 * 373 * \warning State must be initialized by the caller. 374 * 375 * \param state The function state; must be initialized 376 * \param input input buffer 377 * \param inlen length of input buffer 378 */ 379 void OQS_SHA3_shake256_inc_absorb(OQS_SHA3_shake256_inc_ctx *state, const uint8_t *input, size_t inlen); 380 381 /** 382 * \brief The SHAKE-256 finalize function. 383 * 384 * \param state The function state; must be initialized 385 */ 386 void OQS_SHA3_shake256_inc_finalize(OQS_SHA3_shake256_inc_ctx *state); 387 388 /** 389 * \brief The SHAKE-256 squeeze function. 390 * Extracts to an output byte array. 391 * 392 * \param output output buffer 393 * \param outlen bytes of outbut buffer 394 * \param state The function state; must be initialized 395 */ 396 void OQS_SHA3_shake256_inc_squeeze(uint8_t *output, size_t outlen, OQS_SHA3_shake256_inc_ctx *state); 397 398 /** 399 * \brief Frees the state for the incremental SHAKE-256 API. 400 * 401 * \param state The state to free 402 */ 403 void OQS_SHA3_shake256_inc_ctx_release(OQS_SHA3_shake256_inc_ctx *state); 404 405 /** 406 * \brief Copies the state for the incremental SHAKE-256 API. 407 * 408 * \warning dest must be allocated. dest must be freed by calling 409 * OQS_SHA3_shake256_inc_ctx_release. 410 * 411 * \param dest The state to copy into; must be initialized 412 * \param src The state to copy from; must be initialized 413 */ 414 void OQS_SHA3_shake256_inc_ctx_clone(OQS_SHA3_shake256_inc_ctx *dest, const OQS_SHA3_shake256_inc_ctx *src); 415 416 /** 417 * \brief Resets the state for the SHAKE-256 incremental API. Allows a context 418 * to be re-used without free and init calls. 419 * 420 * \param state The function state; must be initialized 421 */ 422 void OQS_SHA3_shake256_inc_ctx_reset(OQS_SHA3_shake256_inc_ctx *state); 423 424 425 #if defined(__cplusplus) 426 } // extern "C" 427 #endif 428 429 #endif // OQS_SHA3_H 430