1CRYPTO_BLAKE2B(3MONOCYPHER)          LOCAL         CRYPTO_BLAKE2B(3MONOCYPHER)
2

NAME

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

SYNOPSIS

9     #include <monocypher.h>
10
11     void
12     crypto_blake2b(uint8_t hash[64], const uint8_t *message,
13         size_t message_size);
14
15     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
20     void
21     crypto_blake2b_init(crypto_blake2b_ctx *ctx);
22
23     void
24     crypto_blake2b_general_init(crypto_blake2b_ctx *ctx, size_t hash_size,
25         const uint8_t *key, size_t key_size);
26
27     void
28     crypto_blake2b_update(crypto_blake2b_ctx *ctx, const uint8_t *message,
29         size_t message_size);
30
31     void
32     crypto_blake2b_final(crypto_blake2b_ctx *ctx, uint8_t *hash);
33

DESCRIPTION

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
38     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
42     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
45     The arguments are:
46
47     hash    The output hash.
48
49     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
55     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
63     key_size
64             Length of key, in bytes.  Must be between 0 and 64.  32 is a good
65             default.
66
67     message
68             The message to hash.  May overlap with hash.  May be NULL if
69             message_size is 0.
70
71     message_size
72             Length of message, in bytes.
73
74   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
80     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
85   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
89     initialisation with crypto_blake2b_general_init() or
90         crypto_blake2b_init(), which sets up a context with the hashing pa‐
91         rameters;
92
93     update with crypto_blake2b_update(), which hashes the message chunk
94         by chunk, and keep the intermediary result in the context;
95
96     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
100     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

RETURN VALUES

106     These functions return nothing.
107

EXAMPLES

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
114     Hashing a message all at once:
115
116           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
120     Computing a message authentication code all at once:
121
122           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
131     Hashing a message incrementally (without a key):
132
133           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
142     Computing a message authentication code incrementally:
143
144           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

SEE ALSO

160     crypto_key_exchange(3monocypher), crypto_lock(3monocypher),
161     intro(3monocypher)
162

STANDARDS

164     These functions implement BLAKE2b, described in RFC 7693.
165

HISTORY

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

CAVEATS

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

SECURITY CONSIDERATIONS

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.
189
190BSD                             March 31, 2020                             BSD
Impressum