Crypto.Hash
package¶
Cryptographic hash functions take arbitrary binary strings as input, and produce a random-like fixed-length output (called digest or hash value).
It is practically infeasible to derive the original input data from the digest. In other words, the cryptographic hash function is one-way (pre-image resistance).
Given the digest of one message, it is also practically infeasible to find another message (second pre-image) with the same digest (weak collision resistance).
Finally, it is infeasible to find two arbitrary messages with the same digest (strong collision resistance).
Regardless of the hash algorithm, an n bits long digest is at most as secure as a symmetric encryption algorithm keyed with n/2 bits (birthday attack).
Hash functions can be simply used as integrity checks. In combination with a public-key algorithm, you can implement a digital signature.
API principles¶
Every time you want to hash a message, you have to create a new hash object
with the new()
function in the relevant algorithm module (e.g.
Crypto.Hash.SHA256.new()
).
A first piece of message to hash can be passed to new()
with the data
parameter:
>> from Crypto.Hash import SHA256
>>
>> hash_object = SHA256.new(data=b'First')
Note
You can only hash byte strings or byte arrays (no Python 2 Unicode strings or Python 3 strings).
Afterwards, the method update()
can be invoked any number of times
as necessary, with other pieces of message:
>>> hash_object.update(b'Second')
>>> hash_object.update(b'Third')
The two steps above are equivalent to:
>>> hash_object.update(b'SecondThird')
At the end, the digest can be retrieved with the methods digest()
or
hexdigest()
:
>>> print(hash_object.digest())
b'}\x96\xfd@\xb2$?O\xca\xc1a\x10\x15\x8c\x94\xe4\xb4\x085"\xd5"\xa8\xa4C\x9e+\x00\x859\xc7A'
>>> print(hash_object.hexdigest())
7d96fd40b2243f4fcac16110158c94e4b4083522d522a8a4439e2b008539c741
Attributes of hash objects¶
Every hash object has the following attributes:
Attribute |
Description |
---|---|
digest_size |
Size of the digest in bytes, that is, the output
of the |
block_size |
The size of the message block in bytes, input to the compression
function. Only applicable for algorithms based on the Merkle-Damgard
construction (e.g. |
oid |
A string with the dotted representation of the ASN.1 OID assigned to the hash algorithm. |
Modern hash algorithms¶
SHA-2 family (FIPS 180-4)
SHA-3 family (FIPS 202)
BLAKE2
Extensible-Output Functions (XOF)¶
A XOF is similar to a conventional cryptographic hash: it is a one-way function that maps a piece of data of arbitrary size to a random-like output. It provides some guarantees over collision resistance, pre-image resistance, and second pre-image resistance.
Unlike a conventional hash, an application using a XOF can choose the length of the output.
For this reason, a XOF does not have a digest()
method.
Instead, it has a read(N)
method to extract the next N
bytes of the output.
SHA-3 family (FIPS 202)
SHA-3 derived functions (NIST SP 800-185)
Message Authentication Code (MAC) algorithms¶
Historic hash algorithms¶
The following algorithms should not be used in new designs: