AES Manual

About

An Advanced Encryption Standard (AES, also known as Rijndael) class to encrypt/decrypt data.

Warning
For encryption using the MAXON API see Stream Conversions Manual.
// This example demonstrates the encryption and decryption of a string.
// Some plain text to encrypt.
const Char plainText[] = "O brave new world / That has such people in't!";
const Int32 length = sizeof(plainText);
ApplicationOutput("Plain Text: @", maxon::String { plainText });
// Declare secret key and encryption block size.
const Int32 blockSize = 256; // in bits (either 128, 192 or 256)
const Char key[32] = { '7', 'c', '3', '0', 'e', '0', '0', 'b', 'b', '6', '2', '7', '1', '4', '9', '5' }; // either 16, 24 or 32 bytes
const Int32 keyLength = sizeof(key) * 8; // in bits (either 128, 192 or 256)
DebugAssert((keyLength == 128) || (keyLength == 192) || (keyLength == 256));
// Memory to store the encrypted data.
void* buffer = nullptr;
Int encryptedSize = 0;
// Encrypt data.
{
// Get size of the memory needed to store the encrypted data.
encryptedSize = AES::CalcEncryptedDataSize(blockSize, length);
DebugAssert(encryptedSize >= length); // Note: encrytedSize is always equal or larger than unencrypted size.
// Allocate needed memory.
buffer = NewMem(char, encryptedSize) iferr_return; // No need to clear memory here, will be filled with random data next.
// Fill buffer with random content for increased security (the buffer part behind plainText is also input to the encryption).
maxon::Block<UChar> memBlock((UChar*)buffer, encryptedSize);
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// Copy the given text into the memory.
CopyMem(plainText, buffer, length);
if (aes && aes->Init(blockSize, keyLength))
{
aes->Encrypt(buffer, encryptedSize, key);
}
}
// Decrypt data again.
{
if (buffer && aes && aes->Init(blockSize, keyLength))
{
if (aes->Decrypt(buffer, encryptedSize, key))
{
const maxon::String text { (char*)buffer };
ApplicationOutput("Plain Text: @", text);
}
}
}
DeleteMem(buffer);

Create

AES objects are created with the usual tools, see Entity Creation and Destruction Manual (Classic).

Use

  • AES::Init(): Initializes the AES cipher to the given block length and key length.
  • AES::CalcEncryptedDataSize(): Calculates the size of the data block (data size + encryption overhead).
    Note
    The encrypted data size is always equal or larger than the unencrypted data size.

Encryption / Decryption

  • AES::Encrypt(): Encrypts a data block.
  • AES::Decrypt(): Decrypts a data block.
    Note
    Use a buffer of encrypted data size for both operations.
    Warning
    It is recommended to fill the end of the buffer (encrypted size >= data size, so the part after the data to encrypt) with random values (e.g. via maxon::SecureRandom) to increase security.

Further Reading

maxon::SecureRandom::GetDefaultProvider
static MAXON_METHOD SecureRandomProvider GetDefaultProvider()
Int
maxon::Int Int
Definition: ge_sys_math.h:64
AES::Init
Bool Init(Int32 lBlockLength, Int32 lKeyLength)
maxon::String
Definition: string.h:1213
iferr_return
#define iferr_return
Definition: resultbase.h:1465
AES::CalcEncryptedDataSize
static Int CalcEncryptedDataSize(Int32 lBlockLength, Int lDataLength)
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
UChar
maxon::UChar UChar
Definition: ge_sys_math.h:57
maxon::SecureRandom::GetRandomNumber
static MAXON_METHOD Bool GetRandomNumber(SecureRandomProvider provider, const Block< Byte > &buffer)
maxon::DeleteMem
void DeleteMem(T *&p)
Definition: defaultallocator.h:257
AES::Encrypt
Bool Encrypt(void *pData, Int lDataLength, const void *pKey)
Int32
maxon::Int32 Int32
Definition: ge_sys_math.h:60
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:208
AutoAlloc
Definition: ge_autoptr.h:36
NewMem
#define NewMem(T, cnt)
Definition: defaultallocator.h:195
AES::Decrypt
Bool Decrypt(void *pData, Int lDataLength, const void *pKey)
DebugAssert
#define DebugAssert(condition,...)
Definition: debugdiagnostics.h:246
maxon::BaseRef
Definition: apibase.h:1527
Char
maxon::Char Char
Definition: ge_sys_math.h:56
CopyMem
void CopyMem(const void *s, void *d, Int size)
Definition: c4d_memory.h:66
maxon::Block
Definition: apibase.h:302