Block Ciphers
=======================

Block ciphers are a n-bit permutation for some small n, typically 64 or 128
bits.  They are a cryptographic primitive used to generate higher level
operations such as authenticated encryption.

.. note::

   In general a bare block cipher is not what you should be using. You probably
   want a cipher mode instead (see :ref:`cipher_modes`)

.. cpp:class:: BlockCipher

  .. cpp:function:: static std::unique_ptr<BlockCipher> create(const std::string& algo_spec, \
                                                               const std::string& provider = "")

      Create a new block cipher object, or else return null.

  .. cpp:function:: static std::unique_ptr<BlockCipher> create_or_throw(const std::string& algo_spec, \
                                                                        const std::string& provider = "")

      Like ``create``, except instead of returning null an exception is thrown
      if the cipher is not known.

  .. cpp:function:: void set_key(const uint8_t* key, size_t length)

      This sets the key to the value specified. Most algorithms only accept keys
      of certain lengths. If you attempt to call ``set_key`` with a key length
      that is not supported, the exception ``Invalid_Key_Length`` will be
      thrown.

      In all cases, ``set_key`` must be called on an object before any data
      processing (encryption, decryption, etc) is done by that object. If this
      is not done, an exception will be thrown.
      thrown.

  .. cpp:function:: bool valid_keylength(size_t length) const

     This function returns true if and only if *length* is a valid keylength for
     this algorithm.

  .. cpp:function:: size_t minimum_keylength() const

     Return the smallest key length (in bytes) that is acceptible for the
     algorithm.

  .. cpp:function:: size_t maximum_keylength() const

     Return the largest key length (in bytes) that is acceptible for the
     algorithm.

  .. cpp:function:: std::string name() const

      Return a human readable name for this algorithm. This is guaranteed to round-trip with
      ``create`` and ``create_or_throw`` calls, ie create("Foo")->name() == "Foo"

  .. cpp:function:: void clear()

     Zero out the key. The key must be reset before the cipher object can be used.

  .. cpp:function:: BlockCipher* clone() const

     Return a newly allocated BlockCipher object of the same type as this one.

  .. cpp:function:: size_t block_size() const

      Return the size (in *bytes*) of the cipher.

  .. cpp:function:: size_t parallelism() const

     Return the parallelism underlying this implementation of the cipher. This
     value can vary across versions and machines. A return value of N means that
     encrypting or decrypting with N blocks can operate in parallel.

  .. cpp:function:: size_t parallel_bytes() const

     Returns ``parallelism`` multiplied by the block size as well as a small
     fudge factor. That's because even ciphers that have no implicit parallism
     typically see a small speedup for being called with several blocks due to
     caching effects.

  .. cpp:function:: std::string provider() const

     Return the provider type. Default value is "base" but can be any arbitrary string.
     Other example values are "sse2", "avx2", "openssl".

  .. cpp:function:: void encrypt_n(const uint8_t in[], uint8_t out[], size_t blocks) const

     Encrypt *blocks* blocks of data, taking the input from the array *in* and
     placing the ciphertext into *out*. The two pointers may be identical, but
     should not overlap ranges.

  .. cpp:function:: void decrypt_n(const uint8_t in[], uint8_t out[], size_t blocks) const

     Decrypt *blocks* blocks of data, taking the input from the array *in* and
     placing the plaintext into *out*. The two pointers may be identical, but
     should not overlap ranges.

  .. cpp:function:: void encrypt(const uint8_t in[], uint8_t out[]) const

     Encrypt a single block. Equivalent to :cpp:func:`encrypt_n`\ (in, out, 1).

  .. cpp:function:: void encrypt(uint8_t block[]) const

     Encrypt a single block. Equivalent to :cpp:func:`encrypt_n`\ (block, block, 1)

  .. cpp:function:: void decrypt(const uint8_t in[], uint8_t out[]) const

     Decrypt a single block. Equivalent to :cpp:func:`decrypt_n`\ (in, out, 1)

  .. cpp:function:: void decrypt(uint8_t block[]) const

     Decrypt a single block. Equivalent to :cpp:func:`decrypt_n`\ (block, block, 1)

  .. cpp:function:: template<typename Alloc> void encrypt(std::vector<uint8_t, Alloc>& block) const

     Assumes ``block`` is of a multiple of the block size.

  .. cpp:function:: template<typename Alloc> void decrypt(std::vector<uint8_t, Alloc>& block) const

     Assumes ``block`` is of a multiple of the block size.

Code Example
-----------------

For sheer demonstrative purposes, the following code encrypts a provided single
block of plaintext with AES-256 using two different keys.

.. code-block:: cpp

    #include <botan/block_cipher.h>
    #include <botan/hex.h>
    #include <iostream>
    int main ()
       {
       std::vector<uint8_t> key = Botan::hex_decode("000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F");
       std::vector<uint8_t> block = Botan::hex_decode("00112233445566778899AABBCCDDEEFF");
       std::unique_ptr<Botan::BlockCipher> cipher(Botan::BlockCipher::create("AES-256"));
       cipher->set_key(key);
       cipher->encrypt(block);
       std::cout << std::endl <<cipher->name() << "single block encrypt: " << Botan::hex_encode(block);

       //clear cipher for 2nd encryption with other key
       cipher->clear();
       key = Botan::hex_decode("1337133713371337133713371337133713371337133713371337133713371337");
       cipher->set_key(key);
       cipher->encrypt(block);

       std::cout << std::endl << cipher->name() << "single block encrypt: " << Botan::hex_encode(block);
       return 0;
       }

Available Ciphers
---------------------

Botan includes a number of block ciphers that are specific to particular
countries, as well as a few that are included mostly due to their use in
specific protocols such as PGP but not widely used elsewhere. The ciphers that
seem best for new code are AES, Serpent, and Threefish-512.

Avoid any 64-bit cipher in new code. There are combinatoric issues that affect
any 64-bit cipher that render it insecure when large amounts of data are
processed.

AES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Comes in three variants, AES-128, AES-192, and AES-256.

The standard 128-bit block cipher. Many modern platforms offer hardware
acceleration. However, on platforms without hardware support, AES
implementations typically are vulnerable to side channel attacks.

If you are developing new code and have no particular opinion, pick AES.

Available if ``BOTAN_HAS_AES`` is defined.

ARIA
~~~~~~

South Korean cipher used in industry there. No reason to use it otherwise.

Available if ``BOTAN_HAS_ARIA`` is defined.

Blowfish
~~~~~~~~~

A 64-bit cipher popular in the pre-AES era. Very slow key setup. Also used (with
bcrypt) for password hashing.

Available if ``BOTAN_HAS_BLOWFISH`` is defined.

CAST-128
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A 64-bit cipher, commonly used in OpenPGP.

Available if ``BOTAN_HAS_CAST128`` is defined.

CAST-256
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A 128-bit cipher that was a contestent in the NIST AES competition.
Rarely used, and now deprecated in Botan. Use AES or Serpent instead.

Available if ``BOTAN_HAS_CAST256`` is defined.

Camellia
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Comes in three variants, Camellia-128, Camellia-192, and Camellia-256.

A Japanese design standardized by ISO, NESSIE and CRYPTREC. Somewhat common.
Prefer AES or Serpent in new designs.

Available if ``BOTAN_HAS_CAMELLIA`` is defined.

Cascade
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Creates a block cipher cascade, where each block is encrypted by two ciphers
with independent keys. Useful if you're very paranoid. In practice any single
good cipher (such as Serpent, SHACAL2, or AES-256) is more than sufficient.

Available if ``BOTAN_HAS_CASCADE`` is defined.

DES, 3DES, DESX
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Originally designed by IBM and NSA in the 1970s. Very slow, but still common in
some industries such as finance. Avoid in new code.

Available if ``BOTAN_HAS_DES`` is defined.

GOST-28147-89
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A old 64-bit Russian cipher. Possible security issues. Avoid unless
compatability is needed.

Available if ``BOTAN_HAS_GOST_28147_89`` is defined.

IDEA
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

An older but still unbroken 64-bit cipher with a 128-bit key. Somewhat common
due to its use in PGP. Avoid in new designs.

Available if ``BOTAN_HAS_IDEA`` is defined.

Kasumi
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A 64-bit cipher used in 3GPP mobile phone protocols. There is no reason to use
it outside of this context.

Available if ``BOTAN_HAS_KASUMI`` is defined.

Lion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A "block cipher construction" which can encrypt blocks of nearly arbitrary
length.  Built from a stream cipher and a hash function. Useful in certain
protocols where being able to encrypt large or arbitrary length blocks is
necessary.

Available if ``BOTAN_HAS_LION`` is defined.

MISTY1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A 64-bit Japanese cipher standardized by NESSIE and ISO. Seemingly secure, but
quite slow and saw little adoption. No reason to use it in new code. The
implementation in Botan is deprecated, and it is likely to be removed in a
future release.

Available if ``BOTAN_HAS_MISTY1`` is defined.

Noekeon
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A fast 128-bit cipher by the designers of AES. Easily secured against side
channels.

Available if ``BOTAN_HAS_NOEKEON`` is defined.

SEED
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A older South Korean cipher, widely used in industry there.

Available if ``BOTAN_HAS_SEED`` is defined.

SHACAL2
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The 256-bit block cipher used inside SHA-256. Accepts up to a 512-bit key.
Fast and seemingly very secure, but obscure. Standardized by NESSIE.

Available if ``BOTAN_HAS_SHACAL2`` is defined.

SM4
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A 128-bit Chinese national cipher, required for use in certain commercial
applications in China. Quite slow. Probably no reason to use it outside of legal
requirements.

Available if ``BOTAN_HAS_SM4`` is defined.

Serpent
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

An AES contender. Widely considered the most conservative design. Fairly slow,
especially if no SIMD instruction set is available.

Available if ``BOTAN_HAS_SERPENT`` is defined.

Threefish-512
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A 512-bit tweakable block cipher that was used in the Skein hash function.
Very fast on 64-bit processors.

Available if ``BOTAN_HAS_THREEFISH_512`` is defined.

Twofish
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

An AES contender. Somewhat complicated key setup and a "kitchen sink" design.

Available if ``BOTAN_HAS_TWOFISH`` is defined.

XTEA
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A 64-bit cipher popular for its simple implementation. Avoid in new code.

Available if ``BOTAN_HAS_XTEA`` is defined.