:mod:`Crypto.Util` package
==========================

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

.. toctree::
    :hidden:
    
    asn1

:mod:`Crypto.Util.Padding` module
---------------------------------

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

    >>> from Crypto.Util.Padding import pad, unpad
    >>> from Crypto.Cipher import AES
    >>> from Crypto.Random import get_random_bytes
    >>>
    >>> data = b'Unaligned'   # 9 bytes
    >>> key = get_random_bytes(32)
    >>> iv = get_random_bytes(16)
    >>>
    >>> cipher1 = AES.new(key, AES.MODE_CBC, iv)
    >>> ct = cipher1.encrypt(pad(data, 16))
    >>>
    >>> cipher2 = AES.new(key, AES.MODE_CBC, iv)
    >>> pt = unpad(cipher2.decrypt(ct), 16)
    >>> assert(data == pt)

.. automodule:: Crypto.Util.Padding
    :members:

:mod:`Crypto.Util.RFC1751` module
---------------------------------

.. automodule:: Crypto.Util.RFC1751
    :members:

:mod:`Crypto.Util.strxor` module
--------------------------------

Fast XOR for byte strings.

.. automodule:: Crypto.Util.strxor
    :members:

:mod:`Crypto.Util.Counter` module
---------------------------------

The :mod:`Crypto.Util.Counter` module provides the functionality
to create more complex counter blocks for the CTR cipher mode.

Introduction to counter blocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:ref:`CTR <ctr_mode>` (Counter) is a mode of operation for block ciphers.
In CTR mode, the ciphertext is generated by dividing the plaintext into blocks
and then XOR-ing each block with a unique *keystream*.

The *keystream* is produced by encrypting a sequence of *counter blocks*,
which must all be distinct to prevent repetitions in the keystream.
Counter blocks themselves do not need to be kept secret.
Encryption is done using :ref:`ECB <ecb_mode>`.

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

Creating counter blocks without Counter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :func:`new` function, at the module level under ``Crypto.Cipher``,
allows you to create a new CTR cipher object for a specific base algorithm.
It provides parameters for defining the structure of the counter block:

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

The combined length of these two components must match the block size of the algorithm being used.
For example, in the case of AES, the block size is typically 16 bytes.

Creating counter blocks with Counter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you need a more complex structure for the counter block,
you can define it in advance with the function :func:`Crypto.Util.Counter.new()`,
and then pass it to :func:`new` of the cipher with the ``counter`` parameter.
The counter block can then have:

* 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:

.. figure:: counter_be.png
    :align: center

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

.. figure:: counter_le.png
    :align: center

This is an example of AES-CTR encryption with a custom counter::

    from Crypto.Cipher import AES
    from Crypto.Util import Counter
    from Crypto import Random
    
    # The counter block must be
    #
    # +--------+----------------+--------+
    # | nonce  +     counter    +  EFGH  +
    # +--------+----------------+--------+
    #  4 bytes      8 bytes       4 bytes
    nonce = Random.get_random_bytes(4)
    ctr = Counter.new(64, prefix=nonce, suffix=b'EFGH', 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)

.. automodule:: Crypto.Util.Counter
    :members:

:mod:`Crypto.Util.number` module
--------------------------------

.. automodule:: Crypto.Util.number
    :members: