AEAD_EncryptWithTag

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

VBA/VB6 Syntax

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

C/C++ Syntax

Parameters

lpOutput

[out] buffer of sufficient length to receive the output.

nOutLen

[in] length of the output buffer in bytes.

lpInput

[in] byte array containing the input data.

nInputLen

[in] length of the input data in bytes.

lpKey

[in] byte array containing the key.

nKeyLen

[in] length of the key in bytes (must be either 16 or 32).

lpNonce

[in] (required) initialization vector (IV), a.k.a. nonce.

nNonceLen

[in] length of the nonce in bytes (must be either 12 or 16).

lpAAD

[in] (optional) additional authenticated data (AAD).

nAadLen

[in] length of the AAD in bytes.

nOptions

[in] 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 (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

.NET Equivalent

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

C++ (STL) Equivalent

Python Equivalent

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.

Example (VBA core function)

This is the same example as in AEAD_Encrypt but with the tag appended to the output and the IV (nonce) prefixed.

' IEEE P802.1 MACsec 2.4.1 54-byte Packet Encryption Using GCM-AES-128:
Dim abKey() As Byte
Dim abNonce() As Byte
Dim abAAD() As Byte
Dim abPT() As Byte
Dim abCT() As Byte
Dim abDT() As Byte

Dim nKeyLen As Long
Dim nNonceLen As Long
Dim nAadLen As Long
Dim nPtLen As Long
Dim nCtLen As Long
Dim nDtLen As Long
Dim strCTOK As String

Debug.Print "IEEE P802.1 MACsec 2.4.1 54-byte Packet Encryption Using GCM-AES-128:"
Debug.Print "-- using AEAD_EncryptWithTag to output in form IV||CT||TAG"
' Set byte arrays from hex strings
abKey = cnvBytesFromHexStr("071b113b 0ca743fe cccf3d05 1f737382")
abNonce = cnvBytesFromHexStr("f0761e8d cd3d0001 76d457ed")
abAAD = cnvBytesFromHexStr("e20106d7 cd0df076 1e8dcd3d 88e54c2a 76d457ed")
abPT = cnvBytesFromHexStr("08000f10 11121314 15161718 191a1b1c 1d1e1f20 21222324 25262728 292a2b2c 2d2e2f30 31323334 0004")

' Output is ciphertext (same length as plaintext) plus 96-bit IV prefixed and 128-bit tag appended
strCTOK = "f0761e8dcd3d000176d457ed" & _
    "13b4c72b389dc5018e72a171dd85a5d3752274d3a019fbcaed09a425cd9b2e1c9b72eee7c9de7d52b3f3" & _
    "d6a5284f4a6d3fe22a5d6c2b960494c3"

' Get lengths of input byte arrays
nKeyLen = UBound(abKey) + 1
nNonceLen = UBound(abNonce) + 1
nAadLen = UBound(abAAD) + 1
nPtLen = UBound(abPT) + 1

' Display input
Debug.Print "K: " & cnvHexStrFromBytes(abKey)
Debug.Print "N: " & cnvHexStrFromBytes(abNonce)
Debug.Print "A: " & cnvHexStrFromBytes(abAAD)
Debug.Print "P: " & cnvHexStrFromBytes(abPT)
Debug.Print "Len(P)=" & UBound(abPT) + 1

' Find required output length and dimension output array
' -- this will be the length of plaintext in bytes plus 28
nCtLen = AEAD_EncryptWithTag(0, 0, abPT(0), nPtLen, abKey(0), nKeyLen, abNonce(0), nNonceLen, abAAD(0), nAadLen, _
    API_AEAD_AES_128_GCM Or API_IV_PREFIX)
Debug.Assert (nCtLen > 0)
ReDim abCT(nCtLen - 1)

' Do authenticated encryption using AEAD_AES_128_GCM
nCtLen = AEAD_EncryptWithTag(abCT(0), nCtLen, abPT(0), nPtLen, abKey(0), nKeyLen, abNonce(0), nNonceLen, _
    abAAD(0), nAadLen, API_AEAD_AES_128_GCM Or API_IV_PREFIX)
Debug.Print "AEAD_EncryptWithTag returns " & nCtLen & " (expected >0)"
Debug.Print "C: " & cnvHexStrFromBytes(abCT)
Debug.Print "OK " & strCTOK

' Do authenticated decryption (NB do *not* overwrite input with output)
' Find required output length
' -- this will be the length of ciphertext in bytes minus 28
nDtLen = AEAD_DecryptWithTag(0, 0, abCT(0), nCtLen, abKey(0), nKeyLen, abNonce(0), nNonceLen, _
    abAAD(0), nAadLen, API_AEAD_AES_128_GCM Or API_IV_PREFIX)
Debug.Print "AEAD_DecryptWithTag returns " & nDtLen & " (expected >0)"
Debug.Assert (nDtLen > 0)
ReDim abDT(nDtLen - 1)
nDtLen = AEAD_DecryptWithTag(abDT(0), nDtLen, abCT(0), nCtLen, abKey(0), nKeyLen, abNonce(0), nNonceLen, _
    abAAD(0), nAadLen, API_AEAD_AES_128_GCM Or API_IV_PREFIX)
Debug.Print "P`:" & cnvHexStrFromBytes(abDT)
Debug.Print "OK " & cnvHexStrFromBytes(abPT)

IEEE P802.1 MACsec 2.4.1 54-byte Packet Encryption Using GCM-AES-128:
-- using AEAD_EncryptWithTag to output in form IV||CT||TAG
K: 071B113B0CA743FECCCF3D051F737382
N: F0761E8DCD3D000176D457ED
A: E20106D7CD0DF0761E8DCD3D88E54C2A76D457ED
P: 08000F101112131415161718191A1B1C1D1E1F202122232425262728292A2B2C2D2E2F30313233340004
Len(P)=42
AEAD_EncryptWithTag returns 70 (expected >0)
C: F0761E8DCD3D000176D457ED13B4C72B389DC5018E72A171DD85A5D3752274D3A019FBCAED09A425CD9B2E1C9B72EEE7C9DE7D52B3F3D6A5284F4A6D3FE22A5D6C2B960494C3
OK f0761e8dcd3d000176d457ed13b4c72b389dc5018e72a171dd85a5d3752274d3a019fbcaed09a425cd9b2e1c9b72eee7c9de7d52b3f3d6a5284f4a6d3fe22a5d6c2b960494c3
AEAD_DecryptWithTag returns 42 (expected >0)
P':08000F101112131415161718191A1B1C1D1E1F202122232425262728292A2B2C2D2E2F30313233340004
OK 08000F101112131415161718191A1B1C1D1E1F202122232425262728292A2B2C2D2E2F30313233340004

Example (VBA wrapper function)

Dim lpKey() As Byte
Dim lpNonce() As Byte
Dim lpAAD() As Byte
Dim lpPT() As Byte
Dim lpCT() As Byte
Dim lpDT() As Byte

' Ref: IEEE P802.1 MACsec 2.4.1 54-byte Packet Encryption Using GCM-AES-128:
' Set byte arrays from hex strings
lpKey = cnvBytesFromHexStr("071b113b 0ca743fe cccf3d05 1f737382")
lpNonce = cnvBytesFromHexStr("f0761e8d cd3d0001 76d457ed")
lpAAD = cnvBytesFromHexStr("e20106d7 cd0df076 1e8dcd3d 88e54c2a 76d457ed")
lpPT = cnvBytesFromHexStr("08000f10 11121314 15161718 191a1b1c 1d1e1f20 21222324 25262728 292a2b2c 2d2e2f30 31323334 0004")

lpCT = aeadEncryptWithTag(lpPT, lpKey, lpNonce, lpAAD, API_AEAD_AES_128_GCM Or API_IV_PREFIX)
Debug.Print "C: " & cnvHexStrFromBytes(lpCT)
Debug.Print "OK f0761e8dcd3d000176d457ed13b4c72b389dc5018e72a171dd85a5d3752274d3a019fbcaed09a425cd9b2e1c9b72eee7c9de7d52b3f3d6a5284f4a6d3fe22a5d6c2b960494c3"

lpDT = aeadDecryptWithTag(lpCT, lpKey, lpNonce, lpAAD, API_AEAD_AES_128_GCM Or API_IV_PREFIX)
Debug.Print "P: " & cnvHexStrFromBytes(lpDT)
Debug.Print "OK 08000F101112131415161718191A1B1C1D1E1F202122232425262728292A2B2C2D2E2F30313233340004"

See Also

AEAD_DecryptWithTag AEAD_Encrypt AEAD_Decrypt

[Contents] [Index]