KangarooTwelve¶
KangarooTwelve is an extendable-output function (XOF) based on the Keccak permutation, which is also the basis for SHA-3.
As a XOF, KangarooTwelve is a generalization of a cryptographic hash function. It is not limited to creating fixed-length digests (e.g., SHA-256 will always output exactly 32 bytes): it produces digests of any length, and it can be used as a Pseudo Random Generator (PRG).
Output bits do not depend on the output length.
KangarooTwelve is specified by RFC9861. It provides 128 bit of security against (second) pre-image attacks when the output is at least 128 bits long. It provides the same security level against collision attacks when the output is at least 256 bits long.
In addition to hashing, KangarooTwelve allows for domain separation
via a customization string (custom parameter to Crypto.Hash.KangarooTwelve.new()).
Hint
For instance, if you are using KangarooTwelve in two applications, by picking different customization strings you can ensure that they will never end up using the same digest in practice. The important factor is that the strings are different; what the strings say does not matter.
In the following example, we extract 26 bytes (208 bits) from the XOF:
>>> from Crypto.Hash import KangarooTwelve as K12
>>>
>>> kangaroo = K12.new(custom=b'Email Signature')
>>> kangaroo.update(b'Some data')
>>> print(kangaroo.read(26).hex())
61e571c51da64228a85d495f3546c43a4dd2c1fd5de87e45dc58
If the whole message is available at once, Crypto.Hash.KangarooTwelve.digest()
returns the output with a single call, which is much faster for short messages:
>>> print(K12.digest(b'Some data', length=26, custom=b'Email Signature').hex())
61e571c51da64228a85d495f3546c43a4dd2c1fd5de87e45dc58
KangarooTwelve hashes long messages as a tree of independent 8 KiB leaves,
so it can use several CPU cores. This is disabled by default; enable it with
the threads parameter to Crypto.Hash.KangarooTwelve.new():
>>> kangaroo = K12.new(threads=4)
>>> kangaroo.update(very_long_message)
With threads=0, it uses as many threads as the CPU cores available to the process.
The output does not depend on the number of threads.
Threads only help with long data passed in large chunks:
each thread hashes at least 256 KiB of a single update() call.
- class Crypto.Hash.KangarooTwelve.K12_XOF(data, custom, threads=1)¶
A KangarooTwelve hash object. Do not instantiate directly. Use the
new()function.- read(length)¶
Produce more bytes of the digest.
- Parameters:
length (integer) – the amount of bytes this method must return
- Returns:
the next piece of XOF output (of the given length)
- Return type:
byte string
- Crypto.Hash.KangarooTwelve.digest(data, *, length, custom=None)¶
Compute the KangarooTwelve output for a complete message, in one go.
It returns the same bytes as
new(data, custom).read(length), but it is much faster for short messages.- Parameters:
data (bytes/bytearray/memoryview) – The whole message to hash.
length (integer) – Keyword-only. The amount of bytes to return.
custom (bytes) – Optional, keyword-only. A customization byte string.
- Return:
the output of the XOF,
lengthbytes long- Return type:
byte string
- Crypto.Hash.KangarooTwelve.new(data=None, custom=None, threads=1)¶
Return a fresh instance of a KangarooTwelve object.
- Parameters:
data (bytes/bytearray/memoryview) – Optional. The very first chunk of the message to hash. It is equivalent to an early call to
update().custom (bytes) – Optional. A customization byte string.
threads (integer) – Optional. The maximum number of threads used to hash long messages (default: 1, no extra threads). Use 0 for as many threads as the CPU cores available to this process. Each thread hashes at least 256 KiB of a single call to
K12_XOF.update()(or ofdata): with shorter inputs, fewer threads are used, or none at all. For best results, do not exceed the number of physical cores. The output does not depend on the number of threads.
- Return:
A
K12_XOFobject- Return type: