Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(81326)

Side by Side Diff: Doc/library/hashlib-blake2.rst

Issue 26798: add BLAKE2 to hashlib
Patch Set: Created 3 years, 2 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « Doc/library/crypto.rst ('k') | Doc/library/hashlib.rst » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
(Empty)
1 .. _hashlib-blake2:
2
3 :mod:`hashlib` --- BLAKE2 hash functions
4 ========================================
5
6 .. module:: hashlib
7 :synopsis: BLAKE2 hash function for Python
8 .. sectionauthor:: Dmitry Chestnykh
9
10 .. index::
11 single: blake2b, blake2s
12
13 BLAKE2_ is a cryptographic hash function, which offers highest security while
14 being as fast as MD5 or SHA-1, and comes in two flavors:
15
16 * **BLAKE2b**, optimized for 64-bit platforms and produces digests of any size
17 between 1 and 64 bytes,
18
19 * **BLAKE2s**, optimized for 8- to 32-bit platforms and produces digests of any
20 size between 1 and 32 bytes.
21
22 BLAKE2 supports **keyed mode** (a faster and simpler replacement for HMAC_),
23 **salted hashing**, **personalization**, and **tree hashing**.
24
25 Hash objects from this module follow the API of standard library's
26 :mod:`hashlib` objects.
27
28
29 Module
30 ======
31
32 Creating hash objects
33 ---------------------
34
35 New hash objects are created by calling constructor functions:
36
37
38 .. function:: blake2b(data=b'', digest_size=64, key=b'', salt=b'', \
39 person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, \
40 node_depth=0, inner_size=0, last_node=False)
41
42 .. function:: blake2s(data=b'', digest_size=32, key=b'', salt=b'', \
43 person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, \
44 node_depth=0, inner_size=0, last_node=False)
45
46
47 These functions return the corresponding hash objects for calculating
48 BLAKE2b or BLAKE2s. They optionally take these general parameters:
49
50 * *data*: initial chunk of data to hash, which must be interpretable as buffer
51 of bytes.
52
53 * *digest_size*: size of output digest in bytes.
54
55 * *key*: key for keyed hashing (up to 64 bytes for BLAKE2b, up to 32 bytes for
56 BLAKE2s).
57
58 * *salt*: salt for randomized hashing (up to 16 bytes for BLAKE2b, up to 8
59 bytes for BLAKE2s).
60
61 * *person*: personalization string (up to 16 bytes for BLAKE2b, up to 8 bytes
62 for BLAKE2s).
63
64 The following table shows limits for general parameters (in bytes):
65
66 ======= =========== ======== ========= ===========
67 Hash digest_size len(key) len(salt) len(person)
68 ======= =========== ======== ========= ===========
69 BLAKE2b 64 64 16 16
70 BLAKE2s 32 32 8 8
71 ======= =========== ======== ========= ===========
72
73 .. note::
74
75 BLAKE2 specification defines constant lengths for salt and personalization
76 parameters, however, for convenience, this implementation accepts byte
77 strings of any size up to the specified length. If the length of the
78 parameter is less than specified, it is padded with zeros, thus, for
79 example, ``b'salt'`` and ``b'salt\x00'`` is the same value. (This is not
80 the case for *key*.)
81
82 These sizes are available as module `constants`_ described below.
83
84 Constructor functions also accept the following tree hashing parameters:
85
86 * *fanout*: fanout (0 to 255, 0 if unlimited, 1 in sequential mode).
87
88 * *depth*: maximal depth of tree (1 to 255, 255 if unlimited, 1 in
89 sequential mode).
90
91 * *leaf_size*: maximal byte length of leaf (0 to 2**32-1, 0 if unlimited or in
92 sequential mode).
93
94 * *node_offset*: node offset (0 to 2**64-1 for BLAKE2b, 0 to 2**48-1 for
95 BLAKE2s, 0 for the first, leftmost, leaf, or in sequential mode).
96
97 * *node_depth*: node depth (0 to 255, 0 for leaves, or in sequential mode).
98
99 * *inner_size*: inner digest size (0 to 64 for BLAKE2b, 0 to 32 for
100 BLAKE2s, 0 in sequential mode).
101
102 * *last_node*: boolean indicating whether the processed node is the last
103 one (`False` for sequential mode).
104
105 .. figure:: hashlib-blake2-tree.png
106 :alt: Explanation of tree mode parameters.
107
108 See section 2.10 in `BLAKE2 specification
109 <https://blake2.net/blake2_20130129.pdf>`_ for comprehensive review of tree
110 hashing.
111
112
113 Constants
114 ---------
115
116 .. data:: blake2b.SALT_SIZE
117 .. data:: blake2s.SALT_SIZE
118
119 Salt length (maximum length accepted by constructors).
120
121
122 .. data:: blake2b.PERSON_SIZE
123 .. data:: blake2s.PERSON_SIZE
124
125 Personalization string length (maximum length accepted by constructors).
126
127
128 .. data:: blake2b.MAX_KEY_SIZE
129 .. data:: blake2s.MAX_KEY_SIZE
130
131 Maximum key size.
132
133
134 .. data:: blake2b.MAX_DIGEST_SIZE
135 .. data:: blake2s.MAX_DIGEST_SIZE
136
137 Maximum digest size that the hash function can output.
138
139
140 Examples
141 ========
142
143 Simple hashing
144 --------------
145
146 To calculate hash of some data, you should first construct a hash object by
147 calling the appropriate constructor function (:func:`blake2b` or
148 :func:`blake2s`), then update it with the data by calling :meth:`update` on the
149 object, and, finally, get the digest out of the object by calling
150 :meth:`digest` (or :meth:`hexdigest` for hex-encoded string).
151
152 >>> from hashlib import blake2b
153 >>> h = blake2b()
154 >>> h.update(b'Hello world')
155 >>> h.hexdigest()
156 '6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551 134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
157
158
159 As a shortcut, you can pass the first chunk of data to update directly to the
160 constructor as the first argument (or as *data* keyword argument):
161
162 >>> from hashlib import blake2b
163 >>> blake2b(b'Hello world').hexdigest()
164 '6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551 134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
165
166 You can call :meth:`hash.update` as many times as you need to iteratively
167 update the hash:
168
169 >>> from hashlib import blake2b
170 >>> items = [b'Hello', b' ', b'world']
171 >>> h = blake2b()
172 >>> for item in items:
173 ... h.update(item)
174 >>> h.hexdigest()
175 '6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551 134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
176
177
178 Using different digest sizes
179 ----------------------------
180
181 BLAKE2 has configurable size of digests up to 64 bytes for BLAKE2b and up to 32
182 bytes for BLAKE2s. For example, to replace SHA-1 with BLAKE2b without changing
183 the size of output, we can tell BLAKE2b to produce 20-byte digests:
184
185 >>> from hashlib import blake2b
186 >>> h = blake2b(digest_size=20)
187 >>> h.update(b'Replacing SHA1 with the more secure function')
188 >>> h.hexdigest()
189 'd24f26cf8de66472d58d4e1b1774b4c9158b1f4c'
190 >>> h.digest_size
191 20
192 >>> len(h.digest())
193 20
194
195 Hash objects with different digest sizes have completely different outputs
196 (shorter hashes are *not* prefixes of longer hashes); BLAKE2b and BLAKE2s
197 produce different outputs even if the output length is the same:
198
199 >>> from hashlib import blake2b, blake2s
200 >>> blake2b(digest_size=10).hexdigest()
201 '6fa1d8fcfd719046d762'
202 >>> blake2b(digest_size=11).hexdigest()
203 'eb6ec15daf9546254f0809'
204 >>> blake2s(digest_size=10).hexdigest()
205 '1bf21a98c78a1c376ae9'
206 >>> blake2s(digest_size=11).hexdigest()
207 '567004bf96e4a25773ebf4'
208
209
210 Keyed hashing
211 -------------
212
213 Keyed hashing can be used for authentication as a faster and simpler
214 replacement for `Hash-based message authentication code
215 <http://en.wikipedia.org/wiki/Hash-based_message_authentication_code>`_ (HMAC).
216 BLAKE2 can be securely used in prefix-MAC mode thanks to the
217 indifferentiability property inherited from BLAKE.
218
219 This example shows how to get a (hex-encoded) 128-bit authentication code for
220 message ``b'message data'`` with key ``b'pseudorandom key'``:
221
222 >>> from hashlib import blake2b
223 >>> h = blake2b(key=b'pseudorandom key', digest_size=16)
224 >>> h.update(b'message data')
225 >>> h.hexdigest()
226 '3d363ff7401e02026f4a4687d4863ced'
227
228
229 As a practical example, a web application can symmetrically sign cookies sent
230 to users and later verify them to make sure they weren't tampered with:
231
232 >>> from hashlib import blake2b
233 >>> from hmac import compare_digest
234 >>>
235 >>> SECRET_KEY = b'pseudorandomly generated server secret key'
236 >>> AUTH_SIZE = 16
237 >>>
238 >>> def sign(cookie):
239 ... h = blake2b(data=cookie, digest_size=AUTH_SIZE, key=SECRET_KEY)
240 ... return h.hexdigest()
241 >>>
242 >>> cookie = b'user:vatrogasac'
243 >>> sig = sign(cookie)
244 >>> print("{0},{1}".format(cookie.decode('utf-8'), sig))
245 user:vatrogasac,349cf904533767ed2d755279a8df84d0
246 >>> compare_digest(cookie, sig)
247 True
248 >>> compare_digest(b'user:policajac', sig)
249 False
250 >>> compare_digesty(cookie, '0102030405060708090a0b0c0d0e0f00')
251 False
252
253 Even though there's a native keyed hashing mode, BLAKE2 can, of course, be used
254 in HMAC construction with :mod:`hmac` module:
255
256 >>> import hmac, hashlib
257 >>> m = hmac.new(b'secret key', digestmod=hashlib.blake2s)
258 >>> m.update(b'message')
259 >>> m.hexdigest()
260 'e3c8102868d28b5ff85fc35dda07329970d1a01e273c37481326fe0c861c8142'
261
262
263 Randomized hashing
264 ------------------
265
266 By setting *salt* parameter users can introduce randomization to the hash
267 function. Randomized hashing is useful for protecting against collision attacks
268 on the hash function used in digital signatures.
269
270 Randomized hashing is designed for situations where one party, the message
271 preparer, generates all or part of a message to be signed by a second
272 party, the message signer. If the message preparer is able to find
273 cryptographic hash function collisions (i.e., two messages producing the
274 same hash value), then she might prepare meaningful versions of the message
275 that would produce the same hash value and digital signature, but with
276 different results (e.g., transferring $1,000,000 to an account, rather than
277 $10). Cryptographic hash functions have been designed with collision
278 resistance as a major goal, but the current concentration on attacking
279 cryptographic hash functions may result in a given cryptographic hash
280 function providing less collision resistance than expected. Randomized
281 hashing offers the signer additional protection by reducing the likelihood
282 that a preparer can generate two or more messages that ultimately yield the
283 same hash value during the digital signature generation process – even if
284 it is practical to find collisions for the hash function. However, the use
285 of randomized hashing may reduce the amount of security provided by a
286 digital signature when all portions of the message are prepared
287 by the signer.
288
289 (`NIST SP-800-106 "Randomized Hashing for Digital Signatures"
290 <http://csrc.nist.gov/publications/nistpubs/800-106/NIST-SP-800-106.pdf>`_)
291
292 In BLAKE2 the salt is processed as a one-time input to the hash function during
293 initialization, rather than as an input to each compression function.
294
295 .. warning::
296
297 *Salted hashing* (or just hashing) with BLAKE2 or any other general-purpose
298 cryptographic hash function, such as SHA-256, is not suitable for hashing
299 passwords. See `BLAKE2 FAQ <https://blake2.net/#qa>`_ for more
300 information.
301 ..
302
303 >>> import os
304 >>> from hashlib import blake2b
305 >>> msg = b'some message'
306 >>> # Calculate the first hash with a random salt.
307 >>> salt1 = os.urandom(blake2b.SALT_SIZE)
308 >>> h1 = blake2b(salt=salt1)
309 >>> h1.update(msg)
310 >>> # Calculate the second hash with a different random salt.
311 >>> salt2 = os.urandom(blake2b.SALT_SIZE)
312 >>> h2 = blake2b(salt=salt2)
313 >>> h2.update(msg)
314 >>> # The digests are different.
315 >>> h1.digest() != h2.digest()
316 True
317
318
319 Personalization
320 ---------------
321
322 Sometimes it is useful to force hash function to produce different digests for
323 the same input for different purposes. Quoting the authors of the Skein hash
324 function:
325
326 We recommend that all application designers seriously consider doing this;
327 we have seen many protocols where a hash that is computed in one part of
328 the protocol can be used in an entirely different part because two hash
329 computations were done on similar or related data, and the attacker can
330 force the application to make the hash inputs the same. Personalizing each
331 hash function used in the protocol summarily stops this type of attack.
332
333 (`The Skein Hash Function Family
334 <http://www.skein-hash.info/sites/default/files/skein1.3.pdf>`_,
335 p. 21)
336
337 BLAKE2 can be personalized by passing bytes to the *person* argument:
338
339 >>> from hashlib import blake2b
340 >>> FILES_HASH_PERSON = b'MyApp Files Hash'
341 >>> BLOCK_HASH_PERSON = b'MyApp Block Hash'
342 >>> h = blake2b(digest_size=32, person=FILES_HASH_PERSON)
343 >>> h.update(b'the same content')
344 >>> h.hexdigest()
345 '20d9cd024d4fb086aae819a1432dd2466de12947831b75c5a30cf2676095d3b4'
346 >>> h = blake2b(digest_size=32, person=BLOCK_HASH_PERSON)
347 >>> h.update(b'the same content')
348 >>> h.hexdigest()
349 'cf68fb5761b9c44e7878bfb2c4c9aea52264a80b75005e65619778de59f383a3'
350
351 Personalization together with the keyed mode can also be used to derive differen t
352 keys from a single one.
353
354 >>> from hashlib import blake2s
355 >>> from base64 import b64decode, b64encode
356 >>> orig_key = b64decode(b'Rm5EPJai72qcK3RGBpW3vPNfZy5OZothY+kHY6h21KM=')
357 >>> enc_key = blake2s(key=orig_key, person=b'kEncrypt').digest()
358 >>> mac_key = blake2s(key=orig_key, person=b'kMAC').digest()
359 >>> print(b64encode(enc_key).decode('utf-8'))
360 rbPb15S/Z9t+agffno5wuhB77VbRi6F9Iv2qIxU7WHw=
361 >>> print(b64encode(mac_key).decode('utf-8'))
362 G9GtHFE1YluXY1zWPlYk1e/nWfu0WSEb0KRcjhDeP/o=
363
364 Tree mode
365 ---------
366
367 Here's an example of hashing a minimal tree with two leaf nodes::
368
369 10
370 / \
371 00 01
372
373 The example uses 64-byte internal digests, and returns the 32-byte final
374 digest.
375
376 >>> from hashlib import blake2b
377 >>>
378 >>> FANOUT = 2
379 >>> DEPTH = 2
380 >>> LEAF_SIZE = 4096
381 >>> INNER_SIZE = 64
382 >>>
383 >>> buf = bytearray(6000)
384 >>>
385 >>> # Left leaf
386 ... h00 = blake2b(buf[0:LEAF_SIZE], fanout=FANOUT, depth=DEPTH,
387 ... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
388 ... node_offset=0, node_depth=0, last_node=False)
389 >>> # Right leaf
390 ... h01 = blake2b(buf[LEAF_SIZE:], fanout=FANOUT, depth=DEPTH,
391 ... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
392 ... node_offset=1, node_depth=0, last_node=True)
393 >>> # Root node
394 ... h10 = blake2b(digest_size=32, fanout=FANOUT, depth=DEPTH,
395 ... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
396 ... node_offset=0, node_depth=1, last_node=True)
397 >>> h10.update(h00.digest())
398 >>> h10.update(h01.digest())
399 >>> h10.hexdigest()
400 '3ad2a9b37c6070e374c7a8c508fe20ca86b6ed54e286e93a0318e95e881db5aa'
401
402 Credits
403 =======
404
405 BLAKE2_ was designed by *Jean-Philippe Aumasson*, *Samuel Neves*, *Zooko
406 Wilcox-O'Hearn*, and *Christian Winnerlein* based on SHA-3_ finalist BLAKE_
407 created by *Jean-Philippe Aumasson*, *Luca Henzen*, *Willi Meier*, and
408 *Raphael C.-W. Phan*.
409
410 It uses core algorithm from ChaCha_ cipher designed by *Daniel J. Bernstein*.
411
412 The stdlib implementation is based on pyblake2_ module. It was written by
413 *Dmitry Chestnykh* based on C implementation written by *Samuel Neves*. The
414 documentation was copied from pyblake2_ and written by *Dmitry Chestnykh*.
415
416 The C code was partly rewritten for Python by *Christian Heimes*.
417
418 The following public domain dedication applies for both C hash function
419 implementation, extension code, and this documentation:
420
421 To the extent possible under law, the author(s) have dedicated all copyright
422 and related and neighboring rights to this software to the public domain
423 worldwide. This software is distributed without any warranty.
424
425 You should have received a copy of the CC0 Public Domain Dedication along
426 with this software. If not, see
427 http://creativecommons.org/publicdomain/zero/1.0/.
428
429 The following people have helped with development or contributed their changes
430 to the project and the public domain according to the Creative Commons Public
431 Domain Dedication 1.0 Universal:
432
433 * *Alexandr Sokolovskiy*
434
435 .. seealso:: Official BLAKE2 website: https://blake2.net
436
437 .. _BLAKE2: https://blake2.net
438 .. _HMAC: http://en.wikipedia.org/wiki/Hash-based_message_authentication_code
439 .. _BLAKE: https://131002.net/blake/
440 .. _SHA-3: http://en.wikipedia.org/wiki/NIST_hash_function_competition
441 .. _ChaCha: http://cr.yp.to/chacha.html
442 .. _pyblake2: https://pythonhosted.org/pyblake2/
443
OLDNEW
« no previous file with comments | « Doc/library/crypto.rst ('k') | Doc/library/hashlib.rst » ('j') | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+