1CRYPTO_BLAKE2B(3MONOCYPHER) LOCAL CRYPTO_BLAKE2B(3MONOCYPHER)
2
4 crypto_blake2b, crypto_blake2b_general, crypto_blake2b_general_init,
5 crypto_blake2b_init, crypto_blake2b_update, crypto_blake2b_final — cryp‐
6 tographic hashing
7
9 #include <monocypher.h>
10 void
12 crypto_blake2b(uint8_t hash[64], const uint8_t *message,
13 size_t message_size);
14 void
16 crypto_blake2b_general(uint8_t *hash, size_t hash_size,
17 const uint8_t *key, size_t key_size, const uint8_t *message,
18 size_t message_size);
19 void
21 crypto_blake2b_init(crypto_blake2b_ctx *ctx);
22 void
24 crypto_blake2b_general_init(crypto_blake2b_ctx *ctx, size_t hash_size,
25 const uint8_t *key, size_t key_size);
26 void
28 crypto_blake2b_update(crypto_blake2b_ctx *ctx, const uint8_t *message,
29 size_t message_size);
30 void
32 crypto_blake2b_final(crypto_blake2b_ctx *ctx, uint8_t *hash);
33
35 BLAKE2b is a fast cryptographically secure hash, based on the ideas of
36 Chacha20. It is faster than MD5, yet just as secure as SHA-3.
37 Note that BLAKE2b itself is not suitable for hashing passwords and deriv‐
39 ing keys from them; use the crypto_argon2i(3monocypher) family of func‐
40 tions for that purpose instead.
41 BLAKE2b is immune to length extension attacks, and as such does not re‐
43 quire any specific precautions, such as using the HMAC algorithm.
44 The arguments are:
46 hash The output hash.
48 hash_size
50 Length of hash, in bytes. Must be between 1 and 64. Anything
51 below 32 is discouraged when using Blake2b as a general-purpose
52 hash function; anything below 16 is discouraged when using
53 Blake2b as a message authentication code.
54 key Some secret key. One cannot predict the final hash without it.
56 May be NULL if key_size is 0, in which case no key is used. Keys
57 can be used to create a message authentication code (MAC). Use
58 crypto_verify16(3monocypher), crypto_verify32(3monocypher), or
59 crypto_verify64(3monocypher) to compare MACs created this way.
60 Choose the size of the hash accordingly. Users may want to wipe
61 the key with crypto_wipe(3monocypher) once they are done with it.
62 key_size
64 Length of key, in bytes. Must be between 0 and 64. 32 is a good
65 default.
66 message
68 The message to hash. May overlap with hash. May be NULL if
69 message_size is 0.
70 message_size
72 Length of message, in bytes.
73 Direct interface
75 The direct interface has two functions, crypto_blake2b() and
76 crypto_blake2b_general(). crypto_blake2b() is provided for convenience,
77 and is equivalent to calling crypto_blake2b_general() with no key and a
78 64-byte hash.
79 crypto_blake2b_general() users can specify the size of the hash, and use
81 a secret key to make the hash unpredictable – useful for message authen‐
82 tication codes. Even when using a key, you do not have to wipe the con‐
83 text struct with crypto_wipe(3monocypher).
84 Incremental interface
86 The incremental interface is useful for handling streams of data or large
87 files without using too much memory. This interface uses three steps:
88 • initialisation with crypto_blake2b_general_init() or
90 crypto_blake2b_init(), which sets up a context with the hashing pa‐
91 rameters;
92 • update with crypto_blake2b_update(), which hashes the message chunk
94 by chunk, and keep the intermediary result in the context;
95 • and finalisation with crypto_blake2b_final(), which produces the fi‐
97 nal hash. The crypto_blake2b_ctx is automatically wiped upon finali‐
98 sation.
99 The invariants of the parameters are the same as for
101 crypto_blake2b_general(). crypto_blake2b_init() is a convenience ini‐
102 tialisation function that specifies a 64-byte hash and no key. This is
103 considered a good default.
104
106 These functions return nothing.
107
109 The following examples assume the existence of arc4random_buf(), which
110 fills the given buffer with cryptographically secure random bytes. If
111 arc4random_buf() does not exist on your system, see intro(3monocypher)
112 for advice about how to generate cryptographically secure random bytes.
113 Hashing a message all at once:
115 uint8_t hash [64]; /* Output hash (64 bytes) */
117 uint8_t message[12] = "Lorem ipsum"; /* Message to hash */
118 crypto_blake2b(hash, message, 12);
119 Computing a message authentication code all at once:
121 uint8_t hash [16];
123 uint8_t key [32];
124 uint8_t message[11] = "Lorem ipsu"; /* Message to authenticate */
125 arc4random_buf(key, 32);
126 crypto_blake2b_general(hash, 16, key, 32, message, 11);
127 /* Wipe secrets if they are no longer needed */
128 crypto_wipe(message, 11);
129 crypto_wipe(key, 32);
130 Hashing a message incrementally (without a key):
132 uint8_t hash [ 64]; /* Output hash (64 bytes) */
134 uint8_t message[500] = {1}; /* Message to hash */
135 crypto_blake2b_ctx ctx;
136 crypto_blake2b_init(&ctx);
137 for (size_t i = 0; i < 500; i += 100) {
138 crypto_blake2b_update(&ctx, message + i, 100);
139 }
140 crypto_blake2b_final(&ctx, hash);
141 Computing a message authentication code incrementally:
143 uint8_t hash [ 16];
145 uint8_t key [ 32];
146 uint8_t message[500] = {1}; /* Message to authenticate */
147 crypto_blake2b_ctx ctx;
148 arc4random_buf(key, 32);
149 crypto_blake2b_general_init(&ctx, 16, key, 32);
150 /* Wipe the key */
151 crypto_wipe(key, 32);
152 for (size_t i = 0; i < 500; i += 100) {
153 crypto_blake2b_update(&ctx, message + i, 100);
154 /* Wipe secrets if they are no longer needed */
155 crypto_wipe(message + i, 100);
156 }
157 crypto_blake2b_final(&ctx, hash);
158
160 crypto_key_exchange(3monocypher), crypto_lock(3monocypher),
161 intro(3monocypher)
162
164 These functions implement BLAKE2b, described in RFC 7693.
165
167 The crypto_blake2b(), crypto_blake2b_general(),
168 crypto_blake2b_general_init(), crypto_blake2b_init(),
169 crypto_blake2b_update(), and crypto_blake2b_final() functions first ap‐
170 peared in Monocypher 0.1.
171
173 Monocypher does not perform any input validation. Any deviation from the
174 specified input and output length ranges results in undefined behaviour.
175 Make sure your inputs are correct.
176
178 BLAKE2b is a general-purpose cryptographic hash function; this means that
179 it is not suited for hashing passwords and deriving cryptographic keys
180 from passwords in particular. While cryptographic keys usually have hun‐
181 dreds of bits of entropy, passwords are often much less complex. When
182 storing passwords as hashes or when deriving keys from them, the goal is
183 normally to prevent attackers from quickly iterating all possible pass‐
184 words. Because passwords tend to be simple, it is important to artifi‐
185 cially slow down attackers by using especially computationally difficult
186 hashing algorithms. Monocypher therefore provides
187 crypto_argon2i(3monocypher) for password hashing and deriving keys from
188 passwords.
189BSD March 31, 2020 BSD