CIPHER_EncryptAEAD

CryptoSys PKI Pro Manual

CIPHER_EncryptAEAD

Encrypt data using an authenticated encryption algorithm.

VBA/VB6 Syntax


Public Declare Function CIPHER_EncryptAEAD Lib "diCrPKI.dll" (ByRef lpOutput As Byte, ByVal nOutBytes As Long, ByRef lpInput As Byte, ByVal nInputLen As Long, ByRef lpKey As Byte, ByVal nKeyLen As Long, ByRef lpIV As Byte, ByVal nIvLen As Long, ByRef lpAAD As Byte, ByVal nAadLen As Long, ByVal nOptions As Long) As Long

nRet = CIPHER_EncryptAEAD(lpOutput(0), nOutBytes, lpInput(0), nInputLen, lpKey(0), nKeylen, lpIV(0), nIvLen, lpAAD(0), nAadLen, nOptions)

C/C++ Syntax


long __stdcall CIPHER_EncryptAEAD(unsigned char *lpOutput, long nOutBytes, const unsigned char *lpInput, long nInputLen, const unsigned char *lpKey, long nKeyLen, const unsigned char *lpIV, long nIvLen, const unsigned char *lpAAD, long nAadLen, long nOptions);

Parameters

lpOutput: [out] array of sufficient length to receive the output.
nOutBytes: [in] length of the output buffer in bytes.
lpInput: [in] array containing the input data.
nInputLen: [in] length of the input data in bytes.
lpKey: [in] array containing the key.
nKeyLen: [in] length of the key in bytes.
lpIV: [in] (required) initialization vector (IV), a.k.a. nonce.
nIvLen: [in] length of the IV in bytes (must be exactly 12).
lpAAD: [in] (optional) additional authenticated data (AAD)
nAadLen: [in] length of the AAD in bytes.
nOptions: [in] option flags. Must be one of:
PKI_AEAD_AES_128_GCM to use AEAD_AES_128_GCM authenticated encryption algorithm from RFC 5116
PKI_AEAD_AES_256_GCM to use AEAD_AES_256_GCM authenticated encryption algorithm from RFC 5116
PKI_AEAD_AES_192_GCM to use the AES-192-GCM authenticated encryption algorithm in the same manner
PKI_AEAD_CHACHA20_POLY1305 to use the AEAD_CHACHA20_POLY1305 authenticated encryption algorithm (RFC 8439)
and optionally add
PKI_IV_PREFIX to prepend the IV before the ciphertext in the output.

Returns (VBA/C)

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

VBA Wrapper Syntax

Public Function cipherEncryptAEAD (lpInput() As Byte, lpKey() As Byte, lpIV() As Byte, lpAAD() As Byte, nOptions As Long) As Byte()

.NET Equivalent

Cipher.EncryptAEAD Method (Byte[], Byte[], Byte[], AeadAlgorithm)
Cipher.EncryptAEAD Method (Byte[], Byte[], Byte[], Byte[], AeadAlgorithm, Cipher.Opts)

C++ (STL) Equivalent

static bvec_t dipki::Cipher::EncryptAEAD (const bvec_t &input, const bvec_t &key, const bvec_t &iv, AeadAlg aeadAlg, Opts opts=Opts::None, const bvec_t &aad=bvec_t())

Python Equivalent

static Cipher.encrypt_aead(data, key, iv, aeadalg, aad=None, opts=Opts.DEFAULT)

Remarks

This function carries out authenticated encryption using AES-GCM. In this implementation, the function must have a fixed-length nonce (IV) of exactly 12 bytes (96 bits) and only creates a fixed-length tag of exactly 16 bytes (128 bits). There is no option to use different lengths for the IV or tag. The tag is automatically appended to the output of the encryption operation. The IV may optionally be prepended to the output using the PKI_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 PKI_AEAD_AES_128_GCM, 24 for PKI_AEAD_AES_192_GCM, or 32 for PKI_AEAD_AES_256_GCM. It is an error if a PKI_AEAD_ option is not provided in the nOptions argument. The length of the IV must be 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 16 bytes longer than the length of the input, or exactly 28 bytes longer if the PKI_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)

Dim key() As Byte
Dim iv() As Byte
Dim pt() As Byte
Dim ct() As Byte
Dim strOK As String
Dim ptlen As Long
Dim ctlen As Long
Dim keylen As Long
Dim ivlen As Long

' GCM Test Case #03 (AES-128)
key = cnvBytesFromHexStr("feffe9928665731c6d6a8f9467308308")
iv = cnvBytesFromHexStr("cafebabefacedbaddecaf888")
pt = cnvBytesFromHexStr("d9313225f88406e5a55909c5aff5269a86a7a9531534f7da2e4c303d8a318a721c3c0c95956809532fcf0e2449a6b525b16aedf5aa0de657ba637b391aafd255")
strOK = "42831ec2217774244b7221b784d0d49ce3aa212f2c02a4e035c17e2329aca12e21d514b25466931c7d8f6a5aac84aa051ba30b396a0aac973d58e091473f59854d5c2af327cd64a62cf35abd2ba6fab4"
keylen = UBound(key) + 1
ivlen = UBound(iv) + 1
ptlen = UBound(pt) + 1
Debug.Print "KY=" & cnvHexStrFromBytes(key)
Debug.Print "IV=" & cnvHexStrFromBytes(iv)
Debug.Print "PT=" & cnvHexStrFromBytes(pt)
' 1. Find out how long an output buffer we need
ctlen = CIPHER_EncryptAEAD(ByVal 0&, 0, pt(0), ptlen, key(0), keylen, iv(0), ivlen, ByVal 0&, 0, PKI_AEAD_AES_128_GCM)
Debug.Print "CIPHER_EncryptAEAD returns " & ctlen
Debug.Assert ctlen > 0
' 2. Allocate the buffer
ReDim ct(ctlen - 1)
' 3. Encrypt to output buffer (NB tag is appended to the end)
ctlen = CIPHER_EncryptAEAD(ct(0), ctlen, pt(0), ptlen, key(0), keylen, iv(0), ivlen, ByVal 0&, 0, PKI_AEAD_AES_128_GCM)

Debug.Print "CT=" & cnvHexStrFromBytes(ct)
Debug.Print "OK=" & strOK
    
' Repeat but prepend IV to output
ctlen = CIPHER_EncryptAEAD(ByVal 0&, 0, pt(0), ptlen, key(0), keylen, iv(0), ivlen, ByVal 0&, 0, PKI_AEAD_AES_128_GCM Or PKI_IV_PREFIX)
Debug.Print "CIPHER_EncryptAEAD returns " & ctlen
Debug.Assert ctlen > 0
ReDim ct(ctlen - 1)
ctlen = CIPHER_EncryptAEAD(ct(0), ctlen, pt(0), ptlen, key(0), keylen, iv(0), ivlen, ByVal 0&, 0, PKI_AEAD_AES_128_GCM Or PKI_IV_PREFIX)

Debug.Print "IV|CT=" & cnvHexStrFromBytes(ct)

This should result in output as follows:

KY=FEFFE9928665731C6D6A8F9467308308
IV=CAFEBABEFACEDBADDECAF888
PT=D9313225F88406E5A55909C5AFF5269A86A7A9531534F7DA2E4C303D8A318A721C3C0C95956809532FCF0E2449A6B525B16AEDF5AA0DE657BA637B391AAFD255
CIPHER_EncryptAEAD returns 80
CT=42831EC2217774244B7221B784D0D49CE3AA212F2C02A4E035C17E2329ACA12E21D514B25466931C7D8F6A5AAC84AA051BA30B396A0AAC973D58E091473F59854D5C2AF327CD64A62CF35ABD2BA6FAB4
OK=42831ec2217774244b7221b784d0d49ce3aa212f2c02a4e035c17e2329aca12e21d514b25466931c7d8f6a5aac84aa051ba30b396a0aac973d58e091473f59854d5c2af327cd64a62cf35abd2ba6fab4
CIPHER_EncryptAEAD returns 92
IV|CT=CAFEBABEFACEDBADDECAF88842831EC2217774244B7221B784D0D49CE3AA212F2C02A4E035C17E2329ACA12E21D514B25466931C7D8F6A5AAC84AA051BA30B396A0AAC973D58E091473F59854D5C2AF327CD64A62CF35ABD2BA6FAB4

Example (VBA wrapper function)

Dim key() As Byte
Dim iv() As Byte
Dim pt() As Byte
Dim ct() As Byte
Dim lpDummy() As Byte
' GCM Test Case #03 (AES-128)
key = cnvBytesFromHexStr("feffe9928665731c6d6a8f9467308308")
iv = cnvBytesFromHexStr("cafebabefacedbaddecaf888")
pt = cnvBytesFromHexStr("d9313225f88406e5a55909c5aff5269a86a7a9531534f7da2e4c303d8a318a721c3c0c95956809532fcf0e2449a6b525b16aedf5aa0de657ba637b391aafd255")
ct = cipherEncryptAEAD(pt, key, iv, lpDummy, PKI_AEAD_AES_128_GCM Or PKI_IV_PREFIX)
Debug.Print "IV|CT=" & cnvHexStrFromBytes(ct)
Debug.Print "OK=   " & _
    "CAFEBABEFACEDBADDECAF888" & _
"42831EC2217774244B7221B784D0D49CE3AA212F2C02A4E035C17E2329ACA12E21D514B25466931C7D8F6A5AAC84AA051BA30B396A0AAC973D58E091473F59854D5C2AF327CD64A62CF35ABD2BA6FAB4"