Package Cryptodome :: Package Util :: Module Counter

Module Counter

Fast counter functions for CTR cipher modes.

CTR is a chaining mode for symmetric block encryption or decryption. Messages are divideded into blocks, and the cipher operation takes place on each block using the secret key and a unique counter block.

The most straightforward way to fulfil the uniqueness property is to start with an initial, random counter block value, and increment it as the next block is processed.

The block ciphers from Cryptodome.Cipher (when configured in MODE_CTR mode) invoke a callable object (the counter parameter) to get the next counter block. Unfortunately, the Python calling protocol leads to major performance degradations.

The counter functions instantiated by this module will be invoked directly by the ciphers in Cryptodome.Cipher. The fact that the Python layer is bypassed lead to more efficient (and faster) execution of CTR cipher modes.

An example of usage is the following:

>>> from Cryptodome.Cipher import AES
>>> from Cryptodome.Util import Counter
>>> from Cryptodome import Random
>>>
>>> nonce = Random.get_random_bytes(8)
>>> ctr = Counter.new(64, nonce)
>>> key = b'AES-128 symm key'
>>> plaintext = b'X'*1000000
>>> cipher = AES.new(key, AES.MODE_CTR, counter=ctr)
>>> ciphertext = cipher.encrypt(plaintext)
Functions
 
new(nbits, prefix='', suffix='', initial_value=1, little_endian=False, allow_wraparound=False)
Create a stateful counter block function suitable for CTR encryption modes.
Variables
  __package__ = 'Cryptodome.Util'
Function Details

new(nbits, prefix='', suffix='', 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.

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

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.