Crypto.Util package

Useful modules that don’t belong in any other package.

Crypto.Util.Padding module

This module provides minimal support for adding and removing standard padding from data.

Crypto.Util.Padding.pad(data_to_pad, block_size, style='pkcs7')

Apply standard padding.

Parameters:
  • data_to_pad (byte string) – The data that needs to be padded.
  • block_size (integer) – The block boundary to use for padding. The output length is guaranteed to be a multiple of block_size.
  • style (string) – Padding algorithm. It can be ‘pkcs7’ (default), ‘iso7816’ or ‘x923’.
Returns:

the original data with the appropriate padding added at the end.

Return type:

byte string

Crypto.Util.Padding.unpad(padded_data, block_size, style='pkcs7')

Remove standard padding.

Parameters:
  • padded_data (byte string) – A piece of data with padding that needs to be stripped.
  • block_size (integer) – The block boundary to use for padding. The input length must be a multiple of block_size.
  • style (string) – Padding algorithm. It can be ‘pkcs7’ (default), ‘iso7816’ or ‘x923’.
Returns:

data without padding.

Return type:

byte string

Raises:

ValueError – if the padding is incorrect.

Crypto.Util.RFC1751 module

Crypto.Util.strxor module

Fast XOR for byte strings.

Crypto.Util.strxor.strxor(term1, term2)

XOR of two byte strings. They must have equal length.

Returns:A new byte string, term1 xored with term2.
Crypto.Util.strxor.strxor_c(term, c)

XOR of a byte string with a repeated sequence of characters.

Returns:A new byte string, term with all its bytes xored with c.

Crypto.Util.Counter module

Richer counter functions for CTR cipher mode.

CTR is a mode of operation for block ciphers.

The plaintext is broken up in blocks and each block is XOR-ed with a keystream to obtain the ciphertext. The keystream is produced by the encryption of a sequence of counter blocks, which all need to be different to avoid repetitions in the keystream. Counter blocks don’t need to be secret.

The most straightforward approach is to include a counter field, and increment it by one within each subsequent counter block.

The new() function at the module level under Crypto.Cipher instantiates a new CTR cipher object for the relevant base algorithm. Its parameters allow you define a counter block with a fixed structure:

  • an optional, fixed prefix
  • the counter field encoded in big endian mode

The length of the two components can vary, but together they must be as large as the block size (e.g. 16 bytes for AES).

Alternatively, the counter parameter can be used to pass a counter block object (created in advance with the function Crypto.Util.Counter.new()) for a more complex composition:

  • an optional, fixed prefix
  • the counter field, encoded in big endian or little endian mode
  • an optional, fixed suffix

As before, the total length must match the block size.

The counter blocks with a big endian counter will look like this:

../../_images/counter_be.png

The counter blocks with a little endian counter will look like this:

../../_images/counter_le.png

Example of AES-CTR encryption with custom counter:

from Crypto.Cipher import AES
from Crypto.Util import Counter
from Crypto import Random

nonce = Random.get_random_bytes(4)
ctr = Counter.new(64, prefix=nonce, suffix=b'ABCD', little_endian=True, initial_value=10)
key = b'AES-128 symm key'
plaintext = b'X'*1000000
cipher = AES.new(key, AES.MODE_CTR, counter=ctr)
ciphertext = cipher.encrypt(plaintext)
Crypto.Util.Counter.new(nbits, prefix=b'', suffix=b'', initial_value=1, little_endian=False, allow_wraparound=False)

Create a stateful counter block function suitable for CTR encryption modes.

Each call to the function returns the next counter block. Each counter block is made up by three parts:

prefix counter value postfix

The counter value is incremented by 1 at each call.

Parameters:
  • nbits (integer) – Length of the desired counter value, in bits. It must be a multiple of 8.
  • prefix (byte string) – The constant prefix of the counter block. By default, no prefix is used.
  • suffix (byte string) – The constant postfix of the counter block. By default, no suffix is used.
  • initial_value (integer) – The initial value of the counter. Default value is 1.
  • little_endian (boolean) – If True, the counter number will be encoded in little endian format. If False (default), in big endian format.
  • allow_wraparound (boolean) – This parameter is ignored.
Returns:

An object that can be passed with the counter parameter to a CTR mode cipher.

It must hold that len(prefix) + nbits//8 + len(suffix) matches the block size of the underlying block cipher.

Crypto.Util.number module