projects/linux·blob master · refs

132 lines · 4.0 KiB

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