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