mirror of
https://github.com/torvalds/linux.git
synced 2025-12-07 20:06:24 +00:00
15c64c47e4
Add a SHA3 kunit test suite, providing the following:
(*) A simple test of each of SHA3-224, SHA3-256, SHA3-384, SHA3-512,
SHAKE128 and SHAKE256.
(*) NIST 0- and 1600-bit test vectors for SHAKE128 and SHAKE256.
(*) Output tiling (multiple squeezing) tests for SHAKE256.
(*) Standard hash template test for SHA3-256. To make this possible,
gen-hash-testvecs.py is modified to support sha3-256.
(*) Standard benchmark test for SHA3-256.
[EB: dropped some unnecessary changes to gen-hash-testvecs.py, moved
addition of Testing section in doc file into this commit, and
other small cleanups]
Signed-off-by: David Howells <dhowells@redhat.com>
Reviewed-by: Ard Biesheuvel <ardb@kernel.org>
Tested-by: Harald Freudenberger <freude@linux.ibm.com>
Link: https://lore.kernel.org/r/20251026055032.1413733-6-ebiggers@kernel.org
Signed-off-by: Eric Biggers <ebiggers@kernel.org>
131 lines
4.0 KiB
ReStructuredText
131 lines
4.0 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0-or-later
|
|
|
|
==========================
|
|
SHA-3 Algorithm Collection
|
|
==========================
|
|
|
|
.. contents::
|
|
|
|
Overview
|
|
========
|
|
|
|
The SHA-3 family of algorithms, as specified in NIST FIPS-202 [1]_, contains six
|
|
algorithms based on the Keccak sponge function. The differences between them
|
|
are: the "rate" (how much of the state buffer gets updated with new data between
|
|
invocations of the Keccak function and analogous to the "block size"), what
|
|
domain separation suffix gets appended to the input data, and how much output
|
|
data is extracted at the end. The Keccak sponge function is designed such that
|
|
arbitrary amounts of output can be obtained for certain algorithms.
|
|
|
|
Four digest algorithms are provided:
|
|
|
|
- SHA3-224
|
|
- SHA3-256
|
|
- SHA3-384
|
|
- SHA3-512
|
|
|
|
Additionally, two Extendable-Output Functions (XOFs) are provided:
|
|
|
|
- SHAKE128
|
|
- SHAKE256
|
|
|
|
The SHA-3 library API supports all six of these algorithms. The four digest
|
|
algorithms are also supported by the crypto_shash and crypto_ahash APIs.
|
|
|
|
This document describes the SHA-3 library API.
|
|
|
|
|
|
Digests
|
|
=======
|
|
|
|
The following functions compute SHA-3 digests::
|
|
|
|
void sha3_224(const u8 *in, size_t in_len, u8 out[SHA3_224_DIGEST_SIZE]);
|
|
void sha3_256(const u8 *in, size_t in_len, u8 out[SHA3_256_DIGEST_SIZE]);
|
|
void sha3_384(const u8 *in, size_t in_len, u8 out[SHA3_384_DIGEST_SIZE]);
|
|
void sha3_512(const u8 *in, size_t in_len, u8 out[SHA3_512_DIGEST_SIZE]);
|
|
|
|
For users that need to pass in data incrementally, an incremental API is also
|
|
provided. The incremental API uses the following struct::
|
|
|
|
struct sha3_ctx { ... };
|
|
|
|
Initialization is done with one of::
|
|
|
|
void sha3_224_init(struct sha3_ctx *ctx);
|
|
void sha3_256_init(struct sha3_ctx *ctx);
|
|
void sha3_384_init(struct sha3_ctx *ctx);
|
|
void sha3_512_init(struct sha3_ctx *ctx);
|
|
|
|
Input data is then added with any number of calls to::
|
|
|
|
void sha3_update(struct sha3_ctx *ctx, const u8 *in, size_t in_len);
|
|
|
|
Finally, the digest is generated using::
|
|
|
|
void sha3_final(struct sha3_ctx *ctx, u8 *out);
|
|
|
|
which also zeroizes the context. The length of the digest is determined by the
|
|
initialization function that was called.
|
|
|
|
|
|
Extendable-Output Functions
|
|
===========================
|
|
|
|
The following functions compute the SHA-3 extendable-output functions (XOFs)::
|
|
|
|
void shake128(const u8 *in, size_t in_len, u8 *out, size_t out_len);
|
|
void shake256(const u8 *in, size_t in_len, u8 *out, size_t out_len);
|
|
|
|
For users that need to provide the input data incrementally and/or receive the
|
|
output data incrementally, an incremental API is also provided. The incremental
|
|
API uses the following struct::
|
|
|
|
struct shake_ctx { ... };
|
|
|
|
Initialization is done with one of::
|
|
|
|
void shake128_init(struct shake_ctx *ctx);
|
|
void shake256_init(struct shake_ctx *ctx);
|
|
|
|
Input data is then added with any number of calls to::
|
|
|
|
void shake_update(struct shake_ctx *ctx, const u8 *in, size_t in_len);
|
|
|
|
Finally, the output data is extracted with any number of calls to::
|
|
|
|
void shake_squeeze(struct shake_ctx *ctx, u8 *out, size_t out_len);
|
|
|
|
and telling it how much data should be extracted. Note that performing multiple
|
|
squeezes, with the output laid consecutively in a buffer, gets exactly the same
|
|
output as doing a single squeeze for the combined amount over the same buffer.
|
|
|
|
More input data cannot be added after squeezing has started.
|
|
|
|
Once all the desired output has been extracted, zeroize the context::
|
|
|
|
void shake_zeroize_ctx(struct shake_ctx *ctx);
|
|
|
|
|
|
Testing
|
|
=======
|
|
|
|
To test the SHA-3 code, use sha3_kunit (CONFIG_CRYPTO_LIB_SHA3_KUNIT_TEST).
|
|
|
|
Since the SHA-3 algorithms are FIPS-approved, when the kernel is booted in FIPS
|
|
mode the SHA-3 library also performs a simple self-test. This is purely to meet
|
|
a FIPS requirement. Normal testing done by kernel developers and integrators
|
|
should use the much more comprehensive KUnit test suite instead.
|
|
|
|
|
|
References
|
|
==========
|
|
|
|
.. [1] https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf
|
|
|
|
|
|
API Function Reference
|
|
======================
|
|
|
|
.. kernel-doc:: include/crypto/sha3.h
|