CryptoSys API Library Manual

AEAD_Encrypt

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.

VBA/VB6 Syntax

Public Declare Function AEAD_Encrypt Lib "diCryptoSys.dll" (ByRef lpOutput As Byte, ByVal nOutLen As Long, ByRef lpTagOut As Byte, ByVal nTagLen As Long, ByRef lpData As Byte, ByVal nDataLen 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_Encrypt(lpOutput(0), nOutLen, abTagOut(0), nTagLen, abData(0), nDataLen, abKey(0), nKeyLen, abNonce(0), nNonceLen, abAAD(0), nAadLen, nOptions)

C/C++ Syntax

long __stdcall AEAD_Encrypt(unsigned char *lpOutput, long nOutLen, unsigned char *lpTagOut, long nTagLen, const unsigned char *lpData, long nDataLen, const unsigned char *lpKey, long nKeyLen,const unsigned char *lpNonce, long nNonceLen, const unsigned char *lpAAD, long nAadLen, long nOptions);

Parameters

lpOutput
[out] byte array of sufficient length to receive the output.
nOutLen
[in] length in bytes of the output buffer.
lpTagOut
[out] byte array of sufficient length to receive the tag (currently 16 bytes for all supported algorithms).
nTagLen
[in] length in bytes of the tag array.
lpData
[in] byte array containing the input data.
nDataLen
[in] length in bytes of the input data.
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] containing the nonce (IV) of exact length for the given algorithm (currently always 12 bytes).
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. 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 (VBA/C)

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

.NET Equivalent

Aead.Encrypt Method

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.

Example

' 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 abTag() As Byte

Dim nRet As Long
Dim nKeyLen As Long
Dim nNonceLen As Long
Dim nAadLen As Long
Dim nDataLen As Long
Dim nTagLen As Long
Dim strCTOK As String
Dim strTagOK As String

Debug.Print "IEEE P802.1 MACsec 2.4.1 54-byte Packet Encryption Using GCM-AES-128:"
' 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")

strCTOK = "13b4c72b389dc5018e72a171dd85a5d3752274d3a019fbcaed09a425cd9b2e1c9b72eee7c9de7d52b3f3"
strTagOK = "d6a5284f4a6d3fe22a5d6c2b960494c3"

' Set lengths of byte arrays
nKeyLen = UBound(abKey) + 1
nNonceLen = UBound(abNonce) + 1
nAadLen = UBound(abAAD) + 1
nDataLen = UBound(abPT) + 1
nTagLen = API_AEAD_TAG_MAX_BYTES

' Dimension arrays for output
ReDim abCT(nDataLen - 1)
ReDim abTag(nTagLen - 1)

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

' Do authenticated encryption using AEAD_AES_128_GCM
nRet = AEAD_Encrypt(abCT(0), nDataLen, abTag(0), nTagLen, abPT(0), nDataLen, _
    abKey(0), nKeyLen, abNonce(0), nNonceLen, abAAD(0), nAadLen, API_AEAD_AES_128_GCM)
Debug.Print "AEAD_Encrypt returns " & nRet & " (expected 0)"
Debug.Print "C: " & cnvHexStrFromBytes(abCT)
Debug.Print "OK " & strCTOK
Debug.Print "T: " & cnvHexStrFromBytes(abTag)
Debug.Print "OK " & strTagOK

' Do authenticated decryption overwriting input CT buffer
nRet = AEAD_Decrypt(abCT(0), nDataLen, abCT(0), nDataLen, abKey(0), nKeyLen, _
    abNonce(0), nNonceLen, abAAD(0), nAadLen, abTag(0), nTagLen, API_AEAD_AES_128_GCM)
Debug.Print "AEAD_Decrypt returns " & nRet & " (0 => OK)"
Debug.Print "P':" & cnvHexStrFromBytes(abCT)

' Do authenticated encryption using AEAD_AES_128_GCM, overwriting input with output
nRet = AEAD_Encrypt(abCT(0), nDataLen, abTag(0), nTagLen, abCT(0), nDataLen, _
    abKey(0), nKeyLen, abNonce(0), nNonceLen, abAAD(0), nAadLen, API_AEAD_AES_128_GCM)
Debug.Print "AEAD_Encrypt returns " & nRet & " (expected 0)"
Debug.Print "C: " & cnvHexStrFromBytes(abCT)
Debug.Print "OK " & strCTOK
Debug.Print "T: " & cnvHexStrFromBytes(abTag)
Debug.Print "OK " & strTagOK

This should result in output as follows:

IEEE P802.1 MACsec 2.4.1 54-byte Packet Encryption Using GCM-AES-128:
K: 071B113B0CA743FECCCF3D051F737382
N: F0761E8DCD3D000176D457ED
A: E20106D7CD0DF0761E8DCD3D88E54C2A76D457ED
P: 08000F101112131415161718191A1B1C1D1E1F202122232425262728292A2B2C2D2E2F30313233340004
AEAD_Encrypt returns 0 (expected 0)
C: 13B4C72B389DC5018E72A171DD85A5D3752274D3A019FBCAED09A425CD9B2E1C9B72EEE7C9DE7D52B3F3
OK 13b4c72b389dc5018e72a171dd85a5d3752274d3a019fbcaed09a425cd9b2e1c9b72eee7c9de7d52b3f3
T: D6A5284F4A6D3FE22A5D6C2B960494C3
OK d6a5284f4a6d3fe22a5d6c2b960494c3
AEAD_Decrypt returns 0 (0 => OK)
P':08000F101112131415161718191A1B1C1D1E1F202122232425262728292A2B2C2D2E2F30313233340004
AEAD_Encrypt returns 0 (expected 0)
C: 13B4C72B389DC5018E72A171DD85A5D3752274D3A019FBCAED09A425CD9B2E1C9B72EEE7C9DE7D52B3F3
OK 13b4c72b389dc5018e72a171dd85a5d3752274d3a019fbcaed09a425cd9b2e1c9b72eee7c9de7d52b3f3
T: D6A5284F4A6D3FE22A5D6C2B960494C3
OK d6a5284f4a6d3fe22a5d6c2b960494c3

This example carries out packet authentication

' IEEE P802.1 MACsec 2.5.2 65-byte Packet Authentication Using GCM-AES-256:
Dim abKey() As Byte
Dim abNonce() As Byte
Dim abAAD() As Byte
Dim abTag() As Byte

Dim nRet As Long
Dim nKeyLen As Long
Dim nNonceLen As Long
Dim nAadLen As Long
Dim nTagLen As Long
Dim strTagOK As String

Debug.Print "IEEE P802.1 MACsec 2.5.2 65-byte Packet Authentication Using GCM-AES-256:"
' Set byte arrays from hex strings
abKey = cnvBytesFromHexStr("83C093B58DE7FFE1C0DA926AC43FB3609AC1C80FEE1B624497EF942E2F79A823")
abNonce = cnvBytesFromHexStr("7CFDE9F9E33724C68932D612")
abAAD = cnvBytesFromHexStr("84C5D513D2AAF6E5BBD2727788E523008932D6127CFDE9F9E33724C608000F101112131415161718191A1B1C1D1E1F202122232425262728292A2B2C2D2E2F303132333435363738393A3B3C3D3E3F0005")

strTagOK = "6ee160e8faeca4b36c86b234920ca975"

' Set lengths of byte arrays
nKeyLen = UBound(abKey) + 1
nNonceLen = UBound(abNonce) + 1
nAadLen = UBound(abAAD) + 1
nTagLen = API_AEAD_TAG_MAX_BYTES

' Dimension arrays for output
ReDim abTag(nTagLen - 1)

' Display input
Debug.Print "K: " & cnvHexStrFromBytes(abKey)
Debug.Print "N: " & cnvHexStrFromBytes(abNonce)
Debug.Print "A: " & cnvHexStrFromBytes(abAAD)

' Do authenticated encryption using AEAD_AES_256_GCM
' Note that CT and PT are empty => just computing a MAC over the AAD
nRet = AEAD_Encrypt(0, 0, abTag(0), nTagLen, 0, 0, _
    abKey(0), nKeyLen, abNonce(0), nNonceLen, abAAD(0), nAadLen, API_AEAD_AES_256_GCM)
Debug.Print "AEAD_Encrypt returns " & nRet & " (expected 0)"
Debug.Print "T: " & cnvHexStrFromBytes(abTag)
Debug.Print "OK " & strTagOK

' Do authenticated decryption
' Note that CT and PT are empty => just authenticating the tag over the AAD
nRet = AEAD_Decrypt(0, 0, 0, 0, abKey(0), nKeyLen, _
    abNonce(0), nNonceLen, abAAD(0), nAadLen, abTag(0), nTagLen, API_AEAD_AES_256_GCM)
Debug.Print "AEAD_Decrypt returns " & nRet & " (0 => OK)"

IEEE P802.1 MACsec 2.5.2 65-byte Packet Authentication Using GCM-AES-256:
K: 83C093B58DE7FFE1C0DA926AC43FB3609AC1C80FEE1B624497EF942E2F79A823
N: 7CFDE9F9E33724C68932D612
A: 84C5D513D2AAF6E5BBD2727788E523008932D6127CFDE9F9E33724C608000F101112131415161718191A1B1C1D1E1F202122232425262728292A2B2C2D2E2F303132333435363738393A3B3C3D3E3F0005
AEAD_Encrypt returns 0 (expected 0)
T: 6EE160E8FAECA4B36C86B234920CA975
OK 6ee160e8faeca4b36c86b234920ca975
AEAD_Decrypt returns 0 (0 => OK)

See Also

AEAD_EncryptWithTag AEAD_Decrypt AEAD_DecryptWithTag

[Contents] [Index]

[PREV: AEAD_Destroy...]   [Contents]   [Index]   
   [NEXT: AEAD_EncryptWithTag...]
Copyright © 2001-24 D.I. Management Services Pty Ltd. All rights reserved. Generated 2024-01-07T07:42:00Z.