1.. SPDX-License-Identifier: GPL-2.0-or-later 2 3========================== 4SHA-3 Algorithm Collection 5========================== 6 7.. contents:: 8 9Overview 10======== 11 12The SHA-3 family of algorithms, as specified in NIST FIPS-202 [1]_, contains six 13algorithms based on the Keccak sponge function. The differences between them 14are: the "rate" (how much of the state buffer gets updated with new data between 15invocations of the Keccak function and analogous to the "block size"), what 16domain separation suffix gets appended to the input data, and how much output 17data is extracted at the end. The Keccak sponge function is designed such that 18arbitrary amounts of output can be obtained for certain algorithms. 19 20Four digest algorithms are provided: 21 22 - SHA3-224 23 - SHA3-256 24 - SHA3-384 25 - SHA3-512 26 27Additionally, two Extendable-Output Functions (XOFs) are provided: 28 29 - SHAKE128 30 - SHAKE256 31 32The SHA-3 library API supports all six of these algorithms. The four digest 33algorithms are also supported by the crypto_shash and crypto_ahash APIs. 34 35This document describes the SHA-3 library API. 36 37 38Digests 39======= 40 41The following functions compute SHA-3 digests:: 42 43 void sha3_224(const u8 *in, size_t in_len, u8 out[SHA3_224_DIGEST_SIZE]); 44 void sha3_256(const u8 *in, size_t in_len, u8 out[SHA3_256_DIGEST_SIZE]); 45 void sha3_384(const u8 *in, size_t in_len, u8 out[SHA3_384_DIGEST_SIZE]); 46 void sha3_512(const u8 *in, size_t in_len, u8 out[SHA3_512_DIGEST_SIZE]); 47 48For users that need to pass in data incrementally, an incremental API is also 49provided. The incremental API uses the following struct:: 50 51 struct sha3_ctx { ... }; 52 53Initialization is done with one of:: 54 55 void sha3_224_init(struct sha3_ctx *ctx); 56 void sha3_256_init(struct sha3_ctx *ctx); 57 void sha3_384_init(struct sha3_ctx *ctx); 58 void sha3_512_init(struct sha3_ctx *ctx); 59 60Input data is then added with any number of calls to:: 61 62 void sha3_update(struct sha3_ctx *ctx, const u8 *in, size_t in_len); 63 64Finally, the digest is generated using:: 65 66 void sha3_final(struct sha3_ctx *ctx, u8 *out); 67 68which also zeroizes the context. The length of the digest is determined by the 69initialization function that was called. 70 71 72Extendable-Output Functions 73=========================== 74 75The following functions compute the SHA-3 extendable-output functions (XOFs):: 76 77 void shake128(const u8 *in, size_t in_len, u8 *out, size_t out_len); 78 void shake256(const u8 *in, size_t in_len, u8 *out, size_t out_len); 79 80For users that need to provide the input data incrementally and/or receive the 81output data incrementally, an incremental API is also provided. The incremental 82API uses the following struct:: 83 84 struct shake_ctx { ... }; 85 86Initialization is done with one of:: 87 88 void shake128_init(struct shake_ctx *ctx); 89 void shake256_init(struct shake_ctx *ctx); 90 91Input data is then added with any number of calls to:: 92 93 void shake_update(struct shake_ctx *ctx, const u8 *in, size_t in_len); 94 95Finally, the output data is extracted with any number of calls to:: 96 97 void shake_squeeze(struct shake_ctx *ctx, u8 *out, size_t out_len); 98 99and telling it how much data should be extracted. Note that performing multiple 100squeezes, with the output laid consecutively in a buffer, gets exactly the same 101output as doing a single squeeze for the combined amount over the same buffer. 102 103More input data cannot be added after squeezing has started. 104 105Once all the desired output has been extracted, zeroize the context:: 106 107 void shake_zeroize_ctx(struct shake_ctx *ctx); 108 109 110Testing 111======= 112 113To test the SHA-3 code, use sha3_kunit (CONFIG_CRYPTO_LIB_SHA3_KUNIT_TEST). 114 115Since the SHA-3 algorithms are FIPS-approved, when the kernel is booted in FIPS 116mode the SHA-3 library also performs a simple self-test. This is purely to meet 117a FIPS requirement. Normal testing done by kernel developers and integrators 118should use the much more comprehensive KUnit test suite instead. 119 120 121References 122========== 123 124.. [1] https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf 125 126 127API Function Reference 128====================== 129 130.. kernel-doc:: include/crypto/sha3.h 131