Documentation/crypto/sha3.rst

Source file repositories/reference/linux-study-clean/Documentation/crypto/sha3.rst

File Facts

System
Linux kernel
Corpus path
Documentation/crypto/sha3.rst
Extension
.rst
Size
4073 bytes
Lines
133
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

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.

Annotation

Implementation Notes