tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
lib/crypto: blake2s: Document the BLAKE2s library API
Add kerneldoc for the BLAKE2s library API.
Reviewed-by: Ard Biesheuvel <ardb@kernel.org>
Link: https://lore.kernel.org/r/20251018043106.375964-5-ebiggers@kernel.org
Signed-off-by: Eric Biggers <ebiggers@kernel.org>
+58
+58
include/crypto/blake2s.h
+58
include/crypto/blake2s.h
···
22
22
BLAKE2S_256_HASH_SIZE = 32,
23
23
};
24
24
25
+
/**
26
+
* struct blake2s_ctx - Context for hashing a message with BLAKE2s
27
+
* @h: compression function state
28
+
* @t: block counter
29
+
* @f: finalization indicator
30
+
* @buf: partial block buffer; 'buflen' bytes are valid
31
+
* @buflen: number of bytes buffered in @buf
32
+
* @outlen: length of output hash value in bytes, at most BLAKE2S_HASH_SIZE
33
+
*/
25
34
struct blake2s_ctx {
26
35
/* 'h', 't', and 'f' are used in assembly code, so keep them as-is. */
27
36
u32 h[8];
···
76
67
}
77
68
}
78
69
70
+
/**
71
+
* blake2s_init() - Initialize a BLAKE2s context for a new message (unkeyed)
72
+
* @ctx: the context to initialize
73
+
* @outlen: length of output hash value in bytes, at most BLAKE2S_HASH_SIZE
74
+
*
75
+
* Context: Any context.
76
+
*/
79
77
static inline void blake2s_init(struct blake2s_ctx *ctx, size_t outlen)
80
78
{
81
79
__blake2s_init(ctx, outlen, NULL, 0);
82
80
}
83
81
82
+
/**
83
+
* blake2s_init_key() - Initialize a BLAKE2s context for a new message (keyed)
84
+
* @ctx: the context to initialize
85
+
* @outlen: length of output hash value in bytes, at most BLAKE2S_HASH_SIZE
86
+
* @key: the key
87
+
* @keylen: the key length in bytes, at most BLAKE2S_KEY_SIZE
88
+
*
89
+
* Context: Any context.
90
+
*/
84
91
static inline void blake2s_init_key(struct blake2s_ctx *ctx, size_t outlen,
85
92
const void *key, size_t keylen)
86
93
{
···
106
81
__blake2s_init(ctx, outlen, key, keylen);
107
82
}
108
83
84
+
/**
85
+
* blake2s_update() - Update a BLAKE2s context with message data
86
+
* @ctx: the context to update; must have been initialized
87
+
* @in: the message data
88
+
* @inlen: the data length in bytes
89
+
*
90
+
* This can be called any number of times.
91
+
*
92
+
* Context: Any context.
93
+
*/
109
94
void blake2s_update(struct blake2s_ctx *ctx, const u8 *in, size_t inlen);
95
+
96
+
/**
97
+
* blake2s_final() - Finish computing a BLAKE2s hash
98
+
* @ctx: the context to finalize; must have been initialized
99
+
* @out: (output) the resulting BLAKE2s hash. Its length will be equal to the
100
+
* @outlen that was passed to blake2s_init() or blake2s_init_key().
101
+
*
102
+
* After finishing, this zeroizes @ctx. So the caller does not need to do it.
103
+
*
104
+
* Context: Any context.
105
+
*/
110
106
void blake2s_final(struct blake2s_ctx *ctx, u8 *out);
111
107
108
+
/**
109
+
* blake2s() - Compute BLAKE2s hash in one shot
110
+
* @key: the key, or NULL for an unkeyed hash
111
+
* @keylen: the key length in bytes (at most BLAKE2S_KEY_SIZE), or 0 for an
112
+
* unkeyed hash
113
+
* @in: the message data
114
+
* @inlen: the data length in bytes
115
+
* @out: (output) the resulting BLAKE2s hash, with length @outlen
116
+
* @outlen: length of output hash value in bytes, at most BLAKE2S_HASH_SIZE
117
+
*
118
+
* Context: Any context.
119
+
*/
112
120
static inline void blake2s(const u8 *key, size_t keylen,
113
121
const u8 *in, size_t inlen,
114
122
u8 *out, size_t outlen)