ChaCha20-Poly1305 and XChaCha20-Poly1305¶
ChaCha20-Poly1305 is an authenticated cipher with associated data (AEAD). It works with a 32 bytes secret key and a nonce which must never be reused across encryptions performed under the same key. The cipher produces a 16 byte tag that the receiver must use to validate the message.
There are three variants of the algorithm, defined by the length of the nonce:
Nonce length |
Description |
Max plaintext |
If random nonce as same key |
---|---|---|---|
8 bytes |
Based on Bernstein’s original ChaCha20. |
No limitations |
Max 200 000 messages |
12 bytes (default) |
Version used in TLS and specified in RFC7539. |
256 GB |
Max 13 billions messages |
24 bytes |
XChaCha20-Poly1305, still in draft stage. |
256 GB |
No limitations |
The API of the cipher and its finite state machine are the same as for the modern modes of operation of block ciphers.
You create a new cipher by calling Crypto.Cipher.ChaCha20_Poly1305.new()
.
This is an example of how ChaCha20-Poly1305 (TLS version) can encrypt and authenticate data:
>>> import json
>>> from base64 import b64encode
>>> from Crypto.Cipher import ChaCha20_Poly1305
>>> from Crypto.Random import get_random_bytes
>>>
>>> header = b"header"
>>> plaintext = b'Attack at dawn'
>>> key = get_random_bytes(32)
>>> cipher = ChaCha20_Poly1305.new(key=key)
>>> cipher.update(header)
>>> ciphertext, tag = cipher.encrypt_and_digest(plaintext)
>>>
>>> jk = [ 'nonce', 'header', 'ciphertext', 'tag' ]
>>> jv = [ b64encode(x).decode('utf-8') for x in (cipher.nonce, header, ciphertext, tag) ]
>>> result = json.dumps(dict(zip(jk, jv)))
>>> print(result)
{"nonce": "4EE/9uqhoZ3mQXmm", "header": "aGVhZGVy", "ciphertext": "Wmmo4Vzn+eS3tUPv2a8=", "tag": "/FgVbM8qhzssPRY80T0iVA=="}
In the example above, a 96 bit (12 byte) nonce is automatically created.
It can be accessed as the nonce
member in the cipher
object.
This is how you decrypt the data and check its authenticity:
>>> import json
>>> from base64 import b64decode
>>> from Crypto.Cipher import ChaCha20_Poly1305
>>>
>>> # We assume that the key was securely shared beforehand
>>> try:
>>> b64 = json.loads(json_input)
>>> jk = [ 'nonce', 'header', 'ciphertext', 'tag' ]
>>> jv = {k:b64decode(b64[k]) for k in jk}
>>>
>>> cipher = ChaCha20_Poly1305.new(key=key, nonce=jv['nonce'])
>>> cipher.update(jv['header'])
>>> plaintext = cipher.decrypt_and_verify(jv['ciphertext'], jv['tag'])
>>> print("The message was: " + plaintext)
>>> except ValueError, KeyError:
>>> print("Incorrect decryption")
-
class
Crypto.Cipher.ChaCha20_Poly1305.
ChaCha20Poly1305Cipher
(key, nonce)¶ ChaCha20-Poly1305 and XChaCha20-Poly1305 cipher object. Do not create it directly. Use
new()
instead.- Variables
nonce (byte string) – The nonce with length 8, 12 or 24 bytes
-
decrypt
(ciphertext, output=None)¶ Decrypt a piece of data.
- Parameters
ciphertext (bytes/bytearray/memoryview) – The data to decrypt, of any size.
- Keyword Arguments
output (bytes/bytearray/memoryview) – The location where the plaintext is written to. If
None
, the plaintext is returned.- Returns
If
output
isNone
, the plaintext is returned asbytes
. Otherwise,None
.
-
decrypt_and_verify
(ciphertext, received_mac_tag)¶ Perform
decrypt()
andverify()
in one step.- Parameters
ciphertext (bytes/bytearray/memoryview) – The piece of data to decrypt.
received_mac_tag (bytes) – This is the 16-byte binary MAC, as received from the sender.
- Returns
the decrypted data (as
bytes
)- Raises
ValueError – if the MAC does not match. The message has been tampered with or the key is incorrect.
-
digest
()¶ Compute the binary authentication tag (MAC).
- Return
the MAC tag, as 16
bytes
.
-
encrypt
(plaintext, output=None)¶ Encrypt a piece of data.
- Parameters
plaintext (bytes/bytearray/memoryview) – The data to encrypt, of any size.
- Keyword Arguments
output (bytes/bytearray/memoryview) – The location where the ciphertext is written to. If
None
, the ciphertext is returned.- Returns
If
output
isNone
, the ciphertext is returned asbytes
. Otherwise,None
.
-
encrypt_and_digest
(plaintext)¶ Perform
encrypt()
anddigest()
in one step.- Parameters
plaintext (bytes/bytearray/memoryview) – The data to encrypt, of any size.
- Returns
a tuple with two
bytes
objects:the ciphertext, of equal length as the plaintext
the 16-byte MAC tag
-
hexdigest
()¶ Compute the printable authentication tag (MAC).
This method is like
digest()
.- Return
the MAC tag, as a hexadecimal string.
-
hexverify
(hex_mac_tag)¶ Validate the printable authentication tag (MAC).
This method is like
verify()
.- Parameters
hex_mac_tag (string) – This is the printable MAC.
- Raises ValueError
if the MAC does not match. The message has been tampered with or the key is incorrect.
-
update
(data)¶ Protect the associated data.
Associated data (also known as additional authenticated data - AAD) is the piece of the message that must stay in the clear, while still allowing the receiver to verify its integrity. An example is packet headers.
The associated data (possibly split into multiple segments) is fed into
update()
before any call todecrypt()
orencrypt()
. If there is no associated data,update()
is not called.- Parameters
assoc_data (bytes/bytearray/memoryview) – A piece of associated data. There are no restrictions on its size.
-
verify
(received_mac_tag)¶ Validate the binary authentication tag (MAC).
The receiver invokes this method at the very end, to check if the associated data (if any) and the decrypted messages are valid.
- Parameters
received_mac_tag (bytes/bytearray/memoryview) – This is the 16-byte binary MAC, as received from the sender.
- Raises ValueError
if the MAC does not match. The message has been tampered with or the key is incorrect.
-
Crypto.Cipher.ChaCha20_Poly1305.
new
(**kwargs)¶ Create a new ChaCha20-Poly1305 or XChaCha20-Poly1305 AEAD cipher.
- Keyword Arguments
key – The secret key to use. It must be 32 bytes long.
nonce –
A value that must never be reused for any other encryption done with this key.
For ChaCha20-Poly1305, it must be 8 or 12 bytes long.
For XChaCha20-Poly1305, it must be 24 bytes long.
If not provided, 12
bytes
will be generated randomly (you can find them back in thenonce
attribute).
- Return
a
Crypto.Cipher.ChaCha20.ChaCha20Poly1305Cipher
object