CIPHER_KeyUnwrap

CryptoSys PKI Pro Manual

CIPHER_KeyUnwrap

Unwrap (decrypt) a content-encryption key with a key-encryption key.

VBA/VB6 Syntax


Public Declare Function CIPHER_KeyUnwrap Lib "diCrPKI.dll" 
(ByRef lpOutput As Byte, ByVal nOutBytes As Long, 
ByRef lpData As Byte, ByVal nDataLen As Long, 
ByRef lpKek As Byte, ByVal nKekLen As Long, ByVal nOptions As Long) As Long

nRet = CIPHER_KeyUnwrap(lpOutput(0), nOutBytes, lpData(0), nDataLen, lpKek(0), nKekLen, nOptions)

C/C++ Syntax


long __stdcall CIPHER_KeyUnwrap(unsigned char *lpOutput, long nOutBytes, const unsigned char *lpData, long nDataLen, const unsigned char *lpKek, long nKekLen, long nOptions);

Parameters

lpOutput: [out] array of sufficient length to receive the output.
nOutBytes: [in] specifying the maximum length of the output array.
lpData: [in] array containing the input data (wrapped key).
nDataLen: [in] specifying the length of the input data in bytes.
lpKek: [in] array containing the key encryption key.
nKekLen: [in] specifying the length of the key encryption key.
nOptions: [in] option flags:
Select the key wrap algorithm from one of the following:
PKI_KWRAP_AES128 (or PKI_BC_AES128) to use AES128-Wrap
PKI_KWRAP_AES192 (or PKI_BC_AES192) to use AES128-Wrap
PKI_KWRAP_AES256 (or PKI_BC_AES256) to use AES128-Wrap
PKI_KWRAP_3DES (or PKI_BC_3DES) to use cms3DESWrap

Returns (VBA/C)

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

VBA Wrapper Syntax

Public Function cipherKeyUnwrap (lpData() As Byte, lpKEK() As Byte, nOptions As Long) As Byte()

.NET Equivalent

Cipher.KeyUnwrap Method

C++ (STL) Equivalent

static bvec_t dipki::Cipher::KeyUnwrap (const bvec_t &data, const bvec_t &kek, Alg alg)

Python Equivalent

static Cipher.key_unwrap(data, kek, alg)

Remarks

This unwraps (decrypts) key material using a key encryption key (KEK) and uses either the AES Key Wrap Algorithm from [RFC3394] or the Triple-DES Key Wrap algorithm from [RFC3217]. There is no default algorithm. The algorithm must be specified in the nOptions parameter. To find the required length for the output key material, pass zero as the nOutBytes parameter. This will be 8 bytes less than the input length for AES and 16 bytes less for triple DES. No parity bit checks or changes are made for a Triple-DES key.

Example (VBA core function)

Dim abWK() As Byte
Dim abKeyData() As Byte
Dim abKek() As Byte
Dim nWkLen As Long
Dim nKdLen As Long
Dim nKekLen As Long

abWK = cnvBytesFromHexStr("503D75C73630A7B02ECF51B9B29B907749310B77B0B2E054")
abKek = cnvBytesFromHexStr("c17a44e8 e28d7d64 81d1ddd5 0a3b8914")
nWkLen = UBound(abWK) + 1
nKekLen = UBound(abKek) + 1

nKdLen = CIPHER_KeyUnwrap(0, 0, abWK(0), nWkLen, abKek(0), nKekLen, PKI_BC_AES128)
If nKdLen <= 0 Then
    Debug.Print " returns " & nKdLen & ": " & pkiErrorLookup(nKdLen)
    Exit Sub
End If
ReDim abKeyData(nKdLen - 1)
nWkLen = CIPHER_KeyUnwrap(abKeyData(0), nKdLen, abWK(0), nWkLen, abKek(0), nKekLen, PKI_BC_AES128)
Debug.Print "K=" & cnvHexStrFromBytes(abKeyData)

This should result in output as follows:

K=00112233445566778899AABBCCDDEEFF

Example (VBA wrapper function)

Dim lpWK() As Byte
Dim lpKeyData() As Byte
Dim lpKek() As Byte

lpKeyData = cnvBytesFromHexStr("00112233 44556677 8899aabb ccddeeff")
lpKek = cnvBytesFromHexStr("c17a44e8 e28d7d64 81d1ddd5 0a3b8914")
' NB Specific nonzero option required in nOptions
lpWK = cipherKeyWrap(lpKeyData, lpKek, PKI_BC_AES128)
Debug.Print "WK=" & cnvHexStrFromBytes(lpWK)
Debug.Print "OK=503D75C73630A7B02ECF51B9B29B907749310B77B0B2E054"

' Now unwrap the KEK
Dim lpKeyUnwrapped() As Byte
lpKeyUnwrapped = cipherKeyUnwrap(lpWK, lpKek, PKI_BC_AES128)
Debug.Print "KY=" & cnvHexStrFromBytes(lpKeyUnwrapped)
Debug.Print "OK=00112233445566778899AABBCCDDEEFF"