Skip to content

Commit e465f92

Browse files
douzzerdouzzer
authored
Merge pull request wolfSSL#9642 from holtrop-wolfssl/hmac-blake2
Add HMAC-BLAKE2b and HMAC-BLAKE2s API functions
2 parents c2cf8b1 + e90429d commit e465f92

File tree

7 files changed

+755
-19
lines changed

7 files changed

+755
-19
lines changed

‎README‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,9 @@ and feature set. It is commonly used in standard operating environments as well
77
because of its royalty-free pricing and excellent cross platform support.
88
wolfSSL supports industry standards up to the current TLS 1.3 and DTLS 1.3
99
levels, is up to 20 times smaller than OpenSSL, and offers progressive ciphers
10-
such as ChaCha20, Curve25519, and Blake2b. User benchmarking and feedback
11-
reports dramatically better performance when using wolfSSL over OpenSSL.
10+
such as ChaCha20, Curve25519, BLAKE2b/BLAKE2s and Post-Quantum TLS 1.3 groups.
11+
User benchmarking and feedback reports dramatically better performance when
12+
using wolfSSL over OpenSSL.
1213

1314
wolfSSL is powered by the wolfCrypt library. Two versions of the wolfCrypt
1415
cryptography library have been FIPS 140-2 validated (Certificate #2425 and

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@ standard operating environments as well because of its royalty-free pricing
88
and excellent cross platform support. wolfSSL supports industry standards up
99
to the current [TLS 1.3](https://www.wolfssl.com/tls13) and DTLS 1.3, is up to
1010
20 times smaller than OpenSSL, and offers progressive ciphers such as ChaCha20,
11-
Curve25519, Blake2b and Post-Quantum TLS 1.3 groups. User benchmarking and
12-
feedback reports dramatically better performance when using wolfSSL over
11+
Curve25519, BLAKE2b/BLAKE2s and Post-Quantum TLS 1.3 groups. User benchmarking
12+
and feedback reports dramatically better performance when using wolfSSL over
1313
OpenSSL.
1414

1515
wolfSSL is powered by the wolfCrypt cryptography library. Two versions of

‎doc/dox_comments/header_files/blake2.h‎

Lines changed: 332 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
\code
1515
Blake2b b2b;
1616
// initialize Blake2b structure with 64 byte digest
17-
wc_InitBlake2b(&b2b, 64);
17+
wc_InitBlake2b(&b2b, WC_BLAKE2B_DIGEST_SIZE);
1818
\endcode
1919
2020
\sa wc_Blake2bUpdate
@@ -41,13 +41,13 @@ int wc_InitBlake2b(Blake2b* b2b, word32 digestSz);
4141
int ret;
4242
Blake2b b2b;
4343
// initialize Blake2b structure with 64 byte digest
44-
wc_InitBlake2b(&b2b, 64);
44+
wc_InitBlake2b(&b2b, WC_BLAKE2B_DIGEST_SIZE);
4545
4646
byte plain[] = { // initialize input };
4747
4848
ret = wc_Blake2bUpdate(&b2b, plain, sizeof(plain));
49-
if( ret != 0) {
50-
// error updating blake2b
49+
if (ret != 0) {
50+
// error updating blake2b
5151
}
5252
\endcode
5353
@@ -78,18 +78,341 @@ int wc_Blake2bUpdate(Blake2b* b2b, const byte* data, word32 sz);
7878
\code
7979
int ret;
8080
Blake2b b2b;
81-
byte hash[64];
81+
byte hash[WC_BLAKE2B_DIGEST_SIZE];
8282
// initialize Blake2b structure with 64 byte digest
83-
wc_InitBlake2b(&b2b, 64);
83+
wc_InitBlake2b(&b2b, WC_BLAKE2B_DIGEST_SIZE);
8484
... // call wc_Blake2bUpdate to add data to hash
8585
86-
ret = wc_Blake2bFinal(&b2b, hash, 64);
87-
if( ret != 0) {
88-
// error generating blake2b hash
86+
ret = wc_Blake2bFinal(&b2b, hash, WC_BLAKE2B_DIGEST_SIZE);
87+
if (ret != 0) {
88+
// error generating blake2b hash
8989
}
9090
\endcode
9191
9292
\sa wc_InitBlake2b
9393
\sa wc_Blake2bUpdate
9494
*/
9595
int wc_Blake2bFinal(Blake2b* b2b, byte* final, word32 requestSz);
96+
97+
/*!
98+
\ingroup BLAKE2
99+
100+
\brief Initialize an HMAC-BLAKE2b message authentication code computation.
101+
102+
\return 0 Returned upon successfully initializing the HMAC-BLAKE2b MAC
103+
computation.
104+
105+
\param b2b Blake2b structure to be used for the MAC computation.
106+
\param key pointer to the key
107+
\param key_len length of the key
108+
109+
_Example_
110+
\code
111+
Blake2b b2b;
112+
int ret;
113+
byte key[] = {4, 5, 6};
114+
ret = wc_Blake2bHmacInit(&b2b, key);
115+
if (ret != 0) {
116+
// error generating HMAC-BLAKE2b
117+
}
118+
\endcode
119+
*/
120+
int wc_Blake2bHmacInit(Blake2b * b2b,
121+
const byte * key, size_t key_len);
122+
123+
/*!
124+
\ingroup BLAKE2
125+
126+
\brief Update an HMAC-BLAKE2b message authentication code computation with
127+
additional input data.
128+
129+
\return 0 Returned upon successfully updating the HMAC-BLAKE2b MAC
130+
computation.
131+
132+
\param b2b Blake2b structure to be used for the MAC computation.
133+
\param in pointer to the input data
134+
\param in_len length of the input data
135+
136+
_Example_
137+
\code
138+
Blake2b b2b;
139+
int ret;
140+
byte key[] = {4, 5, 6};
141+
byte data[] = {1, 2, 3};
142+
ret = wc_Blake2bHmacInit(&b2b, key, sizeof(key));
143+
ret = wc_Blake2bHmacUpdate(&b2b, data, sizeof(data));
144+
\endcode
145+
*/
146+
int wc_Blake2bHmacUpdate(Blake2b * b2b,
147+
const byte * in, size_t in_len);
148+
149+
/*!
150+
\ingroup BLAKE2
151+
152+
\brief Finalize an HMAC-BLAKE2b message authentication code computation.
153+
154+
\return 0 Returned upon successfully finalizing the HMAC-BLAKE2b MAC
155+
computation.
156+
157+
\param b2b Blake2b structure to be used for the MAC computation.
158+
\param key pointer to the key
159+
\param key_len length of the key
160+
\param out output buffer to store computed MAC
161+
\param out_len length of output buffer
162+
163+
_Example_
164+
\code
165+
Blake2b b2b;
166+
int ret;
167+
byte key[] = {4, 5, 6};
168+
byte data[] = {1, 2, 3};
169+
byte mac[WC_BLAKE2B_DIGEST_SIZE];
170+
ret = wc_Blake2bHmacInit(&b2b, key, sizeof(key));
171+
ret = wc_Blake2bHmacUpdate(&b2b, data, sizeof(data));
172+
ret = wc_Blake2bHmacFinalize(&b2b, key, sizeof(key), mac, sizezof(mac));
173+
\endcode
174+
*/
175+
int wc_Blake2bHmacFinal(Blake2b * b2b,
176+
const byte * key, size_t key_len,
177+
byte * out, size_t out_len);
178+
179+
/*!
180+
\ingroup BLAKE2
181+
182+
\brief Compute the HMAC-BLAKE2b message authentication code of the given
183+
input data using the given key.
184+
185+
\return 0 Returned upon successfully computing the HMAC-BLAKE2b MAC.
186+
187+
\param in pointer to the input data
188+
\param in_len length of the input data
189+
\param key pointer to the key
190+
\param key_len length of the key
191+
\param out output buffer to store computed MAC
192+
\param out_len length of output buffer
193+
194+
_Example_
195+
\code
196+
int ret;
197+
byte mac[WC_BLAKE2B_DIGEST_SIZE];
198+
byte data[] = {1, 2, 3};
199+
byte key[] = {4, 5, 6};
200+
ret = wc_Blake2bHmac(data, sizeof(data), key, sizeof(key), mac, sizeof(mac));
201+
if (ret != 0) {
202+
// error generating HMAC-BLAKE2b
203+
}
204+
\endcode
205+
*/
206+
int wc_Blake2bHmac(const byte * in, size_t in_len,
207+
const byte * key, size_t key_len,
208+
byte * out, size_t out_len);
209+
210+
211+
/*!
212+
\ingroup BLAKE2
213+
214+
\brief This function initializes a Blake2s structure for use with the
215+
Blake2 hash function.
216+
217+
\return 0 Returned upon successfully initializing the Blake2s structure and
218+
setting the digest size.
219+
220+
\param b2s pointer to the Blake2s structure to initialize
221+
\param digestSz length of the blake 2 digest to implement
222+
223+
_Example_
224+
\code
225+
Blake2s b2s;
226+
// initialize Blake2s structure with 32 byte digest
227+
wc_InitBlake2s(&b2s, WC_BLAKE2S_DIGEST_SIZE);
228+
\endcode
229+
230+
\sa wc_Blake2sUpdate
231+
*/
232+
int wc_InitBlake2s(Blake2s* b2s, word32 digestSz);
233+
234+
/*!
235+
\ingroup BLAKE2
236+
237+
\brief This function updates the Blake2s hash with the given input data.
238+
This function should be called after wc_InitBlake2s, and repeated until
239+
one is ready for the final hash: wc_Blake2sFinal.
240+
241+
\return 0 Returned upon successfully update the Blake2s structure with
242+
the given data
243+
\return -1 Returned if there is a failure while compressing the input data
244+
245+
\param b2s pointer to the Blake2s structure to update
246+
\param data pointer to a buffer containing the data to append
247+
\param sz length of the input data to append
248+
249+
_Example_
250+
\code
251+
int ret;
252+
Blake2s b2s;
253+
// initialize Blake2s structure with 32 byte digest
254+
wc_InitBlake2s(&b2s, WC_BLAKE2S_DIGEST_SIZE);
255+
256+
byte plain[] = { // initialize input };
257+
258+
ret = wc_Blake2sUpdate(&b2s, plain, sizeof(plain));
259+
if (ret != 0) {
260+
// error updating blake2s
261+
}
262+
\endcode
263+
264+
\sa wc_InitBlake2s
265+
\sa wc_Blake2sFinal
266+
*/
267+
int wc_Blake2sUpdate(Blake2s* b2s, const byte* data, word32 sz);
268+
269+
/*!
270+
\ingroup BLAKE2
271+
272+
\brief This function computes the Blake2s hash of the previously supplied
273+
input data. The output hash will be of length requestSz, or, if
274+
requestSz==0, the digestSz of the b2s structure. This function should be
275+
called after wc_InitBlake2s and wc_Blake2sUpdate has been processed for
276+
each piece of input data desired.
277+
278+
\return 0 Returned upon successfully computing the Blake2s hash
279+
\return -1 Returned if there is a failure while parsing the Blake2s hash
280+
281+
\param b2s pointer to the Blake2s structure to update
282+
\param final pointer to a buffer in which to store the blake2s hash.
283+
Should be of length requestSz
284+
\param requestSz length of the digest to compute. When this is zero,
285+
b2s->digestSz will be used instead
286+
287+
_Example_
288+
\code
289+
int ret;
290+
Blake2s b2s;
291+
byte hash[WC_BLAKE2S_DIGEST_SIZE];
292+
// initialize Blake2s structure with 32 byte digest
293+
wc_InitBlake2s(&b2s, WC_BLAKE2S_DIGEST_SIZE);
294+
... // call wc_Blake2sUpdate to add data to hash
295+
296+
ret = wc_Blake2sFinal(&b2s, hash, WC_BLAKE2S_DIGEST_SIZE);
297+
if (ret != 0) {
298+
// error generating blake2s hash
299+
}
300+
\endcode
301+
302+
\sa wc_InitBlake2s
303+
\sa wc_Blake2sUpdate
304+
*/
305+
int wc_Blake2sFinal(Blake2s* b2s, byte* final, word32 requestSz);
306+
307+
/*!
308+
\ingroup BLAKE2
309+
310+
\brief Initialize an HMAC-BLAKE2s message authentication code computation.
311+
312+
\return 0 Returned upon successfully initializing the HMAC-BLAKE2s MAC
313+
computation.
314+
315+
\param b2s Blake2s structure to be used for the MAC computation.
316+
\param key pointer to the key
317+
\param key_len length of the key
318+
319+
_Example_
320+
\code
321+
Blake2s b2s;
322+
int ret;
323+
byte key[] = {4, 5, 6};
324+
ret = wc_Blake2sHmacInit(&b2s, key);
325+
if (ret != 0) {
326+
// error generating HMAC-BLAKE2s
327+
}
328+
\endcode
329+
*/
330+
int wc_Blake2sHmacInit(Blake2s * b2s,
331+
const byte * key, size_t key_len);
332+
333+
/*!
334+
\ingroup BLAKE2
335+
336+
\brief Update an HMAC-BLAKE2s message authentication code computation with
337+
additional input data.
338+
339+
\return 0 Returned upon successfully updating the HMAC-BLAKE2s MAC
340+
computation.
341+
342+
\param b2s Blake2s structure to be used for the MAC computation.
343+
\param in pointer to the input data
344+
\param in_len length of the input data
345+
346+
_Example_
347+
\code
348+
Blake2s b2s;
349+
int ret;
350+
byte key[] = {4, 5, 6};
351+
byte data[] = {1, 2, 3};
352+
ret = wc_Blake2sHmacInit(&b2s, key, sizeof(key));
353+
ret = wc_Blake2sHmacUpdate(&b2s, data, sizeof(data));
354+
\endcode
355+
*/
356+
int wc_Blake2sHmacUpdate(Blake2s * b2s,
357+
const byte * in, size_t in_len);
358+
359+
/*!
360+
\ingroup BLAKE2
361+
362+
\brief Finalize an HMAC-BLAKE2s message authentication code computation.
363+
364+
\return 0 Returned upon successfully finalizing the HMAC-BLAKE2s MAC
365+
computation.
366+
367+
\param b2s Blake2s structure to be used for the MAC computation.
368+
\param key pointer to the key
369+
\param key_len length of the key
370+
\param out output buffer to store computed MAC
371+
\param out_len length of output buffer
372+
373+
_Example_
374+
\code
375+
Blake2s b2s;
376+
int ret;
377+
byte key[] = {4, 5, 6};
378+
byte data[] = {1, 2, 3};
379+
byte mac[WC_BLAKE2S_DIGEST_SIZE];
380+
ret = wc_Blake2sHmacInit(&b2s, key, sizeof(key));
381+
ret = wc_Blake2sHmacUpdate(&b2s, data, sizeof(data));
382+
ret = wc_Blake2sHmacFinalize(&b2s, key, sizeof(key), mac, sizezof(mac));
383+
\endcode
384+
*/
385+
int wc_Blake2sHmacFinal(Blake2s * b2s,
386+
const byte * key, size_t key_len,
387+
byte * out, size_t out_len);
388+
389+
/*!
390+
\ingroup BLAKE2
391+
392+
\brief This function computes the HMAC-BLAKE2s message authentication code
393+
of the given input data using the given key.
394+
395+
\return 0 Returned upon successfully computing the HMAC-BLAKE2s MAC.
396+
397+
\param in pointer to the input data
398+
\param in_len length of the input data
399+
\param key pointer to the key
400+
\param key_len length of the key
401+
\param out output buffer to store computed MAC
402+
\param out_len length of output buffer
403+
404+
_Example_
405+
\code
406+
int ret;
407+
byte mac[WC_BLAKE2S_DIGEST_SIZE];
408+
byte data[] = {1, 2, 3};
409+
byte key[] = {4, 5, 6};
410+
ret = wc_Blake2sHmac(data, sizeof(data), key, sizeof(key), mac, sizeof(mac));
411+
if (ret != 0) {
412+
// error generating HMAC-BLAKE2s
413+
}
414+
\endcode
415+
*/
416+
int wc_Blake2sHmac(const byte * in, size_t in_len,
417+
const byte * key, size_t key_len,
418+
byte * out, size_t out_len);

0 commit comments

Comments
 (0)