AES encryption and decryption in EAX mode with authentication. More...

Inheritance diagram for MAesEax:

Public Member Functions
	MAesEax ()
	Create EAX encryption/decryption class without setting the key. More...

	MAesEax (const MByteString &key)
	Create EAX encryption/decryption class with key, given as raw 16 bytes. More...

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

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

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

unsigned	EaxEncryptBuffer (const char clearText, unsigned clearTextSize, char cipherText, unsigned cipherTextSize)
	Version of EaxEncrypt that accepts pointers and lengths of the data. More...

unsigned	EaxDecryptBuffer (const char clearText, unsigned clearTextSize, char cipherText, unsigned cipherTextSize)
	Performance sensitive version of EaxDecrypt that accepts pointers and lengths of the data. More...

unsigned	EaxAuthenticateBuffer (const char *clearText, unsigned clearTextSize)
	Performance sensitive version of EaxAuthenticate that accepts pointers and lengths of the data. More...

bool	EaxDecryptToResult (const MByteString &clearText, const MByteString &data, MByteString &result)
	Performance sensitive version of EaxDecrypt that avoids returning a string. More...

MByteString	EaxEncrypt (const MByteString &clearText, const MByteString &plainText)
	Encrypt and authenticate a given chunk of data with AES using EAX mode. More...

MByteString	EaxDecrypt (const MByteString &clearText, const MByteString &cipherText)
	Decrypt and authenticate a given chunk of data with AES using EAX mode. More...

unsigned	EaxAuthenticate (const MByteString &clearText)
	Compute MAC of a given message using EAX mode of AES as an algorithm. More...

Public Member Functions inherited from MAes
	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 MByteString	StaticEaxEncrypt (const MByteString &key, const MByteString &clearText, const MByteString &plainText)
	Static version of MAesEax::EaxEncrypt that accepts key as parameter. More...

static MByteString	StaticEaxDecrypt (const MByteString &key, const MByteString &clearText, const MByteString &cipherText)
	Static version of MAesEax::EaxDecrypt that accepts key as parameter. More...

static unsigned	StaticEaxAuthenticate (const MByteString &key, const MByteString &clearText)
	Static version of MAesEax::EaxAuthenticate that accepts key as parameter. More...

Static Public Member Functions inherited from MAes
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
Public Types inherited from MAes
enum	{ KeySize = 16, BlockSize = 16, KeyWrapEncryptionExtraSize = 8, KeyWrapMinimumSize = KeySize, KeyWrapMaximumSize = 2048 }

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 in EAX mode with authentication.

Currently only 128-bit AES key is supported, which corresponds to ANSI C12.22 use of EAX mode of AES. Different from all the other MeteringSDK classes that accept AES key as a sequence of hexadecimal characters, this class is primarily using key as a raw byte string exactly 16 bytes long. There is a special extra property GetHexKey that does necessary conversion.

EAX mode can be recommended for all cases where the plain text has entropy lower than cryptographic randomness. The following are features of this mode:

It accepts an extra parameter, clearText, that is used for seeding the cipher. Clear text, or its part, shall be randomly generated. In case of ANSI C12.22, four bytes of initialization vector is random.
It encrypts data of any size, not necessarily divisible by 16.
It provides message authentication through 32-bit MAC number (message authentication code). While this is by far not any type of cryptographic signature, 32-bit MAC is good enough for cases when the message has some sort of structure, without which it will not be recognized as valid. Computation of EAX mode MAC is fast, compared to speed of AES.

There are the following set of methods of class MAesEax, shown in overlapped groups:

EAX mode encryption and decryption: EaxEncrypt(), EaxDecrypt(), StaticEaxEncrypt(), StaticEaxDecrypt()
EAX authentication: EaxAuthenticate(), StaticEaxAuthenticate()

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 MAesEax.

Constructor & Destructor Documentation

MAesEax::MAesEax ( )

Create EAX encryption/decryption class without setting the key.

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

MAesEax::MAesEax ( const MByteString & key )

Create EAX encryption/decryption 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

MAesEax::MAesEax ( const MAesEax & 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 MAesEax 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

unsigned MAesEax::EaxAuthenticate ( const MByteString & clearText )

Compute MAC of a given message using EAX mode of AES as an algorithm.

MAC returned is only 32 bits, which is not a cryptographically strong method of message authentication, however without knowledge of key, a malicious party would have one out of four billion case when an altered message does pass authentication. This is considered strong enough for cases of ANSI C12.22.

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

Parameters

clearText Message to authenticate

Returns: 32-bit message authentication code, MAC.

unsigned MAesEax::EaxAuthenticateBuffer	(	const char *	clearText,
		unsigned	clearTextSize
	)

Performance sensitive version of EaxAuthenticate that accepts pointers and lengths of the data.

See EaxAuthenticate() for detailed description.

Returns: 32-bit MAC, message authentication code of clear text.

MByteString MAesEax::EaxDecrypt	(	const MByteString &	clearText,
		const MByteString &	cipherText
	)

Decrypt and authenticate a given chunk of data with AES using EAX mode.

EAX mode is capable of handling chunks of data of any size, it authenticates the message, and it also takes an extra parameter, clearText that participates in authentication.

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

Precondition: Key shall be set to MAesEax instance, or an exception is thrown. Also, as the call provides authentication, for the method to succeed, the same clearText given at AexEncrypt() shall be given, same key shall be set, and cipherText shall be unaltered. Otherwise possible tampering is reported as exception.

Parameters

clearText Text that was used during EAX encryption. Clear text shall be randomly generated, or shall have a randomly generated part. In either case the randomly generated part shall have no less than 32 bits of entropy, which is the size of MAC, message authentication code, as generated by EaxEncrypt, and appended to the end of the returned string. Clear text will typically have some open information about the encrypted message. Clear text gets authenticated together with plain text.

cipherText This is the data to be decrypted. The last four bytes of the data is message authentication code, MAC.

Returns: MByteString - result authenticated plain text.

See also: EaxEncrypt - decrypting and authenticating the data decrypted by this method.; StaticEaxDecrypt - static version, method of a class that gets key as parameter

unsigned MAesEax::EaxDecryptBuffer	(	const char *	clearText,
		unsigned	clearTextSize,
		char *	cipherText,
		unsigned	cipherTextSize
	)

Performance sensitive version of EaxDecrypt that accepts pointers and lengths of the data.

See EaxDecrypt() for detailed description.

Returns: 32-bit MAC, message authentication code of clear text.

bool MAesEax::EaxDecryptToResult	(	const MByteString &	clearText,
		const MByteString &	data,
		MByteString &	result
	)

Performance sensitive version of EaxDecrypt that avoids returning a string.

The method never throws an exception, but rather returns a boolean result. See EaxDecrypt() for detailed description.

Returns: bool - whether the decryption passed MAC authentication.

MByteString MAesEax::EaxEncrypt	(	const MByteString &	clearText,
		const MByteString &	plainText
	)

Encrypt and authenticate a given chunk of data with AES using EAX mode.

EAX mode is capable of handling chunks of data of any size, it authenticates the message, and it also takes an extra parameter, clearText that participates in authentication.

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

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

Parameters

clearText Text that shall be available during EAX decryption with authentication phase. Clear text shall be randomly generated, or shall have a randomly generated part. In either case the randomly generated part shall have no less than 32 bits of entropy, which is the size of MAC, message authentication code, as generated by EaxEncrypt, and appended to the end of the returned string. Clear text will typically have some open information about the encrypted message. Clear text gets authenticated together with plain text.

plainText This is the data to be encrypted, the data size is not necessarily divisible by 16.

Returns: MByteString - cipher text with 4-byte MAC at the end.

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

unsigned MAesEax::EaxEncryptBuffer	(	const char *	clearText,
		unsigned	clearTextSize,
		char *	cipherText,
		unsigned	cipherTextSize
	)

Version of EaxEncrypt that accepts pointers and lengths of the data.

See EaxEncrypt() for detailed description.

Returns: 32-bit MAC, message authentication code of clear text.

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

Assignment operator that copies key from another class.

Parameters

other Other object from which to copy

static unsigned MAesEax::StaticEaxAuthenticate	(	const MByteString &	key,
		const MByteString &	clearText
	)

static

Static version of MAesEax::EaxAuthenticate that accepts key as parameter.

MAC returned is only 32 bits, which is not a cryptographically strong method of message authentication, however without knowledge of key, a malicious party would have one out of four billion case when an altered message does pass authentication. This is considered strong enough for cases of ANSI C12.22.

Parameters

key	Shall be exactly 16 bytes, raw data not hex, or an exception is thrown.
clearText	Message to authenticate

Returns: 32-bit message authentication code, MAC.

static MByteString MAesEax::StaticEaxDecrypt	(	const MByteString &	key,
		const MByteString &	clearText,
		const MByteString &	cipherText
	)

static

Static version of MAesEax::EaxDecrypt that accepts key as parameter.

EAX mode is capable of handling chunks of data of any size, it authenticates the message, and it also takes an extra parameter, clearText that participates in authentication.

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

Parameters

key	Key, as used when the message was encrypted with AES in EAX mode, shall be exactly 16 bytes in size. As the call provides authentication, for the method to succeed, the same (correct) key shall be given, the one with which the data were encrypted. Otherwise possible tampering is reported as exception.
clearText	Text that was used during EAX encryption. Clear text shall be randomly generated, or shall have a randomly generated part. In either case the randomly generated part shall have no less than 32 bits of entropy, which is the size of MAC, message authentication code, as generated by EaxEncrypt, and appended to the end of the returned string. Clear text will typically have some open information about the encrypted message. Clear text gets authenticated together with plain text.
cipherText	This is the data to be decrypted. The last four bytes of the data is message authentication code, MAC.

Returns: MByteString - result authenticated plain text.

See also: EaxDecrypt - object version of StaticEaxEncrypt; StaticEaxEncrypt - static encrypt method, the one that directly corresponds to this decryption method

static MByteString MAesEax::StaticEaxEncrypt	(	const MByteString &	key,
		const MByteString &	clearText,
		const MByteString &	plainText
	)

static

Static version of MAesEax::EaxEncrypt that accepts key as parameter.

EAX mode is capable of handling chunks of data of any size, it authenticates the message, and it also takes an extra parameter, clearText that participates in authentication.

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

Parameters

key	Shall be 16 raw bytes in size, or an exception is thrown.
clearText	Text that shall be available during EAX decryption with authentication phase. Clear text shall be randomly generated, or shall have a randomly generated part. In either case the randomly generated part shall have no less than 32 bits of entropy, which is the size of MAC, message authentication code, as generated by EaxEncrypt, and appended to the end of the returned string. Clear text will typically have some open information about the encrypted message. Clear text gets authenticated together with plain text.
plainText	This is the data to be encrypted, the data size is not necessarily divisible by 16.

Returns: MByteString - cipher text with 4-byte MAC at the end.

See also: EaxEncrypt - object version of StaticEaxEncrypt; StaticEaxDecrypt - static decrypt method, the one that directly corresponds to this encryption method

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation