Add a chunk of additional authenticated data (in incremental mode).

Parameters

[in]	hContext	handle to the AEAD context set up by an earlier call to AEAD_InitKey.
[in]	lpAAD	array containing the chunk of Additional Authenticated Data (AAD) to add.
[in]	nAadLen	equal to length of the AAD chunk in bytes.

Returns

If successful, the return value is zero; otherwise it returns a nonnegative error code.

Remarks

May be repeated to add additional data in chunks. Must eventually be followed by either AEAD_StartEncrypt or AEAD_StartDecrypt. Returns MISUSE_ERROR if called out of sequence.

Decrypt and authenticate input using specified AEAD algorithm in one-off operation.

All the input and output parameters are in byte arrays. The authentication tag is specified separately.

Parameters

[out]	lpOutput	byte array of sufficient length to receive the plaintext output (at least as long as the input).
[in]	nOutLen	length in bytes of the output array.
[in]	lpData	byte array containing the input data.
[in]	nDataLen	length of the input data in bytes.
[in]	lpKey	byte array containing the key of exact length for given algorithm (currently either 16 or 32 bytes).
[in]	nKeyLen	length of the key in bytes.
[in]	lpNonce	containing the nonce of exact length for the given algorithm (currently always 12 bytes).
[in]	nNonceLen	length of the nonce in bytes.
[in]	lpAAD	byte array containing the optional Additional Authenticated Data (AAD).
[in]	nAadLen	length of the AAD in bytes.
[in]	lpTag	byte array containing the tag.
[in]	nTagLen	length of the tag in bytes.
[in]	nOptions	option flags. Select one of the following: API_AEAD_AES_128_GCM to use the AEAD_AES_128_GCM authenticated encryption algorithm (RFC 5116) API_AEAD_AES_256_GCM to use the AEAD_AES_256_GCM authenticated encryption algorithm (RFC 5116) API_AEAD_CHACHA20_POLY1305 to use the AEAD_CHACHA20_POLY1305 authenticated encryption algorithm (RFC 7539)

Returns

If successful, the return value is zero; otherwise it returns a nonnegative error code.

Remarks

This is a one-off, stateless function. The output plaintext is always exactly the same length as the input ciphertext (excluding any IV or tags in the input). If the inputs are not authentic, the function returns the non-zero error code AUTH_FAILED_ERROR and the decrypted output should be rejected. Note that the term "IV" is used here to mean exactly the same as "nonce". For more details of AEAD see Authenticated Encryption with Additional Data (AEAD).

Decrypt and authenticate input using specified AEAD algorithm in one-off operation.

All the input and output parameters are in byte arrays. The authentication tag is expected to be appended to the input ciphertext.

Parameters

[out]	lpOutput	buffer of sufficient length to receive the plaintext output.
[in]	nOutLen	length in bytes of the output buffer.
[in]	lpInput	byte array containing the input data.
[in]	nInputLen	length of the input data in bytes.
[in]	lpKey	byte array containing the key of exact length for given algorithm (currently either 16 or 32 bytes).
[in]	nKeyLen	length of the key in bytes.
[in]	lpNonce	(optional) initialization vector (IV), a.k.a. nonce, if not provided in input.
[in]	nNonceLen	length of the nonce in bytes.
[in]	lpAAD	byte array containing the optional Additional Authenticated Data (AAD).
[in]	nAadLen	length of the AAD in bytes.
[in]	nOptions	option flags. Select one of the following: API_AEAD_AES_128_GCM to use the AEAD_AES_128_GCM authenticated encryption algorithm (RFC 5116) API_AEAD_AES_256_GCM to use the AEAD_AES_256_GCM authenticated encryption algorithm (RFC 5116) API_AEAD_CHACHA20_POLY1305 to use the AEAD_CHACHA20_POLY1305 authenticated encryption algorithm (RFC 7539) API_AEAD_ASCON_128 to use the ASCON-128 authentication scheme (see ASCON) (provisional, subject to NIST final approval) API_AEAD_ASCON_128A to use the ASCON-128A authentication scheme (provisional, subject to NIST final approval) and optionally add: API_IV_PREFIX to expect the IV (nonce) to be prepended at the start of the input.

Returns

If successful, the return value is the number of bytes in or required in the output otherwise it returns a negative error code.

Remarks

This is a one-off, stateless function.

The input is expected to be the ciphertext with a 16-byte tag appended ciphertext||Tag, or, if the API_IV_PREFIX option is set, then the same but with the 12/16-byte IV (nonce) prepended IV||ciphertext||Tag, where || denotes concatenation. If the IV is not prepended to the input, then it must be provided in the lpNonce argument. The length of the nonce/IV must be exactly 16 bytes for API_AEAD_ASCON_128, otherwise exactly 12 bytes. Note that the term "IV" is used here to mean exactly the same as "nonce". If additional authentication data (AAD) was provided during encryption then the exact same AAD data must be provided here.

The output plaintext is always exactly the same length as the input ciphertext (excluding any IV or tags in the input). If nOutBytes is set to zero or lpOutput set to 0 (or NULL in C or ByVal 0& in VBA), the required number of bytes will be returned. This will be either exactly 16 bytes shorter than the length of the input, or 28/32 bytes shorter if the API_IV_PREFIX option is used.

If the inputs are not authentic, the function returns the error code AUTH_FAILED_ERROR and the decrypted output should be rejected.

The output buffer lpOutput must not be the same as or overlap with the input lpInput.

Closes the AEAD context and destroys the key (in incremental mode).

Parameters

[in]

hContext

handle to the AEAD context set up by an earlier call to AEAD_InitKey.

Returns

If successful, the return value is zero; otherwise it returns a nonnegative error code.

Encrypt input using specified AEAD algorithm in one-off operation.

All the input and output parameters are in byte arrays. The authentication tag is output separately.

Parameters

[out]	lpOutput	byte array of sufficient length to receive the output.
[in]	nOutLen	length in bytes of the output buffer.
[out]	lpTagOut	byte array of sufficient length to receive the tag (currently 16 bytes for all supported algorithms).
[in]	nTagLen	length in bytes of the tag array.
[in]	lpData	byte array containing the input data.
[in]	nDataLen	length in bytes of the input data.
[in]	lpKey	byte array containing the key of exact length for given algorithm (currently either 16 or 32 bytes).
[in]	nKeyLen	length of the key in bytes.
[in]	lpNonce	containing the nonce (IV) of exact length for the given algorithm (currently always 12 bytes).
[in]	nNonceLen	length of the nonce in bytes.
[in]	lpAAD	byte array containing the optional Additional Authenticated Data (AAD).
[in]	nAadLen	length of the AAD in bytes.
[in]	nOptions	option flags. Must be one of the following: API_AEAD_AES_128_GCM to use the AEAD_AES_128_GCM authenticated encryption algorithm (RFC 5116) API_AEAD_AES_256_GCM to use the AEAD_AES_256_GCM authenticated encryption algorithm (RFC 5116) API_AEAD_CHACHA20_POLY1305 to use the AEAD_CHACHA20_POLY1305 authenticated encryption algorithm (RFC 7539)

Returns

If successful, the return value is zero; otherwise it returns a nonnegative error code.

Remarks

This is a one-off, stateless function. The output buffer lpOutput must be at least as long as the input. The ciphertext is always the same length as the plaintext and the authentication tag is always exactly 16 bytes long. Note this function does not concatenate the tag after the ciphertext as suggested in [RFC5116]: for that behaviour, use AEAD_EncryptWithTag.

MAC

To compute a message authentication code (MAC) over the additional data (AAD), pass zero values for both nOutLen and nDataLen (lpOutput and lpData are ignored and may be NULL). The "message" is passed in the AAD parameter and the MAC value is output in lpTagOut. A nonce is still required.

Encrypt input using specified AEAD algorithm in one-off operation with the authentication tag appended to output.

Parameters

[out]	lpOutput	buffer of sufficient length to receive the output.
[in]	nOutLen	length of the output buffer in bytes.
[in]	lpInput	byte array containing the input data.
[in]	nInputLen	length of the input data in bytes.
[in]	lpKey	byte array containing the key.
[in]	nKeyLen	length of the key in bytes (must be either 16 or 32).
[in]	lpNonce	(required) initialization vector (IV), a.k.a. nonce.
[in]	nNonceLen	length of the nonce in bytes (must be either 12 or 16).
[in]	lpAAD	(optional) additional authenticated data (AAD).
[in]	nAadLen	length of the AAD in bytes.
[in]	nOptions	option flags. Must be one of the following: API_AEAD_AES_128_GCM to use the AEAD_AES_128_GCM authenticated encryption algorithm (RFC 5116) API_AEAD_AES_256_GCM to use the AEAD_AES_256_GCM authenticated encryption algorithm (RFC 5116) API_AEAD_CHACHA20_POLY1305 to use the AEAD_CHACHA20_POLY1305 authenticated encryption algorithm (RFC 7539) API_AEAD_ASCON_128 to use the ASCON-128 authentication scheme (see ASCON) (provisional, subject to NIST final approval) API_AEAD_ASCON_128A to use the ASCON-128A authentication scheme (provisional, subject to NIST final approval) and optionally add: API_IV_PREFIX to prepend the IV (nonce) before the ciphertext in the output.

Returns

If successful, the return value is the number of bytes in or required in the output; otherwise it returns a negative error code.

Remarks

This is a one-off, stateless function that carries out Authenticated Encryption with Additional Data (AEAD). In this implementation, the tag is always exactly 16 bytes (128 bits). The tag is automatically appended to the output of the encryption operation in accordance with [RFC5116]. The IV may optionally be prepended to the output using the API_IV_PREFIX option flag. Note that the term "IV" is used here to mean exactly the same as "nonce".

The length of key lpKey must be exactly the required key size in bytes: 16 for API_AEAD_AES_128_GCM and API_AEAD_ASCON_128; or 32 for API_AEAD_AES_256_GCM and API_AEAD_CHACHA20_POLY1305. It is an error if the algorithm is not specified in the nOptions argument. The length of the nonce/IV must be exactly 16 bytes for API_AEAD_ASCON_128, otherwise exactly 12 bytes. The user is responsible for providing a unique IV each time the same key is used. Be aware it is a serious security risk if the same IV and key are used to encrypt different plaintexts.

If nOutBytes is set to zero or lpOutput set to 0 (or NULL in C or ByVal 0& in VBA), the required number of bytes will be returned. This will be either exactly tagLen (16) bytes longer than the length of the input, or exactly tagLen+ivLen (28/32) bytes longer if the API_IV_PREFIX option is used.

The output buffer lpOutput must not be the same as or overlap with the input lpInput.

Finishes the authenticated decryption (in incremental mode) .

Parameters

[in]

hContext

handle to the AEAD context set up by an earlier call to AEAD_InitKey.

Returns

If successful, the return value is zero; otherwise it returns a nonnegative error code.

Remarks

Returns the nonzero error code AUTH_FAILED_ERROR (-40) if the inputs are not authentic. Must be preceded by AEAD_StartDecrypt and zero or more calls to AEAD_Update. May be followed by
AEAD_SetNonce to begin processing another packet with the same key and algorithm; otherwise should be followed by AEAD_Destroy . Returns MISUSE_ERROR if called out of sequence.

Finishes the authenticated encryption (in incremental mode) .

Parameters

[in]	hContext	handle to the AEAD context set up by an earlier call to AEAD_InitKey.
[out]	lpTagOut	byte array of sufficient length to receive the tag (currently 16 bytes for all supported algorithms).
[in]	nTagLen	specifying the length in bytes of the tag array.

Returns

If successful, the return value is zero; otherwise it returns a nonnegative error code.

Remarks

Must be preceded by AEAD_StartEncrypt and zero or more calls to AEAD_Update. May be followed by
AEAD_SetNonce to begin processing another packet with the same key and algorithm; otherwise should be followed by AEAD_Destroy . Returns MISUSE_ERROR if called out of sequence.

Initializes the context with the key and algorithm ready for repeated incremental operations.

Parameters

[in]	lpKey	byte array containing the key of exact length for given algorithm (currently either 16 or 32 bytes).
[in]	nKeyLen	equal to length of the key in bytes.
[in]	nOptions	option flags. Select one of the following: API_AEAD_AES_128_GCM to use the AEAD_AES_128_GCM authenticated encryption algorithm (RFC 5116) API_AEAD_AES_256_GCM to use the AEAD_AES_256_GCM authenticated encryption algorithm (RFC 5116) API_AEAD_CHACHA20_POLY1305 to use the AEAD_CHACHA20_POLY1305 authenticated encryption algorithm (RFC 7539)

Returns

If successful, the return value is the nonzero handle of the AEAD context hContext; otherwise it returns zero if an error occurred.

Remarks

Must be followed by AEAD_SetNonce. This function can be called at any time to cancel any previous context settings. Note that a zero return value indicates an error: Use API_ErrorCode to find more details of the error. For more details of the correct sequence to call the incremental AEAD functions, see Correct sequence for AEAD incremental functions.

Set the nonce (in incremental mode).

Parameters

[in]	hContext	handle to the AEAD context set up by an earlier call to AEAD_InitKey.
[in]	lpNonce	containing the nonce of exact length for the given algorithm (currently always 12 bytes).
[in]	nNonceLen	equal to length of the nonce in bytes.

Returns

If successful, the return value is zero; otherwise it returns a nonnegative error code.

Remarks

Must be followed by zero or more calls to AEAD_AddAAD and then either AEAD_StartEncrypt or AEAD_StartDecrypt. Returns MISUSE_ERROR if called out of sequence.

Start authenticated decryption (in incremental mode).

Parameters

[in]	hContext	handle to the AEAD context set up by an earlier call to AEAD_InitKey.
[in]	lpTagToCheck	byte array containing the tag to be checked.
[in]	nTagLen	equal to length of the tag in bytes.

Returns

If successful, the return value is zero; otherwise it returns a nonnegative error code.

Remarks

May be followed by zero or more calls to AEAD_Update to decrypt data in chunks. Must eventually be followed by
AEAD_FinishDecrypt. Returns MISUSE_ERROR if called out of sequence. Caution: do not trust decrypted data until final authentication.

Start authenticated encryption (in incremental mode).

Parameters

[in]

hContext

handle to the AEAD context set up by an earlier call to AEAD_InitKey.

Returns

If successful, the return value is zero; otherwise it returns a nonnegative error code.

Remarks

May be followed by zero or more calls to AEAD_Update to encrypt data in chunks. Must eventually be followed by
AEAD_FinishEncrypt. Returns MISUSE_ERROR if called out of sequence.

Encrypts or decrypts a chunk of input (in incremental mode).

Parameters

[in]	hContext	handle to the AEAD context set up by an earlier call to AEAD_InitKey.
[out]	lpOutput	byte array of sufficient length to receive the output (at least as long as the input).
[in]	nOutLen	specifying the length in bytes of the output array.
[in]	lpData	byte array containing the input data.
[in]	nDataLen	equal to length of the input data in bytes.

Returns

If successful, the return value is zero; otherwise it returns a nonnegative error code.

Remarks

This function may be repeated to add input data in chunks.

The input data is encrypted or decrypted depending on the start mode set by a preceding call to AEAD_StartEncrypt or AEAD_StartDecrypt, respectively.

It must eventually be followed by either AEAD_FinishEncrypt or AEAD_FinishDecrypt, which must match the start mode.

Returns MISUSE_ERROR if called out of sequence.

Encrypts or decrypts data represented as a base64 string using a specified mode.

The key and initialization vector are represented as base64 strings.

Parameters

[out]	szOutput	of sufficient length to receive the output.
[in]	szInput	containing the input data in base64.
[in]	szKey	containing the key in base64.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	szIV	containing the initialization vector (IV), if required, in base64.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The length of the input string szInput must represent a multiple of the block size (16 bytes) when decoded. If not, an error will be returned. The initialization vector string szIV must represent exactly 16 bytes unless szMode is ECB, in which case szIV is ignored (use ""). The key szKey must also represent exactly 16 bytes, the required key length. The output string szOutput must be set up with at least the same number of characters as the input string before calling. The variables szOutput and szInput should be different.

Encrypts or decrypts an array of Bytes in one step in Electronic Codebook (EBC) mode.

Parameters

[out]	lpOutput	array of sufficient length to receive the output.
[in]	lpInput	array containing the input data.
[in]	nBytes	equal to length of the input data in bytes.
[in]	lpKey	array containing the key.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The input array lpData must be an exact multiple of 16 bytes long. If not, an error code will be returned. The key array abKey() must be exactly 16 bytes long. The output array lpOutput must be at least as long as the input array. lpOutput and lpData may be the same.

This function is equivalent to

nRet = AES128_BytesMode(lpOutput, abData, nDataLen, abKey, bEncrypt, "ECB", 0)

Encrypts or decrypts an array of Bytes using a specified mode.

The key and IV data are in byte arrays.

Parameters

[out]	lpOutput	array of sufficient length to receive the output.
[in]	lpInput	array containing the input data.
[in]	nBytes	equal to length of the input data in bytes.
[in]	lpKey	array containing the key.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	lpIV	containing the initialization vector (IV), or zero (0) for ECB mode.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The input array lpData must be an exact multiple of 16 bytes long. If not, an error code will be returned. The key array abKey() must be exactly 16 bytes long. The initialization vector abInitV() must be exactly the block size of 16 bytes long, except for ECB mode, where it is ignored (use 0). The output array lpOutput must be at least as long as the input array. lpOutput and lpData may be the same.

Encrypts or decrypts a file using a specified mode.

The key and initialization vector are passed as arrays of bytes.

Parameters

[in]	szFileOut	with the full path name of the output file to be created.
[in]	szFileIn	with the full path name of the input file to be processed.
[in]	lpKey	array containing the key.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	lpIV	array containing the initialization vector (IV), or zero (0) for ECB mode.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The key array abKey() must be exactly 16 bytes long. The initialization vector abInitV() must be exactly the block size of 16 bytes long, except for ECB mode, where it is ignored (use 0).

The output file szFileOut will be overwritten without warning. If there is an error [new in version 3.3], the output file will not exist. The input and output filepaths must not be the same.

In ECB and CBC modes, a padding string will be added or assumed according to the method outlined in Section 6.3 of [CMS], which is the same as the padding method in [PKCS7] and [PKCS5].

Encrypts or decrypts a file using a specified mode.

The key and initialization vector are passed as arrays of bytes.

Parameters

[in]	szFileOut	with the full path name of the output file to be created.
[in]	szFileIn	with the full path name of the input file to be processed.
[in]	lpKey	array containing the key.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	lpIV	array containing the initialization vector (IV), or zero (0) for ECB mode.
[in]	nOptions	option flags: Zero (0) for default behaviour as per AES128_File. API_IV_PREFIX to prepend the IV before the ciphertext in the output file (ignored for ECB mode) API_PAD_LEAVE to leave any padding in place when decrypting (ECB and CBC modes only; ignored if encrypting)

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

For the default behaviour, see AES128_File. The options are ignored if not applicable. For more information on the behaviour of the options, see Extensions to block cipher functions for files.

Encrypts or decrypts a file using a specified mode.

The key and initialization vector are passed as hexadecimal strings.

Parameters

[in]	szFileOut	with the full path name of the output file to be created.
[in]	szFileIn	with the full path name of the input file to be processed.
[in]	szKey	containing the key in hexadecimal.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	szIV	containing the initialization vector (IV) in hexadecimal.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The key string szHexKey must be exactly 32 hexadecimal characters long (i.e. representing exactly 16 bytes/128 bits). The initialization vector szHexIV must be exactly 32 hexadecimal characters long (i.e. representing exactly the block size of 16 bytes), except for ECB mode, where it is ignored (use "").

The output file szFileOut will be overwritten without warning. If there is an error [new in version 3.3], the output file will not exist. The input and output filepaths must not be the same.

In ECB and CBC modes, a padding string will be added or assumed according to the method outlined in Section 6.3 of [CMS], which is the same as the padding method in [PKCS7] and [PKCS5].

Note that even though the parameters are in hexadecimal-encoded form, the encrypted file is still binary.

Closes and clears the AES context.

Parameters

[in]

hContext

containing the handle to the AES context.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Encrypts or decrypts data represented as a hexadecimal string using a key represented in hexadecimal notation.

The process is carried out in one step in Electronic Codebook (EBC) mode.

Parameters

[out]	szOutput	of sufficient length to receive the output.
[in]	szInput	containing the input data in hexadecimal.
[in]	szKey	containing the key in hexadecimal.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The length of the input string szInput should be a multiple of 32 hex characters long (i.e. representing a multiple of 16 bytes). The key string szHexKey must be exactly 32 hex characters long (i.e. representing exactly 16 bytes).

The output string szOutput must be set up with at least the same number of characters as the input string before calling. The variables szOutput and szInput should be different. Valid hexadecimal characters are [0-9A-Fa-f].

This function is equivalent to

nRet = AES128_HexMode(strOutput, strInput, strHexKey, bEncrypt, "ECB", 0)

Encrypts or decrypts data represented as a hexadecimal string using a specified mode.

The key and initialization vector are represented as a hexadecimal string.

Parameters

[out]	szOutput	of sufficient length to receive the output.
[in]	szInput	containing the input data in hexadecimal.
[in]	szKey	containing the key in hexadecimal.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	szIV	containing the initialization vector (IV) in hexadecimal.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The length of the input string szInput should be a multiple of 32 hex characters long (i.e. representing a multiple of 16 bytes). The key string szHexKey must be exactly 32 hex characters long (i.e. representing exactly 16 bytes/128 bits).

The initialization vector szHexIV must be exactly 32 hex characters long (i.e. representing exactly the block size of 16 bytes), except for ECB mode, where it is ignored (use ""). The output string szOutput must be set up with at least the same number of characters as the input string before calling. The variables szOutput and szInput should be different. Valid hexadecimal characters are [0-9A-Fa-f].

Initialises the context with the key, direction and mode ready for repeated operations of the AES function.

The key and IV data are in byte arrays.

Parameters

[in]	lpKey	array containing the key.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	lpIV	array containing the initialization vector, or zero (0) for ECB mode.

Returns

Non-zero handle of the context hContext to be used in subsequent calls to the functions AES128_Update, AES128_UpdateHex or AES128_Final. Returns zero if an error occurs.

Remarks

The key array abKey() must be exactly 16 bytes long. The initialization vector abInitV() must be exactly the block size of 16 bytes long, except for ECB mode, where it is ignored (use 0). Unlike most other functions in this API, AES128_Init returns zero if an error occurs. It is important to check that the value of hContext returned is not equal to zero before calling the AES Update function.

Returns the error code after an unsuccessful call to AES128_Init or AES128_InitHex.

Returns

Returns the error code from the last call to AES128_Init or AES128_InitHex.

Initialises the context with the key, direction and mode ready for repeated operations of the AES function.

The key and IV data are passed in hexadecimal format.

Parameters

[in]	szKey	containing the key in hexadecimal representation.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	szIV	containing the initialization vector in hexadecimal.

Returns

Non-zero handle of the context hContext to be used in subsequent calls to the functions AES128_Update, AES128_UpdateHex or AES128_Final. Returns zero if an error occurs.

Remarks

The key string szHexKey must be exactly 32 hexadecimal characters long (i.e. representing exactly 16 bytes/128 bits).

The initialization vector szHexIV must be exactly 32 hexadecimal characters long (i.e. representing exactly the block size of 16 bytes), except for ECB mode, where it is ignored (use ""). Valid hexadecimal characters are [0-9A-Fa-f]. Unlike most other functions in this API, AES128_InitHex returns zero if an error occurs. It is important to check that the value of hContext returned is not equal to zero before calling the AES Update function.

Carries out the AES transformation function on a byte array according to the direction and mode set up by an earlier call to AES128_Init() or AES128_InitHex().

Parameters

[in]	hContext	handle to the AES context set up by an earlier call to AES128_Init() or AES128_InitHex().
[in,out]	lpData	array containing the input to be processed by the AES function and to receive the output.
[in]	nDataLen	containing length of the data in bytes.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The input array lpData must be an exact multiple of 16 bytes long. If not, an error code will be returned. Note that the output overwrites the input.

Carries out the AES transformation function on a hexadecimal string according to the direction and mode set up by an earlier call to AES128_Init() or AES128_InitHex().

Parameters

[in]	hContext	handle to the AES context set up by an earlier call to AES128_Init() or AES128_InitHex().
[in,out]	szHexData	containing input in hexadecimal format to be processed by the AES function and to receive the output.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The length of the input string szHexString must be a multiple of 32 hex characters long (i.e. representing a multiple of the block size of 16 bytes).

If not, an error code will be returned. Valid hexadecimal characters are [0-9A-Fa-f]. Note that the output overwrites the input. szHexString must be a variable that can receive the output, not a constant.

Encrypts or decrypts data represented as a base64 string using a specified mode.

The key and initialization vector are represented as base64 strings.

Parameters

[out]	szOutput	of sufficient length to receive the output.
[in]	szInput	containing the input data in base64.
[in]	szKey	containing the key in base64.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	szIV	containing the initialization vector (IV), if required, in base64.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The length of the input string szInput must represent a multiple of the block size (16 bytes) when decoded. If not, an error will be returned. The initialization vector string szIV must represent exactly 16 bytes unless szMode is ECB, in which case szIV is ignored (use ""). The key szKey must represent exactly 24 bytes, the required key length. The output string szOutput must be set up with at least the same number of characters as the input string before calling. The variables szOutput and szInput should be different.

Encrypts or decrypts an array of Bytes in one step in Electronic Codebook (EBC) mode.

Parameters

[out]	lpOutput	array of sufficient length to receive the output.
[in]	lpInput	array containing the input data.
[in]	nBytes	equal to length of the input data in bytes.
[in]	lpKey	array containing the key.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The input array lpData must be a multiple of the block size of 16 bytes long. If not, an error code will be returned. The key array abKey() must be exactly 24 bytes (i.e. 192 bits) long. The output array lpOutput must be at least as long as the input array. lpOutput and lpData may be the same.

This function is equivalent to

nRet = AES192_BytesMode(lpOutput, abData, nDataLen, abKey, bEncrypt, "ECB", 0)

Encrypts or decrypts an array of Bytes using a specified mode.

The key and IV data are in byte arrays.

Parameters

[out]	lpOutput	array of sufficient length to receive the output.
[in]	lpInput	array containing the input data.
[in]	nBytes	equal to length of the input data in bytes.
[in]	lpKey	array containing the key.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	lpIV	containing the initialization vector (IV), or zero (0) for ECB mode.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The input array lpData must be a multiple of the block size of 16 bytes long. If not, an error code will be returned. The key array abKey() must be exactly 24 bytes long (i.e. 192 bits). The initialization vector abInitV() must be exactly the block size of 16 bytes long, except for ECB mode, where it is ignored (use 0). The output array lpOutput must be at least as long as the input array. lpOutput and lpData may be the same.

Encrypts or decrypts a file using a specified mode.

The key and initialization vector are passed as arrays of bytes.

Parameters

[in]	szFileOut	with the full path name of the output file to be created.
[in]	szFileIn	with the full path name of the input file to be processed.
[in]	lpKey	array containing the key.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	lpIV	array containing the initialization vector (IV), or zero (0) for ECB mode.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The key array abKey() must be exactly 24 bytes long (i.e. 192 bits). The initialization vector abInitV() must be exactly the block size of 16 bytes long, except for ECB mode, where it is ignored (use 0).

The output file szFileOut will be overwritten without warning. If there is an error [new in version 3.3], the output file will not exist. The input and output filepaths must not be the same.

In ECB and CBC modes, a padding string will be added or assumed according to the method outlined in Section 6.3 of [CMS], which is the same as the padding method in [PKCS7] and [PKCS5].

Encrypts or decrypts a file using a specified mode with extended options.

Parameters

[in]	szFileOut	with the full path name of the output file to be created.
[in]	szFileIn	with the full path name of the input file to be processed.
[in]	lpKey	array containing the key.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	lpIV	array containing the initialization vector (IV), or zero (0) for ECB mode.
[in]	nOptions	option flags: Zero (0) for default behaviour as per AES192_File. API_IV_PREFIX to prepend the IV before the ciphertext in the output file (ignored for ECB mode) API_PAD_LEAVE to leave any padding in place when decrypting (ECB and CBC modes only; ignored if encrypting)

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Encrypts or decrypts a file using a specified mode.

The key and initialization vector are passed as hexadecimal strings.

Parameters

[in]	szFileOut	with the full path name of the output file to be created.
[in]	szFileIn	with the full path name of the input file to be processed.
[in]	szKey	containing the key in hexadecimal.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	szIV	containing the initialization vector (IV) in hexadecimal.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The key string szHexKey must be exactly 48 hexadecimal characters long (i.e. representing exactly 24 bytes/192 bits). The initialization vector szHexIV must be exactly 32 hexadecimal characters long (i.e. representing the block size of exactly 16 bytes), except for ECB mode, where it is ignored (use "").

The output file szFileOut will be overwritten without warning. If there is an error [new in version 3.3], the output file will not exist. The input and output filepaths must not be the same.

In ECB and CBC modes, a padding string will be added or assumed according to the method outlined in Section 6.3 of [CMS], which is the same as the padding method in [PKCS7] and [PKCS5].

Note that even though the parameters are in hexadecimal-encoded form, the encrypted file is still binary.

Closes and clears the AES context.

Parameters

[in]

hContext

containing the handle to the AES context.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Encrypts or decrypts data represented as a hexadecimal string using a key represented in hexadecimal notation.

The process is carried out in one step in Electronic Codebook (EBC) mode.

Parameters

[out]	szOutput	of sufficient length to receive the output.
[in]	szInput	containing the input data in hexadecimal.
[in]	szKey	containing the key in hexadecimal.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The length of the input string szInput must be a multiple of 32 hex characters long (i.e. representing a multiple of the block size of 16 bytes). The key string szHexKey must be exactly 48 hex characters long (i.e. representing exactly 24 bytes/192 bits).

The output string szOutput must be set up with at least the same number of characters as the input string before calling. The variables szOutput and szInput should be different. Valid hexadecimal characters are [0-9A-Fa-f].

This function is equivalent to

nRet = AES192_HexMode(strOutput, strInput, strHexKey, bEncrypt, "ECB", 0)

Encrypts or decrypts data represented as a hexadecimal string using a specified mode.

The key and initialization vector are represented as a hexadecimal string.

Parameters

[out]	szOutput	of sufficient length to receive the output.
[in]	szInput	containing the input data in hexadecimal.
[in]	szKey	containing the key in hexadecimal.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	szIV	containing the initialization vector (IV) in hexadecimal.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The length of the input string szInput must be a multiple of 32 hex characters long (i.e. representing a multiple of the block size of 16 bytes). The key string szHexKey must be exactly 48 hex characters long (i.e. representing exactly 24 bytes/192 bits).

The initialization vector szHexIV must be exactly 32 hex characters long (i.e. representing the block size of exactly 16 bytes), except for ECB mode, where it is ignored (use ""). The output string szOutput must be set up with at least the same number of characters as the input string before calling. The variables szOutput and szInput should be different. Valid hexadecimal characters are [0-9A-Fa-f].

Initialises the context with the key, direction and mode ready for repeated operations of the AES function.

The key and IV data are in byte arrays.

Parameters

[in]	lpKey	array containing the key.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	lpIV	array containing the initialization vector, or zero (0) for ECB mode.

Returns

Non-zero handle of the context hContext to be used in subsequent calls to the functions AES192_Update, AES192_UpdateHex or AES192_Final. Returns zero if an error occurs.

Remarks

The key array abKey() must be exactly 24 bytes long (i.e. 192 bits). The initialization vector abInitV() must be exactly the block size of 16 bytes long, except for ECB mode, where it is ignored (use 0). Unlike most other functions in this API, AES192_Init returns zero if an error occurs. It is important to check that the value of hContext returned is not equal to zero before calling the AES Update function.

Returns the error code after an unsuccessful call to AES192_Init or AES192_InitHex.

Returns

Returns the error code from the last call to AES192_Init or AES192_InitHex.

Initialises the context with the key, direction and mode ready for repeated operations of the AES function.

The key and IV data are passed in hexadecimal format.

Parameters

[in]	szKey	containing the key in hexadecimal representation.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	szIV	containing the initialization vector in hexadecimal.

Returns

Non-zero handle of the context hContext to be used in subsequent calls to the functions AES192_Update, AES192_UpdateHex or AES192_Final. Returns zero if an error occurs.

Remarks

The key string szHexKey must be exactly 48 hexadecimal characters long (i.e. representing exactly 24 bytes/192 bits).

The initialization vector szHexIV must be exactly 32 hexadecimal characters long (i.e. representing exactly the block size of 16 bytes), except for ECB mode, where it is ignored (use ""). Valid hexadecimal characters are [0-9A-Fa-f]. Unlike most other functions in this API, AES192_InitHex returns zero if an error occurs. It is important to check that the value of hContext returned is not equal to zero before calling the AES Update function.

Carries out the AES transformation function on a byte array according to the direction and mode set up by an earlier call to AES192_Init() or AES192_InitHex().

Parameters

[in]	hContext	handle to the AES context set up by an earlier call to AES192_Init() or AES192_InitHex().
[in,out]	lpData	array containing the input to be processed by the AES function and to receive the output.
[in]	nDataLen	containing length of the data in bytes.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The input array lpData must be a multiple of the block size of 16 bytes long. If not, an error code will be returned. Note that the output overwrites the input.

Carries out the AES transformation function on a hexadecimal string according to the direction and mode set up by an earlier call to AES192_Init() or AES192_InitHex().

Parameters

[in]	hContext	handle to the AES context set up by an earlier call to AES192_Init() or AES192_InitHex().
[in,out]	szHexData	containing input in hexadecimal format to be processed by the AES function and to receive the output.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

szHexString The length of the input string szHexString must be a multiple of 32 hex characters long (i.e. representing a multiple of the block size of 16 bytes).

If not, an error code will be returned. Valid hexadecimal characters are [0-9A-Fa-f]. Note that the output overwrites the input. szHexString must be a variable that can receive the output, not a constant.

Encrypts or decrypts data represented as a base64 string using a specified mode.

The key and initialization vector are represented as base64 strings.

Parameters

[out]	szOutput	of sufficient length to receive the output.
[in]	szInput	containing the input data in base64.
[in]	szKey	containing the key in base64.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	szIV	containing the initialization vector (IV), if required, in base64.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The length of the input string szInput must represent a multiple of the block size (16 bytes) when decoded. If not, an error will be returned. The initialization vector string szIV must represent exactly 16 bytes unless szMode is ECB, in which case szIV is ignored (use ""). The key szKey must represent exactly 32 bytes, the required key length. The output string szOutput must be set up with at least the same number of characters as the input string before calling. The variables szOutput and szInput should be different.

Encrypts or decrypts an array of Bytes in one step in Electronic Codebook (EBC) mode.

Parameters

[out]	lpOutput	array of sufficient length to receive the output.
[in]	lpInput	array containing the input data.
[in]	nBytes	equal to length of the input data in bytes.
[in]	lpKey	array containing the key.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The input array lpData must be a multiple of the block size of 16 bytes long. If not, an error code will be returned. The key array abKey() must be exactly 32 bytes long (i.e. 256 bits). The output array lpOutput must be at least as long as the input array. lpOutput and lpData may be the same.

This function is equivalent to

nRet = AES256_BytesMode(lpOutput, abData, nDataLen, abKey, bEncrypt, "ECB", 0)

Encrypts or decrypts an array of Bytes using a specified mode.

The key and IV data are in byte arrays.

Parameters

[out]	lpOutput	array of sufficient length to receive the output.
[in]	lpInput	array containing the input data.
[in]	nBytes	equal to length of the input data in bytes.
[in]	lpKey	array containing the key.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	lpIV	containing the initialization vector (IV), or zero (0) for ECB mode.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The input array lpData must be a multiple of the block size of 16 bytes long. If not, an error code will be returned. The key array abKey() must be exactly 32 bytes long (i.e. 256 bits). The initialization vector abInitV() must be exactly the block size of 16 bytes long, except for ECB mode, where it is ignored (use 0). The output array lpOutput must be at least as long as the input array. lpOutput and lpData may be the same.

Encrypts or decrypts a file using a specified mode.

The key and initialization vector are passed as arrays of bytes.

Parameters

[in]	szFileOut	with the full path name of the output file to be created.
[in]	szFileIn	with the full path name of the input file to be processed.
[in]	lpKey	array containing the key.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	lpIV	array containing the initialization vector (IV), or zero (0) for ECB mode.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The key array abKey() must be exactly 32 bytes long (i.e. 256 bits). The initialization vector abInitV() must be exactly the block size of 16 bytes long, except for ECB mode, where it is ignored (use 0).

The output file szFileOut will be overwritten without warning. If there is an error [new in version 3.3], the output file will not exist. The input and output filepaths must not be the same.

In ECB and CBC modes, a padding string will be added or assumed according to the method outlined in Section 6.3 of [CMS], which is the same as the padding method in [PKCS7] and [PKCS5].

Encrypts or decrypts a file using a specified mode with extended options.

Parameters

[in]	szFileOut	with the full path name of the output file to be created.
[in]	szFileIn	with the full path name of the input file to be processed.
[in]	lpKey	array containing the key.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	lpIV	array containing the initialization vector (IV), or zero (0) for ECB mode.
[in]	nOptions	option flags: Zero (0) for default behaviour as per AES256_File. API_IV_PREFIX to prepend the IV before the ciphertext in the output file (ignored for ECB mode) API_PAD_LEAVE to leave any padding in place when decrypting (ECB and CBC modes only; ignored if encrypting)

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

For the default behaviour, see AES256_File. The options are ignored if not applicable. For more information on the behaviour of the options, see Extensions to block cipher functions for files.

Encrypts or decrypts a file using a specified mode.

The key and initialization vector are passed as hexadecimal strings.

Parameters

[in]	szFileOut	with the full path name of the output file to be created.
[in]	szFileIn	with the full path name of the input file to be processed.
[in]	szKey	containing the key in hexadecimal.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	szIV	containing the initialization vector (IV) in hexadecimal.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The key string szHexKey must be exactly 64 hexadecimal characters long (i.e. representing exactly 32 bytes/256 bits). The initialization vector szHexIV must be exactly 32 hexadecimal characters long (i.e. representing exactly the block size of 16 bytes), except for ECB mode, where it is ignored (use "").

The output file szFileOut will be overwritten without warning. If there is an error [new in version 3.3], the output file will not exist. The input and output filepaths must not be the same.

In ECB and CBC modes, a padding string will be added or assumed according to the method outlined in Section 6.3 of [CMS], which is the same as the padding method in [PKCS7] and [PKCS5].

Note that even though the parameters are in hexadecimal-encoded form, the encrypted file is still binary.

Closes and clears the AES context.

Parameters

[in]

hContext

containing the handle to the AES context.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Encrypts or decrypts data represented as a hexadecimal string using a key represented in hexadecimal notation.

The process is carried out in one step in Electronic Codebook (EBC) mode.

Parameters

[out]	szOutput	of sufficient length to receive the output.
[in]	szInput	containing the input data in hexadecimal.
[in]	szKey	containing the key in hexadecimal.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The length of the input string szInput must be a multiple of 32 hex characters long (i.e. representing a multiple of the block size of 16 bytes). The key string szHexKey must be exactly 64 hex characters long (i.e. representing exactly 32 bytes/256 bits).

The output string szOutput must be set up with at least the same number of characters as the input string before calling. The variables szOutput and szInput should be different. Valid hexadecimal characters are [0-9A-Fa-f].

This function is equivalent to

nRet = AES256_HexMode(strOutput, strInput, strHexKey, bEncrypt, "ECB", 0)

Encrypts or decrypts data represented as a hexadecimal string using a specified mode.

The key and initialization vector are represented as a hexadecimal string.

Parameters

[out]	szOutput	of sufficient length to receive the output.
[in]	szInput	containing the input data in hexadecimal.
[in]	szKey	containing the key in hexadecimal.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	szIV	containing the initialization vector (IV) in hexadecimal.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The length of the input string szInput must be a multiple of 32 hex characters long (i.e. representing a multiple of the block size of 16 bytes). The key string szHexKey must be exactly 64 hex characters long (i.e. representing exactly 32 bytes/256 bits).

The initialization vector szHexIV must be exactly 32 hex characters long (i.e. representing exactly the block size of 16 bytes), except for ECB mode, where it is ignored (use ""). The output string szOutput must be set up with at least the same number of characters as the input string before calling. The variables szOutput and szInput should be different. Valid hexadecimal characters are [0-9A-Fa-f].

Initialises the context with the key, direction and mode ready for repeated operations of the AES function.

The key and IV data are in byte arrays.

Parameters

[in]	lpKey	array containing the key.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	lpIV	array containing the initialization vector, or zero (0) for ECB mode.

Returns

Non-zero handle of the context hContext to be used in subsequent calls to the functions AES256_Update, AES256_UpdateHex or AES256_Final. Returns zero if an error occurs.

Remarks

The key array abKey() must be exactly 32 bytes long (i.e. 256 bits). The initialization vector abInitV() must be exactly the block size of 16 bytes long, except for ECB mode, where it is ignored (use 0). Unlike most other functions in this API, AES256_Init returns zero if an error occurs. It is important to check that the value of hContext returned is not equal to zero before calling the AES Update function.

Returns the error code after an unsuccessful call to AES256_Init or AES256_InitHex.

Returns

Returns the error code from the last call to AES256_Init or AES256_InitHex.

Initialises the context with the key, direction and mode ready for repeated operations of the AES function.

The key and IV data are passed in hexadecimal format.

Parameters

[in]	szKey	containing the key in hexadecimal representation.
[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szMode	specifying the confidentiality mode: "ECB" for Electronic Codebook mode, "CBC" for Cipher Block Chaining mode, "CFB" for 128-bit Cipher Feedback mode, "OFB" for Output Feedback mode, or "CTR" for Counter mode.
[in]	szIV	containing the initialization vector in hexadecimal.

Returns

Non-zero handle of the context hContext to be used in subsequent calls to the functions AES256_Update, AES256_UpdateHex or AES256_Final. Returns zero if an error occurs.

Remarks

The key string szHexKey must be exactly 64 hexadecimal characters long (i.e. representing exactly 32 bytes/256 bits).

The initialization vector szHexIV must be exactly 32 hexadecimal characters long (i.e. representing exactly the block size of 16 bytes), except for ECB mode, where it is ignored (use ""). Valid hexadecimal characters are [0-9A-Fa-f]. Unlike most other functions in this API, AES256_InitHex returns zero if an error occurs. It is important to check that the value of hContext returned is not equal to zero before calling the AES Update function.

Carries out the AES transformation function on a byte array according to the direction and mode set up by an earlier call to AES256_Init() or AES256_InitHex().

Parameters

[in]	hContext	handle to the AES context set up by an earlier call to AES256_Init() or AES256_InitHex().
[in,out]	lpData	array containing the input to be processed by the AES function and to receive the output.
[in]	nDataLen	containing length of the data in bytes.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The input array lpData must be a multiple of the block size of 16 bytes long. If not, an error code will be returned. Note that the output overwrites the input.

Carries out the AES transformation function on a hexadecimal string according to the direction and mode set up by an earlier call to AES256_Init() or AES256_InitHex().

Parameters

[in]	hContext	handle to the AES context set up by an earlier call to AES256_Init() or AES256_InitHex().
[in,out]	szHexData	containing input in hexadecimal format to be processed by the AES function and to receive the output.

Returns

If successful, the return value is 0; otherwise it returns a non-zero error code.

Remarks

The length of the input string szHexString must be a multiple of 32 hex characters long (i.e. representing a multiple of the block size of 16 bytes).

If not, an error code will be returned. Valid hexadecimal characters are [0-9A-Fa-f]. Note that the output overwrites the input. szHexString must be a variable that can receive the output, not a constant.

Retrieves the date and time the core library executable was last compiled.

Parameters

[out]	szOutput	to receive the date and time string.
[in]	nMaxChars	specifying the maximum number of characters to be received.

Returns

If successful, the return value is the number of characters in the output string; otherwise it returns a negative error code.

Remarks

For the "raw" VBA/C function, the user must allocate an output string buffer szOutput of the required length. Specify a zero nOutChars or an empty string for szOutput to find the required length of the output string. C/C++ users must add one to this value when allocating memory.

Returns the error code of the error that occurred when calling the last function.

Returns

Returns the error code of the error that occurred when calling the last function, or zero if no error occurred.

Remarks

The value returned is always a non-negative integer greater than or equal to zero. Not all functions set this value.

Retrieves the error message associated with a given error code.

Parameters

[out]	szOutput	to receive error message.
[in]	nMaxChars	specifying the maximum number of characters to be received.
[in]	nErrCode	specifying the error code for which the message is required.

Returns

the number of characters in the output string or zero if there is no corresponding error message.

Remarks

The error message will never be longer than 127 characters.

Returns the ASCII value of the licence type.

Parameters

[in]

nOptions

not used in this release. Specify zero.

Returns

Returns the ASCII value of the licence type, either "D" (ASCII 68, 0x44) for the Developer Edition or "T" (ASCII 84, 0x54) for the Trial Edition.

Remarks

Note the Australian/British spelling of ‘Licence’.

Get additional information about the core DLL module.

Parameters

[out]	szOutput	Buffer to receive output string.
[in]	nOutChars	Maximum length of output string in bytes.
[in]	nOptions	option flags: not used in this release. Specify zero.

Returns

If successful, the return value is the number of characters in or required for the output string; otherwise it returns a negative error code.

Retrieves the name of the current process's module.

Parameters

[out]	szOutput	to receive the name of the module.
[in]	nMaxChars	specifying the maximum number of characters to be received.
[in]	nOptions	option flags: API_GEN_PLATFORM to get the platform name, either "Win32" or "X64".

Returns

If successful, the return value is the number of characters in the output string; otherwise it returns a negative error code.

Remarks

For the "raw" VBA/C function, the user must allocate an output string buffer szOutput of the required length. Specify a zero nOutChars or an empty string for szOutput to find the required length of the output string. C/C++ users must add one to this value when allocating memory.