MechParamGCM Class Reference

Constructs a mechanism parameter for AES encryption or decryption with Galois Counter Chaining (GCM, see NIST SP-800-38D). More...

Inheritance diagram for MechParamGCM:

Collaboration diagram for MechParamGCM:

Public Member Functions
	MechParamGCM (int mech, const ByteArray &iv_init, const ByteArray &ad, int tagbits=128, int iv_gen_func=CXI_MECH_PARAM_IV_NO_GENERATE)
MechanismParameter	getEncoded (void)
Public Member Functions inherited from MechParam
	MechParam (int mech)
	Constructs a mechanism parameter with the given mechanism specifier. More...
MechanismParameter	getEncoded (void)

Detailed Description

Constructs a mechanism parameter for AES encryption or decryption with Galois Counter Chaining (GCM, see NIST SP-800-38D).

The following example illustrates the usage of the MechParamGCM class:

Key key = ...;
ByteArray iv_init = ByteArray("1234567890AB");
ByteArray ad = "My Little Secret";
ByteArray data = ...;
ByteArray iv;
ByteArray tag1 = ByteArray(16);
 
// encrypt data
MechParamGCM mechParam = MechParamGCM(CXI_MECH_MODE_ENCRYPT, iv_init, ad);
 
ByteArray crypt = cxi->crypt(CXI_FLAG_CRYPT_FINAL, key, mechParam.getEncoded(), data, iv, tag1);
 
// decrypt data
 mechParam = MechParamGCM(CXI_MECH_MODE_DECRYPT, iv_init, ad);
 
iv.clear;
ByteArray tag2 = ByteArray(16);
 
// authenticated decryption, tag is verified internally
ByteArray plain = cxi->crypt(CXI_FLAG_CRYPT_FINAL, key, mechParam.getEncoded(), crypt, iv, tag2, tag1);
 
if (plain != data)
  throw Exception("<decrypt>", "decrypted data doesn't match original data");

Constructor & Destructor Documentation

MechParamGCM()

MechParamGCM	(	int	mech,
		const ByteArray &	iv_init,
		const ByteArray &	ad,
		int	tagbits = 128,
		int	iv_gen_func = CXI_MECH_PARAM_IV_NO_GENERATE
	)

Constructs mechanism parameter for Galois Counter Mode (see NIST SP-800-38D).

Parameters

mech	XOR combination of mechanism specifier: crypt mode (see Mode Parameter) CXI_MECH_MODE_ENCRYPT CXI_MECH_MODE_DECRYPT chaining mode: The chaining mode CXI_MECH_CHAIN_GCM is set as default and cannot be changed.
iv_init	Initialization Vector: The length of the Initialization Vector has to be less than 2^16 - 1. 96 bit (12 bytes) length is recommended by the NIST, but other values are allowed as well. On chunked operation the IV has to be given (at least) on the first call of the AES GCM algorithm. For encryption, it is recommended to use a zero length ByteArray as IV. In this case the CryptoServer generates a random 12 byte IV internally.
ad	additional authentication data. On chunked operation additional authentication data should be given once on the first call and has to be absent on subsequent calls.
tagbits	Number of bits in the authentication tag
iv_gen_func	IV generation function: For signing calls we recommend to use CXI_GCM_IV_GENERATE for this parameter. In this case the CryptoServer generates a random IV internally with l_iv_init Bytes. This IV is returned by the final encryption call and must then be used as IV for the decryption.

Member Function Documentation

getEncoded()

MechanismParameter getEncoded

(

void

)

Returns

Returns the encoded mechanism parameter.