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 bytestrings

  • cipher_algo (str) -- one of the supported encryption algorithms

  • key_dict (dict) -- dict with secret key fields

  • verify_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 cipher

  • key_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 bytestring

  • key_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 cipher

  • key_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 bytestrings

  • key_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 cipher

  • key_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 bytestrings

  • key_dict (dict) -- 32 bytes long cryptographic key and nonce

  • verify_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 cipher

  • key_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 chunks

  • key_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