AEAD_DecryptWithTag

CryptoSys API Library Manual

AEAD_DecryptWithTag

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.

VBA/VB6 Syntax


Public Declare Function AEAD_DecryptWithTag Lib "diCryptoSys.dll" (ByRef lpOutput As Byte, ByVal nOutLen As Long, ByRef lpInput As Byte, ByVal nInputLen As Long, ByRef lpKey As Byte, ByVal nKeyLen As Long, ByRef lpNonce As Byte, ByVal nNonceLen As Long, ByRef lpAAD As Byte, ByVal nAadLen As Long, ByVal nOptions As Long) As Long

nRet = AEAD_DecryptWithTag(lpOutput(0), nOutLen, abInput(0), nInputLen, abKey(0), nKeyLen, abNonce(0), nNonceLen, abAAD(0), nAadLen, nOptions)

C/C++ Syntax


long __stdcall  AEAD_DecryptWithTag(unsigned char *lpOutput, long nOutLen, const unsigned char *lpInput, long nInputLen, const unsigned char *lpKey, long nKeyLen, const unsigned char *lpNonce, long nNonceLen,const unsigned char *lpAAD, long nAadLen, long nOptions);

Parameters

lpOutput: [out] buffer of sufficient length to receive the plaintext output.
nOutLen: [in] length in bytes of the output buffer.
lpInput: [in] byte array containing the input data.
nInputLen: [in] length of the input data in bytes.
lpKey: [in] byte array containing the key of exact length for given algorithm (currently either 16 or 32 bytes).
nKeyLen: [in] length of the key in bytes.
lpNonce: [in] (optional) initialization vector (IV), a.k.a. nonce, if not provided in input.
nNonceLen: [in] length of the nonce in bytes.
lpAAD: [in] byte array containing the optional Additional Authenticated Data (AAD).
nAadLen: [in] length of the AAD in bytes.
nOptions: [in] 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 (VBA/C)

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

VBA Wrapper Syntax


Public Function aeadDecryptWithTag(lpData() As Byte, lpKey() As Byte, lpNonce() As Byte, lpAAD() As Byte, nOptions As Long) As Byte()

.NET Equivalent

Aead.DecryptWithTag Method (Byte[], Byte[], Byte[], Aead.Algorithm)
Aead.DecryptWithTag Method (Byte[], Byte[], Byte[], Byte[], Aead.Algorithm, Aead.Opts)

C++ (STL) Equivalent

static crsysapi::bvec_t crsysapi::Aead::DecryptWithTag (const bvec_t &data, const bvec_t &key, const bvec_t &iv, const bvec_t &aad, Alg alg, Opts opts=Opts::Default)

Python Equivalent

static Aead.decrypt_with_tag(input, key, iv, aeadalg, aad=None, opts=Opts.DEFAULT)

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.

Sizes in bytes
Algorithm	keyLen	ivLen	tagLen
`API_AEAD_AES_128_GCM`	16	12	16
`API_AEAD_AES_256_GCM`	32	12	16
`API_AEAD_CHACHA20_POLY1305`	32	12	16
`API_AEAD_ASCON_128`	16	16	16
`API_AEAD_ASCON_128A`	16	16	16

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.

Example (VBA core function)

See the example in AEAD_EncryptWithTag.

Example (VBA wrapper function)

See the example for VBA wrapper aeadEncryptWithTag in AEAD_EncryptWithTag.