Debian Codegraph @

Documentation/crypto/sha3.rst

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