Advanced encryption standard

From Crypto++ Wiki
(Redirected from AES)
Jump to navigation Jump to search

The Advanced Encryption Standard, or AES is a NIST approved block cipher specified in FIPS 197, Advanced Encryption Standard (AES). When using AES, one typically specifies a mode of operation and optionally a padding scheme. AES provides confidentiality only using most modes of operation (such as ECB and CBC). When operating the cipher in CCM, GCM, or EAX mode, the mode provides both confidentiality and authenticity.

If your project is using encryption alone to secure your data, encryption alone is usually not enough. Please take a moment to read Authenticated Encryption and understand why you should prefer to use CCM, GCM, or EAX over other modes, such as CBC or CTR.

Usage

Default Key Length

AES can use 16, 24, or 32 byte keys (128, 192, and 256 bits respectively). The default key length in Crypto++ is 16 bytes and specified by AES::DEFAULT_KEYLENGTH.

Block Size

The block size is determined by AES::BLOCKSIZE. For AES, this is always 16 bytes.

Instance of block cipher

When using AES (or any other block cipher) you typically you use a mode that "has a" instance of a block cipher. For example, for CFB mode you would write:

CFB_Mode<AES>::Encryption encryptor;

CFB_Mode takes the block cipher as a template parameter. Below is some pseudo code describing it:

template < class CIPHER >
class CFB_Mode
{
public:
    ...
private:
    CIPHER m_cipher;
};

Reference to block cipher

You can also create a mode object that holds a reference to an external block cipher object rather than an instance of it. Below is an example of using CFP mode with an external AES object:

AES::Encryption aesEncryption(key, AES::DEFAULT_KEYLENGTH);
CFB_Mode_ExternalCipher::Encryption cfbEncryption(aesEncryption, iv);

The ExternalCipher modes were added to support FIPS on Windows, and you should avoid it unless it is needed.

ECB and CBC mode remarks

For ECB and CBC mode, you must process data in multiples of the block size. Alternatively, you can wrap StreamTransformationFilter around the mode object and use it as a filter object. The StreamTransformationFilter will buffer data into blocks and pad as required.

Sample Programs

There are three sample programs. The first shows AES key and block sizes. The second and third use filters in a pipeline). Pipelining is a high level abstraction and it handles buffering input, buffering output and padding for you.

If you are benchmarking then you may want to visit Benchmarks | Sample Program . It shows you how to use StreamTransformation::ProcessString method to process blocks at a time. Calling a cipher's ProcessString or ProcessBlock eventually call a cipher's ProcessAndXorBlock or AdvancedProcessBlocks, and they are the lowest level API you can use.

The first snippet dumps the minimum, maximum, and default key lengths used by AES.

cout << "key length: " << AES::DEFAULT_KEYLENGTH << endl;
cout << "key length (min): " << AES::MIN_KEYLENGTH << endl;
cout << "key length (max): " << AES::MAX_KEYLENGTH << endl;
cout << "block size: " << AES::BLOCKSIZE << endl;

Output from the above snippet produces the following. Notice the default key size is 128 bits or 16 bytes.

key length: 16
key length (min): 16
key length (max): 32
block size: 16

Encrypting and Decrypting Using AES

The following example uses CFB mode and in-place encryption and decryption. Since the mode is not ECB or CBC, the data's length does not need to be a multiple of AES's block size.

AutoSeededRandomPool rnd;

// Generate a random key
SecByteBlock key(0x00, AES::DEFAULT_KEYLENGTH);
rnd.GenerateBlock( key, key.size() );

// Generate a random IV
SecByteBlock iv(AES::BLOCKSIZE);
rnd.GenerateBlock(iv, iv.size());

byte plainText[] = "Hello! How are you.";
size_tmessageLen = std::strlen((char*)plainText) + 1;

//////////////////////////////////////////////////////////////////////////
// Encrypt

CFB_Mode<AES>::Encryption cfbEncryption(key, key.size(), iv);
cfbEncryption.ProcessData(plainText, plainText, messageLen);

//////////////////////////////////////////////////////////////////////////
// Decrypt

CFB_Mode<AES>::Decryption cfbDecryption(key, key.size(), iv);
cfbDecryption.ProcessData(plainText, plainText, messageLen);

Here is an example of getting the encryptor and decryptor using an externally generated key and IV:

SecByteBlock aes_key(16);
SecByteBlock iv(16);

// stub for how you really get it, e.g. reading it from a file, off of a
//   network socket encrypted with an asymmetric cipher, or whatever
read_key(aes_key, aes_key.size());

// stub for how you really get it, e.g. filling it with random bytes or
//   reading it from the other side of the socket since both sides have
//   to use the same IV as well as the same key
read_initialization_vector(iv);

// the final argument is specific to CFB mode, and specifies the refeeding
//   size in bytes. This invocation corresponds to Java's
//   Cipher.getInstance("AES/CFB8/NoPadding")
auto enc = new CFB_Mode<AES>::Encryption(aes_key, sizeof(aes_key), iv, 1);

// the final argument is specific to CFB mode, and specifies the refeeding
//   size in bytes. This invocation corresponds to Java's
//   Cipher.getInstance("AES/CFB8/NoPadding")
auto dec = new CFB_Mode<AES>::Decryption(aes_key, sizeof(aes_key), iv, 1);

(After that they're used in exactly the same manner as in the previous example.)

Generating an AES Key from a Diffie-Hellman Session Key

See Using Diffie-Hellman to generate an AES key.

Downloads

AES-GCM-Test.zip - Demonstrates encryption and decryption using AES in GCM mode (confidentiality and authentication)

AES-CCM-Test.zip - Demonstrates encryption and decryption using AES in CCM mode (confidentiality and authentication)

AES-EAX-Test.zip - Demonstrates encryption and decryption using AES in EAX mode (confidentiality and authentication)

AES-ECB-Filter.zip - Demonstrates encryption and decryption using AES in ECB mode with filters (confidentiality only)

AES-CBC-Filter.zip - Demonstrates encryption and decryption using AES in CBC mode with filters (confidentiality only)

AES-CFB-Filter.zip - Demonstrates encryption and decryption using AES in CFB mode with filters (confidentiality only)

AES-OFB-Filter.zip - Demonstrates encryption and decryption using AES in OFB mode with filters (confidentiality only)

AES-CTR-Filter.zip - Demonstrates encryption and decryption using AES in CTR mode with filters (confidentiality only)