idnits 2.17.1
draft-saarinen-blake2-01.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (February 1, 2015) is 3344 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
-- Looks like a reference, but probably isn't: '0' on line 358
-- Looks like a reference, but probably isn't: '1' on line 249
-- Looks like a reference, but probably isn't: '2' on line 250
-- Looks like a reference, but probably isn't: '3' on line 251
-- Looks like a reference, but probably isn't: '4' on line 252
-- Looks like a reference, but probably isn't: '5' on line 253
-- Looks like a reference, but probably isn't: '6' on line 254
-- Looks like a reference, but probably isn't: '7' on line 255
-- Looks like a reference, but probably isn't: '8' on line 256
-- Looks like a reference, but probably isn't: '9' on line 257
-- Looks like a reference, but probably isn't: '12' on line 300
-- Looks like a reference, but probably isn't: '13' on line 301
-- Looks like a reference, but probably isn't: '14' on line 304
== Unused Reference: 'RFC2119' is defined on line 473, but no explicit
reference was found in the text
Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 14 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Internet Engineering Task Force M-J. Saarinen, Ed.
3 Internet-Draft Independent Consultant
4 Intended status: Informational J-P. Aumasson
5 Expires: August 5, 2015 Kudelski Security
6 February 1, 2015
8 The BLAKE2 Cryptographic Hash and MAC
9 draft-saarinen-blake2-01
11 Abstract
13 This document describes the cryptographic hash function BLAKE2,
14 making the algorithm specification and C source code conveniently
15 available to the Internet community. BLAKE2 comes in two main
16 flavors: BLAKE2b is optimized for 64-bit platforms, and BLAKE2s for
17 smaller architectures. BLAKE2 can be directly keyed, making it
18 functionally equivalent to a Message Authentication Code (MAC).
20 Status of This Memo
22 This Internet-Draft is submitted in full conformance with the
23 provisions of BCP 78 and BCP 79.
25 Internet-Drafts are working documents of the Internet Engineering
26 Task Force (IETF). Note that other groups may also distribute
27 working documents as Internet-Drafts. The list of current Internet-
28 Drafts is at http://datatracker.ietf.org/drafts/current/.
30 Internet-Drafts are draft documents valid for a maximum of six months
31 and may be updated, replaced, or obsoleted by other documents at any
32 time. It is inappropriate to use Internet-Drafts as reference
33 material or to cite them other than as "work in progress."
35 This Internet-Draft will expire on August 5, 2015.
37 Copyright Notice
39 Copyright (c) 2015 IETF Trust and the persons identified as the
40 document authors. All rights reserved.
42 This document is subject to BCP 78 and the IETF Trust's Legal
43 Provisions Relating to IETF Documents
44 (http://trustee.ietf.org/license-info) in effect on the date of
45 publication of this document. Please review these documents
46 carefully, as they describe your rights and restrictions with respect
47 to this document. Code Components extracted from this document must
48 include Simplified BSD License text as described in Section 4.e of
49 the Trust Legal Provisions and are provided without warranty as
50 described in the Simplified BSD License.
52 Table of Contents
54 1. Introduction and Terminology . . . . . . . . . . . . . . . . 2
55 2. Conventions, Variables, and Constants . . . . . . . . . . . . 3
56 2.1. Parameters . . . . . . . . . . . . . . . . . . . . . . . 3
57 2.2. Other Constants and Variables . . . . . . . . . . . . . . 4
58 2.3. Arithmetic Notation . . . . . . . . . . . . . . . . . . . 4
59 2.4. Little-Endian Interpretation of Words as Byte Sequences . 4
60 2.5. Parameter Block . . . . . . . . . . . . . . . . . . . . . 5
61 2.6. Initialization Vector . . . . . . . . . . . . . . . . . . 5
62 2.7. Message Schedule SIGMA . . . . . . . . . . . . . . . . . 6
63 3. BLAKE2 Processing . . . . . . . . . . . . . . . . . . . . . . 6
64 3.1. Mixing Function G . . . . . . . . . . . . . . . . . . . . 6
65 3.2. Compression Function F . . . . . . . . . . . . . . . . . 6
66 3.3. Padding data and Computing a BLAKE2 Digest . . . . . . . 8
67 4. Standard Parameter Sets and Algorithm Identifiers . . . . . . 9
68 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10
69 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
70 7. Security Considerations . . . . . . . . . . . . . . . . . . . 10
71 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
72 8.1. Normative References . . . . . . . . . . . . . . . . . . 10
73 8.2. Informative References . . . . . . . . . . . . . . . . . 10
74 Appendix A. BLAKE2b Implementation C Source . . . . . . . . . . 11
75 A.1. blake2b.h . . . . . . . . . . . . . . . . . . . . . . . . 11
76 A.2. blake2b.c . . . . . . . . . . . . . . . . . . . . . . . . 12
77 Appendix B. BLAKE2s Implementation C Source . . . . . . . . . . 16
78 B.1. blake2s.h . . . . . . . . . . . . . . . . . . . . . . . . 16
79 B.2. blake2s.c . . . . . . . . . . . . . . . . . . . . . . . . 17
80 Appendix C. BLAKE2b and BLAKE2s Self Test Module C Source . . . 20
81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24
83 1. Introduction and Terminology
85 The [BLAKE2] cryptographic hash function was designed by Jean-
86 Philippe Aumasson, Samuel Neves, Zooko Wilcox-O'Hearn, and Christian
87 Winnerlein.
89 BLAKE2 comes in two basic flavors:
91 o BLAKE2b (or just BLAKE2) is optimized for 64-bit platforms and
92 produces digests of any size between 1 and 64 bytes.
94 o BLAKE2s is optimized for 8- to 32-bit platforms, and produces
95 digests of any size between 1 and 32 bytes.
97 Both BLAKE2b and BLAKE2s are believed to be highly secure and have
98 good performance on any platform, software or hardware. BLAKE2 does
99 not require a special "HMAC" construction for keyed message
100 authentication as they have a built-in keying mechanism.
102 The BLAKE2 hash function may be used by digital signature algorithms
103 and message authentication and integrity protection mechanisms in
104 applications such as Public Key Infrastructure (PKI), secure
105 communication protocols, cloud storage, intrusion detection, forensic
106 suites, and version control systems.
108 The BLAKE2 suite provides a more efficient alternative to US Secure
109 Hash Algorithms SHA and HMAC-SHA [RFC6234]. BLAKE2-128 is especially
110 suited as a fast and more secure plug-in replacement to MD5 and HMAC-
111 MD5 in legacy applications [RFC6151].
113 A reference implementation in C programming language for BLAKE2b can
114 be found in Appendix A and for BLAKE2s in Appendix B of this
115 document. These implementations SHOULD be validated with the Test
116 Module contained in Appendix C.
118 Due to space constraints, this document does not contain a full set
119 of test vectors for BLAKE2. We refer to [BLAKE2] for up to date
120 information about compliance testing and integrating BLAKE2 into
121 various applications.
123 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
124 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
125 document are to be interpreted as described in RFC 2119.
127 2. Conventions, Variables, and Constants
129 2.1. Parameters
131 The following table summarizes various parameters and their ranges:
133 | BLAKE2b | BLAKE2s |
134 --------------+------------------+------------------+
135 Bits in word | w = 64 | w = 32 |
136 Rounds in F | r = 12 | r = 10 |
137 Block bytes | bb = 128 | bb = 64 |
138 Hash bytes | 1 <= nn <= 64 | 1 <= nn <= 32 |
139 Key bytes | 0 <= kk <= 64 | 0 <= kk <= 32 |
140 Input bytes | 0 <= ll < 2**128 | 0 <= ll < 2**64 |
141 --------------+------------------+------------------+
142 G Rotation | (R1, R2, R3, R4) | (R1, R2, R3, R4) |
143 constants = | (32, 24, 16, 63) | (16, 12, 8, 7) |
144 --------------+------------------+------------------+
146 2.2. Other Constants and Variables
148 IV[0..7] Initialization Vector (constant).
150 SIGMA[0..9] Message word permutations (constant).
152 p[0..7] Parameter block (defines hash and key sizes).
154 m[0..15] Sixteen words of a single message block.
156 h[0..7] Internal state of the hash.
158 d[0..dd-1] Padded input blocks. "dd" is the number of blocks.
160 t Byte offset at the end of the current block.
162 f Flag indicating the last block.
164 2.3. Arithmetic Notation
166 For real-valued x we define:
168 floor(x) Floor, the largest integer <= x.
170 ceil(x) Ceiling, the smallest integer >= x.
172 frac(x) Positive fractional part of x, frac(x) = x - floor(x).
174 Operator notation in pseudocode:
176 2**n = 2 to the power "n". 2**0=1, 2**1=2, 2**2=4, 2**3=8, etc.
178 a ^ b = Bitwise exclusive-or operation between "a" and "b".
180 a mod b = Remainder "a" modulo "b", always in range [0, b-1].
182 x >> n = floor(x / 2**n). Logical shift "x" right by "n" bits.
184 x << n = (x * 2**n) mod (2**w). Logical shift "x" left by "n".
186 x >>> n = (x >> n) ^ (x << (w - n)). Rotate "x" right by "n" bits.
188 2.4. Little-Endian Interpretation of Words as Byte Sequences
190 All mathematical operations are on 64-bit words in BLAKE2b and on
191 32-bit words on BLAKE2b.
193 We may also perform operations on vectors of words. Vector indexing
194 is zero-based; the first element of an n-element vector "v" is v[0]
195 and the last one is v[n - 1]. All elements is denoted by v[0..n-1].
197 Byte (octet) streams are interpreted as words in little-endian order,
198 with the least significant byte first. Consider this sequence of
199 eight hexadecimal bytes:
201 x[0..7] = 0x01 0x23 0x45 0x67 0x89 0xAB 0xCD 0xEF
203 When interpreted as a 32-bit word from the beginning memory address,
204 x[0..3] has numerical value 0x67452301 or 1732584193.
206 When interpreted as a 64-bit word, bytes x[0..7] have numerical value
207 0xEFCDAB8967452301 or 17279655951921914625.
209 2.5. Parameter Block
211 We specify the parameter block words p[0..7] as follows:
213 byte offset: 3 2 1 0 (otherwise zero)
214 p[0] = 0x0101kknn p[1..7] = 0
216 Here the "nn" byte specifies the hash size in bytes. The second
217 (little-endian) byte of parameter block, "kk", specifies key size in
218 bytes. Set kk = 00 for for unkeyed hashing. Bytes 2 and 3 are set
219 as 01. All other bytes in the parameter block are set as zero.
221 NOTE. [BLAKE2] defines additional variants of BLAKE2 with features
222 such as salting, personalized hashes, and tree hashing. These
223 OPTIONAL features use fields in the parameter block which are not
224 defined in this document.
226 2.6. Initialization Vector
228 We define the Initialization Vector constant IV mathematically as:
230 IV[i] = floor(2**w * frac(sqrt(prime(i+1)))), where prime(i)
231 is the i:th prime number ( 2, 3, 5, 7, 11, 13, 17, 19 )
232 and sqrt(x) is the square root of x.
234 The numerical values of IV can be also found in implementations in
235 Appendix A and Appendix B for BLAkE2b and BLAKE2s, respectively.
237 NOTE. BLAKE2b IV is the same as SHA-512 IV and BLAKE2s IV is the
238 same as SHA-256 IV; see [RFC6234].
240 2.7. Message Schedule SIGMA
242 Message word schedule permutations for each round of both BLAKE2b and
243 BLAKE2s are defined by SIGMA. For BLAKE2b the two extra permutations
244 for rounds 10 and 11 are SIGMA[10..11] = SIGMA[0..1].
246 Round | 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
247 ----------+-------------------------------------------------+
248 SIGMA[0] | 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
249 SIGMA[1] | 14 10 4 8 9 15 13 6 1 12 0 2 11 7 5 3 |
250 SIGMA[2] | 11 8 12 0 5 2 15 13 10 14 3 6 7 1 9 4 |
251 SIGMA[3] | 7 9 3 1 13 12 11 14 2 6 5 10 4 0 15 8 |
252 SIGMA[4] | 9 0 5 7 2 4 10 15 14 1 11 12 6 8 3 13 |
253 SIGMA[5] | 2 12 6 10 0 11 8 3 4 13 7 5 15 14 1 9 |
254 SIGMA[6] | 12 5 1 15 14 13 4 10 0 7 6 3 9 2 8 11 |
255 SIGMA[7] | 13 11 7 14 12 1 3 9 5 0 15 4 8 6 2 10 |
256 SIGMA[8] | 6 15 14 9 11 3 0 8 12 2 13 7 1 4 10 5 |
257 SIGMA[9] | 10 2 8 4 7 6 1 5 15 11 9 14 3 12 13 0 |
258 ----------+-------------------------------------------------+
260 3. BLAKE2 Processing
262 3.1. Mixing Function G
264 The G primitive function mixes two input words "x" and "y" into four
265 words indexed by "a", "b", "c", and "d" in the working vector
266 v[0..15]. The full modified vector is returned. The rotation
267 constants (R1, R2, R3, R4) are given in Section 2.1.
269 FUNCTION G( v[0..15], a, b, c, d, x, y )
270 |
271 | v[a] := (v[a] + v[b] + x) mod 2**w
272 | v[d] := (v[d] ^ v[a]) >>> R1
273 | v[c] := (v[c] + v[d]) mod 2**w
274 | v[b] := (v[b] ^ v[c]) >>> R2
275 | v[a] := (v[a] + v[b] + y) mod 2**w
276 | v[d] := (v[d] ^ v[a]) >>> R3
277 | v[c] := (v[c] + v[d]) mod 2**w
278 | v[b] := (v[b] ^ v[c]) >>> R4
279 |
280 | RETURN v[0..15]
281 |
282 END FUNCTION.
284 3.2. Compression Function F
286 Compression function F takes as an argument the state vector "h",
287 zero-padded message block vector "m", 2w-bit offset counter "t", and
288 final block indicator flag "f". Local vector v[0..15] is used in
289 processing. F returns a new state vector.
291 The number of rounds "r" is 12 for BLAKE2b and 10 for BLAKE2s.
292 Rounds are numbered from 0 to r - 1.
294 FUNCTION F( h[0..7], m[0..15], t, f )
295 |
296 | // Initialize local work vector v[0..15]
297 | v[0..7] := h[0..7] // First half from state.
298 | v[8..15] := IV[0..7] // Second half from IV.
299 |
300 | v[12] := v[12] ^ (t mod 2**w) // Low word of the offset.
301 | v[13] := v[13] ^ (t >> w) // High word.
302 |
303 | IF f = TRUE THEN // last block flag?
304 | | v[14] := v[14] ^ 0xFF..FF // Invert all bits.
305 | END IF.
306 |
307 | // Cryptographic mixing
308 | FOR i = 0 TO r - 1 DO // Ten or twelve rounds.
309 | |
310 | | // Message word selection permutation for this round.
311 | | s[0..15] := SIGMA[i mod 10][0..15]
312 | |
313 | | v := G( v, 0, 4, 8, 12, m[s[ 0]], m[s[ 1]] )
314 | | v := G( v, 1, 5, 9, 13, m[s[ 2]], m[s[ 3]] )
315 | | v := G( v, 2, 6, 10, 14, m[s[ 4]], m[s[ 5]] )
316 | | v := G( v, 3, 7, 11, 15, m[s[ 6]], m[s[ 7]] )
317 | |
318 | | v := G( v, 0, 5, 10, 15, m[s[ 8]], m[s[ 9]] )
319 | | v := G( v, 1, 6, 11, 12, m[s[10]], m[s[11]] )
320 | | v := G( v, 2, 7, 8, 13, m[s[12]], m[s[13]] )
321 | | v := G( v, 3, 4, 9, 14, m[s[14]], m[s[15]] )
322 | |
323 | END FOR
324 |
325 | FOR i = 0 TO 7 DO
326 | | h[i] := v[i] ^ v[i + 8] // XOR the two halves.
327 | END FOR.
328 |
329 | RETURN h[0..7] // New state.
330 |
331 END FUNCTION.
333 3.3. Padding data and Computing a BLAKE2 Digest
335 We refer the reader to Appendix A and Appendix B for reference C
336 language implementations of BLAkE2b and BLAKE2s, respectively.
338 Key and data input is split and padded into "dd" message blocks
339 d[0..dd-1], each consisting of 16 words (or "bb" bytes).
341 If a secret key is used (kk > 0), it is padded with zero bytes and
342 set as d[0]. Otherwise d[0] is the first data block. The final data
343 block d[dd-1] is also padded with zero to "bb" bytes (16 words).
345 Number of blocks is therefore dd = ceil(kk / bb) + ceil(ll / bb).
346 However in special case of unkeyed empty message (kk = 0 and ll = 0),
347 we still set dd = 1 and d[0] consists of all zeros.
349 The following procedure for processes the padded data blocks into an
350 "nn"-byte final hash value. See Section 2 for description of various
351 variables and constants used.
353 FUNCTION BLAKE2( d[0..dd-1], ll, kk, nn )
354 |
355 | h[0..7] := IV[0..7] // Initialization Vector.
356 |
357 | // Parameter block p[0]
358 | h[0] := h[0] ^ 0x01010000 ^ (kk << 8) ^ nn
359 |
360 | // Process padded key and data blocks
361 | IF dd > 1 THEN
362 | | FOR i = 0 TO dd - 2 DO
363 | | | h := COMPRESS( h, d[i], (i + 1) * bb, FALSE )
364 | | END FOR.
365 | END IF.
366 |
367 | // Final block.
368 | IF kk = 0 THEN
369 | | h := COMPRESS( h, d[dd - 1], ll, TRUE )
370 | ELSE
371 | | h := COMPRESS( h, d[dd - 1], ll + bb, TRUE )
372 | END IF.
373 |
374 | RETURN first "nn" bytes from little-endian word array h[].
375 |
376 END FUNCTION.
378 4. Standard Parameter Sets and Algorithm Identifiers
380 An implementation of BLAKE2b and / or BLAKE2s SHOULD support the
381 following digest size parameters for interoperability (e.g. digital
382 signatures), as long as sufficient level of security is attained by
383 the parameter selections. These parameters and identifiers are
384 intended to be suitable as plug-in replacements to corresponding SHA
385 algorithms.
387 For unkeyed hashing, developers adapting BLAKE2 to ASN.1 - based
388 message formats SHOULD use the OID tree at x = 1.3.6.1.4.1.1722.12.2.
390 Algorithm | Target | Collision | Hash | Hash ASN.1 |
391 Identifier | Arch | Security | nn | OID Suffix |
392 ---------------+--------+-----------+------+------------+
393 id-blake2b160 | 64-bit | 2**80 | 20 | x.1.20 |
394 id-blake2b256 | 64-bit | 2**128 | 32 | x.1.32 |
395 id-blake2b384 | 64-bit | 2**192 | 48 | x.1.48 |
396 id-blake2b512 | 64-bit | 2**256 | 64 | x.1.64 |
397 ---------------+--------+-----------+------+------------+
398 id-blake2s128 | 32-bit | 2**64 | 16 | x.2.16 |
399 id-blake2s160 | 32-bit | 2**80 | 20 | x.2.20 |
400 id-blake2s224 | 32-bit | 2**112 | 28 | x.2.28 |
401 id-blake2s256 | 32-bit | 2**128 | 32 | x.2.32 |
402 ---------------+--------+-----------+------+------------+
404 hashAlgs OBJECT IDENTIFIER ::= {
405 iso(1) identified-organization(3) dod(6) internet(1)
406 private(4) enterprise(1) kudelski(1722) cryptography(12) 2
407 }
409 -- the two BLAKE2 variants --
410 blake2b OBJECT IDENTIFIER ::= { hashAlgs 1 }
411 blake2s OBJECT IDENTIFIER ::= { hashAlgs 2 }
413 -- BLAKE2b Identifiers --
414 id-blake2b160 OBJECT IDENTIFIER ::= { blake2b 20 }
415 id-blake2b256 OBJECT IDENTIFIER ::= { blake2b 32 }
416 id-blake2b384 OBJECT IDENTIFIER ::= { blake2b 48 }
417 id-blake2b512 OBJECT IDENTIFIER ::= { blake2b 64 }
419 -- BLAKE2s Identifiers --
420 id-blake2s128 OBJECT IDENTIFIER ::= { blake2s 16 }
421 id-blake2s160 OBJECT IDENTIFIER ::= { blake2s 20 }
422 id-blake2s224 OBJECT IDENTIFIER ::= { blake2s 28 }
423 id-blake2s256 OBJECT IDENTIFIER ::= { blake2s 32 }
425 5. Acknowledgements
427 The editor wishes to thank the [BLAKE2] team for their encouragement:
428 Jean-Philippe Aumasson, Samuel Neves, Zooko Wilcox-O'Hearn, and
429 Christian Winnerlein. We have borrowed passages from [BLAKE] and
430 [BLAKE2] with permission.
432 BLAKE2 is based on the SHA-3 proposal [BLAKE], designed by Jean-
433 Philippe Aumasson, Luca Henzen, Willi Meier, and Raphael C.-W. Phan.
434 BLAKE2, like BLAKE, relies on a core algorithm borrowed from the
435 ChaCha stream cipher, designed by Daniel J. Bernstein.
437 6. IANA Considerations
439 This memo includes no request to IANA.
441 7. Security Considerations
443 This document is intended to provide convenient open source access by
444 the Internet community to the BLAKE2 cryptographic hash algorithm.
445 We wish to make no independent assertion to its security in this
446 document. We refer the reader to [BLAKE] and [BLAKE2] for detailed
447 cryptanalytic rationale behind its design.
449 In order to avoid bloat, the reference implementations in Appendix A
450 and Appendix B may not erase all sensitive data (such as secret keys)
451 immediately from process memory after use. Such cleanups can be
452 added if needed.
454 8. References
456 8.1. Normative References
458 [BLAKE2] Aumasson, J-P., Neves, S., Wilcox-O'Hearn, Z., and C.
459 Winnerlein, "BLAKE2: simpler, smaller, fast as MD5",
460 January 2013, .
462 8.2. Informative References
464 [BLAKE] Aumasson, J-P., Meier, W., Phan, R., and L. Henzen, "The
465 Hash Function BLAKE", February 2015, .
468 [FIPS140-2IG]
469 NIST, US., "Implementation Guidance for FIPS PUB 140-2 and
470 the Cryptographic Module Validation Program", January
471 2015.
473 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
474 Requirement Levels", RFC 2119, BCP 14, March 1997.
476 [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations
477 for the MD5 Message-Digest and the HMAC-MD5 Algorithms",
478 RFC 6151, March 2011.
480 [RFC6234] Eastlake, D. and T. Hansen, "US Secure Hash Algorithms
481 (SHA and SHA-based HMAC and HKDF)", RFC 6234, May 2011.
483 Appendix A. BLAKE2b Implementation C Source
485 A.1. blake2b.h
487
489 // blake2b.h
490 // BLAKE2b Hashing Context and API Prototypes
492 #ifndef BLAKE2B_H
493 #define BLAKE2B_H
495 #include
496 #include
498 // state context
499 typedef struct {
500 uint8_t b[128]; // input buffer
501 uint64_t h[8]; // chained state
502 uint64_t t[2]; // total number of bytes
503 size_t c; // pointer for b[]
504 size_t outlen; // digest size
505 } blake2b_ctx;
507 // Initialize the hashing context "ctx" with optional key "key".
508 // 1 <= outlen <= 64 gives the digest size in bytes.
509 // Secret key (also <= 64 bytes) is optional (keylen = 0).
510 int blake2b_init(blake2b_ctx *ctx, size_t outlen,
511 const void *key, size_t keylen); // secret key
513 // Add "inlen" bytes from "in" into the hash.
514 void blake2b_update(blake2b_ctx *ctx, // context
515 const void *in, size_t inlen); // data to be hashed
517 // Generate the message digest (size given in init).
518 // Result placed in "out"
519 void blake2b_final(blake2b_ctx *ctx, void *out);
520 // All-in-one convenience function.
521 int blake2b(void *out, size_t outlen, // return buffer for digest
522 const void *key, size_t keylen, // optional secret key
523 const void *in, size_t inlen); // data to be hashed
525 #endif
527
529 A.2. blake2b.c
531
533 // blake2b.c
534 // A simple BLAKE2b Reference Implementation
536 #include "blake2b.h"
538 // cyclic right rotation
540 #ifndef ROTR64
541 #define ROTR64(x, y) (((x) >> (y)) ^ ((x) << (64 - (y))))
542 #endif
544 // little-endian byte access
546 #define B2B_GET64(p) \
547 (((uint64_t) ((uint8_t *) (p))[0]) ^ \
548 (((uint64_t) ((uint8_t *) (p))[1]) << 8) ^ \
549 (((uint64_t) ((uint8_t *) (p))[2]) << 16) ^ \
550 (((uint64_t) ((uint8_t *) (p))[3]) << 24) ^ \
551 (((uint64_t) ((uint8_t *) (p))[4]) << 32) ^ \
552 (((uint64_t) ((uint8_t *) (p))[5]) << 40) ^ \
553 (((uint64_t) ((uint8_t *) (p))[6]) << 48) ^ \
554 (((uint64_t) ((uint8_t *) (p))[7]) << 56))
556 // G Mixing function
558 #define B2B_G(a, b, c, d, x, y) { \
559 v[a] = v[a] + v[b] + x; \
560 v[d] = ROTR64(v[d] ^ v[a], 32); \
561 v[c] = v[c] + v[d]; \
562 v[b] = ROTR64(v[b] ^ v[c], 24); \
563 v[a] = v[a] + v[b] + y; \
564 v[d] = ROTR64(v[d] ^ v[a], 16); \
565 v[c] = v[c] + v[d]; \
566 v[b] = ROTR64(v[b] ^ v[c], 63); }
568 // Initialization Vector
570 static const uint64_t blake2b_iv[8] = {
571 0x6A09E667F3BCC908, 0xBB67AE8584CAA73B,
572 0x3C6EF372FE94F82B, 0xA54FF53A5F1D36F1,
573 0x510E527FADE682D1, 0x9B05688C2B3E6C1F,
574 0x1F83D9ABFB41BD6B, 0x5BE0CD19137E2179
575 };
577 // Compression function. "last" flag indicates last block.
579 static void blake2b_compress(blake2b_ctx *ctx, int last)
580 {
581 const uint8_t sigma[12][16] = {
582 { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 },
583 { 14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3 },
584 { 11, 8, 12, 0, 5, 2, 15, 13, 10, 14, 3, 6, 7, 1, 9, 4 },
585 { 7, 9, 3, 1, 13, 12, 11, 14, 2, 6, 5, 10, 4, 0, 15, 8 },
586 { 9, 0, 5, 7, 2, 4, 10, 15, 14, 1, 11, 12, 6, 8, 3, 13 },
587 { 2, 12, 6, 10, 0, 11, 8, 3, 4, 13, 7, 5, 15, 14, 1, 9 },
588 { 12, 5, 1, 15, 14, 13, 4, 10, 0, 7, 6, 3, 9, 2, 8, 11 },
589 { 13, 11, 7, 14, 12, 1, 3, 9, 5, 0, 15, 4, 8, 6, 2, 10 },
590 { 6, 15, 14, 9, 11, 3, 0, 8, 12, 2, 13, 7, 1, 4, 10, 5 },
591 { 10, 2, 8, 4, 7, 6, 1, 5, 15, 11, 9, 14, 3, 12, 13, 0 },
592 { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 },
593 { 14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3 }
594 };
595 int i;
596 uint64_t v[16], m[16];
598 for (i = 0; i < 8; i++) { // init work variables
599 v[i] = ctx->h[i];
600 v[i + 8] = blake2b_iv[i];
601 }
603 v[12] ^= ctx->t[0]; // low 64 bits of offset
604 v[13] ^= ctx->t[1]; // high 64 bits
605 if (last) // last block flag set ?
606 v[14] = ~v[14];
608 for (i = 0; i < 16; i++) // get little-endian words
609 m[i] = B2B_GET64(&ctx->b[8 * i]);
611 for (i = 0; i < 12; i++) { // twelve rounds
612 B2B_G( 0, 4, 8, 12, m[sigma[i][ 0]], m[sigma[i][ 1]]);
613 B2B_G( 1, 5, 9, 13, m[sigma[i][ 2]], m[sigma[i][ 3]]);
614 B2B_G( 2, 6, 10, 14, m[sigma[i][ 4]], m[sigma[i][ 5]]);
615 B2B_G( 3, 7, 11, 15, m[sigma[i][ 6]], m[sigma[i][ 7]]);
616 B2B_G( 0, 5, 10, 15, m[sigma[i][ 8]], m[sigma[i][ 9]]);
617 B2B_G( 1, 6, 11, 12, m[sigma[i][10]], m[sigma[i][11]]);
618 B2B_G( 2, 7, 8, 13, m[sigma[i][12]], m[sigma[i][13]]);
619 B2B_G( 3, 4, 9, 14, m[sigma[i][14]], m[sigma[i][15]]);
620 }
622 for( i = 0; i < 8; ++i )
623 ctx->h[i] ^= v[i] ^ v[i + 8];
624 }
626 // Initialize the state. key is optional
628 int blake2b_init(blake2b_ctx *ctx, size_t outlen,
629 const void *key, size_t keylen) // (keylen=0: no key)
630 {
631 size_t i;
633 if (outlen == 0 || outlen > 64 || keylen > 64)
634 return -1; // illegal parameters
636 for (i = 0; i < 8; i++) // state, "param block"
637 ctx->h[i] = blake2b_iv[i];
638 ctx->h[0] ^= 0x01010000 ^ (keylen << 8) ^ outlen;
640 ctx->t[0] = 0; // input count low word
641 ctx->t[1] = 0; // input count high word
642 ctx->c = 0; // pointer within buffer
643 ctx->outlen = outlen;
645 for (i = keylen; i < 128; i++) // zero input block
646 ctx->b[i] = 0;
647 if (keylen > 0) {
648 blake2b_update(ctx, key, keylen);
649 ctx->c = 128; // at the end
650 }
652 return 0;
653 }
655 // update with new data
657 void blake2b_update(blake2b_ctx *ctx,
658 const void *in, size_t inlen) // data bytes
659 {
660 size_t i;
662 for (i = 0; i < inlen; i++) {
663 if (ctx->c == 128) { // buffer full ?
664 ctx->t[0] += ctx->c; // add counters
665 if (ctx->t[0] < ctx->c) // carry overflow ?
666 ctx->t[1]++; // high word
667 blake2b_compress(ctx, 0); // compress (not last)
668 ctx->c = 0; // counter to zero
669 }
670 ctx->b[ctx->c++] = ((const uint8_t *) in)[i];
671 }
672 }
674 // finalize
676 void blake2b_final(blake2b_ctx *ctx, void *out)
677 {
678 size_t i;
680 ctx->t[0] += ctx->c; // mark last block offset
681 if (ctx->t[0] < ctx->c) // carry overflow
682 ctx->t[1]++; // high word
684 while (ctx->c < 128) // fill up with zeros
685 ctx->b[ctx->c++] = 0;
686 blake2b_compress(ctx, 1); // final block flag = 1
688 // little endian convert and store
689 for (i = 0; i < ctx->outlen; i++) {
690 ((uint8_t *) out)[i] =
691 (ctx->h[i >> 3] >> (8 * (i & 7))) & 0xFF;
692 }
693 }
695 // convenience function for all-in-one computation
697 int blake2b(void *out, size_t outlen,
698 const void *key, size_t keylen,
699 const void *in, size_t inlen)
700 {
701 blake2b_ctx ctx;
703 if (blake2b_init(&ctx, outlen, key, keylen))
704 return -1;
705 blake2b_update(&ctx, in, inlen);
706 blake2b_final(&ctx, out);
708 return 0;
709 }
710
712 Appendix B. BLAKE2s Implementation C Source
714 B.1. blake2s.h
716
718 // blake2s.h
719 // BLAKE2s Hashing Context and API Prototypes
721 #ifndef BLAKE2S_H
722 #define BLAKE2S_H
724 #include
725 #include
727 // state context
728 typedef struct {
729 uint8_t b[64]; // input buffer
730 uint32_t h[8]; // chained state
731 uint32_t t[2]; // total number of bytes
732 size_t c; // pointer for b[]
733 size_t outlen; // digest size
734 } blake2s_ctx;
736 // Initialize the hashing context "ctx" with optional key "key".
737 // 1 <= outlen <= 32 gives the digest size in bytes.
738 // Secret key (also <= 32 bytes) is optional (keylen = 0).
739 int blake2s_init(blake2s_ctx *ctx, size_t outlen,
740 const void *key, size_t keylen); // secret key
742 // Add "inlen" bytes from "in" into the hash.
743 void blake2s_update(blake2s_ctx *ctx, // context
744 const void *in, size_t inlen); // data to be hashed
746 // Generate the message digest (size given in init).
747 // Result placed in "out"
748 void blake2s_final(blake2s_ctx *ctx, void *out);
750 // All-in-one convenience function.
751 int blake2s(void *out, size_t outlen, // return buffer for digest
752 const void *key, size_t keylen, // optional secret key
753 const void *in, size_t inlen); // data to be hashed
755 #endif
757
759 B.2. blake2s.c
761
763 // blake2s.c
764 // A simple BLAKE2 Reference Implementation
766 #include "blake2s.h"
768 // cyclic right rotation
770 #ifndef ROTR32
771 #define ROTR32(x, y) (((x) >> (y)) ^ ((x) << (32 - (y))))
772 #endif
774 // little-endian byte access
775 #define B2S_GET32(p) \
776 (((uint32_t) ((uint8_t *) (p))[0]) ^ \
777 (((uint32_t) ((uint8_t *) (p))[1]) << 8) ^ \
778 (((uint32_t) ((uint8_t *) (p))[2]) << 16) ^ \
779 (((uint32_t) ((uint8_t *) (p))[3]) << 24))
781 // Mixing function G
782 #define B2S_G(a, b, c, d, x, y) { \
783 v[a] = v[a] + v[b] + x; \
784 v[d] = ROTR32(v[d] ^ v[a], 16); \
785 v[c] = v[c] + v[d]; \
786 v[b] = ROTR32(v[b] ^ v[c], 12); \
787 v[a] = v[a] + v[b] + y; \
788 v[d] = ROTR32(v[d] ^ v[a], 8); \
789 v[c] = v[c] + v[d]; \
790 v[b] = ROTR32(v[b] ^ v[c], 7); }
792 // Initialization Vector
794 static const uint32_t blake2s_iv[8] =
795 {
796 0x6A09E667, 0xBB67AE85, 0x3C6EF372, 0xA54FF53A,
797 0x510E527F, 0x9B05688C, 0x1F83D9AB, 0x5BE0CD19
798 };
800 // Compression function. "last" flag indicates last block.
802 static void blake2s_compress(blake2s_ctx *ctx, int last)
803 {
804 const uint8_t sigma[10][16] = {
805 { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 },
806 { 14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3 },
807 { 11, 8, 12, 0, 5, 2, 15, 13, 10, 14, 3, 6, 7, 1, 9, 4 },
808 { 7, 9, 3, 1, 13, 12, 11, 14, 2, 6, 5, 10, 4, 0, 15, 8 },
809 { 9, 0, 5, 7, 2, 4, 10, 15, 14, 1, 11, 12, 6, 8, 3, 13 },
810 { 2, 12, 6, 10, 0, 11, 8, 3, 4, 13, 7, 5, 15, 14, 1, 9 },
811 { 12, 5, 1, 15, 14, 13, 4, 10, 0, 7, 6, 3, 9, 2, 8, 11 },
812 { 13, 11, 7, 14, 12, 1, 3, 9, 5, 0, 15, 4, 8, 6, 2, 10 },
813 { 6, 15, 14, 9, 11, 3, 0, 8, 12, 2, 13, 7, 1, 4, 10, 5 },
814 { 10, 2, 8, 4, 7, 6, 1, 5, 15, 11, 9, 14, 3, 12, 13, 0 }
815 };
816 int i;
817 uint32_t v[16], m[16];
819 for (i = 0; i < 8; i++) { // init work variables
820 v[i] = ctx->h[i];
821 v[i + 8] = blake2s_iv[i];
822 }
824 v[12] ^= ctx->t[0]; // low 32 bits of offset
825 v[13] ^= ctx->t[1]; // high 32 bits
826 if (last) // last block flag set ?
827 v[14] = ~v[14];
829 for (i = 0; i < 16; i++) // get little-endian words
830 m[i] = B2S_GET32(&ctx->b[4 * i]);
832 for (i = 0; i < 10; i++) { // ten rounds
833 B2S_G( 0, 4, 8, 12, m[sigma[i][ 0]], m[sigma[i][ 1]]);
834 B2S_G( 1, 5, 9, 13, m[sigma[i][ 2]], m[sigma[i][ 3]]);
835 B2S_G( 2, 6, 10, 14, m[sigma[i][ 4]], m[sigma[i][ 5]]);
836 B2S_G( 3, 7, 11, 15, m[sigma[i][ 6]], m[sigma[i][ 7]]);
837 B2S_G( 0, 5, 10, 15, m[sigma[i][ 8]], m[sigma[i][ 9]]);
838 B2S_G( 1, 6, 11, 12, m[sigma[i][10]], m[sigma[i][11]]);
839 B2S_G( 2, 7, 8, 13, m[sigma[i][12]], m[sigma[i][13]]);
840 B2S_G( 3, 4, 9, 14, m[sigma[i][14]], m[sigma[i][15]]);
841 }
843 for( i = 0; i < 8; ++i )
844 ctx->h[i] ^= v[i] ^ v[i + 8];
845 }
847 // Initialize the state. key is optional
849 int blake2s_init(blake2s_ctx *ctx, size_t outlen,
850 const void *key, size_t keylen) // (keylen=0: no key)
851 {
852 size_t i;
854 if (outlen == 0 || outlen > 32 || keylen > 32)
855 return -1; // illegal parameters
857 for (i = 0; i < 8; i++) // state, "param block"
858 ctx->h[i] = blake2s_iv[i];
859 ctx->h[0] ^= 0x01010000 ^ (keylen << 8) ^ outlen;
861 ctx->t[0] = 0; // input count low word
862 ctx->t[1] = 0; // input count high word
863 ctx->c = 0; // pointer within buffer
864 ctx->outlen = outlen;
866 for (i = keylen; i < 64; i++) // zero input block
867 ctx->b[i] = 0;
868 if (keylen > 0) {
869 blake2s_update(ctx, key, keylen);
870 ctx->c = 64; // at the end
871 }
873 return 0;
874 }
876 // update with new data
878 void blake2s_update(blake2s_ctx *ctx,
879 const void *in, size_t inlen) // data bytes
880 {
881 size_t i;
883 for (i = 0; i < inlen; i++) {
884 if (ctx->c == 64) { // buffer full ?
885 ctx->t[0] += ctx->c; // add counters
886 if (ctx->t[0] < ctx->c) // carry overflow ?
887 ctx->t[1]++; // high word
888 blake2s_compress(ctx, 0); // compress (not last)
889 ctx->c = 0; // counter to zero
890 }
891 ctx->b[ctx->c++] = ((const uint8_t *) in)[i];
892 }
893 }
895 // finalize
897 void blake2s_final(blake2s_ctx *ctx, void *out)
898 {
899 size_t i;
901 ctx->t[0] += ctx->c; // mark last block offset
902 if (ctx->t[0] < ctx->c) // carry overflow
903 ctx->t[1]++; // high word
905 while (ctx->c < 64) // fill up with zeros
906 ctx->b[ctx->c++] = 0;
907 blake2s_compress(ctx, 1); // final block flag = 1
909 // little endian convert and store
910 for (i = 0; i < ctx->outlen; i++) {
911 ((uint8_t *) out)[i] =
912 (ctx->h[i >> 2] >> (8 * (i & 3))) & 0xFF;
913 }
914 }
916 // convenience function for all-in-one computation
918 int blake2s(void *out, size_t outlen,
919 const void *key, size_t keylen,
920 const void *in, size_t inlen)
921 {
922 blake2s_ctx ctx;
924 if (blake2s_init(&ctx, outlen, key, keylen))
925 return -1;
926 blake2s_update(&ctx, in, inlen);
927 blake2s_final(&ctx, out);
929 return 0;
930 }
932
934 Appendix C. BLAKE2b and BLAKE2s Self Test Module C Source
936 This module computes a series of keyed and unkeyed hashes from
937 deterministically generated pseudo-random data, and computes a hash
938 over those results. This is fairly a exhaustive, yet compact and
939 fast method for verifying that the hashing module is functioning
940 correctly.
942 Such testing is recommended especially when compiling the
943 implementation for a new a target platform configuration.
944 Furthermore, some security standards such as FIPS-140 may require a
945 Power-On Self Test (POST) to be performed every time the
946 cryptographic module is loaded [FIPS140-2IG].
948
950 // test_main.c
951 // Self test Modules for BLAKE2b and BLAKE2s -- and a stub main().
953 #include
955 #include "blake2b.h"
956 #include "blake2s.h"
958 // Deterministic sequences (Fibonacci generator)
960 static void selftest_seq(uint8_t *out, size_t len, uint32_t seed)
961 {
962 size_t i;
963 uint32_t t, a , b;
965 a = 0xDEAD4BAD * seed; // prime
966 b = 1;
968 for (i = 0; i < len; i++) { // fill the buf
969 t = a + b;
970 a = b;
971 b = t;
972 out[i] = (t >> 24) & 0xFF;
973 }
974 }
976 // BLAKE2b self-test validation. Return 0 when OK.
978 int blake2b_selftest()
979 {
980 // grand hash of hash results
981 const uint8_t blake2b_res[32] = {
982 0xC2, 0x3A, 0x78, 0x00, 0xD9, 0x81, 0x23, 0xBD,
983 0x10, 0xF5, 0x06, 0xC6, 0x1E, 0x29, 0xDA, 0x56,
984 0x03, 0xD7, 0x63, 0xB8, 0xBB, 0xAD, 0x2E, 0x73,
985 0x7F, 0x5E, 0x76, 0x5A, 0x7B, 0xCC, 0xD4, 0x75
986 };
987 // parameter sets
988 const size_t b2b_md_len[4] = { 20, 32, 48, 64 };
989 const size_t b2b_in_len[6] = { 0, 3, 128, 129, 255, 1024 };
991 size_t i, j, outlen, inlen;
992 uint8_t in[1024], md[64], key[64];
993 blake2b_ctx ctx;
995 // 256-bit hash for testing
996 if (blake2b_init(&ctx, 32, NULL, 0))
997 return -1;
999 for (i = 0; i < 4; i++) {
1000 outlen = b2b_md_len[i];
1001 for (j = 0; j < 6; j++) {
1002 inlen = b2b_in_len[j];
1004 selftest_seq(in, inlen, inlen); // unkeyed hash
1005 blake2b(md, outlen, NULL, 0, in, inlen);
1006 blake2b_update(&ctx, md, outlen); // hash the hash
1008 selftest_seq(key, outlen, outlen); // keyed hash
1009 blake2b(md, outlen, key, outlen, in, inlen);
1010 blake2b_update(&ctx, md, outlen); // hash the hash
1011 }
1012 }
1014 // compute and compare the hash of hashes
1015 blake2b_final(&ctx, md);
1016 for (i = 0; i < 32; i++) {
1017 if (md[i] != blake2b_res[i])
1018 return -1;
1019 }
1021 return 0;
1022 }
1024 // BLAKE2s self-test validation. Return 0 when OK.
1026 int blake2s_selftest()
1027 {
1028 // grand hash of hash results
1029 const uint8_t blake2s_res[32] = {
1030 0x6A, 0x41, 0x1F, 0x08, 0xCE, 0x25, 0xAD, 0xCD,
1031 0xFB, 0x02, 0xAB, 0xA6, 0x41, 0x45, 0x1C, 0xEC,
1032 0x53, 0xC5, 0x98, 0xB2, 0x4F, 0x4F, 0xC7, 0x87,
1033 0xFB, 0xDC, 0x88, 0x79, 0x7F, 0x4C, 0x1D, 0xFE
1034 };
1035 // parameter sets
1036 const size_t b2s_md_len[4] = { 16, 20, 28, 32 };
1037 const size_t b2s_in_len[6] = { 0, 3, 64, 65, 255, 1024 };
1039 size_t i, j, outlen, inlen;
1040 uint8_t in[1024], md[32], key[32];
1041 blake2s_ctx ctx;
1043 // 256-bit hash for testing
1044 if (blake2s_init(&ctx, 32, NULL, 0))
1045 return -1;
1047 for (i = 0; i < 4; i++) {
1048 outlen = b2s_md_len[i];
1049 for (j = 0; j < 6; j++) {
1050 inlen = b2s_in_len[j];
1052 selftest_seq(in, inlen, inlen); // unkeyed hash
1053 blake2s(md, outlen, NULL, 0, in, inlen);
1054 blake2s_update(&ctx, md, outlen); // hash the hash
1056 selftest_seq(key, outlen, outlen); // keyed hash
1057 blake2s(md, outlen, key, outlen, in, inlen);
1058 blake2s_update(&ctx, md, outlen); // hash the hash
1059 }
1060 }
1062 // compute and compare the hash of hashes
1063 blake2s_final(&ctx, md);
1064 for (i = 0; i < 32; i++) {
1065 if (md[i] != blake2s_res[i])
1066 return -1;
1067 }
1069 return 0;
1070 }
1072 // test driver
1074 int main(int argc, char **argv)
1075 {
1076 printf("blake2b_selftest() = %s\n",
1077 blake2b_selftest() ? "FAIL" : "OK");
1078 printf("blake2s_selftest() = %s\n",
1079 blake2s_selftest() ? "FAIL" : "OK");
1081 return 0;
1082 }
1084
1086 Authors' Addresses
1088 Markku-Juhani O. Saarinen (editor)
1089 Independent Consultant
1091 Email: mjos@iki.fi
1092 URI: https://mjos.fi
1094 Jean-Philippe Aumasson
1095 Kudelski Security
1096 22-24, Route de Geneve
1097 Case Postale 134
1098 Cheseaux 1033
1099 Switzerland
1101 Email: jean-philippe.aumasson@nagra.com
1102 URI: https://www.kudelskisecurity.com