Header file for the NanoCrypto AES symmetric cipher functions API. More...

Functions
MOC_EXTERN MSTATUS	AESALGO_blockDecrypt (aesCipherContext pAesContext, ubyte iv, ubyte input, sbyte4 inputLen, ubyte outBuffer, sbyte4 *pRetLength)

MOC_EXTERN MSTATUS	AESALGO_blockDecryptEx (MOC_SYM(hwAccelDescr hwAccelCtx) aesCipherContext pAesContext, ubyte iv, ubyte input, sbyte4 inputLen, ubyte outBuffer, sbyte4 *pRetLength)

MOC_EXTERN MSTATUS	AESALGO_blockEncrypt (aesCipherContext pAesContext, ubyte iv, ubyte input, sbyte4 inputLen, ubyte outBuffer, sbyte4 *pRetLength)

MOC_EXTERN MSTATUS	AESALGO_blockEncryptEx (MOC_SYM(hwAccelDescr hwAccelCtx) aesCipherContext pAesContext, ubyte iv, ubyte input, sbyte4 inputLen, ubyte outBuffer, sbyte4 *pRetLength)

MOC_EXTERN MSTATUS	AESALGO_clearKey (aesCipherContext *pAesContext)

MOC_EXTERN MSTATUS	AESALGO_makeAesKey (aesCipherContext pAesContext, sbyte4 keyLen, const ubyte keyMaterial, sbyte4 encrypt, sbyte4 mode)

MOC_EXTERN MSTATUS	AESALGO_makeAesKeyEx (MOC_SYM(hwAccelDescr hwAccelCtx) aesCipherContext pAesContext, sbyte4 keyLen, const ubyte keyMaterial, sbyte4 encrypt, sbyte4 mode)

MOC_EXTERN MSTATUS	CloneAESCtx (MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx pCtx, BulkCtx *ppNewCtx)
	Clone a AES context. More...

MOC_EXTERN BulkCtx	CreateAESCFB1Ctx (MOC_SYM(hwAccelDescr hwAccelCtx) ubyte *keyMaterial, sbyte4 keyLength, sbyte4 encrypt)
	Create a new AES-CFB1 context. More...

MOC_EXTERN BulkCtx	CreateAESCFBCtx (MOC_SYM(hwAccelDescr hwAccelCtx) ubyte *keyMaterial, sbyte4 keyLength, sbyte4 encrypt)
	This function's documentation was added since 5.3.1, and should be reviewed for accuracy and appropriateness. More...

MOC_EXTERN BulkCtx	CreateAESCtx (MOC_SYM(hwAccelDescr hwAccelCtx) ubyte *keyMaterial, sbyte4 keyLength, sbyte4 encrypt)
	Get a new AES CBC context data structure and prepare the key schedule. More...

MOC_EXTERN BulkCtx	CreateAESOFBCtx (MOC_SYM(hwAccelDescr hwAccelCtx) ubyte *keyMaterial, sbyte4 keyLength, sbyte4 encrypt)
	Get a new AES OFB-mode context data structure and prepare the key schedule. More...

MOC_EXTERN MSTATUS	DeleteAESCtx (MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx *ctx)
	Delete AES context data structure. More...

MOC_EXTERN MSTATUS	DoAES (MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx ctx, ubyte data, sbyte4 dataLength, sbyte4 encrypt, ubyte iv)
	AES-encrypt or AES-decrypt a data buffer. More...

Detailed Description

Header file for the NanoCrypto AES symmetric cipher functions API.

Function Documentation

◆ AESALGO_blockDecrypt()

MOC_EXTERN MSTATUS AESALGO_blockDecrypt	(	aesCipherContext *	pAesContext,
		ubyte *	iv,
		ubyte *	input,
		sbyte4	inputLen,
		ubyte *	outBuffer,
		sbyte4 *	pRetLength
	)

Decrypt some data using the provided AES context.

Parameters

pCtx	The context to use for this cipher operation.
pIv	Initialization vector to use for this operation, optional for ECB mode. Must be 16 bytes for all other modes.
pInput	Data to decrypt.
inputLen	Length in bytes of the input data, must be a multiple of the AES block size (16).
pOutBuffer	Buffer that will recieve the decrypted result, must be as large as the input data.
pRetLength	Pointer to the sbyte4 which will recieve the length of the resulting plaintext.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ AESALGO_blockDecryptEx()

MOC_EXTERN MSTATUS AESALGO_blockDecryptEx	(	MOC_SYM(hwAccelDescr hwAccelCtx) aesCipherContext *	pAesContext,
		ubyte *	iv,
		ubyte *	input,
		sbyte4	inputLen,
		ubyte *	outBuffer,
		sbyte4 *	pRetLength
	)

Decrypt some data using the provided AES context.

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pCtx	The context to use for this cipher operation.
pIv	Initialization vector to use for this operation, optional for ECB mode. Must be 16 bytes for all other modes.
pInput	Data to decrypt.
inputLen	Length in bytes of the input data, must be a multiple of the AES block size (16).
pOutBuffer	Buffer that will recieve the decrypted result, must be as large as the input data.
pRetLength	Pointer to the sbyte4 which will recieve the length of the resulting plaintext.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ AESALGO_blockEncrypt()

MOC_EXTERN MSTATUS AESALGO_blockEncrypt	(	aesCipherContext *	pAesContext,
		ubyte *	iv,
		ubyte *	input,
		sbyte4	inputLen,
		ubyte *	outBuffer,
		sbyte4 *	pRetLength
	)

Encrypt some data using the provided AES context.

Parameters

pCtx	The context to use for this cipher operation.
pIv	Initialization vector to use for this operation, optional for ECB mode. Must be 16 bytes for all other modes.
pInput	Data to encrypt.
inputLen	Length in bytes of the input data, must be a multiple of the AES block size (16).
pOutBuffer	Buffer that will recieve the encrypted result, must be as large as the input data.
pRetLength	Pointer to the sbyte4 which will recieve the length of the resulting ciphertext.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ AESALGO_blockEncryptEx()

MOC_EXTERN MSTATUS AESALGO_blockEncryptEx	(	MOC_SYM(hwAccelDescr hwAccelCtx) aesCipherContext *	pAesContext,
		ubyte *	iv,
		ubyte *	input,
		sbyte4	inputLen,
		ubyte *	outBuffer,
		sbyte4 *	pRetLength
	)

Encrypt some data using the provided AES context.

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pCtx	The context to use for this cipher operation.
pIv	Initialization vector to use for this operation, optional for ECB mode. Must be 16 bytes for all other modes.
pInput	Data to encrypt.
inputLen	Length in bytes of the input data, must be a multiple of the AES block size (16).
pOutBuffer	Buffer that will recieve the encrypted result, must be as large as the input data.
pRetLength	Pointer to the sbyte4 which will recieve the length of the resulting ciphertext.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ AESALGO_clearKey()

MOC_EXTERN MSTATUS AESALGO_clearKey ( aesCipherContext * pAesContext )

Delete an AES context previously initialized with AESALGO_makeAesKey. Note that this function frees the underlying context created by the crypto interface. Even though the aesCipherContext pointer was originally allocated by the caller, failing to call this function after use will result in a memory leak.

Parameters

pCtx	Pointer to an AES context previously created with AESALGO_makeAesKey.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h.

◆ AESALGO_makeAesKey()

MOC_EXTERN MSTATUS AESALGO_makeAesKey	(	aesCipherContext *	pAesContext,
		sbyte4	keyLen,
		const ubyte *	keyMaterial,
		sbyte4	encrypt,
		sbyte4	mode
	)

Initialize a raw AES object for operation. Note that this should only be used when constructing a larger cryptographic scheme that requires an AES primitive. To use AES for encrypting/decrypting data in general, use one of the CreateAES*Ctx functions instead. It is the callers responsibility to delete this context after use by calling AESALGO_clearKey.

Parameters

pCtx	Pointer to a caller allocated AES context to be initialized.
keyLen	Length in bytes of key material to use, must be one of {16,24,32}.
pKeyMaterial	Key material to use for this operation.
encrypt	`TRUE` to encrypt, `FALSE` to decrypt.
mode	The AES mode of operation to use. Must be one of { MODE_ECB, MODE_CBC, MODE_CFB128, MODE_OFB }

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ AESALGO_makeAesKeyEx()

MOC_EXTERN MSTATUS AESALGO_makeAesKeyEx	(	MOC_SYM(hwAccelDescr hwAccelCtx) aesCipherContext *	pAesContext,
		sbyte4	keyLen,
		const ubyte *	keyMaterial,
		sbyte4	encrypt,
		sbyte4	mode
	)

Initialize a raw AES object for operation. Note that this should only be used when constructing a larger cryptographic scheme that requires an AES primitive. To use AES for encrypting/decrypting data in general, use one of the CreateAES*Ctx functions instead. It is the callers responsibility to delete this context after use by calling AESALGO_clearKey.

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pCtx	Pointer to a caller allocated AES context to be initialized.
keyLen	Length in bytes of key material to use, must be one of {16,24,32}.
pKeyMaterial	Key material to use for this operation.
encrypt	`TRUE` to encrypt, `FALSE` to decrypt.
mode	The AES mode of operation to use. Must be one of { MODE_ECB, MODE_CBC, MODE_CFB128, MODE_OFB }

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CloneAESCtx()

MOC_EXTERN MSTATUS CloneAESCtx	(	MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx	pCtx,
		BulkCtx *	ppNewCtx
	)

Parameters

pCtx	Pointer to an instantiated BulkCtx.
ppNewCtx	Double pointer to the BulkCtx to be created and populated with the key data from the source key.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h.

◆ CreateAESCFB1Ctx()

MOC_EXTERN BulkCtx CreateAESCFB1Ctx	(	MOC_SYM(hwAccelDescr hwAccelCtx) ubyte *	keyMaterial,
		sbyte4	keyLength,
		sbyte4	encrypt
	)

Note it is the callers responsibility to free this object after use by calling DeleteAESCtx. Once created, you can use this context as input to DoAES to encrypt or decrypt data.

aes.h aes.h

Parameters

pKeyMaterial	Key material to use for the cipher operation.
keyLength	Length in bytes of the key material, valid key lengths are {16, 24, 32}.
encrypt	`TRUE` to prepare this context for encryption, `FALSE` to prepare this context for decryption.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h.

◆ CreateAESCFBCtx()

MOC_EXTERN BulkCtx CreateAESCFBCtx	(	MOC_SYM(hwAccelDescr hwAccelCtx) ubyte *	keyMaterial,
		sbyte4	keyLength,
		sbyte4	encrypt
	)

Get a new AES CFB-mode context data structure and prepare the key schedule.

This function creates and returns a context data structure for AES operations (in the CFB mode) and prepares the key schedule (intermediate key material). This is the first function your application calls when performing AES CFB-mode operations (encryption or decryption). Your application uses the returned structure in subsequent DoAES functions.

See also: For details about AES in CFB mode, see Overview of CFB Mode and Usage Caveats for AES in CFB Mode.

FIPS Approved
Suite B Algorithm
Flowchart	AES-CFB

The AES CFB-mode context is an opaque data structure that holds information such as key length, key schedule, and mode of operation. To avoid memory leaks, your application code must call the DeleteAESCtx function after completing AES-related CFB-mode operations (because the AES context is dynamically allocated by this function during context creation).

Warning: If NULL is returned for the context pointer, you cannot use it as input to any subsequent AES functions.

There are no flag dependencies to enable this function.

aes.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
keyMaterial	AES key to use for encryption or decryption.
keyLength	Number of bytes in AES key; valid key lengths are: 16 (for 128 bit key), 24 (for 192 bit key), and 32 (for 256 bit key).
encrypt	`TRUE` to prepare the key schedule for encryption; `FALSE` to prepare the key schedule for decryption.

Returns: NULL if any error; otherwise pointer to created AES CFB-mode context.

aes.h

◆ CreateAESCtx()

MOC_EXTERN BulkCtx CreateAESCtx	(	MOC_SYM(hwAccelDescr hwAccelCtx) ubyte *	keyMaterial,
		sbyte4	keyLength,
		sbyte4	encrypt
	)

This function creates and returns a context data structure for AES CBC operations, and prepares the key schedule (intermediate key material). This is the first function your application calls when performing AES operations (encryption or decryption). Your application uses the returned structure in subsequent DoAES functions.

FIPS Approved
Suite B Algorithm
Flowchart	AES-CBC

The AES CBC context is an opaque data structure that holds information such as key length, key schedule, and mode of operation. To avoid memory leaks, your application code must call the DeleteAESCtx() function after completing AES-CBC related operations (because the AES context is dynamically allocated by this function during context creation).

See also: For details about AES in CBC mode, see Overview of CBC Mode and Usage Caveats for AES in CBC Mode.

Warning: If NULL is returned for the context pointer, you cannot use it as input to any subsequent AES-CBC functions.

There are no flag dependencies to enable this function.

aes.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing. But... what does the user specify? In the 5.3.1 docs, we just said that this was "Reserved for future use." Ditto this for all aes.{c,h} functions.
keyMaterial	AES key to use for encryption or decryption.
keyLength	Number of bytes in AES key; valid key lengths are: 16 (for 128 bit key), 24 (for 192 bit key), and 32 (for 256 bit key).
encrypt	`TRUE` to prepare the key schedule for encryption; `FALSE` to prepare the key schedule for decryption.

Returns: NULL if any error; otherwise pointer to created AES context.

aes.h

◆ CreateAESOFBCtx()

MOC_EXTERN BulkCtx CreateAESOFBCtx	(	MOC_SYM(hwAccelDescr hwAccelCtx) ubyte *	keyMaterial,
		sbyte4	keyLength,
		sbyte4	encrypt
	)

This function creates and returns a context data structure for AES operations in OFB mode, and prepares the key schedule (intermediate key material).

FIPS Approved
Suite B Algorithm
Flowchart	AES-OFB

This function and its documentation were added since 5.3.1, and should be reviewed for accuracy and appropriateness.

This is the first function your application calls when performing AES OFB-mode operations (encryption or decryption). Your application uses the returned structure in subsequent DoAES() function calls.

The AES OFB-mode context is an opaque data structure that holds information such as key length, key schedule, and mode of operation. To avoid memory leaks, your application code must call the DeleteAESCtx() function after completing AES-related OFB-mode operations (because the AES context is dynamically allocated by this function during context creation).

Warning: If NULL is returned for the context pointer, you cannot use it as input to any subsequent AES functions.

There are no flag dependencies to enable this function.

aes.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
keyMaterial	AES key to use for encryption or decryption.
keyLength	Number of bytes in AES key; valid key lengths are: 16 (for 128 bit key), 24 (for 192 bit key), and 32 (for 256 bit key).
encrypt	`TRUE` to prepare the key schedule for encryption; `FALSE` to prepare the key schedule for decryption.

Returns: NULL if any error; otherwise pointer to created AES OFB-mode context.

aes.h

◆ DeleteAESCtx()

MOC_EXTERN MSTATUS DeleteAESCtx ( MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx * ctx )

This function deletes an AES context previously created by CreateAESCtx(), CreateAESCFBCtx(), or CreateAESOFBCtx(). To avoid memory leaks, your application must call this function after completing AES-related operations for a given context.

FIPS Approved
Suite B Algorithm
Flowchart	AES-CBC

There are no flag dependencies to enable this function.

aes.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
ctx	Pointer to AES context to delete.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

aes.h

◆ DoAES()

MOC_EXTERN MSTATUS DoAES	(	MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx	ctx,
		ubyte *	data,
		sbyte4	dataLength,
		sbyte4	encrypt,
		ubyte *	iv
	)

This function AES-encrypts or AES-decrypts a data buffer. Before calling this function, your application must call CreateAESCtx(), CreateAESCFBCtx(), or CreateAESOFBCtx() to dynamically create a valid, mode-appropriate AES context.

Warning: This function destroys the submitted IV.

FIPS Approved
Suite B Algorithm
Flowchart	AES-CBC

There are no flag dependencies to enable this function.

aes.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
ctx	AES context, previously created by CreateAESCtx(), CreateAESCFBCtx(), or CreateAESOFBCtx().
data	Data to be encrypted or decrypted.
dataLength	Number of bytes of data to encrypt or decrypt (`data`).
encrypt	`TRUE` to encrypt the data; `FALSE` to decrypt the data.
iv	Unique IV for the AES operation.

Warning: For all modes, it is essential that you never reuse an IV under the same key. Otherwise, you will compromise confidentiality for the mode.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

aes.h

Functions

Detailed Description

Function Documentation

◆ AESALGO_blockDecrypt()

◆ AESALGO_blockDecryptEx()

◆ AESALGO_blockEncrypt()

◆ AESALGO_blockEncryptEx()

◆ AESALGO_clearKey()

◆ AESALGO_makeAesKey()

◆ AESALGO_makeAesKeyEx()

◆ CloneAESCtx()

◆ CreateAESCFB1Ctx()

◆ CreateAESCFBCtx()

◆ CreateAESCtx()

◆ CreateAESOFBCtx()

◆ DeleteAESCtx()

◆ DoAES()