idnits 2.17.1 draft-saarinen-blake2-04.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 (June 17, 2015) is 3234 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '0' on line 359 -- 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 301 -- Looks like a reference, but probably isn't: '13' on line 302 -- Looks like a reference, but probably isn't: '14' on line 305 Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 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: December 19, 2015 Kudelski Security 6 June 17, 2015 8 The BLAKE2 Cryptographic Hash and MAC 9 draft-saarinen-blake2-04 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 December 19, 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 . . . . . . . . . . . . . . . . . . . . . . . . 16 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]. BLAKE2s-128 is 110 especially suited as a fast and more secure drop-in replacement to 111 MD5 and HMAC-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 [RFC2119]. 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 BLAKE2s. 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 message block vector "m" (last block is padded with zeros to full 288 block size, if required), 2w-bit offset counter "t", and final block 289 indicator flag "f". Local vector v[0..15] is used in processing. F 290 returns a new state vector. 292 The number of rounds "r" is 12 for BLAKE2b and 10 for BLAKE2s. 293 Rounds are numbered from 0 to r - 1. 295 FUNCTION F( h[0..7], m[0..15], t, f ) 296 | 297 | // Initialize local work vector v[0..15] 298 | v[0..7] := h[0..7] // First half from state. 299 | v[8..15] := IV[0..7] // Second half from IV. 300 | 301 | v[12] := v[12] ^ (t mod 2**w) // Low word of the offset. 302 | v[13] := v[13] ^ (t >> w) // High word. 303 | 304 | IF f = TRUE THEN // last block flag? 305 | | v[14] := v[14] ^ 0xFF..FF // Invert all bits. 306 | END IF. 307 | 308 | // Cryptographic mixing 309 | FOR i = 0 TO r - 1 DO // Ten or twelve rounds. 310 | | 311 | | // Message word selection permutation for this round. 312 | | s[0..15] := SIGMA[i mod 10][0..15] 313 | | 314 | | v := G( v, 0, 4, 8, 12, m[s[ 0]], m[s[ 1]] ) 315 | | v := G( v, 1, 5, 9, 13, m[s[ 2]], m[s[ 3]] ) 316 | | v := G( v, 2, 6, 10, 14, m[s[ 4]], m[s[ 5]] ) 317 | | v := G( v, 3, 7, 11, 15, m[s[ 6]], m[s[ 7]] ) 318 | | 319 | | v := G( v, 0, 5, 10, 15, m[s[ 8]], m[s[ 9]] ) 320 | | v := G( v, 1, 6, 11, 12, m[s[10]], m[s[11]] ) 321 | | v := G( v, 2, 7, 8, 13, m[s[12]], m[s[13]] ) 322 | | v := G( v, 3, 4, 9, 14, m[s[14]], m[s[15]] ) 323 | | 324 | END FOR 325 | 326 | FOR i = 0 TO 7 DO // XOR the two halves. 327 | | h[i] := h[i] ^ v[i] ^ v[i + 8] 328 | END FOR. 329 | 330 | RETURN h[0..7] // New state. 331 | 332 END FUNCTION. 334 3.3. Padding data and Computing a BLAKE2 Digest 336 We refer the reader to Appendix A and Appendix B for reference C 337 language implementations of BLAkE2b and BLAKE2s, respectively. 339 Key and data input is split and padded into "dd" message blocks 340 d[0..dd-1], each consisting of 16 words (or "bb" bytes). 342 If a secret key is used (kk > 0), it is padded with zero bytes and 343 set as d[0]. Otherwise d[0] is the first data block. The final data 344 block d[dd-1] is also padded with zero to "bb" bytes (16 words). 346 Number of blocks is therefore dd = ceil(kk / bb) + ceil(ll / bb). 347 However in special case of unkeyed empty message (kk = 0 and ll = 0), 348 we still set dd = 1 and d[0] consists of all zeros. 350 The following procedure for processes the padded data blocks into an 351 "nn"-byte final hash value. See Section 2 for description of various 352 variables and constants used. 354 FUNCTION BLAKE2( d[0..dd-1], ll, kk, nn ) 355 | 356 | h[0..7] := IV[0..7] // Initialization Vector. 357 | 358 | // Parameter block p[0] 359 | h[0] := h[0] ^ 0x01010000 ^ (kk << 8) ^ nn 360 | 361 | // Process padded key and data blocks 362 | IF dd > 1 THEN 363 | | FOR i = 0 TO dd - 2 DO 364 | | | h := COMPRESS( h, d[i], (i + 1) * bb, FALSE ) 365 | | END FOR. 366 | END IF. 367 | 368 | // Final block. 369 | IF kk = 0 THEN 370 | | h := COMPRESS( h, d[dd - 1], ll, TRUE ) 371 | ELSE 372 | | h := COMPRESS( h, d[dd - 1], ll + bb, TRUE ) 373 | END IF. 374 | 375 | RETURN first "nn" bytes from little-endian word array h[]. 376 | 377 END FUNCTION. 379 4. Standard Parameter Sets and Algorithm Identifiers 381 An implementation of BLAKE2b and / or BLAKE2s SHOULD support the 382 following digest size parameters for interoperability (e.g. digital 383 signatures), as long as sufficient level of security is attained by 384 the parameter selections. These parameters and identifiers are 385 intended to be suitable as drop-in replacements to corresponding SHA 386 algorithms. 388 For unkeyed hashing, developers adapting BLAKE2 to ASN.1-based 389 message formats SHOULD use the OID tree at x = 1.3.6.1.4.1.1722.12.2. 391 Algorithm | Target | Collision | Hash | Hash ASN.1 | 392 Identifier | Arch | Security | nn | OID Suffix | 393 ---------------+--------+-----------+------+------------+ 394 id-blake2b160 | 64-bit | 2**80 | 20 | x.1.5 | 395 id-blake2b256 | 64-bit | 2**128 | 32 | x.1.8 | 396 id-blake2b384 | 64-bit | 2**192 | 48 | x.1.12 | 397 id-blake2b512 | 64-bit | 2**256 | 64 | x.1.16 | 398 ---------------+--------+-----------+------+------------+ 399 id-blake2s128 | 32-bit | 2**64 | 16 | x.2.4 | 400 id-blake2s160 | 32-bit | 2**80 | 20 | x.2.5 | 401 id-blake2s224 | 32-bit | 2**112 | 28 | x.2.7 | 402 id-blake2s256 | 32-bit | 2**128 | 32 | x.2.8 | 403 ---------------+--------+-----------+------+------------+ 405 hashAlgs OBJECT IDENTIFIER ::= { 406 iso(1) identified-organization(3) dod(6) internet(1) 407 private(4) enterprise(1) kudelski(1722) cryptography(12) 2 408 } 410 -- the two BLAKE2 variants -- 411 blake2b OBJECT IDENTIFIER ::= { hashAlgs 1 } 412 blake2s OBJECT IDENTIFIER ::= { hashAlgs 2 } 414 -- BLAKE2b Identifiers -- 415 id-blake2b160 OBJECT IDENTIFIER ::= { blake2b 5 } 416 id-blake2b256 OBJECT IDENTIFIER ::= { blake2b 8 } 417 id-blake2b384 OBJECT IDENTIFIER ::= { blake2b 12 } 418 id-blake2b512 OBJECT IDENTIFIER ::= { blake2b 16 } 420 -- BLAKE2s Identifiers -- 421 id-blake2s128 OBJECT IDENTIFIER ::= { blake2s 4 } 422 id-blake2s160 OBJECT IDENTIFIER ::= { blake2s 5 } 423 id-blake2s224 OBJECT IDENTIFIER ::= { blake2s 7 } 424 id-blake2s256 OBJECT IDENTIFIER ::= { blake2s 8 } 426 5. Acknowledgements 428 The editor wishes to thank the [BLAKE2] team for their encouragement: 429 Jean-Philippe Aumasson, Samuel Neves, Zooko Wilcox-O'Hearn, and 430 Christian Winnerlein. We have borrowed passages from [BLAKE] and 431 [BLAKE2] with permission. 433 BLAKE2 is based on the SHA-3 proposal [BLAKE], designed by Jean- 434 Philippe Aumasson, Luca Henzen, Willi Meier, and Raphael C.-W. Phan. 435 BLAKE2, like BLAKE, relies on a core algorithm borrowed from the 436 ChaCha stream cipher, designed by Daniel J. Bernstein. 438 6. IANA Considerations 440 This memo includes no request to IANA. 442 7. Security Considerations 444 This document is intended to provide convenient open source access by 445 the Internet community to the BLAKE2 cryptographic hash algorithm. 446 We wish to make no independent assertion to its security in this 447 document. We refer the reader to [BLAKE] and [BLAKE2] for detailed 448 cryptanalytic rationale behind its design. 450 In order to avoid bloat, the reference implementations in Appendix A 451 and Appendix B may not erase all sensitive data (such as secret keys) 452 immediately from process memory after use. Such cleanups can be 453 added if needed. 455 8. References 457 8.1. Normative References 459 [BLAKE2] Aumasson, J-P., Neves, S., Wilcox-O'Hearn, Z., and C. 460 Winnerlein, "BLAKE2: simpler, smaller, fast as MD5", 461 January 2013, . 463 8.2. Informative References 465 [BLAKE] Aumasson, J-P., Meier, W., Phan, R., and L. Henzen, "The 466 Hash Function BLAKE", February 2015, . 469 [FIPS140-2IG] 470 NIST, US., "Implementation Guidance for FIPS PUB 140-2 and 471 the Cryptographic Module Validation Program", January 472 2015. 474 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 475 Requirement Levels", RFC 2119, BCP 14, March 1997. 477 [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations 478 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 479 RFC 6151, March 2011. 481 [RFC6234] Eastlake, D. and T. Hansen, "US Secure Hash Algorithms 482 (SHA and SHA-based HMAC and HKDF)", RFC 6234, May 2011. 484 Appendix A. BLAKE2b Implementation C Source 486 A.1. blake2b.h 488 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); 521 // All-in-one convenience function. 523 int blake2b(void *out, size_t outlen, // return buffer for digest 524 const void *key, size_t keylen, // optional secret key 525 const void *in, size_t inlen); // data to be hashed 527 #endif 528 530 A.2. blake2b.c 532 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 hashing context "ctx" with optional key "key". 627 // 1 <= outlen <= 64 gives the digest size in bytes. 628 // Secret key (also <= 64 bytes) is optional (keylen = 0). 630 int blake2b_init(blake2b_ctx *ctx, size_t outlen, 631 const void *key, size_t keylen) // (keylen=0: no key) 632 { 633 size_t i; 635 if (outlen == 0 || outlen > 64 || keylen > 64) 636 return -1; // illegal parameters 638 for (i = 0; i < 8; i++) // state, "param block" 639 ctx->h[i] = blake2b_iv[i]; 640 ctx->h[0] ^= 0x01010000 ^ (keylen << 8) ^ outlen; 642 ctx->t[0] = 0; // input count low word 643 ctx->t[1] = 0; // input count high word 644 ctx->c = 0; // pointer within buffer 645 ctx->outlen = outlen; 647 for (i = keylen; i < 128; i++) // zero input block 648 ctx->b[i] = 0; 649 if (keylen > 0) { 650 blake2b_update(ctx, key, keylen); 651 ctx->c = 128; // at the end 652 } 654 return 0; 655 } 657 // Add "inlen" bytes from "in" into the hash. 659 void blake2b_update(blake2b_ctx *ctx, 660 const void *in, size_t inlen) // data bytes 661 { 662 size_t i; 664 for (i = 0; i < inlen; i++) { 665 if (ctx->c == 128) { // buffer full ? 666 ctx->t[0] += ctx->c; // add counters 667 if (ctx->t[0] < ctx->c) // carry overflow ? 668 ctx->t[1]++; // high word 669 blake2b_compress(ctx, 0); // compress (not last) 670 ctx->c = 0; // counter to zero 671 } 672 ctx->b[ctx->c++] = ((const uint8_t *) in)[i]; 673 } 674 } 676 // Generate the message digest (size given in init). 677 // Result placed in "out". 679 void blake2b_final(blake2b_ctx *ctx, void *out) 680 { 681 size_t i; 683 ctx->t[0] += ctx->c; // mark last block offset 684 if (ctx->t[0] < ctx->c) // carry overflow 685 ctx->t[1]++; // high word 687 while (ctx->c < 128) // fill up with zeros 688 ctx->b[ctx->c++] = 0; 689 blake2b_compress(ctx, 1); // final block flag = 1 691 // little endian convert and store 692 for (i = 0; i < ctx->outlen; i++) { 693 ((uint8_t *) out)[i] = 694 (ctx->h[i >> 3] >> (8 * (i & 7))) & 0xFF; 695 } 696 } 698 // Convenience function for all-in-one computation. 700 int blake2b(void *out, size_t outlen, 701 const void *key, size_t keylen, 702 const void *in, size_t inlen) 703 { 704 blake2b_ctx ctx; 706 if (blake2b_init(&ctx, outlen, key, keylen)) 707 return -1; 708 blake2b_update(&ctx, in, inlen); 709 blake2b_final(&ctx, out); 711 return 0; 712 } 713 715 Appendix B. BLAKE2s Implementation C Source 717 B.1. blake2s.h 719 720 // blake2s.h 721 // BLAKE2s Hashing Context and API Prototypes 723 #ifndef BLAKE2S_H 724 #define BLAKE2S_H 726 #include 727 #include 729 // state context 730 typedef struct { 731 uint8_t b[64]; // input buffer 732 uint32_t h[8]; // chained state 733 uint32_t t[2]; // total number of bytes 734 size_t c; // pointer for b[] 735 size_t outlen; // digest size 736 } blake2s_ctx; 738 // Initialize the hashing context "ctx" with optional key "key". 739 // 1 <= outlen <= 32 gives the digest size in bytes. 740 // Secret key (also <= 32 bytes) is optional (keylen = 0). 741 int blake2s_init(blake2s_ctx *ctx, size_t outlen, 742 const void *key, size_t keylen); // secret key 744 // Add "inlen" bytes from "in" into the hash. 745 void blake2s_update(blake2s_ctx *ctx, // context 746 const void *in, size_t inlen); // data to be hashed 748 // Generate the message digest (size given in init). 749 // Result placed in "out". 750 void blake2s_final(blake2s_ctx *ctx, void *out); 752 // All-in-one convenience function. 753 int blake2s(void *out, size_t outlen, // return buffer for digest 754 const void *key, size_t keylen, // optional secret key 755 const void *in, size_t inlen); // data to be hashed 757 #endif 758 760 B.2. blake2s.c 762 763 // blake2s.c 764 // A simple blake2s 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. 776 #define B2S_GET32(p) \ 777 (((uint32_t) ((uint8_t *) (p))[0]) ^ \ 778 (((uint32_t) ((uint8_t *) (p))[1]) << 8) ^ \ 779 (((uint32_t) ((uint8_t *) (p))[2]) << 16) ^ \ 780 (((uint32_t) ((uint8_t *) (p))[3]) << 24)) 782 // Mixing function G. 784 #define B2S_G(a, b, c, d, x, y) { \ 785 v[a] = v[a] + v[b] + x; \ 786 v[d] = ROTR32(v[d] ^ v[a], 16); \ 787 v[c] = v[c] + v[d]; \ 788 v[b] = ROTR32(v[b] ^ v[c], 12); \ 789 v[a] = v[a] + v[b] + y; \ 790 v[d] = ROTR32(v[d] ^ v[a], 8); \ 791 v[c] = v[c] + v[d]; \ 792 v[b] = ROTR32(v[b] ^ v[c], 7); } 794 // Initialization Vector. 796 static const uint32_t blake2s_iv[8] = 797 { 798 0x6A09E667, 0xBB67AE85, 0x3C6EF372, 0xA54FF53A, 799 0x510E527F, 0x9B05688C, 0x1F83D9AB, 0x5BE0CD19 800 }; 802 // Compression function. "last" flag indicates last block. 804 static void blake2s_compress(blake2s_ctx *ctx, int last) 805 { 806 const uint8_t sigma[10][16] = { 807 { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 }, 808 { 14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3 }, 809 { 11, 8, 12, 0, 5, 2, 15, 13, 10, 14, 3, 6, 7, 1, 9, 4 }, 810 { 7, 9, 3, 1, 13, 12, 11, 14, 2, 6, 5, 10, 4, 0, 15, 8 }, 811 { 9, 0, 5, 7, 2, 4, 10, 15, 14, 1, 11, 12, 6, 8, 3, 13 }, 812 { 2, 12, 6, 10, 0, 11, 8, 3, 4, 13, 7, 5, 15, 14, 1, 9 }, 813 { 12, 5, 1, 15, 14, 13, 4, 10, 0, 7, 6, 3, 9, 2, 8, 11 }, 814 { 13, 11, 7, 14, 12, 1, 3, 9, 5, 0, 15, 4, 8, 6, 2, 10 }, 815 { 6, 15, 14, 9, 11, 3, 0, 8, 12, 2, 13, 7, 1, 4, 10, 5 }, 816 { 10, 2, 8, 4, 7, 6, 1, 5, 15, 11, 9, 14, 3, 12, 13, 0 } 817 }; 818 int i; 819 uint32_t v[16], m[16]; 821 for (i = 0; i < 8; i++) { // init work variables 822 v[i] = ctx->h[i]; 823 v[i + 8] = blake2s_iv[i]; 824 } 826 v[12] ^= ctx->t[0]; // low 32 bits of offset 827 v[13] ^= ctx->t[1]; // high 32 bits 828 if (last) // last block flag set ? 829 v[14] = ~v[14]; 831 for (i = 0; i < 16; i++) // get little-endian words 832 m[i] = B2S_GET32(&ctx->b[4 * i]); 834 for (i = 0; i < 10; i++) { // ten rounds 835 B2S_G( 0, 4, 8, 12, m[sigma[i][ 0]], m[sigma[i][ 1]]); 836 B2S_G( 1, 5, 9, 13, m[sigma[i][ 2]], m[sigma[i][ 3]]); 837 B2S_G( 2, 6, 10, 14, m[sigma[i][ 4]], m[sigma[i][ 5]]); 838 B2S_G( 3, 7, 11, 15, m[sigma[i][ 6]], m[sigma[i][ 7]]); 839 B2S_G( 0, 5, 10, 15, m[sigma[i][ 8]], m[sigma[i][ 9]]); 840 B2S_G( 1, 6, 11, 12, m[sigma[i][10]], m[sigma[i][11]]); 841 B2S_G( 2, 7, 8, 13, m[sigma[i][12]], m[sigma[i][13]]); 842 B2S_G( 3, 4, 9, 14, m[sigma[i][14]], m[sigma[i][15]]); 843 } 845 for( i = 0; i < 8; ++i ) 846 ctx->h[i] ^= v[i] ^ v[i + 8]; 847 } 849 // Initialize the hashing context "ctx" with optional key "key". 850 // 1 <= outlen <= 32 gives the digest size in bytes. 851 // Secret key (also <= 32 bytes) is optional (keylen = 0). 853 int blake2s_init(blake2s_ctx *ctx, size_t outlen, 854 const void *key, size_t keylen) // (keylen=0: no key) 855 { 856 size_t i; 858 if (outlen == 0 || outlen > 32 || keylen > 32) 859 return -1; // illegal parameters 861 for (i = 0; i < 8; i++) // state, "param block" 862 ctx->h[i] = blake2s_iv[i]; 863 ctx->h[0] ^= 0x01010000 ^ (keylen << 8) ^ outlen; 865 ctx->t[0] = 0; // input count low word 866 ctx->t[1] = 0; // input count high word 867 ctx->c = 0; // pointer within buffer 868 ctx->outlen = outlen; 870 for (i = keylen; i < 64; i++) // zero input block 871 ctx->b[i] = 0; 872 if (keylen > 0) { 873 blake2s_update(ctx, key, keylen); 874 ctx->c = 64; // at the end 875 } 877 return 0; 878 } 880 // Add "inlen" bytes from "in" into the hash. 882 void blake2s_update(blake2s_ctx *ctx, 883 const void *in, size_t inlen) // data bytes 884 { 885 size_t i; 887 for (i = 0; i < inlen; i++) { 888 if (ctx->c == 64) { // buffer full ? 889 ctx->t[0] += ctx->c; // add counters 890 if (ctx->t[0] < ctx->c) // carry overflow ? 891 ctx->t[1]++; // high word 892 blake2s_compress(ctx, 0); // compress (not last) 893 ctx->c = 0; // counter to zero 894 } 895 ctx->b[ctx->c++] = ((const uint8_t *) in)[i]; 896 } 897 } 899 // Generate the message digest (size given in init). 900 // Result placed in "out". 902 void blake2s_final(blake2s_ctx *ctx, void *out) 903 { 904 size_t i; 906 ctx->t[0] += ctx->c; // mark last block offset 907 if (ctx->t[0] < ctx->c) // carry overflow 908 ctx->t[1]++; // high word 910 while (ctx->c < 64) // fill up with zeros 911 ctx->b[ctx->c++] = 0; 912 blake2s_compress(ctx, 1); // final block flag = 1 914 // little endian convert and store 915 for (i = 0; i < ctx->outlen; i++) { 916 ((uint8_t *) out)[i] = 917 (ctx->h[i >> 2] >> (8 * (i & 3))) & 0xFF; 918 } 919 } 921 // Convenience function for all-in-one computation. 923 int blake2s(void *out, size_t outlen, 924 const void *key, size_t keylen, 925 const void *in, size_t inlen) 926 { 927 blake2s_ctx ctx; 929 if (blake2s_init(&ctx, outlen, key, keylen)) 930 return -1; 931 blake2s_update(&ctx, in, inlen); 932 blake2s_final(&ctx, out); 934 return 0; 935 } 936 938 Appendix C. BLAKE2b and BLAKE2s Self Test Module C Source 940 This module computes a series of keyed and unkeyed hashes from 941 deterministically generated pseudo-random data, and computes a hash 942 over those results. This is fairly a exhaustive, yet compact and 943 fast method for verifying that the hashing module is functioning 944 correctly. 946 Such testing is RECOMMEDED especially when compiling the 947 implementation for a new a target platform configuration. 948 Furthermore, some security standards such as FIPS-140 may require a 949 Power-On Self Test (POST) to be performed every time the 950 cryptographic module is loaded [FIPS140-2IG]. 952 953 // test_main.c 954 // Self test Modules for BLAKE2b and BLAKE2s -- and a stub main(). 956 #include 958 #include "blake2b.h" 959 #include "blake2s.h" 961 // Deterministic sequences (Fibonacci generator). 963 static void selftest_seq(uint8_t *out, size_t len, uint32_t seed) 964 { 965 size_t i; 966 uint32_t t, a , b; 968 a = 0xDEAD4BAD * seed; // prime 969 b = 1; 971 for (i = 0; i < len; i++) { // fill the buf 972 t = a + b; 973 a = b; 974 b = t; 975 out[i] = (t >> 24) & 0xFF; 976 } 977 } 979 // BLAKE2b self-test validation. Return 0 when OK. 981 int blake2b_selftest() 982 { 983 // grand hash of hash results 984 const uint8_t blake2b_res[32] = { 985 0xC2, 0x3A, 0x78, 0x00, 0xD9, 0x81, 0x23, 0xBD, 986 0x10, 0xF5, 0x06, 0xC6, 0x1E, 0x29, 0xDA, 0x56, 987 0x03, 0xD7, 0x63, 0xB8, 0xBB, 0xAD, 0x2E, 0x73, 988 0x7F, 0x5E, 0x76, 0x5A, 0x7B, 0xCC, 0xD4, 0x75 989 }; 990 // parameter sets 991 const size_t b2b_md_len[4] = { 20, 32, 48, 64 }; 992 const size_t b2b_in_len[6] = { 0, 3, 128, 129, 255, 1024 }; 994 size_t i, j, outlen, inlen; 995 uint8_t in[1024], md[64], key[64]; 996 blake2b_ctx ctx; 998 // 256-bit hash for testing 999 if (blake2b_init(&ctx, 32, NULL, 0)) 1000 return -1; 1002 for (i = 0; i < 4; i++) { 1003 outlen = b2b_md_len[i]; 1004 for (j = 0; j < 6; j++) { 1005 inlen = b2b_in_len[j]; 1007 selftest_seq(in, inlen, inlen); // unkeyed hash 1008 blake2b(md, outlen, NULL, 0, in, inlen); 1009 blake2b_update(&ctx, md, outlen); // hash the hash 1011 selftest_seq(key, outlen, outlen); // keyed hash 1012 blake2b(md, outlen, key, outlen, in, inlen); 1013 blake2b_update(&ctx, md, outlen); // hash the hash 1014 } 1015 } 1017 // compute and compare the hash of hashes 1018 blake2b_final(&ctx, md); 1019 for (i = 0; i < 32; i++) { 1020 if (md[i] != blake2b_res[i]) 1021 return -1; 1022 } 1024 return 0; 1025 } 1027 // BLAKE2s self-test validation. Return 0 when OK. 1029 int blake2s_selftest() 1030 { 1031 // Grand hash of hash results. 1032 const uint8_t blake2s_res[32] = { 1033 0x6A, 0x41, 0x1F, 0x08, 0xCE, 0x25, 0xAD, 0xCD, 1034 0xFB, 0x02, 0xAB, 0xA6, 0x41, 0x45, 0x1C, 0xEC, 1035 0x53, 0xC5, 0x98, 0xB2, 0x4F, 0x4F, 0xC7, 0x87, 1036 0xFB, 0xDC, 0x88, 0x79, 0x7F, 0x4C, 0x1D, 0xFE 1037 }; 1038 // Parameter sets. 1039 const size_t b2s_md_len[4] = { 16, 20, 28, 32 }; 1040 const size_t b2s_in_len[6] = { 0, 3, 64, 65, 255, 1024 }; 1042 size_t i, j, outlen, inlen; 1043 uint8_t in[1024], md[32], key[32]; 1044 blake2s_ctx ctx; 1046 // 256-bit hash for testing. 1047 if (blake2s_init(&ctx, 32, NULL, 0)) 1048 return -1; 1050 for (i = 0; i < 4; i++) { 1051 outlen = b2s_md_len[i]; 1052 for (j = 0; j < 6; j++) { 1053 inlen = b2s_in_len[j]; 1055 selftest_seq(in, inlen, inlen); // unkeyed hash 1056 blake2s(md, outlen, NULL, 0, in, inlen); 1057 blake2s_update(&ctx, md, outlen); // hash the hash 1059 selftest_seq(key, outlen, outlen); // keyed hash 1060 blake2s(md, outlen, key, outlen, in, inlen); 1061 blake2s_update(&ctx, md, outlen); // hash the hash 1062 } 1063 } 1065 // Compute and compare the hash of hashes. 1066 blake2s_final(&ctx, md); 1067 for (i = 0; i < 32; i++) { 1068 if (md[i] != blake2s_res[i]) 1069 return -1; 1070 } 1072 return 0; 1073 } 1075 // Test driver. 1077 int main(int argc, char **argv) 1078 { 1079 printf("blake2b_selftest() = %s\n", 1080 blake2b_selftest() ? "FAIL" : "OK"); 1081 printf("blake2s_selftest() = %s\n", 1082 blake2s_selftest() ? "FAIL" : "OK"); 1084 return 0; 1085 } 1086 1088 Authors' Addresses 1090 Markku-Juhani O. Saarinen (editor) 1091 Independent Consultant 1093 Email: mjos@iki.fi 1094 URI: https://mjos.fi 1096 Jean-Philippe Aumasson 1097 Kudelski Security 1098 22-24, Route de Geneve 1099 Case Postale 134 1100 Cheseaux 1033 1101 Switzerland 1103 Email: jean-philippe.aumasson@nagra.com 1104 URI: https://www.kudelskisecurity.com