1Block Ciphers 2======================= 3 4Block ciphers are a n-bit permutation for some small n, typically 64 or 128 5bits. They are a cryptographic primitive used to generate higher level 6operations such as authenticated encryption. 7 8.. warning:: 9 10 In almost all cases, a bare block cipher is not what you should be using. 11 You probably want an authenticated cipher mode instead (see :ref:`cipher_modes`) 12 This interface is used to build higher level operations (such as cipher 13 modes or MACs), or in the very rare situation where ECB is required, 14 eg for compatibility with an existing system. 15 16.. cpp:class:: BlockCipher 17 18 .. cpp:function:: static std::unique_ptr<BlockCipher> create(const std::string& algo_spec, \ 19 const std::string& provider = "") 20 21 Create a new block cipher object, or else return null. 22 23 .. cpp:function:: static std::unique_ptr<BlockCipher> create_or_throw(const std::string& algo_spec, \ 24 const std::string& provider = "") 25 26 Like ``create``, except instead of returning null an exception is thrown 27 if the cipher is not known. 28 29 .. cpp:function:: void set_key(const uint8_t* key, size_t length) 30 31 This sets the key to the value specified. Most algorithms only accept keys 32 of certain lengths. If you attempt to call ``set_key`` with a key length 33 that is not supported, the exception ``Invalid_Key_Length`` will be 34 thrown. 35 36 In all cases, ``set_key`` must be called on an object before any data 37 processing (encryption, decryption, etc) is done by that object. If this 38 is not done, an exception will be thrown. 39 thrown. 40 41 .. cpp:function:: bool valid_keylength(size_t length) const 42 43 This function returns true if and only if *length* is a valid keylength for 44 this algorithm. 45 46 .. cpp:function:: size_t minimum_keylength() const 47 48 Return the smallest key length (in bytes) that is acceptable for the 49 algorithm. 50 51 .. cpp:function:: size_t maximum_keylength() const 52 53 Return the largest key length (in bytes) that is acceptable for the 54 algorithm. 55 56 .. cpp:function:: std::string name() const 57 58 Return a human readable name for this algorithm. This is guaranteed to round-trip with 59 ``create`` and ``create_or_throw`` calls, ie create("Foo")->name() == "Foo" 60 61 .. cpp:function:: void clear() 62 63 Zero out the key. The key must be reset before the cipher object can be used. 64 65 .. cpp:function:: BlockCipher* clone() const 66 67 Return a newly allocated BlockCipher object of the same type as this one. 68 69 .. cpp:function:: size_t block_size() const 70 71 Return the size (in *bytes*) of the cipher. 72 73 .. cpp:function:: size_t parallelism() const 74 75 Return the parallelism underlying this implementation of the cipher. This 76 value can vary across versions and machines. A return value of N means that 77 encrypting or decrypting with N blocks can operate in parallel. 78 79 .. cpp:function:: size_t parallel_bytes() const 80 81 Returns ``parallelism`` multiplied by the block size as well as a small 82 fudge factor. That's because even ciphers that have no implicit parallelism 83 typically see a small speedup for being called with several blocks due to 84 caching effects. 85 86 .. cpp:function:: std::string provider() const 87 88 Return the provider type. Default value is "base" but can be any arbitrary string. 89 Other example values are "sse2", "avx2", "openssl". 90 91 .. cpp:function:: void encrypt_n(const uint8_t in[], uint8_t out[], size_t blocks) const 92 93 Encrypt *blocks* blocks of data, taking the input from the array *in* and 94 placing the ciphertext into *out*. The two pointers may be identical, but 95 should not overlap ranges. 96 97 .. cpp:function:: void decrypt_n(const uint8_t in[], uint8_t out[], size_t blocks) const 98 99 Decrypt *blocks* blocks of data, taking the input from the array *in* and 100 placing the plaintext into *out*. The two pointers may be identical, but 101 should not overlap ranges. 102 103 .. cpp:function:: void encrypt(const uint8_t in[], uint8_t out[]) const 104 105 Encrypt a single block. Equivalent to :cpp:func:`encrypt_n`\ (in, out, 1). 106 107 .. cpp:function:: void encrypt(uint8_t block[]) const 108 109 Encrypt a single block. Equivalent to :cpp:func:`encrypt_n`\ (block, block, 1) 110 111 .. cpp:function:: void decrypt(const uint8_t in[], uint8_t out[]) const 112 113 Decrypt a single block. Equivalent to :cpp:func:`decrypt_n`\ (in, out, 1) 114 115 .. cpp:function:: void decrypt(uint8_t block[]) const 116 117 Decrypt a single block. Equivalent to :cpp:func:`decrypt_n`\ (block, block, 1) 118 119 .. cpp:function:: template<typename Alloc> void encrypt(std::vector<uint8_t, Alloc>& block) const 120 121 Assumes ``block`` is of a multiple of the block size. 122 123 .. cpp:function:: template<typename Alloc> void decrypt(std::vector<uint8_t, Alloc>& block) const 124 125 Assumes ``block`` is of a multiple of the block size. 126 127Code Example 128----------------- 129 130For sheer demonstrative purposes, the following code encrypts a provided single 131block of plaintext with AES-256 using two different keys. 132 133.. code-block:: cpp 134 135 #include <botan/block_cipher.h> 136 #include <botan/hex.h> 137 #include <iostream> 138 int main () 139 { 140 std::vector<uint8_t> key = Botan::hex_decode("000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F"); 141 std::vector<uint8_t> block = Botan::hex_decode("00112233445566778899AABBCCDDEEFF"); 142 std::unique_ptr<Botan::BlockCipher> cipher(Botan::BlockCipher::create("AES-256")); 143 cipher->set_key(key); 144 cipher->encrypt(block); 145 std::cout << std::endl <<cipher->name() << "single block encrypt: " << Botan::hex_encode(block); 146 147 //clear cipher for 2nd encryption with other key 148 cipher->clear(); 149 key = Botan::hex_decode("1337133713371337133713371337133713371337133713371337133713371337"); 150 cipher->set_key(key); 151 cipher->encrypt(block); 152 153 std::cout << std::endl << cipher->name() << "single block encrypt: " << Botan::hex_encode(block); 154 return 0; 155 } 156 157Available Ciphers 158--------------------- 159 160Botan includes a number of block ciphers that are specific to particular countries, as 161well as a few that are included mostly due to their use in specific protocols such as PGP 162but not widely used elsewhere. If you are developing new code and have no particular 163opinion, use AES-256. If you desire an alternative to AES, consider Serpent, SHACAL2 or 164Threefish. 165 166.. warning:: Avoid any 64-bit block cipher in new designs. There are 167 combinatoric issues that affect any 64-bit cipher that render it 168 insecure when large amounts of data are processed. 169 170AES 171~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 172 173Comes in three variants, AES-128, AES-192, and AES-256. 174 175The standard 128-bit block cipher. Many modern platforms offer hardware 176acceleration. However, on platforms without hardware support, AES 177implementations typically are vulnerable to side channel attacks. For x86 178systems with SSSE3 but without AES-NI, Botan has an implementation which avoids 179known side channels. 180 181Available if ``BOTAN_HAS_AES`` is defined. 182 183ARIA 184~~~~~~ 185 186South Korean cipher used in industry there. No reason to use it otherwise. 187 188Available if ``BOTAN_HAS_ARIA`` is defined. 189 190Blowfish 191~~~~~~~~~ 192 193A 64-bit cipher popular in the pre-AES era. Very slow key setup. Also used (with 194bcrypt) for password hashing. 195 196Available if ``BOTAN_HAS_BLOWFISH`` is defined. 197 198CAST-128 199~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 200 201A 64-bit cipher, commonly used in OpenPGP. 202 203Available if ``BOTAN_HAS_CAST128`` is defined. 204 205CAST-256 206~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 207 208A 128-bit cipher that was a contestant in the NIST AES competition. 209Almost never used in practice. Prefer AES or Serpent. 210 211Available if ``BOTAN_HAS_CAST256`` is defined. 212 213.. warning:: 214 Support for CAST-256 is deprecated and will be removed in a future major release. 215 216Camellia 217~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 218 219Comes in three variants, Camellia-128, Camellia-192, and Camellia-256. 220 221A Japanese design standardized by ISO, NESSIE and CRYPTREC. 222Rarely used outside of Japan. 223 224Available if ``BOTAN_HAS_CAMELLIA`` is defined. 225 226Cascade 227~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 228 229Creates a block cipher cascade, where each block is encrypted by two ciphers 230with independent keys. Useful if you're very paranoid. In practice any single 231good cipher (such as Serpent, SHACAL2, or AES-256) is more than sufficient. 232 233Available if ``BOTAN_HAS_CASCADE`` is defined. 234 235DES, 3DES, DESX 236~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 237 238Originally designed by IBM and NSA in the 1970s. Today, DES's 56-bit key renders 239it insecure to any well-resourced attacker. DESX and 3DES extend the key length, 240and are still thought to be secure, modulo the limitation of a 64-bit block. 241All are somewhat common in some industries such as finance. Avoid in new code. 242 243.. warning:: 244 Support for DESX is deprecated and it will be removed in a future major release. 245 246Available if ``BOTAN_HAS_DES`` is defined. 247 248GOST-28147-89 249~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 250 251Aka "Magma". An old 64-bit Russian cipher. Possible security issues, avoid 252unless compatibility is needed. 253 254Available if ``BOTAN_HAS_GOST_28147_89`` is defined. 255 256.. warning:: 257 Support for this cipher is deprecated and will be removed in a future major release. 258 259IDEA 260~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 261 262An older but still unbroken 64-bit cipher with a 128-bit key. Somewhat common 263due to its use in PGP. Avoid in new designs. 264 265Available if ``BOTAN_HAS_IDEA`` is defined. 266 267Kasumi 268~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 269 270A 64-bit cipher used in 3GPP mobile phone protocols. There is no reason to use 271it outside of this context. 272 273Available if ``BOTAN_HAS_KASUMI`` is defined. 274 275.. warning:: 276 Support for Kasumi is deprecated and will be removed in a future major release. 277 278Lion 279~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 280 281A "block cipher construction" which can encrypt blocks of nearly arbitrary 282length. Built from a stream cipher and a hash function. Useful in certain 283protocols where being able to encrypt large or arbitrary length blocks is 284necessary. 285 286Available if ``BOTAN_HAS_LION`` is defined. 287 288MISTY1 289~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 290 291A 64-bit Japanese cipher standardized by NESSIE and ISO. Seemingly secure, but 292quite slow and saw little adoption. No reason to use it in new code. 293 294Available if ``BOTAN_HAS_MISTY1`` is defined. 295 296.. warning:: 297 Support for MISTY1 is deprecated and will be removed in a future major release. 298 299Noekeon 300~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 301 302A fast 128-bit cipher by the designers of AES. Easily secured against side 303channels. 304 305Available if ``BOTAN_HAS_NOEKEON`` is defined. 306 307.. warning:: 308 Support for Noekeon is deprecated and will be removed in a future major release. 309 310SEED 311~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 312 313A older South Korean cipher, widely used in industry there. No reason to choose it otherwise. 314 315Available if ``BOTAN_HAS_SEED`` is defined. 316 317SHACAL2 318~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 319 320The 256-bit block cipher used inside SHA-256. Accepts up to a 512-bit key. 321Fast, especially when SIMD or SHA-2 acceleration instructions are available. 322Standardized by NESSIE but otherwise obscure. 323 324Available if ``BOTAN_HAS_SHACAL2`` is defined. 325 326SM4 327~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 328 329A 128-bit Chinese national cipher, required for use in certain commercial 330applications in China. Quite slow. Probably no reason to use it outside of legal 331requirements. 332 333Available if ``BOTAN_HAS_SM4`` is defined. 334 335Serpent 336~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 337 338An AES contender. Widely considered the most conservative design. Fairly slow 339unless SIMD instructions are available. 340 341Available if ``BOTAN_HAS_SERPENT`` is defined. 342 343Threefish-512 344~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 345 346A 512-bit tweakable block cipher that was used in the Skein hash function. 347Very fast on 64-bit processors. 348 349Available if ``BOTAN_HAS_THREEFISH_512`` is defined. 350 351Twofish 352~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 353 354A 128-bit block cipher that was one of the AES finalists. Has a somewhat complicated key 355setup and a "kitchen sink" design. 356 357Available if ``BOTAN_HAS_TWOFISH`` is defined. 358 359XTEA 360~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 361 362A 64-bit cipher popular for its simple implementation. Avoid in new code. 363 364Available if ``BOTAN_HAS_XTEA`` is defined. 365