Cryptolib
Introduction
This module provides a set of classes and functions that can be used to encrypt and decrypt data.
The general principle is to create an object of the type of cipher with which you want to encrypt/decrypt. This object will be created with all required parameters once, after which it can be used multiple times to either encrypt or decrypt pieces of data.
Note
The cipher object will contain all information needed to encrypt/decrypt a piece of data. Depending on the block-mode used, this will also contain the intermediate state needed to chain multiple blocks of data. For these block-modes, an object can only be used for encryption or decryption, but not both at the same time.
MODE_ECB
is an exception because it does not use chaining, hence this object can be used
for both encryption and decryption at the same time.
Ciphers
- AES(key, mode, *, padding=None, iv=None):
Create a new AES cipher object. This object can then be used to encrypt and/or decrypt data.
- Parameters
key (bytes) –
The secret key to use.
It must be 16, 24 or 32 bytes long (respectively for AES-128, AES-192 and AES-256).
mode (One of the MODE_* constants.) – The chaining mode.
padding –
Padding algorithm to be automatically applied.
When provided, the cleartext will be automatically padded/unpadded. The value of this attribute is the style of padding to use.
This method can only be used if the complete data to be encrypted/decrypted is passed in as a whole. In case the data is encrypted in multiple invocations of
encrypt()
anddecrypt()
, manual (un)padding needs to be applied on the last block.See the documentation for
pad()
for the supported values.iv (bytes) –
The initial vector.
For mode
MODE_ECB
this argument is not valid.For mode
MODE_CBC
it must be 16 bytes long.If not provided (but required), a random bytestring is generated. You must then read its value via the
iv
attribute.
- encrypt(plaintext, /, *, output=None):
Encrypt a piece of plaintext.
The function either returns the encrypted data or places it in a preallocated buffer passed in via the
output
parameter.- Parameters
plaintext (bytes) – The plaintext that needs to be encrypted. Should be a multiple of the configured
block_size
, unless automatic padding is configured.output (bytearray) – Preallocated buffer into which the encrypted data is written. Must be of the correct size (ie the same length as the plaintext input). Cannot be used when the object is configured to automatically apply padding, as the size might increase due to an extra padding-block.
- Returns
the ciphertext or None when an
output
buffer was provided.
- decrypt(ciphertext, /, *, output=None):
Decrypt a piece of ciphertext.
The function either returns the plaintext or places it in a preallocated buffer passed in via the
output
parameter.- Parameters
ciphertext (bytes) – The ciphertext that needs to be decrypted. Should be a multiple of the configured
block_size
, unless automatic padding is configured.output (bytearray) – Preallocated buffer into which the decrypted plaintext is written. Must be of the correct size (ie the same length as the ciphertext input). Cannot be used when the object is configured to automatically apply padding, as the size might decrease due to an stripped padding.
- Returns
the cleartext or None when an
output
buffer was provided.
Note
All places where parameters of type bytes are expected, objects of type bytearray or str can also be provided.
Mode constants
- MODE_ECB
Electronic Code Book mode
- MODE_CBC
Cipher-Block Chaining mode
Utilities
- cryptolib.pad(data, block_size, /, style='pkcs7')
Apply standard padding.
- Parameters
data (bytes) – The data that needs to be padded.
block_size (int) – The block size to use. The output will be a multiple of block_size.
style (string) – Padding algorithm. It can be pkcs7 (default), iso7816 or x923.
- Returns
The original data with appropriate padding added to the end. If the length of
data
is already a multiple ofblock_size
, a whole extra block will be added.- Return type
bytes
- cryptolib.unpad(data, block_size, /, style='pkcs7')
Remove standard padding.
- Parameters
data (bytes) – The data that needs to be stripped of padding.
block_size (int) – The block size to use. The input must be a multiple of block_size.
style (string) – Padding algorithm. It can be pkcs7 (default), iso7816 or x923.
- Returns
The data without the padding-bytes.
- Return type
bytes
- Raises
ValueError – if the padding is incorrect.
Examples
Example 1: Encrypting
from cryptolib import AES, MODE_ECB
key = b'0123456789abcdef'
aes = AES(key, MODE_ECB, padding='pkcs7')
aes.encrypt(b'My super-secret message')
# b'\xd8V\x01\x08\xb9f\xad\xbe\xa1\xbe\x8c\xe4I0E\xc7J\xf1W\xf9\xa0\xf8\x18Nu\xb5\xbd\xe9L_E\xa7'
Example 2: Decrypting
from cryptolib import AES, MODE_ECB
key = b'0123456789abcdef'
aes = AES(key, MODE_ECB, padding='pkcs7')
aes.decrypt(b'\xd8V\x01\x08\xb9f\xad\xbe\xa1\xbe\x8c\xe4I0E\xc7J\xf1W\xf9\xa0\xf8\x18Nu\xb5\xbd\xe9L_E\xa7')
#b'My super-secret message'