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() and decrypt(), 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 of block_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'