1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3 * Common values for SHA-3 algorithms
4 *
5 * See also Documentation/crypto/sha3.rst
6 */
7 #ifndef __CRYPTO_SHA3_H__
8 #define __CRYPTO_SHA3_H__
9
10 #include <linux/types.h>
11 #include <linux/string.h>
12
13 #define SHA3_224_DIGEST_SIZE (224 / 8)
14 #define SHA3_224_BLOCK_SIZE (200 - 2 * SHA3_224_DIGEST_SIZE)
15 #define SHA3_224_EXPORT_SIZE SHA3_STATE_SIZE + SHA3_224_BLOCK_SIZE + 1
16
17 #define SHA3_256_DIGEST_SIZE (256 / 8)
18 #define SHA3_256_BLOCK_SIZE (200 - 2 * SHA3_256_DIGEST_SIZE)
19 #define SHA3_256_EXPORT_SIZE SHA3_STATE_SIZE + SHA3_256_BLOCK_SIZE + 1
20
21 #define SHA3_384_DIGEST_SIZE (384 / 8)
22 #define SHA3_384_BLOCK_SIZE (200 - 2 * SHA3_384_DIGEST_SIZE)
23 #define SHA3_384_EXPORT_SIZE SHA3_STATE_SIZE + SHA3_384_BLOCK_SIZE + 1
24
25 #define SHA3_512_DIGEST_SIZE (512 / 8)
26 #define SHA3_512_BLOCK_SIZE (200 - 2 * SHA3_512_DIGEST_SIZE)
27 #define SHA3_512_EXPORT_SIZE SHA3_STATE_SIZE + SHA3_512_BLOCK_SIZE + 1
28
29 /*
30 * SHAKE128 and SHAKE256 actually have variable output size, but this is used to
31 * calculate the block size (rate) analogously to the above.
32 */
33 #define SHAKE128_DEFAULT_SIZE (128 / 8)
34 #define SHAKE128_BLOCK_SIZE (200 - 2 * SHAKE128_DEFAULT_SIZE)
35 #define SHAKE256_DEFAULT_SIZE (256 / 8)
36 #define SHAKE256_BLOCK_SIZE (200 - 2 * SHAKE256_DEFAULT_SIZE)
37
38 #define SHA3_STATE_SIZE 200
39
40 /*
41 * State for the Keccak-f[1600] permutation: 25 64-bit words.
42 *
43 * We usually keep the state words as little-endian, to make absorbing and
44 * squeezing easier. (It means that absorbing and squeezing can just treat the
45 * state as a byte array.) The state words are converted to native-endian only
46 * temporarily by implementations of the permutation that need native-endian
47 * words. Of course, that conversion is a no-op on little-endian machines.
48 */
49 struct sha3_state {
50 union {
51 __le64 words[SHA3_STATE_SIZE / 8];
52 u8 bytes[SHA3_STATE_SIZE];
53
54 u64 native_words[SHA3_STATE_SIZE / 8]; /* see comment above */
55 };
56 };
57
58 /* Internal context, shared by the digests (SHA3-*) and the XOFs (SHAKE*) */
59 struct __sha3_ctx {
60 struct sha3_state state;
61 u8 digest_size; /* Digests only: the digest size in bytes */
62 u8 block_size; /* Block size in bytes */
63 u8 absorb_offset; /* Index of next state byte to absorb into */
64 u8 squeeze_offset; /* XOFs only: index of next state byte to extract */
65 };
66
67 void __sha3_update(struct __sha3_ctx *ctx, const u8 *in, size_t in_len);
68
69 /**
70 * struct sha3_ctx - Context for SHA3-224, SHA3-256, SHA3-384, or SHA3-512
71 * @ctx: private
72 */
73 struct sha3_ctx {
74 struct __sha3_ctx ctx;
75 };
76
77 /**
78 * sha3_zeroize_ctx() - Zeroize a SHA-3 context
79 * @ctx: The context to zeroize
80 *
81 * This is already called by sha3_final(). Call this explicitly when abandoning
82 * a context without calling sha3_final().
83 */
sha3_zeroize_ctx(struct sha3_ctx * ctx)84 static inline void sha3_zeroize_ctx(struct sha3_ctx *ctx)
85 {
86 memzero_explicit(ctx, sizeof(*ctx));
87 }
88
89 /**
90 * struct shake_ctx - Context for SHAKE128 or SHAKE256
91 * @ctx: private
92 */
93 struct shake_ctx {
94 struct __sha3_ctx ctx;
95 };
96
97 /**
98 * shake_zeroize_ctx() - Zeroize a SHAKE context
99 * @ctx: The context to zeroize
100 *
101 * Call this after the last squeeze.
102 */
shake_zeroize_ctx(struct shake_ctx * ctx)103 static inline void shake_zeroize_ctx(struct shake_ctx *ctx)
104 {
105 memzero_explicit(ctx, sizeof(*ctx));
106 }
107
108 /**
109 * sha3_224_init() - Initialize a context for SHA3-224
110 * @ctx: The context to initialize
111 *
112 * This begins a new SHA3-224 message digest computation.
113 *
114 * Context: Any context.
115 */
sha3_224_init(struct sha3_ctx * ctx)116 static inline void sha3_224_init(struct sha3_ctx *ctx)
117 {
118 *ctx = (struct sha3_ctx){
119 .ctx.digest_size = SHA3_224_DIGEST_SIZE,
120 .ctx.block_size = SHA3_224_BLOCK_SIZE,
121 };
122 }
123
124 /**
125 * sha3_256_init() - Initialize a context for SHA3-256
126 * @ctx: The context to initialize
127 *
128 * This begins a new SHA3-256 message digest computation.
129 *
130 * Context: Any context.
131 */
sha3_256_init(struct sha3_ctx * ctx)132 static inline void sha3_256_init(struct sha3_ctx *ctx)
133 {
134 *ctx = (struct sha3_ctx){
135 .ctx.digest_size = SHA3_256_DIGEST_SIZE,
136 .ctx.block_size = SHA3_256_BLOCK_SIZE,
137 };
138 }
139
140 /**
141 * sha3_384_init() - Initialize a context for SHA3-384
142 * @ctx: The context to initialize
143 *
144 * This begins a new SHA3-384 message digest computation.
145 *
146 * Context: Any context.
147 */
sha3_384_init(struct sha3_ctx * ctx)148 static inline void sha3_384_init(struct sha3_ctx *ctx)
149 {
150 *ctx = (struct sha3_ctx){
151 .ctx.digest_size = SHA3_384_DIGEST_SIZE,
152 .ctx.block_size = SHA3_384_BLOCK_SIZE,
153 };
154 }
155
156 /**
157 * sha3_512_init() - Initialize a context for SHA3-512
158 * @ctx: The context to initialize
159 *
160 * This begins a new SHA3-512 message digest computation.
161 *
162 * Context: Any context.
163 */
sha3_512_init(struct sha3_ctx * ctx)164 static inline void sha3_512_init(struct sha3_ctx *ctx)
165 {
166 *ctx = (struct sha3_ctx){
167 .ctx.digest_size = SHA3_512_DIGEST_SIZE,
168 .ctx.block_size = SHA3_512_BLOCK_SIZE,
169 };
170 }
171
172 /**
173 * sha3_update() - Update a SHA-3 digest context with input data
174 * @ctx: The context to update; must have been initialized
175 * @in: The input data
176 * @in_len: Length of the input data in bytes
177 *
178 * This can be called any number of times to add data to a SHA3-224, SHA3-256,
179 * SHA3-384, or SHA3-512 digest (depending on which init function was called).
180 *
181 * Context: Any context.
182 */
sha3_update(struct sha3_ctx * ctx,const u8 * in,size_t in_len)183 static inline void sha3_update(struct sha3_ctx *ctx,
184 const u8 *in, size_t in_len)
185 {
186 __sha3_update(&ctx->ctx, in, in_len);
187 }
188
189 /**
190 * sha3_final() - Finish computing a SHA-3 message digest
191 * @ctx: The context to finalize; must have been initialized
192 * @out: (output) The resulting SHA3-224, SHA3-256, SHA3-384, or SHA3-512
193 * message digest, matching the init function that was called. Note that
194 * the size differs for each one; see SHA3_*_DIGEST_SIZE.
195 *
196 * After finishing, this zeroizes @ctx. So the caller does not need to do it.
197 *
198 * Context: Any context.
199 */
200 void sha3_final(struct sha3_ctx *ctx, u8 *out);
201
202 /**
203 * shake128_init() - Initialize a context for SHAKE128
204 * @ctx: The context to initialize
205 *
206 * This begins a new SHAKE128 extendable-output function (XOF) computation.
207 *
208 * Context: Any context.
209 */
shake128_init(struct shake_ctx * ctx)210 static inline void shake128_init(struct shake_ctx *ctx)
211 {
212 *ctx = (struct shake_ctx){
213 .ctx.block_size = SHAKE128_BLOCK_SIZE,
214 };
215 }
216
217 /**
218 * shake256_init() - Initialize a context for SHAKE256
219 * @ctx: The context to initialize
220 *
221 * This begins a new SHAKE256 extendable-output function (XOF) computation.
222 *
223 * Context: Any context.
224 */
shake256_init(struct shake_ctx * ctx)225 static inline void shake256_init(struct shake_ctx *ctx)
226 {
227 *ctx = (struct shake_ctx){
228 .ctx.block_size = SHAKE256_BLOCK_SIZE,
229 };
230 }
231
232 /**
233 * shake_update() - Update a SHAKE context with input data
234 * @ctx: The context to update; must have been initialized
235 * @in: The input data
236 * @in_len: Length of the input data in bytes
237 *
238 * This can be called any number of times to add more input data to SHAKE128 or
239 * SHAKE256. This cannot be called after squeezing has begun.
240 *
241 * Context: Any context.
242 */
shake_update(struct shake_ctx * ctx,const u8 * in,size_t in_len)243 static inline void shake_update(struct shake_ctx *ctx,
244 const u8 *in, size_t in_len)
245 {
246 __sha3_update(&ctx->ctx, in, in_len);
247 }
248
249 /**
250 * shake_squeeze() - Generate output from SHAKE128 or SHAKE256
251 * @ctx: The context to squeeze; must have been initialized
252 * @out: Where to write the resulting output data
253 * @out_len: The amount of data to extract to @out in bytes
254 *
255 * This may be called multiple times. A number of consecutive squeezes laid
256 * end-to-end will yield the same output as one big squeeze generating the same
257 * total amount of output. More input cannot be provided after squeezing has
258 * begun. After the last squeeze, call shake_zeroize_ctx().
259 *
260 * Context: Any context.
261 */
262 void shake_squeeze(struct shake_ctx *ctx, u8 *out, size_t out_len);
263
264 /**
265 * sha3_224() - Compute SHA3-224 digest in one shot
266 * @in: The input data to be digested
267 * @in_len: Length of the input data in bytes
268 * @out: The buffer into which the digest will be stored
269 *
270 * Convenience function that computes a SHA3-224 digest. Use this instead of
271 * the incremental API if you're able to provide all the input at once.
272 *
273 * Context: Any context.
274 */
275 void sha3_224(const u8 *in, size_t in_len, u8 out[SHA3_224_DIGEST_SIZE]);
276
277 /**
278 * sha3_256() - Compute SHA3-256 digest in one shot
279 * @in: The input data to be digested
280 * @in_len: Length of the input data in bytes
281 * @out: The buffer into which the digest will be stored
282 *
283 * Convenience function that computes a SHA3-256 digest. Use this instead of
284 * the incremental API if you're able to provide all the input at once.
285 *
286 * Context: Any context.
287 */
288 void sha3_256(const u8 *in, size_t in_len, u8 out[SHA3_256_DIGEST_SIZE]);
289
290 /**
291 * sha3_384() - Compute SHA3-384 digest in one shot
292 * @in: The input data to be digested
293 * @in_len: Length of the input data in bytes
294 * @out: The buffer into which the digest will be stored
295 *
296 * Convenience function that computes a SHA3-384 digest. Use this instead of
297 * the incremental API if you're able to provide all the input at once.
298 *
299 * Context: Any context.
300 */
301 void sha3_384(const u8 *in, size_t in_len, u8 out[SHA3_384_DIGEST_SIZE]);
302
303 /**
304 * sha3_512() - Compute SHA3-512 digest in one shot
305 * @in: The input data to be digested
306 * @in_len: Length of the input data in bytes
307 * @out: The buffer into which the digest will be stored
308 *
309 * Convenience function that computes a SHA3-512 digest. Use this instead of
310 * the incremental API if you're able to provide all the input at once.
311 *
312 * Context: Any context.
313 */
314 void sha3_512(const u8 *in, size_t in_len, u8 out[SHA3_512_DIGEST_SIZE]);
315
316 /**
317 * shake128() - Compute SHAKE128 in one shot
318 * @in: The input data to be used
319 * @in_len: Length of the input data in bytes
320 * @out: The buffer into which the output will be stored
321 * @out_len: Length of the output to produce in bytes
322 *
323 * Convenience function that computes SHAKE128 in one shot. Use this instead of
324 * the incremental API if you're able to provide all the input at once as well
325 * as receive all the output at once. All output lengths are supported.
326 *
327 * Context: Any context.
328 */
329 void shake128(const u8 *in, size_t in_len, u8 *out, size_t out_len);
330
331 /**
332 * shake256() - Compute SHAKE256 in one shot
333 * @in: The input data to be used
334 * @in_len: Length of the input data in bytes
335 * @out: The buffer into which the output will be stored
336 * @out_len: Length of the output to produce in bytes
337 *
338 * Convenience function that computes SHAKE256 in one shot. Use this instead of
339 * the incremental API if you're able to provide all the input at once as well
340 * as receive all the output at once. All output lengths are supported.
341 *
342 * Context: Any context.
343 */
344 void shake256(const u8 *in, size_t in_len, u8 *out, size_t out_len);
345
346 #endif /* __CRYPTO_SHA3_H__ */
347