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