AEAD_InitKey

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

VBA/VB6 Syntax

nRet = AEAD_InitKey(abKey(0), nKeyLen, nOptions)

C/C++ Syntax

Parameters

lpKey

[in] byte array containing the key of exact length for given algorithm (currently either 16 or 32 bytes).

nKeyLen

[in] equal to length of the key 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)

Returns (VBA/C)

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

.NET Equivalent

Aead.InitKey Method

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.

Example

This is a test case of ChaCha20-Poly1305 from RFC 7739. It encrypts the data in incremental mode (simulating adding chunks) and then decrypts in incremental mode using the same key.

' RFC7739 ChaCha20_Poly1305 Sunscreen test - INCREMENTAL MODE:
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
Dim hContext As Long
Dim nOffset As Long
Dim nLen As Long
Dim nLeft As Long

Debug.Print "RFC7739 ChaCha20_Poly1305 Sunscreen test:"
' Set byte arrays from hex strings
abKey = cnvBytesFromHexStr("808182838485868788898A8B8C8D8E8F909192939495969798999A9B9C9D9E9F")
abNonce = cnvBytesFromHexStr("070000004041424344454647")
abAAD = cnvBytesFromHexStr("50515253C0C1C2C3C4C5C6C7")
abPT = cnvBytesFromHexStr("4C616469657320616E642047656E746C656D656E206F662074686520636C617373206F66202739393A204966204920636F756C64206F6666657220796F75206F6E6C79206F6E652074697020666F7220746865206675747572652C2073756E73637265656E20776F756C642062652069742E")

strCTOK = "d31a8d34648e60db7b86afbc53ef7ec2a4aded51296e08fea9e2b5a736ee62d63dbea45e8ca9671282fafb69da92728b1a71de0a9e060b2905d6a5b67ecd3b3692ddbd7f2d778b8c9803aee328091b58fab324e4fad675945585808b4831d7bc3ff4def08e4b7a9de576d26586cec64b6116"
strTagOK = "1ae10b594f09e26a7e902ecbd0600691"

' 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_CHACHA20_POLY1305
' 1.1 Initialize with the key and AEAD algorithm
hContext = AEAD_InitKey(abKey(0), nKeyLen, API_AEAD_CHACHA20_POLY1305)
Debug.Print "AEAD_InitKey returns 0x" & Hex(hContext) & " (expecting non-zero)"

' 1.2 Set the nonce
nRet = AEAD_SetNonce(hContext, abNonce(0), nNonceLen)

' 1.3 Add the AAD (simulate adding in two parts)
nLen = nAadLen / 2
nOffset = 0
nRet = AEAD_AddAAD(hContext, abAAD(nOffset), nLen)
nOffset = nLen
nLen = nAadLen - nLen
nRet = AEAD_AddAAD(hContext, abAAD(nOffset), nLen)

' 1.4 Start Encrypting
nRet = AEAD_StartEncrypt(hContext)

' 1.5 Update plaintext -> ciphertext (simulate adding in chunks)
Debug.Print "Adding plaintext in chunks"
nLen = 17
nLeft = nDataLen
nOffset = 0
While nLeft > 0
    If nLeft < nLen Then
        nLen = nLeft
    End If
    ' Update another chunk of plaintext
    Debug.Print "P: " & cnvHexFromBytesMid(abPT, nOffset, nLen)
    nRet = AEAD_Update(hContext, abCT(nOffset), nLen, abPT(nOffset), nLen)
    Debug.Print "C: " & cnvHexFromBytesMid(abCT, nOffset, nLen)
    nOffset = nOffset + nLen
    nLeft = nLeft - nLen
Wend

' 1.6 Finish encrypting and output Tag
nRet = AEAD_FinishEncrypt(hContext, abTag(0), nTagLen)

Debug.Print "C: " & cnvHexStrFromBytes(abCT)
Debug.Print "OK " & strCTOK
Debug.Print "T: " & cnvHexStrFromBytes(abTag)
Debug.Print "OK " & strTagOK

' DECRYPTING...
Debug.Print "DECRYPTING..."
' 2.1 Use key we initialized with in step 1.1
' 2.2 Set Nonce
nRet = AEAD_SetNonce(hContext, abNonce(0), nNonceLen)
' 2.3 Add AAD (this time in one go)
nRet = AEAD_AddAAD(hContext, abAAD(0), nAadLen)
' 2.4 Start decrypting using Tag we just made
nRet = AEAD_StartDecrypt(hContext, abTag(0), nTagLen)

' 2.5. Update with ciphertext -> plaintext (simulate adding in chunks)
Debug.Print "Adding ciphertext in chunks"
nLen = 13
nLeft = nDataLen
nOffset = 0
While nLeft > 0
    If nLeft < nLen Then
        nLen = nLeft
    End If
    ' Update chunk of ciphertext in situ
    Debug.Print "C: " & cnvHexFromBytesMid(abCT, nOffset, nLen)
    nRet = AEAD_Update(hContext, abCT(nOffset), nLen, abCT(nOffset), nLen)
    Debug.Print "P: " & cnvHexFromBytesMid(abCT, nOffset, nLen)
    nOffset = nOffset + nLen
    nLeft = nLeft - nLen
Wend
' Note: treat plaintext output as suspect until authenticated by FinishDecrypt
Debug.Print "P':" & cnvHexStrFromBytes(abCT)

' 2.6 Finish decrypting and check OK|FAIL
nRet = AEAD_FinishDecrypt(hContext)
Debug.Print "AEAD_FinishDecrypt returns " & nRet & " (0 => OK)"


' 3. We are done with the key so destroy it
nRet = AEAD_Destroy(hContext)
Debug.Print "AEAD_Destroy returns " & nRet & " (expecting 0)"

This should result in output as follows:

RFC7739 ChaCha20_Poly1305 Sunscreen test:
K: 808182838485868788898A8B8C8D8E8F909192939495969798999A9B9C9D9E9F
N: 070000004041424344454647
A: 50515253C0C1C2C3C4C5C6C7
P: 4C616469657320616E642047656E746C656D656E206F662074686520636C617373206F66202739393A204966204920636F756C64206F6666657220796F75206F6E6C79206F6E652074697020666F7220746865206675747572652C2073756E73637265656E20776F756C642062652069742E
AEAD_InitKey returns 0x1BE3AC35 (expecting non-zero)
Adding plaintext in chunks
P: 4C616469657320616E642047656E746C65
C: D31A8D34648E60DB7B86AFBC53EF7EC2A4
P: 6D656E206F662074686520636C61737320
C: ADED51296E08FEA9E2B5A736EE62D63DBE
P: 6F66202739393A204966204920636F756C
C: A45E8CA9671282FAFB69DA92728B1A71DE
P: 64206F6666657220796F75206F6E6C7920
C: 0A9E060B2905D6A5B67ECD3B3692DDBD7F
P: 6F6E652074697020666F72207468652066
C: 2D778B8C9803AEE328091B58FAB324E4FA
P: 75747572652C2073756E73637265656E20
C: D675945585808B4831D7BC3FF4DEF08E4B
P: 776F756C642062652069742E
C: 7A9DE576D26586CEC64B6116
C: D31A8D34648E60DB7B86AFBC53EF7EC2A4ADED51296E08FEA9E2B5A736EE62D63DBEA45E8CA9671282FAFB69DA92728B1A71DE0A9E060B2905D6A5B67ECD3B3692DDBD7F2D778B8C9803AEE328091B58FAB324E4FAD675945585808B4831D7BC3FF4DEF08E4B7A9DE576D26586CEC64B6116
OK d31a8d34648e60db7b86afbc53ef7ec2a4aded51296e08fea9e2b5a736ee62d63dbea45e8ca9671282fafb69da92728b1a71de0a9e060b2905d6a5b67ecd3b3692ddbd7f2d778b8c9803aee328091b58fab324e4fad675945585808b4831d7bc3ff4def08e4b7a9de576d26586cec64b6116
T: 1AE10B594F09E26A7E902ECBD0600691
OK 1ae10b594f09e26a7e902ecbd0600691
DECRYPTING...
Adding ciphertext in chunks
C: D31A8D34648E60DB7B86AFBC53
P: 4C616469657320616E64204765
C: EF7EC2A4ADED51296E08FEA9E2
P: 6E746C656D656E206F66207468
C: B5A736EE62D63DBEA45E8CA967
P: 6520636C617373206F66202739
C: 1282FAFB69DA92728B1A71DE0A
P: 393A204966204920636F756C64
C: 9E060B2905D6A5B67ECD3B3692
P: 206F6666657220796F75206F6E
C: DDBD7F2D778B8C9803AEE32809
P: 6C79206F6E652074697020666F
C: 1B58FAB324E4FAD67594558580
P: 7220746865206675747572652C
C: 8B4831D7BC3FF4DEF08E4B7A9D
P: 2073756E73637265656E20776F
C: E576D26586CEC64B6116
P: 756C642062652069742E
P':4C616469657320616E642047656E746C656D656E206F662074686520636C617373206F66202739393A204966204920636F756C64206F6666657220796F75206F6E6C79206F6E652074697020666F7220746865206675747572652C2073756E73637265656E20776F756C642062652069742E
AEAD_FinishDecrypt returns 0 (0 => OK)
AEAD_Destroy returns 0 (expecting 0)

[Contents] [Index]