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

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

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

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