Registry /
auth-security / chacha20poly1305-reuseable
Install & Compatibility
Where this runs
tested against v0.13.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.915 runs
installs and imports cleanly · install 0.0s · import 0.029s · 34.4MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 2.4s · import 0.026s · 35MB
33MB installed
● package 33MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ChaCha20Poly1305Reusable
✓ from chacha20poly1305_reuseable import ChaCha20Poly1305Reusable
This quickstart demonstrates how to initialize the `ChaCha20Poly1305Reusable` cipher with a 32-byte key, encrypt plaintext with optional associated data (AAD), and then decrypt it, verifying integrity. It highlights how the cipher object itself can be reused, but crucially, a new cryptographic nonce is generated and required for each distinct encryption operation.
import os
from chacha20poly1305_reuseable import ChaCha20Poly1305Reusable
# In a real application, securely load your key (32 bytes).
# For demonstration, a random key is generated.
key = os.urandom(32)
# Associated data (AAD) is optional, but recommended for integrity checks.
associated_data = b"Config data, not encrypted but authenticated."
plaintext = b"This is the secret message to be encrypted."
# Initialize the cipher object with the key
cipher = ChaCha20Poly1305Reusable(key)
# Encrypt the plaintext
# The nonce is generated internally and returned, must be unique per encryption.
nonce, ciphertext, tag = cipher.encrypt(plaintext, associated_data)
print(f"Encryption successful:")
print(f" Nonce: {nonce.hex()}")
print(f" Ciphertext: {ciphertext.hex()}")
print(f" Tag: {tag.hex()}")
# Decrypt the ciphertext
try:
decrypted_text = cipher.decrypt(nonce, ciphertext, tag, associated_data)
print(f"Decryption successful: {decrypted_text.decode()}")
assert decrypted_text == plaintext
print("Message integrity verified.")
except Exception as e:
print(f"Decryption failed: {e}")
# The 'cipher' object can be reused for subsequent encryptions/decryptions
# with a *new*, unique nonce for each operation.
new_plaintext = b"Another secret message, secured by the same key."
new_nonce, new_ciphertext, new_tag = cipher.encrypt(new_plaintext, associated_data)
print(f"\nReused cipher for new encryption (new nonce): {new_nonce.hex()}")
Debug
Known issues
breakingThis library is considered obsolete for new projects. The underlying `cryptography` library now provides its own highly optimized, Rust-based implementation of ChaCha20Poly1305. It is recommended to use `cryptography.hazmat.primitives.ciphers.aead.ChaCha20Poly1305` directly instead of this wrapper library for modern applications.fixFor new projects, use `from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305` instead. For existing projects, consider migrating to `cryptography`'s native AEAD for long-term support and performance.
affects: All versions, especially from v0.13.0 onwards due to underlying `cryptography` changes.
gotchaDespite the library's name including 'reuseable', this refers to the Python object instance, not the cryptographic nonce. Reusing the same nonce (IV) with the same key for two different plaintexts is a critical security vulnerability that completely compromises the confidentiality of ChaCha20Poly1305. A unique nonce *must* be used for every encryption with a given key.fixAlways generate a cryptographically secure, unique nonce (usually 12 bytes) for each encryption operation under the same key. The `encrypt` method of this library generates a new nonce for you by default; ensure you store and transmit it with the ciphertext.
affects: All versions.
gotchaOlder versions of `chacha20poly1305-reuseable` (prior to v0.12.1) had compatibility issues with `cryptography` library versions, specifically `cryptography 42`, due to internal cipher checks. This could lead to runtime errors or unexpected behavior if `cryptography` was updated independently.fixUpgrade to `chacha20poly1305-reuseable` version 0.12.1 or newer to ensure compatibility with recent `cryptography` releases. If upgrading is not possible, pin `cryptography<42` for older versions of this library.
affects: <0.12.1
Errors
Common errors & fixes
ValueError: MAC did not verify
During decryption, the authentication tag (MAC) generated from the provided ciphertext, associated data, and key does not match the tag received. This indicates that either the ciphertext or the associated data has been tampered with, or an incorrect key/nonce/tag was used for decryption.
fixEnsure that the `key`, `nonce`, `ciphertext`, `tag`, and `associated_data` used during decryption are precisely the same as those used during encryption and that none have been modified in transit. Verify the integrity of the message source.
AttributeError: module 'chacha20poly1305_reuseable' has no attribute 'ChaCha20Poly1305Reusable'
The main class `ChaCha20Poly1305Reusable` was not found. This typically happens if the library is not installed, or the import path is incorrect (e.g., trying `import chacha20poly1305_reuseable` directly and accessing attributes from it).
fixFirst, ensure the library is installed: `pip install chacha20poly1305-reuseable`. Then, use the correct import statement: `from chacha20poly1305_reuseable import ChaCha20Poly1305Reusable`.
Security warning: Nonce reuse detected with ChaCha20Poly1305
Attempting to encrypt multiple distinct messages using the same cryptographic key and the same nonce. While the library itself handles nonce generation for its `encrypt` method, manual or incorrect nonce management can lead to this vulnerability.
fixAlways use a unique, randomly generated nonce for every single encryption operation performed with a given key. The `encrypt` method in `chacha20poly1305-reuseable` automatically generates a new nonce for each call, so this issue primarily arises from manual misuse if a fixed nonce is forced.
Upgrade
Version history
0.13.2latest on PyPI · released Jul 21, 2024
Audit
Dependencies
cryptographyrequiredProvides the underlying cryptographic primitives for ChaCha20 and Poly1305. The 'chacha20poly1305-reuseable' library leverages 'cryptography' for its core functions.