Encryption
This module allows to encrypt bytestring data, then decrypt it.
Public API
- wacryptolib.cipher.SUPPORTED_CIPHER_ALGOS = ['AES_CBC', 'AES_EAX', 'CHACHA20_POLY1305', 'RSA_OAEP']
These values can be used as 'cipher_algo'.
- wacryptolib.cipher.AUTHENTICATED_CIPHER_ALGOS = ['AES_EAX', 'CHACHA20_POLY1305']
Built-in mutable sequence.
If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
- wacryptolib.cipher.STREAMABLE_CIPHER_ALGOS = ['AES_CBC', 'AES_EAX', 'CHACHA20_POLY1305']
Built-in mutable sequence.
If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
- wacryptolib.cipher.encrypt_bytestring(plaintext, *, cipher_algo, key_dict)
Encrypt a bytestring with the selected algorithm for the given payload, using the provided key dict (which must contain keys/initializers of proper types and lengths).
- Return type:
dict
- Returns:
dictionary with encryption data
- wacryptolib.cipher.decrypt_bytestring(cipherdict, *, cipher_algo, key_dict, verify_integrity_tags=True)
Decrypt a bytestring with the selected algorithm for the given encrypted data dict, using the provided key (which must be of a compatible type and length).
- Parameters:
cipherdict (
dict
) -- dict with field "ciphertext" as bytestring and (depending on the cipher_algo) some other fields like "tag" or "nonce" as bytestringscipher_algo (
str
) -- one of the supported encryption algorithmskey_dict (
dict
) -- dict with secret key fieldsverify_integrity_tags (
bool
) -- whether to check MAC tags of the ciphertext
- Return type:
bytes
- Returns:
dictionary with encryption data.
- class wacryptolib.cipher.PayloadEncryptionPipeline(output_stream, payload_cipher_layer_extracts)
Bases:
object
PRIVATE API FOR NOW
Pipeline to encrypt data through several encryption nodes, and stream it to an output binary stream (e.g. file or ByteIO)
Private API
The objects below are only documented for the details they give on specific arguments.
AES with CBC mode
- class wacryptolib.cipher.AesCbcEncryptionNode(key_dict, payload_digest_algo=())
Bases:
EncryptionNodeBase
Encrypt a bytestring using AES (CBC mode).
- wacryptolib.cipher._encrypt_via_aes_cbc(plaintext, key_dict)
Encrypt a bytestring using AES (CBC mode).
- Parameters:
plaintext (
bytes
) -- the bytes to cipherkey_dict (
dict
) -- dict with AES cryptographic main key and iv. Main key must be 16, 24 or 32 bytes long (respectively for AES-128, AES-192 or AES-256).
- Return type:
dict
- Returns:
dict with field "ciphertext" as bytestring
- wacryptolib.cipher._decrypt_via_aes_cbc(cipherdict, key_dict, verify_integrity_tags=True)
Decrypt a bytestring using AES (CBC mode).
- Parameters:
cipherdict (
dict
) -- dict with field "ciphertext" as bytestringkey_dict (
dict
) -- dict with AES cryptographic main key and nonce.verify_integrity_tags (
bool
) -- whether to check MAC tags of the ciphertext (not applicable for this cipher)
- Return type:
bytes
- Returns:
the decrypted bytestring
AES with EAX mode
- class wacryptolib.cipher.AesEaxEncryptionNode(key_dict, payload_digest_algo=())
Bases:
EncryptionNodeBase
Encrypt a bytestring using AES (EAX mode).
- wacryptolib.cipher._encrypt_via_aes_eax(plaintext, key_dict)
Encrypt a bytestring using AES (EAX mode).
- Parameters:
plaintext (
bytes
) -- the bytes to cipherkey_dict (
dict
) -- dict with AES cryptographic main key and nonce. Main key must be 16, 24 or 32 bytes long (respectively for AES-128, AES-192 or AES-256).
- Return type:
dict
- Returns:
dict with fields "ciphertext" and "tag" as bytestrings
- wacryptolib.cipher._decrypt_via_aes_eax(cipherdict, key_dict, verify_integrity_tags=True)
Decrypt a bytestring using AES (EAX mode).
- Parameters:
cipherdict (
dict
) -- dict with fields "ciphertext", "tag" as bytestringskey_dict (
dict
) -- dict with AES cryptographic main key and nonce.verify_integrity_tags (
bool
) -- whether to check MAC tags of the ciphertext
- Return type:
bytes
- Returns:
the decrypted bytestring
ChaCha20_Poly1305
- class wacryptolib.cipher.Chacha20Poly1305EncryptionNode(key_dict, payload_digest_algo=())
Bases:
EncryptionNodeBase
Encrypt a bytestring using ChaCha20 with Poly1305 authentication.
- wacryptolib.cipher._encrypt_via_chacha20_poly1305(plaintext, key_dict)
Encrypt a bytestring with the stream cipher ChaCha20.
Additional cleartext data can be provided so that the generated mac tag also verifies its integrity.
- Parameters:
plaintext (
bytes
) -- the bytes to cipherkey_dict (
dict
) -- 32 bytes long cryptographic key and nonce
- Return type:
dict
- Returns:
dict with fields "ciphertext", "tag", and "header" as bytestrings
- wacryptolib.cipher._decrypt_via_chacha20_poly1305(cipherdict, key_dict, verify_integrity_tags=True)
Decrypt a bytestring with the stream cipher ChaCha20.
- Parameters:
cipherdict (
dict
) -- dict with fields "ciphertext", "tag" and "nonce" as bytestringskey_dict (
dict
) -- 32 bytes long cryptographic key and nonceverify_integrity_tags (
bool
) -- whether to check MAC tags of the ciphertext
- Return type:
bytes
- Returns:
the decrypted bytestring
RSA - PKCS#1 OAEP
- wacryptolib.cipher._encrypt_via_rsa_oaep(plaintext, key_dict)
Encrypt a bytestring with PKCS#1 RSA OAEP (asymmetric algo).
- Parameters:
plaintext (
bytes
) -- the bytes to cipherkey_dict (
dict
) -- dict with PUBLIC RSA key object (RSA.RsaKey)
- Return type:
dict
- Returns:
a dict with field digest_list, containing bytestring chunks of variable width.
- wacryptolib.cipher._decrypt_via_rsa_oaep(cipherdict, key_dict, verify_integrity_tags=True)
Decrypt a bytestring with PKCS#1 RSA OAEP (asymmetric algo).
- Parameters:
cipherdict (
dict
) -- list of ciphertext chunkskey_dict (
dict
) -- dict with PRIVATE RSA key object (RSA.RsaKey)verify_integrity_tags (
bool
) -- whether to check MAC tags of the ciphertext (not applicable for this cipher)
- Return type:
bytes
- Returns:
the decrypted bytestring