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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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