Cryptolib
=========

.. module:: cryptolib
   :synopsis: cryptographic functions

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

.. class:: 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.

    :param bytes key: The secret key to use.

        It must be 16, 24 or 32 bytes long (respectively for *AES-128*, *AES-192* and *AES-256*).

    :param mode: The chaining mode.
    :type mode: One of the :ref:`MODE_* <cryptolib_mode_constants>` constants.

    :param 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 :func:`encrypt` and  :func:`decrypt`,
        manual (un)padding needs to be applied on the last block.

        See the documentation for :func:`pad` for the supported values.
    
    :param bytes iv: 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 :attr:`iv` attribute.

    .. method:: 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.

        :param bytes plaintext:

            The plaintext that needs to be encrypted.
            Should be a multiple of the configured ``block_size``, unless automatic padding is configured.

        :param bytearray output:

            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.


    .. method:: 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.

        :param bytes ciphertext:

            The ciphertext that needs to be decrypted.
            Should be a multiple of the configured ``block_size``, unless automatic padding is configured.

        :param bytearray output:

            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.

   
.. _cryptolib_mode_constants: 
Mode constants
--------------

MODE_ECB
    Electronic Code Book mode

MODE_CBC
    Cipher-Block Chaining mode

Utilities
---------

.. function:: pad(data, block_size, /, style='pkcs7')

    Apply standard padding.

    :param bytes data: The data that needs to be padded.
    :param int block_size: The block size to use. The output will be a multiple of `block_size`.
    :param string style: Padding algorithm. It can be `pkcs7` (default), `iso7816` or `x923`.
    :return: 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.
    :rtype: bytes

    ..
.. function:: unpad(data, block_size, /, style='pkcs7')

    Remove standard padding.

    :param bytes data: The data that needs to be stripped of padding.
    :param int block_size: The block size to use. The input must be a multiple of `block_size`.
    :param string style: Padding algorithm. It can be `pkcs7` (default), `iso7816` or `x923`.
    :return: The data without the padding-bytes.
    :rtype: 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'