GCM_InitKey

Initializes the context with the key ready for repeated operations of GCM_NextEncrypt and GCM_NextDecrypt.

VBA/VB6 Syntax

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

C/C++ Syntax

Parameters

lpKey

[in] array containing the key.

nKeyLen

[in] equal to length of the key in bytes. Must be one of 16, 24 or 32 corresponding to the required key bytes for AES-128, AES-192 or AES-256, respectively.

nOptions

[in] for future use. Specify zero.

Returns (VBA/C)

non-zero handle of the GCM context hContext. Returns zero if an error occurs.

.NET Equivalent

Gcm.InitKey Method

Remarks

It is important to check for a zero context handle and stop if one occurs.

Example

Dim abKey() As Byte
Dim nKeyLen As Long
Dim hContext As Long
Dim nCode As Long

' Initialise with a valid key
abKey = cnvBytesFromHexStr("feffe9928665731c6d6a8f9467308308")
nKeyLen = UBound(abKey) + 1
hContext = GCM_InitKey(abKey(0), nKeyLen, 0)
Debug.Print "GCM_InitKey returns " & Hex(hContext) & " (expected non-0)"
If hContext <> 0 Then
    '... do something here...
    ' Destroy the key
    Call GCM_FinishKey(hContext)
End If

' Now try an invalid key (length must be 16,24, or 32 bytes)
abKey = cnvBytesFromHexStr("badace")
nKeyLen = UBound(abKey) + 1
hContext = GCM_InitKey(abKey(0), nKeyLen, 0)
Debug.Print "GCM_InitKey returns " & Hex(hContext)
' Use API_ErrorCode to find the error value
nCode = API_ErrorCode()
Debug.Print "API_ErrorCode returns " & nCode & ": " & apiErrorLookup(nCode)

This should result in output as follows:

GCM_InitKey returns 3C8D3BD3 (expected non-0)
GCM_InitKey returns 0
API_ErrorCode returns 33: Invalid key length (BAD_KEY_LEN_ERROR)

See Also

GCM_NextEncrypt GCM_NextDecrypt

[Contents] [Index]