AES encryption and decryption class. More...

Inheritance diagram for MAes:

Public Types
enum	{ KeySize = 16, BlockSize = 16, KeyWrapEncryptionExtraSize = 8, KeyWrapMinimumSize = KeySize, KeyWrapMaximumSize = 2048 }

Public Member Functions
	MAes ()
	Create AES encryption class without setting the key. More...

	MAes (const MByteString &key)
	Create AES encryption class with key, given as raw 16 bytes. More...

	MAes (const MAes &other)
	Copy constructor, creates a copy of a given object. More...

virtual	~MAes ()
	Destructor, reclaims memory allocated by the object.

MAes &	operator= (const MAes &other)
	Assignment operator that copies the key from another class. More...

MByteString	Encrypt (const MByteString &plainText)
	Encrypt a given chunk of data with AES using plain and simple ECB mode. More...

MByteString	Decrypt (const MByteString &cipherText)
	Decrypt a given chunk of data with AES using plain and simple ECB mode. More...

MByteString	KeyWrap (const MByteString &keys)
	Wrap the given key material, one or more keys, using RFC 3394 key wrap algorithm. More...

MByteString	KeyUnwrap (const MByteString &cipher)
	Unwrap the given cipher and produce the original key material, one or more keys. More...


const MByteString &	GetKey () const

void	SetKey (const MByteString &)


MStdString	GetHexKey () const

void	SetHexKey (const MStdString &)


void	EncryptBuffer (const Muint8 plainText, Muint8 cipherText)

void	EncryptBuffer (const char plainText, char cipherText)


void	DecryptBuffer (const Muint8 cipherText, Muint8 plainText)

void	DecryptBuffer (const char cipherText, char plainText)


unsigned	KeyWrapBuffer (const Muint8 keyText, unsigned keyTextSize, Muint8 cipherText)

unsigned	KeyWrapBuffer (const char keyText, unsigned keyTextSize, char cipherText)


unsigned	KeyUnwrapBuffer (const Muint8 cipherText, unsigned cipherTextSize, Muint8 keyText)

unsigned	KeyUnwrapBuffer (const char cipherText, unsigned cipherTextSize, char keyText)

Public Member Functions inherited from MObject
virtual	~MObject ()
	Object destructor.

virtual const MClass *	GetClass () const =0
	Get the final class of the object. More...

virtual unsigned	GetEmbeddedSizeof () const
	For embedded object types, return the size of the class. More...

bool	IsEmbeddedObject () const
	Tell if the object is of embedded kind. More...

SHOW_INTERNAL MVariant	Call (const MStdString &name, const MVariant &params)
	Call the object service with parameters, given as variant. More...

MVariant	Call0 (const MStdString &name)
	Call the object service with no parameters. More...

MVariant	Call1 (const MStdString &name, const MVariant &p1)
	Call the object service with one parameter. More...

MVariant	Call2 (const MStdString &name, const MVariant &p1, const MVariant &p2)
	Call the object service with two parameter. More...

MVariant	Call3 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3)
	Call the object service with three parameter. More...

MVariant	Call4 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4)
	Call the object service with four parameter. More...

MVariant	Call5 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4, const MVariant &p5)
	Call the object service with five parameter. More...

MVariant	Call6 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4, const MVariant &p5, const MVariant &p6)
	Call the object service with six parameter. More...

virtual MVariant	CallV (const MStdString &name, const MVariant::VariantVector &params)
	Call the object service with parameters, given as variant vector. More...

virtual bool	IsPropertyPresent (const MStdString &name) const
	Tell if the property with the given name exists.

virtual bool	IsServicePresent (const MStdString &name) const
	Tell if the service with the given name exists.

virtual MVariant	GetProperty (const MStdString &name) const
	Get the property value using name of the property. More...

virtual void	SetProperty (const MStdString &name, const MVariant &value)
	Set the property using name of the property, and value. More...

virtual MStdStringVector	GetAllPropertyNames () const
	Return the list of publicly available properties, persistent or not. More...

virtual MStdStringVector	GetAllPersistentPropertyNames () const
	Return the list of persistent properties. More...

virtual void	SetPersistentPropertiesToDefault ()
	Set the persistent properties of the object to their default values. More...

virtual MVariant	GetPersistentPropertyDefaultValue (const MStdString &name) const
	Get the default value of persistent property with the name given. More...

virtual void	SetPersistentPropertyToDefault (const MStdString &name)
	Set the persistent property with the name given to default value. More...

virtual const char *	GetType () const
	Get the name of the type for the object (could be the same as class name).

virtual void	SetType (const MStdString &)
	Intentionally, it will set the name of the type for the object, but the service will not allow setting the name to anything other than the current name. More...

virtual void	Validate ()
	Validate internal structures of the object. More...

Static Public Member Functions
static void	CheckKeySizeValid (const MByteString &key)
	Verify the byte size of a given binary key is exactly 16 bytes. More...

static void	CheckHexKeySizeValid (const MStdString &key)
	Verify HEX representation and byte size of a given HEX key. More...

static MByteString	StaticEncrypt (const MByteString &key, const MByteString &plainText)
	Static version of Encrypt that accepts key as parameter. More...

static MByteString	StaticDecrypt (const MByteString &key, const MByteString &cipherText)
	Static version of Decrypt that accepts key as parameter. More...

static MByteString	StaticKeyWrap (const MByteString &key, const MByteString &keys)
	Static variant of KeyWrap. More...

static MByteString	StaticKeyUnwrap (const MByteString &key, const MByteString &cipher)
	Static variant of KeyUnwrap. More...

static M_NORETURN_FUNC void	ThrowValidationError ()
	Throw an error that tells about a validation problem in the encrypted or authenticated message. More...


static void	DestroySecureData (MByteString &data)

static void	DestroySecureData (MByteStringVector &data)

static void	DestroySecureData (Muint8 *data, unsigned size)

static void	DestroySecureData (char *data, unsigned size)


static void	AssignSecureData (MByteString &destination, const MByteString &source)

static void	AssignSecureData (MByteStringVector &destination, const MByteStringVector &source)


static void	MoveSecureData (MByteString &destination, MByteString &source)

static void	MoveSecureData (MByteStringVector &destination, MByteStringVector &source)


static void	SwapSecureData (MByteString &v1, MByteString &v2)

static void	SwapSecureData (MByteStringVector &v1, MByteStringVector &v2)

Static Public Member Functions inherited from MObject
static const MClass *	GetStaticClass ()
	Get the declared class of this particular object. More...

static bool	IsClassPresent (const MStdString &name)
	Tells if the given class name is available. More...

Additional Inherited Members
Static Public Attributes inherited from MObject
static const MClass	s_class
	Class of MObject.

Protected Member Functions inherited from MObject
	MObject ()
	Object constructor, protected as the class is abstract.

void	DoSetPersistentPropertiesToDefault (const MClass *staticClass)
	Set the persistent properties to their default values for one object provided the class for that object. More...

Detailed Description

AES encryption and decryption class.

Currently only 128-bit AES key is supported, but the interface is generic to support other sizes. Different from all the other MeteringSDK classes that accept AES key as a sequence of hexadecimal characters, this class is primarily using the key as a raw byte string exactly 16 bytes long. There is a special extra property GetHexKey that does the necessary conversion.

This class implements the simplest possible ECB mode, in which every chunk of 16 bytes gets parameterless translation into cipher using key. ECB mode has known security issues as the 16-byte chunks of data with the same contents will produce the very same 16-byte chunks of cipher. This fact presents to an attacker the unwanted knowledge about the contents of plain text. ECB mode is still usable for cases when the data to encrypt has a good entropy, and never repeats, such as cryptographic hash or a key itself.

For EAX mode refer to MAesEax There is also EAX-mode authentication.

Only one thread shall access this object at a time, however since encryption and decryption are long operations, it is a better design to have a per-thread instance of MAes.

Member Enumeration Documentation

anonymous enum

Enumerator
KeySize	Supported binary key size in bytes of this AES algorithm. Currently this is only 16 bytes, which corresponds to 128-bit AES.
BlockSize	AES encryption block size. This is 16 bytes.
KeyWrapEncryptionExtraSize	Extra size added to key material at wrapping.
KeyWrapMinimumSize	Maximum size of key material for key wrap. The result encrypted key material will be KeyWrapMinimumSize + KeyWrapEncryptionExtraSize.
KeyWrapMaximumSize	Maximum size of key material for key wrap. The result encrypted key material will be KeyWrapMaximumSize + KeyWrapEncryptionExtraSize.

Constructor & Destructor Documentation

MAes::MAes ( )

Create AES encryption class without setting the key.

Any attempt to use this class prior to setting the key will fail with an exception.

MAes::MAes ( const MByteString & key )

Create AES encryption class with key, given as raw 16 bytes.

After successful initialization, assuming the key has correct size, the result object can be used for data encryption or decryption.

Parameters

key	Raw 16 bytes, key to use during encryption or decryption.

MAes::MAes ( const MAes & other )

Copy constructor, creates a copy of a given object.

The key gets copied, if the other object has it set. If the other object does not have key, the result MAes object will have to be assigned a key before using it for encryption.

Parameters

other An object from which to create a copy.

Member Function Documentation

static void MAes::AssignSecureData	(	MByteString &	destination,
		const MByteString &	source
	)

static

Assign one secure data such as key or password to another variable.

As the data size of a new buffer can be different as a safety measure the previous contents of the destination is erased.

Parameters

destination	Where to put the new secure material.
source	From which value to copy data. The source value does not change.

See also: MoveSecureData(MByteString& destination, MByteString& source); MoveSecureData(MByteStringVector& destination, MByteStringVector& source); SwapSecureData(MByteString& v1, MByteString& v2);; SwapSecureData(MByteStringVector& v1, MByteStringVector& v2)

static void MAes::AssignSecureData	(	MByteStringVector &	destination,
		const MByteStringVector &	source
	)

static

Assign one secure data such as key or password to another variable.

As the data size of a new buffer can be different as a safety measure the previous contents of the destination is erased.

Parameters

destination	Where to put the new secure material.
source	From which value to copy data. The source value does not change.

See also: MoveSecureData(MByteString& destination, MByteString& source); MoveSecureData(MByteStringVector& destination, MByteStringVector& source); SwapSecureData(MByteString& v1, MByteString& v2);; SwapSecureData(MByteStringVector& v1, MByteStringVector& v2)

static void MAes::CheckHexKeySizeValid ( const MStdString & key )

static

Verify HEX representation and byte size of a given HEX key.

For the call to succeed, the given string shall be a valid sequence of hex digits that evaluates into 16-byte raw data. Hex digits can have blanks, however no blank shall split the hex pair.

Examples of valid HEX key:

"000102030405060708090A0B0C0D0E0F"
"0102 0304 0506 0708 090A 0B0C 0D0E 0F00"

Parameters

key	The hex representation of key which size is to be checked.

static void MAes::CheckKeySizeValid ( const MByteString & key )

static

Verify the byte size of a given binary key is exactly 16 bytes.

An exception is thrown if the given binary key has size other than 16 bytes.

Parameters

key	The key which size is to be checked.

MByteString MAes::Decrypt ( const MByteString & cipherText )

Decrypt a given chunk of data with AES using plain and simple ECB mode.

ECB mode has known security issues as the 16-byte chunks of data with the same contents will produce the same 16-byte chunks of cipher. This fact presents to an attacker the unwanted knowledge about the contents of plain text. ECB mode is still usable for cases when the data to encrypt has a good entropy, and never repeats, such as cryptographic hash.

For cases other than encrypting random or pseudorandom data, EAX mode of AES is preferred, see class MAesEax. This mode is also capable of handling data of sizes not divisible by 16.

When decryption is to be done once for a given key, StaticDecrypt() call is more convenient, but when key has to be reused for decryption of many chunks, using MAes::Decrypt() yields better performance when it reuses the same MAes instance. This is because there is a key expansion algorithm that is performed per single key assignment.

Precondition: Key shall be set to MAes instance, or an exception is thrown.

Parameters

cipherText Raw bytes of size divisible by 16. If the size is not divisible by 16, an exception is thrown.

Returns: MByteString - result plain text, same size as cipherText.

See also: Encrypt - how to encrypt the data using ECB mode.; StaticDecrypt - static version, method of a class that gets key as parameter.

void MAes::DecryptBuffer	(	const Muint8 *	cipherText,
		Muint8 *	plainText
	)

Decrypt buffer of size equal to block size

Cipher text and plain text can be the same buffer in which case the plain text will be decrypted in-place.

Parameters

cipherText	Buffer of size 16 bytes, previously encrypted with this key.
plainText	Result buffer of size 16 bytes.

void MAes::DecryptBuffer	(	const char *	cipherText,
		char *	plainText
	)

inline

Decrypt buffer of size equal to block size

Cipher text and plain text can be the same buffer in which case the plain text will be decrypted in-place.

Parameters

cipherText	Buffer of size 16 bytes, previously encrypted with this key.
plainText	Result buffer of size 16 bytes.

static void MAes::DestroySecureData ( MByteString & data )

static

Destroy secure data such as key, password and so on.

The memory area denoted by the data will be filled with zeros. Only the data are erased, while the array sizes are unchanged.

static void MAes::DestroySecureData ( MByteStringVector & data )

static

Destroy secure data such as key, password and so on.

The memory area denoted by the data will be filled with zeros. Only the data are erased, while the array sizes are unchanged.

static void MAes::DestroySecureData	(	Muint8 *	data,
		unsigned	size
	)

inlinestatic

Destroy secure data such as key, password and so on.

The memory area denoted by the data will be filled with zeros. Only the data are erased, while the array sizes are unchanged.

static void MAes::DestroySecureData	(	char *	data,
		unsigned	size
	)

inlinestatic

Destroy secure data such as key, password and so on.

The memory area denoted by the data will be filled with zeros. Only the data are erased, while the array sizes are unchanged.

MByteString MAes::Encrypt ( const MByteString & plainText )

Encrypt a given chunk of data with AES using plain and simple ECB mode.

ECB mode has known security issues as the 16-byte chunks of data with the same contents will produce the same 16-byte chunks of cipher. This fact presents to an attacker the unwanted knowledge about the contents of plain text. ECB mode is still usable for cases when the data to encrypt has a good entropy, and never repeats, such as cryptographic hash.

For cases other than encrypting random or pseudorandom data, EAX mode of AES is preferred, see class MAesEax. This mode is also capable of handling data of sizes not divisible by 16.

When decryption is to be done once for a given key, StaticDecrypt() call is more convenient, but when key has to be reused for decryption of many chunks, using MAes::Decrypt() yields better performance when it reuses the same MAes instance. This is because there is a key expansion algorithm that is performed per single key assignment.

Precondition: Key shall be set to MAes instance, or an exception is thrown.

Parameters

plainText Raw bytes of size divisible by 16. If the size is not divisible by 16, an exception is thrown.

Returns: MByteString - result cipher text, same size as plainText.

See also: Decrypt - decrypting the data encrypted by this method.; StaticEncrypt - static version, method of a class that gets key as parameter.

void MAes::EncryptBuffer	(	const Muint8 *	plainText,
		Muint8 *	cipherText
	)

Encrypt buffer of size equal to block size.

Plain text and cipher text can be the same buffer in which case the plain text will be encrypted in-place.

Parameters

plainText	Buffer of size 16 bytes.
cipherText	Result buffer of size 16 bytes.

void MAes::EncryptBuffer	(	const char *	plainText,
		char *	cipherText
	)

inline

Encrypt buffer of size equal to block size.

Plain text and cipher text can be the same buffer in which case the plain text will be encrypted in-place.

Parameters

plainText	Buffer of size 16 bytes.
cipherText	Result buffer of size 16 bytes.

MStdString MAes::GetHexKey ( ) const

AES Key to use by the class, hexadecimal representation.

The key has binary form, not hex, which is different from all the other MeteringSDK classes that accept AES key as a sequence of hexadecimal characters.

Since: MeteringSDK Version 5.0.

Precondition: When assigning to this property, the given key must be a proper hexadecimal string that evaluates into exactly 16 bytes in size, or an invalid size exception will be thrown. Hexadecimal string can have blanks for clarity, but such blanks must not split pairs of hexadecimal digits that represent the key.

See also: GetKey property for handling key given as raw bytes.

const MByteString& MAes::GetKey ( ) const

inline

AES Key to use by the class, binary representation.

The key has binary form, not hex, which is different from all the other MeteringSDK classes that accept AES key as a sequence of hexadecimal characters.

Precondition: When assigning to this property, the given key must be exactly 16 bytes in size, or an invalid size exception will be thrown.

See also: GetHexKey property for handling key given as a sequence of hexadecimal characters.

MByteString MAes::KeyUnwrap ( const MByteString & cipher )

Unwrap the given cipher and produce the original key material, one or more keys.

The key unwrap function takes a pointer to the full encrypted data including the encrypted header.

The return value is true if there was no error (i.e. the prefix matches the fixed prefix that we know we started with) or false if there was an error. In the case of error, the data is overwritten with zeros to avoid leaking information which might be used to guess the key (such as a known ciphertext attack).

Parameters

cipher Input that contains wrapped key material.

Returns: bytes - keys, the size is 8 bytes shorter than the given cipher.

See also: KeyWrap - reverse operation.; StaticKeyUnwrap - version that accepts key directly.

unsigned MAes::KeyUnwrapBuffer	(	const Muint8 *	cipherText,
		unsigned	cipherTextSize,
		Muint8 *	keyText
	)

Decrypt key material with AES key wrap algorithm.

If the key is not correct an exception will be thrown as the verification will not be successful. Plain text and cipher text can be the same buffer in which case the plain text will be decrypted in-place. However remember the size of cipher text buffer should be bigger by 8 bytes.

Parameters

cipherText	Encrypted buffer with key material that has to be decrypted and verified.
cipherTextSize	Size of the encrypted buffer.
keyText	Result cipher text, the buffer should be 8 bytes bigger than keyTextSize.

Returns: keyTextSize - 8 is returned, keyText buffer size.

See also: KeyUnwrap for complete description of functionality.

unsigned MAes::KeyUnwrapBuffer	(	const char *	cipherText,
		unsigned	cipherTextSize,
		char *	keyText
	)

inline

Decrypt key material with AES key wrap algorithm.

If the key is not correct an exception will be thrown as the verification will not be successful. Plain text and cipher text can be the same buffer in which case the plain text will be decrypted in-place. However remember the size of cipher text buffer should be bigger by 8 bytes.

Parameters

cipherText	Encrypted buffer with key material that has to be decrypted and verified.
cipherTextSize	Size of the encrypted buffer.
keyText	Result cipher text, the buffer should be 8 bytes bigger than keyTextSize.

Returns: keyTextSize - 8 is returned, keyText buffer size.

See also: KeyUnwrap for complete description of functionality.

MByteString MAes::KeyWrap ( const MByteString & keys )

Wrap the given key material, one or more keys, using RFC 3394 key wrap algorithm.

The key wrapping algorithm is described in a NIST document dated 16 November 2001 and titled "AES Key Wrap Specification" It is later accepted as RFC 3394.

The algorithm, as implemented here, is intended to be able to wrap an arbitrary number of 128-byte blocks (the specification allows for 64-bit blocks, but this is a simplification).

Key wrap:

initialize variables A_0 = IV (0xA6A6A6...)
for i=1...n, R_i^0 = P_i
calculate intermediate values
for j=0...5
for i=1...n
B = AES_K(A | R_i)
A = MSB_{64}(B) xor t, where t= (n*j)+1
R_i = LSB_{64}(B)
Output the results
C_0 = A
for i=1...n
C_i = R_i

Note that passed data pointer must start with 8 bytes of padding in front of the actual data, and that the data length must be an integral multiple of 8 bytes. In other words, if you have two 128-bit (16-byte) keys you need to wrap, the data pointer must point to a 24-byte buffer (16+8) with the actual data starting at offset 8. The code will then process the data in place (so it cannot be ROM) and uses the key encryption key (kek) which can be in ROM. When the algorithm completes, the entire buffer must be transmitted since the 8 prepended bytes are required to assure that the data has arrived intact.

Parameters

keys	One or more keys, should be 16 bytes or more, size divisible by 8.

Returns: bytes - cipher, which is 8 bytes longer than the keys string given.

See also: KeyUnwrap - reverse operation.; StaticKeyWrap - version that accepts key directly.

unsigned MAes::KeyWrapBuffer	(	const Muint8 *	keyText,
		unsigned	keyTextSize,
		Muint8 *	cipherText
	)

Encrypt key material with AES key wrap algorithm.

Cipher text and plain text can be the same buffer in which case the plain text will be decrypted in-place. However remember the size of cipher text buffer should be bigger by 8 bytes.

Parameters

keyText	Buffer with key material that has to be wrapped.
keyTextSize	Size of the buffer with key material.
cipherText	Result cipher text, the buffer should be 8 bytes bigger than keyTextSize.

Returns: keyTextSize + 8 is returned, cipherText buffer size.

See also: KeyWrap for complete description of functionality.

unsigned MAes::KeyWrapBuffer	(	const char *	keyText,
		unsigned	keyTextSize,
		char *	cipherText
	)

inline

Encrypt key material with AES key wrap algorithm.

Cipher text and plain text can be the same buffer in which case the plain text will be decrypted in-place. However remember the size of cipher text buffer should be bigger by 8 bytes.

Parameters

keyText	Buffer with key material that has to be wrapped.
keyTextSize	Size of the buffer with key material.
cipherText	Result cipher text, the buffer should be 8 bytes bigger than keyTextSize.

Returns: keyTextSize + 8 is returned, cipherText buffer size.

See also: KeyWrap for complete description of functionality.

static void MAes::MoveSecureData	(	MByteString &	destination,
		MByteString &	source
	)

static

Move one secure data such as key or password into another variable, destroy source value.

As the data size of a new buffer can be different as a safety measure the previous contents of the destination is erased. The contents of the source is destroyed after assignment.

Parameters

destination	Where to put the new secure material.
source	From which value to copy data. The source value is destroyed after assignment.

See also: AssignSecureData(MByteString& destination, const MByteString& source); AssignSecureData(MByteStringVector& destination, const MByteStringVector& source); SwapSecureData(MByteString& v1, MByteString& v2);; SwapSecureData(MByteStringVector& v1, MByteStringVector& v2)

static void MAes::MoveSecureData	(	MByteStringVector &	destination,
		MByteStringVector &	source
	)

static

Move one secure data such as key or password into another variable, destroy source value.

As the data size of a new buffer can be different as a safety measure the previous contents of the destination is erased. The contents of the source is destroyed after assignment.

Parameters

destination	Where to put the new secure material.
source	From which value to copy data. The source value is destroyed after assignment.

See also: AssignSecureData(MByteString& destination, const MByteString& source); AssignSecureData(MByteStringVector& destination, const MByteStringVector& source); SwapSecureData(MByteString& v1, MByteString& v2);; SwapSecureData(MByteStringVector& v1, MByteStringVector& v2)

MAes& MAes::operator= ( const MAes & other )

Assignment operator that copies the key from another class.

Parameters

other Other object from which to copy.

void MAes::SetHexKey ( const MStdString & )

AES Key to use by the class, hexadecimal representation.

The key has binary form, not hex, which is different from all the other MeteringSDK classes that accept AES key as a sequence of hexadecimal characters.

Since: MeteringSDK Version 5.0.

Precondition: When assigning to this property, the given key must be a proper hexadecimal string that evaluates into exactly 16 bytes in size, or an invalid size exception will be thrown. Hexadecimal string can have blanks for clarity, but such blanks must not split pairs of hexadecimal digits that represent the key.

See also: GetKey property for handling key given as raw bytes.

void MAes::SetKey ( const MByteString & )

AES Key to use by the class, binary representation.

The key has binary form, not hex, which is different from all the other MeteringSDK classes that accept AES key as a sequence of hexadecimal characters.

Precondition: When assigning to this property, the given key must be exactly 16 bytes in size, or an invalid size exception will be thrown.

See also: GetHexKey property for handling key given as a sequence of hexadecimal characters.

static MByteString MAes::StaticDecrypt	(	const MByteString &	key,
		const MByteString &	cipherText
	)

static

Static version of Decrypt that accepts key as parameter.

ECB mode has known security issues as the 16-byte chunks of data with the same contents will produce the same 16-byte chunks of cipher. This fact presents to an attacker the unwanted knowledge about the contents of plain text. ECB mode is still usable for cases when the data to encrypt has a good entropy, and never repeats, such as cryptographic hash.

For cases other than encrypting random or pseudorandom data, EAX mode of AES is preferred, see class MAesEax. This mode is also capable of handling data of sizes not divisible by 16.

When encryption is to be done once for a given key, StaticDecrypt() call is more convenient, but when key has to be reused for encryption of many chunks, using MAes::Decrypt() yields better performance when it reuses the same MAes instance. This is because there is a key expansion algorithm that is performed per single key assignment.

Parameters

key	Shall be exactly 16 bytes, binary. Notice, the difference from all other MeteringSDK classes is that Key property of MAes is binary, not a hex string.
cipherText	Raw bytes of size divisible by 16. If the size is not divisible by 16, an exception is thrown.

Returns: MByteString - result plain text, same size as cipherText.

See also: Decrypt - object version of StaticEncrypt.; StaticEncrypt - static version, method of a class that gets key as parameter.

static MByteString MAes::StaticEncrypt	(	const MByteString &	key,
		const MByteString &	plainText
	)

static

Static version of Encrypt that accepts key as parameter.

ECB mode has known security issues as the 16-byte chunks of data with the same contents will produce the same 16-byte chunks of cipher. This fact presents to an attacker the unwanted knowledge about the contents of plain text. ECB mode is still usable for cases when the data to encrypt has a good entropy, and never repeats, such as cryptographic hash.

For cases other than encrypting random or pseudorandom data, EAX mode of AES is preferred, see class MAesEax. This mode is also capable of handling data of sizes not divisible by 16.

When encryption is to be done once for a given key, StaticEncrypt() call is more convenient, but when key has to be reused for encryption of many chunks, using MAes::Encrypt() yields better performance when it reuses the same MAes instance. This is because there is a key expansion algorithm that is performed per single key assignment.

Parameters

key	Shall be exactly 16 bytes, binary. Notice, the difference from all other MeteringSDK classes is that Key property of MAes is binary, not a hex string.
plainText	Raw bytes of size divisible by 16. If the size is not divisible by 16, an exception is thrown.

Returns: MByteString - result cipher text, same size as plainText.

See also: Encrypt - object version of StaticEncrypt.; StaticDecrypt - static version, method of a class that gets key as parameter.

static MByteString MAes::StaticKeyUnwrap	(	const MByteString &	key,
		const MByteString &	cipher
	)

static

Static variant of KeyUnwrap.

See also: KeyUnwrap - object version that accepts key as property.; StaticKeyWrap - reverse static operation.

Parameters

key	Encryption key to use in key unwrap, should be the same as the one in the wrap call.
cipher	Cipher text as produced by keys wrap call.

Returns: bytes - byte string of keys, which is 8 bytes shorter than the cipher given.

static MByteString MAes::StaticKeyWrap	(	const MByteString &	key,
		const MByteString &	keys
	)

static

Static variant of KeyWrap.

See also: KeyWrap - object version that accepts key as property.; StaticKeyUnwrap - reverse static operation.

Parameters

key	Encryption key to use in key wrap, should be the same as the one in the unwrap call.
keys	One or more 16-byte keys to wrap.

Returns: bytes - cipher, which is 8 bytes longer than the keys string given.

static void MAes::SwapSecureData	(	MByteString &	v1,
		MByteString &	v2
	)

static

Swap secure data such as key or password with another data.

As the data sizes of these can be different, the data gets erased to make sure nothing stays in memory after the operation.

Parameters

v1	Data to be swapped with v2.
v2	Data to be swapped with v1.

See also: AssignSecureData(MByteString& destination, const MByteString& source); AssignSecureData(MByteStringVector& destination, const MByteStringVector& source); MoveSecureData(MByteString& destination, MByteString& source); MoveSecureData(MByteStringVector& destination, MByteStringVector& source)

static void MAes::SwapSecureData	(	MByteStringVector &	v1,
		MByteStringVector &	v2
	)

static

Swap secure data such as key or password with another data.

As the data sizes of these can be different, the data gets erased to make sure nothing stays in memory after the operation.

Parameters

v1	Data to be swapped with v2.
v2	Data to be swapped with v1.

See also: AssignSecureData(MByteString& destination, const MByteString& source); AssignSecureData(MByteStringVector& destination, const MByteStringVector& source); MoveSecureData(MByteString& destination, MByteString& source); MoveSecureData(MByteStringVector& destination, MByteStringVector& source)

static M_NORETURN_FUNC void MAes::ThrowValidationError ( )

static

Throw an error that tells about a validation problem in the encrypted or authenticated message.

Validation is supported in EAX mode of AES, as supported by child class MAesEax, and by key unwrap procedures. The user might decide to throw this error if there is a separate way of validating the encrypted buffer, such as MD5 checksum.

The message thrown mentions that the problem can result from tampering.

Public Types

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation