SHA-3 Algorithm Collection

Overview

The SHA-3 family of algorithms, as specified in NIST FIPS-202[1], contains sixalgorithms based on the Keccak sponge function. The differences between themare: the “rate” (how much of the state buffer gets updated with new data betweeninvocations of the Keccak function and analogous to the “block size”), whatdomain separation suffix gets appended to the input data, and how much outputdata is extracted at the end. The Keccak sponge function is designed such thatarbitrary 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 digestalgorithms 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 alsoprovided. 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 theinitialization 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 theoutput data incrementally, an incremental API is also provided. The incrementalAPI 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 multiplesqueezes, with the output laid consecutively in a buffer, gets exactly the sameoutput 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 FIPSmode the SHA-3 library also performs a simple self-test. This is purely to meeta FIPS requirement. Normal testing done by kernel developers and integratorsshould use the much more comprehensive KUnit test suite instead.

References

[1]

https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf

API Function Reference

structsha3_ctx

Context for SHA3-224, SHA3-256, SHA3-384, or SHA3-512

Definition:

struct sha3_ctx {    struct __sha3_ctx ctx;};

Members

ctx

private

voidsha3_zeroize_ctx(structsha3_ctx*ctx)

Zeroize a SHA-3 context

Parameters

structsha3_ctx*ctx

The context to zeroize

Description

This is already called bysha3_final(). Call this explicitly when abandoninga context without callingsha3_final().

structshake_ctx

Context for SHAKE128 or SHAKE256

Definition:

struct shake_ctx {    struct __sha3_ctx ctx;};

Members

ctx

private

voidshake_zeroize_ctx(structshake_ctx*ctx)

Zeroize a SHAKE context

Parameters

structshake_ctx*ctx

The context to zeroize

Description

Call this after the last squeeze.

voidsha3_224_init(structsha3_ctx*ctx)

Initialize a context for SHA3-224

Parameters

structsha3_ctx*ctx

The context to initialize

Description

This begins a new SHA3-224 message digest computation.

Context

Any context.

voidsha3_256_init(structsha3_ctx*ctx)

Initialize a context for SHA3-256

Parameters

structsha3_ctx*ctx

The context to initialize

Description

This begins a new SHA3-256 message digest computation.

Context

Any context.

voidsha3_384_init(structsha3_ctx*ctx)

Initialize a context for SHA3-384

Parameters

structsha3_ctx*ctx

The context to initialize

Description

This begins a new SHA3-384 message digest computation.

Context

Any context.

voidsha3_512_init(structsha3_ctx*ctx)

Initialize a context for SHA3-512

Parameters

structsha3_ctx*ctx

The context to initialize

Description

This begins a new SHA3-512 message digest computation.

Context

Any context.

voidsha3_update(structsha3_ctx*ctx,constu8*in,size_tin_len)

Update a SHA-3 digest context with input data

Parameters

structsha3_ctx*ctx

The context to update; must have been initialized

constu8*in

The input data

size_tin_len

Length of the input data in bytes

Description

This can be called any number of times to add data to a SHA3-224, SHA3-256,SHA3-384, or SHA3-512 digest (depending on which init function was called).

Context

Any context.

voidsha3_final(structsha3_ctx*ctx,u8*out)

Finish computing a SHA-3 message digest

Parameters

structsha3_ctx*ctx

The context to finalize; must have been initialized

u8*out

(output) The resulting SHA3-224, SHA3-256, SHA3-384, or SHA3-512message digest, matching the init function that was called. Note thatthe size differs for each one; see SHA3_*_DIGEST_SIZE.

Description

After finishing, this zeroizesctx. So the caller does not need to do it.

Context

Any context.

voidshake128_init(structshake_ctx*ctx)

Initialize a context for SHAKE128

Parameters

structshake_ctx*ctx

The context to initialize

Description

This begins a new SHAKE128 extendable-output function (XOF) computation.

Context

Any context.

voidshake256_init(structshake_ctx*ctx)

Initialize a context for SHAKE256

Parameters

structshake_ctx*ctx

The context to initialize

Description

This begins a new SHAKE256 extendable-output function (XOF) computation.

Context

Any context.

voidshake_update(structshake_ctx*ctx,constu8*in,size_tin_len)

Update a SHAKE context with input data

Parameters

structshake_ctx*ctx

The context to update; must have been initialized

constu8*in

The input data

size_tin_len

Length of the input data in bytes

Description

This can be called any number of times to add more input data to SHAKE128 orSHAKE256. This cannot be called after squeezing has begun.

Context

Any context.

voidshake_squeeze(structshake_ctx*ctx,u8*out,size_tout_len)

Generate output from SHAKE128 or SHAKE256

Parameters

structshake_ctx*ctx

The context to squeeze; must have been initialized

u8*out

Where to write the resulting output data

size_tout_len

The amount of data to extract toout in bytes

Description

This may be called multiple times. A number of consecutive squeezes laidend-to-end will yield the same output as one big squeeze generating the sametotal amount of output. More input cannot be provided after squeezing hasbegun. After the last squeeze, callshake_zeroize_ctx().

Context

Any context.

voidsha3_224(constu8*in,size_tin_len,u8out[SHA3_224_DIGEST_SIZE])

Compute SHA3-224 digest in one shot

Parameters

constu8*in

The input data to be digested

size_tin_len

Length of the input data in bytes

u8out[SHA3_224_DIGEST_SIZE]

The buffer into which the digest will be stored

Description

Convenience function that computes a SHA3-224 digest. Use this instead ofthe incremental API if you’re able to provide all the input at once.

Context

Any context.

voidsha3_256(constu8*in,size_tin_len,u8out[SHA3_256_DIGEST_SIZE])

Compute SHA3-256 digest in one shot

Parameters

constu8*in

The input data to be digested

size_tin_len

Length of the input data in bytes

u8out[SHA3_256_DIGEST_SIZE]

The buffer into which the digest will be stored

Description

Convenience function that computes a SHA3-256 digest. Use this instead ofthe incremental API if you’re able to provide all the input at once.

Context

Any context.

voidsha3_384(constu8*in,size_tin_len,u8out[SHA3_384_DIGEST_SIZE])

Compute SHA3-384 digest in one shot

Parameters

constu8*in

The input data to be digested

size_tin_len

Length of the input data in bytes

u8out[SHA3_384_DIGEST_SIZE]

The buffer into which the digest will be stored

Description

Convenience function that computes a SHA3-384 digest. Use this instead ofthe incremental API if you’re able to provide all the input at once.

Context

Any context.

voidsha3_512(constu8*in,size_tin_len,u8out[SHA3_512_DIGEST_SIZE])

Compute SHA3-512 digest in one shot

Parameters

constu8*in

The input data to be digested

size_tin_len

Length of the input data in bytes

u8out[SHA3_512_DIGEST_SIZE]

The buffer into which the digest will be stored

Description

Convenience function that computes a SHA3-512 digest. Use this instead ofthe incremental API if you’re able to provide all the input at once.

Context

Any context.

voidshake128(constu8*in,size_tin_len,u8*out,size_tout_len)

Compute SHAKE128 in one shot

Parameters

constu8*in

The input data to be used

size_tin_len

Length of the input data in bytes

u8*out

The buffer into which the output will be stored

size_tout_len

Length of the output to produce in bytes

Description

Convenience function that computes SHAKE128 in one shot. Use this instead ofthe incremental API if you’re able to provide all the input at once as wellas receive all the output at once. All output lengths are supported.

Context

Any context.

voidshake256(constu8*in,size_tin_len,u8*out,size_tout_len)

Compute SHAKE256 in one shot

Parameters

constu8*in

The input data to be used

size_tin_len

Length of the input data in bytes

u8*out

The buffer into which the output will be stored

size_tout_len

Length of the output to produce in bytes

Description

Convenience function that computes SHAKE256 in one shot. Use this instead ofthe incremental API if you’re able to provide all the input at once as wellas receive all the output at once. All output lengths are supported.

Context

Any context.