1:mod:`Crypto.Hash` package 2========================== 3 4Cryptographic hash functions take arbitrary binary strings as input, 5and produce a random-like fixed-length output (called *digest* or *hash value*). 6 7It is practically infeasible to derive the original input data 8from the digest. In other words, the cryptographic hash function is *one-way* 9(*pre-image resistance*). 10 11Given the digest of one message, it is also practically infeasible 12to find another message (*second pre-image*) with the same digest 13(*weak collision resistance*). 14 15Finally, it is infeasible to find two arbitrary messages with the 16same digest (*strong collision resistance*). 17 18Regardless of the hash algorithm, an *n* bits long digest is at most 19as secure as a symmetric encryption algorithm keyed with *n/2* bits 20(`birthday attack <https://en.wikipedia.org/wiki/Birthday_attack>`_). 21 22Hash functions can be simply used as integrity checks. In 23combination with a public-key algorithm, you can implement a 24digital signature. 25 26API principles 27-------------- 28 29.. figure:: hashing.png 30 :align: center 31 :figwidth: 50% 32 33 Generic state diagram for a hash object 34 35Every time you want to hash a message, you have to create a new hash object 36with the :func:`new` function in the relevant algorithm module (e.g. 37:func:`Crypto.Hash.SHA256.new`). 38 39A first piece of message to hash can be passed to :func:`new` with the :attr:`data` parameter:: 40 41 >> from Crypto.Hash import SHA256 42 >> 43 >> hash_object = SHA256.new(data=b'First') 44 45.. note:: 46 You can only hash *byte strings* or *byte arrays* (no Python 2 Unicode strings 47 or Python 3 strings). 48 49Afterwards, the method :meth:`update` can be invoked any number of times 50as necessary, with other pieces of message:: 51 52 >>> hash_object.update(b'Second') 53 >>> hash_object.update(b'Third') 54 55The two steps above are equivalent to:: 56 57 >>> hash_object.update(b'SecondThird') 58 59At the end, the digest can be retrieved with the methods :meth:`digest` or 60:meth:`hexdigest`:: 61 62 >>> print(hash_object.digest()) 63 b'}\x96\xfd@\xb2$?O\xca\xc1a\x10\x15\x8c\x94\xe4\xb4\x085"\xd5"\xa8\xa4C\x9e+\x00\x859\xc7A' 64 >>> print(hash_object.hexdigest()) 65 7d96fd40b2243f4fcac16110158c94e4b4083522d522a8a4439e2b008539c741 66 67Attributes of hash objects 68-------------------------- 69 70Every hash object has the following attributes: 71 72.. csv-table:: 73 :header: Attribute, Description 74 :widths: 20, 80 75 76 digest_size, "Size of the digest in bytes, that is, the output 77 of the :meth:`digest` method. 78 It does not exist for hash functions with variable digest output 79 (such as :mod:`Crypto.Hash.SHAKE128`). 80 This is also a module attribute." 81 block_size, "The size of the message block in bytes, input to the compression 82 function. Only applicable for algorithms based on the Merkle-Damgard 83 construction (e.g. :mod:`Crypto.Hash.SHA256`). 84 This is also a module attribute." 85 oid, "A string with the dotted representation of the ASN.1 OID 86 assigned to the hash algorithm." 87 88Modern hash algorithms 89---------------------- 90 91- SHA-2 family 92 93 - :doc:`sha224` 94 - :doc:`sha256` 95 - :doc:`sha384` 96 - :doc:`sha512` 97 98- SHA-3 family 99 100 - :doc:`sha3_224` 101 - :doc:`sha3_256` 102 - :doc:`sha3_384` 103 - :doc:`sha3_512` 104 105- BLAKE2 106 107 - :doc:`blake2s` 108 - :doc:`blake2b` 109 110Extensible-Output Functions (XOF) 111--------------------------------- 112 113- SHAKE (in the SHA-3 family) 114 115 - :doc:`shake128` 116 - :doc:`shake256` 117 118Message Authentication Code (MAC) algorithms 119-------------------------------------------- 120 121- :doc:`hmac` 122- :doc:`cmac` 123- :doc:`poly1305` 124 125Historic hash algorithms 126------------------------- 127 128The following algorithms should not be used in new designs: 129 130- :doc:`sha1` 131- :doc:`md2` 132- :doc:`md5` 133- :doc:`ripemd160` 134- :doc:`keccak` 135