AEAD_Decrypt

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 specified separately.

VBA/VB6 Syntax

nRet = AEAD_Decrypt(lpOutput(0), nOutLen, abData(0), nDataLen, abKey(0), nKeyLen, abNonce(0), nNonceLen, abAAD(0), nAadLen, abTag(0), nTagLen, nOptions)

C/C++ Syntax

Parameters

lpOutput

[out] byte array of sufficient length to receive the plaintext output (at least as long as the input).

nOutLen

[in] length in bytes of the output array.

lpData

[in] byte array containing the input data.

nDataLen

[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] containing the nonce 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.

lpTag

[in] byte array containing the tag.

nTagLen

[in] length of the tag 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 zero; otherwise it returns a nonnegative error code.

.NET Equivalent

Aead.Decrypt Method

Remarks

This is a one-off, stateless function. The output plaintext is always exactly the same length as the input ciphertext (excluding any IV or tags in the input). If the inputs are not authentic, the function returns the non-zero error code AUTH_FAILED_ERROR and the decrypted output should be rejected. Note that the term "IV" is used here to mean exactly the same as "nonce". For more details of AEAD see Authenticated Encryption with Additional Data (AEAD).

Example

This is from Appendix A.5 of [RFC7539].

' Ref: RFC 7539 Appendix A.5
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 strPTOK As String

Debug.Print "RFC7739 ChaCha20_Poly1305 Appendix A.5:"
' Set byte arrays from hex strings
abKey = cnvBytesFromHexStr("1c9240a5eb55d38af333888604f6b5f0473917c1402b80099dca5cbc207075c0")
abNonce = cnvBytesFromHexStr("000000000102030405060708")
abAAD = cnvBytesFromHexStr("f33388860000000000004e91")
abCT = cnvBytesFromHexStr("64a0861575861af460f062c79be643bd5e805cfd345cf389f108670ac76c8cb24c6cfc18755d43eea09ee94e382d26b0bdb7b73c321b0100d4f03b7f355894cf332f830e710b97ce98c8a84abd0b948114ad176e008d33bd60f982b1ff37c8559797a06ef4f0ef61c186324e2b3506383606907b6a7c02b0f9f6157b53c867e4b9166c767b804d46a59b5216cde7a4e99040c5a40433225ee282a1b0a06c523eaf4534d7f83fa1155b0047718cbc546a0d072b04b3564eea1b422273f548271a0bb2316053fa76991955ebd63159434ecebb4e466dae5a1073a6727627097a1049e617d91d361094fa68f0ff77987130305beaba2eda04df997b714d6c6f2c29a6ad5cb4022b02709b")
abTag = cnvBytesFromHexStr("eead9d67890cbb22392336fea1851f38")

strPTOK = "496e7465726e65742d4472616674732061726520647261667420646f63756d656e74732076616c696420666f722061206d6178696d756d206f6620736978206d6f6e74687320616e64206d617920626520757064617465642c207265706c616365642c206f72206f62736f6c65746564206279206f7468657220646f63756d656e747320617420616e792074696d652e20497420697320696e617070726f70726961746520746f2075736520496e7465726e65742d447261667473206173207265666572656e6365206d6174657269616c206f7220746f2063697465207468656d206f74686572207468616e206173202fe2809c776f726b20696e2070726f67726573732e2fe2809d"

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

' Dimension arrays for output (we are decrypting CT->PT)
ReDim abPT(nDataLen - 1)

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

' Do authenticated decryption using AEAD_CHACHA20_POLY1305
nRet = AEAD_Decrypt(abPT(0), nDataLen, abCT(0), nDataLen, _
    abKey(0), nKeyLen, abNonce(0), nNonceLen, abAAD(0), nAadLen, abTag(0), nTagLen, API_AEAD_CHACHA20_POLY1305)
Debug.Print "AEAD_Decrypt returns " & nRet & " (expected 0)"
Debug.Print "P: " & cnvHexStrFromBytes(abPT)
Debug.Print "OK " & strPTOK
' Show plaintext as string (note the UTF-8 double quotation marks do not decode in VB6)
Debug.Print "   " & StrConv(abPT, vbUnicode)

This should result in output as follows - note the VB6 display of the UTF-8-encoded double quotation marks characters (U+201C and U+201D):

RFC7739 ChaCha20_Poly1305 Appendix A.5:
K: 1C9240A5EB55D38AF333888604F6B5F0473917C1402B80099DCA5CBC207075C0
N: 000000000102030405060708
A: F33388860000000000004E91
C: 64A0861575861AF460F062C79BE643BD5E805CFD345CF389F108670AC76C8CB24C6CFC18755D43EEA09EE94E382D26B0BDB7B73C321B0100D4F03B7F355894CF332F830E710B97CE98C8A84ABD0B948114AD176E008D33BD60F982B1FF37C8559797A06EF4F0EF61C186324E2B3506383606907B6A7C02B0F9F6157B53C867E4B9166C767B804D46A59B5216CDE7A4E99040C5A40433225EE282A1B0A06C523EAF4534D7F83FA1155B0047718CBC546A0D072B04B3564EEA1B422273F548271A0BB2316053FA76991955EBD63159434ECEBB4E466DAE5A1073A6727627097A1049E617D91D361094FA68F0FF77987130305BEABA2EDA04DF997B714D6C6F2C29A6AD5CB4022B02709B
T: EEAD9D67890CBB22392336FEA1851F38
AEAD_Decrypt returns 0 (expected 0)
P: 496E7465726E65742D4472616674732061726520647261667420646F63756D656E74732076616C696420666F722061206D6178696D756D206F6620736978206D6F6E74687320616E64206D617920626520757064617465642C207265706C616365642C206F72206F62736F6C65746564206279206F7468657220646F63756D656E747320617420616E792074696D652E20497420697320696E617070726F70726961746520746F2075736520496E7465726E65742D447261667473206173207265666572656E6365206D6174657269616C206F7220746F2063697465207468656D206F74686572207468616E206173202FE2809C776F726B20696E2070726F67726573732E2FE2809D
OK 496e7465726e65742d4472616674732061726520647261667420646f63756d656e74732076616c696420666f722061206d6178696d756d206f6620736978206d6f6e74687320616e64206d617920626520757064617465642c207265706c616365642c206f72206f62736f6c65746564206279206f7468657220646f63756d656e747320617420616e792074696d652e20497420697320696e617070726f70726961746520746f2075736520496e7465726e65742d447261667473206173207265666572656e6365206d6174657269616c206f7220746f2063697465207468656d206f74686572207468616e206173202fe2809c776f726b20696e2070726f67726573732e2fe2809d
   Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as /“work in progress./�

See Also

AEAD_DecryptWithTag AEAD_Encrypt AEAD_EncryptWithTag

[Contents] [Index]