CIPHER_KeyUnwrap

CryptoSys PKI Toolkit Manual

CIPHER_KeyUnwrap

CIPHER_KeyUnwrap unwraps (decrypts) a content-encryption key with a key-encryption key.

VB6/VBA Syntax


Public Declare Function CIPHER_KeyUnwrap Lib "diCrPKI.dll" 
(ByRef abOutput As Byte, ByVal nOutBytes As Long, 
ByRef abData As Byte, ByVal nDataLen As Long, 
ByRef abKek As Byte, ByVal nKekLen As Long, ByVal nOptions As Long) As Long

nRet = CIPHER_KeyUnwrap(abOutput(0), nOutBytes, abInput(0), nDataLen, abKek(0), nKekLen, nOptions)

Parameters

abOutput: [out] Byte array of sufficient length to receive the output.
nOutBytes: [in] Long specifying the maximum length of the output array.
abData: [in] Byte array containing the input data (wrapped key).
nDataLen: [in] Long specifying the length of the input data in bytes.
abKek: [in] Byte array containing the key encryption key.
nKekLen: [in] Long specifying the length of the key encryption key.
nOptions: [in] Long option flags:
Select the key wrap algorithm from one of the following:
PKI_BC_AES128 to use AES128-Wrap
PKI_BC_AES192 to use AES128-Wrap
PKI_BC_AES256 to use AES128-Wrap
PKI_BC_3DES to use cms3DESWrap

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);

Returns (VB6/C)

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

.NET Equivalent

Cipher.KeyUnwrap Method

Remarks

This unwraps (decrypts) key material using a key encryption key (KEK) and uses either the AES Key Wrap Algorithm from RFC 3394 [AES-WRAP] or the Triple-DES Key Wrap algorithm from RFC 3217 [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

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