CryptoSys API Library Manual

CIPHER_KeyWrap

Wraps a content-encryption key with a key-encryption key.

VBA/VB6 Syntax

Public Declare Function CIPHER_KeyWrap Lib "diCryptoSys.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_KeyWrap(lpOutput(0), nOutBytes, abInput(0), nDataLen, abKek(0), nKekLen, nOptions)

C/C++ Syntax

long __stdcall CIPHER_KeyWrap(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 (key material).
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:
API_BC_AES128 to use AES128-Wrap
API_BC_AES192 to use AES192-Wrap
API_BC_AES256 to use AES256-Wrap
API_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 cipherKeyWrap(lpData() As Byte, lpKek() As Byte, nOptions As Long) As Byte()

.NET Equivalent

Cipher.KeyWrap Method

Python Equivalent

static Cipher.key_wrap(data, kek, alg)

Remarks

This wraps (encrypts) 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 [WRAP-3DES]. There is no default algorithm. The algorithm must be specified in the nOptions parameter. The input data to be wrapped must be a valid length for the underlying data encapsulation mechanism; specifically, at least 16 bytes and a multiple of 8 bytes for AES, or exactly 24 bytes for Triple DES. To find the required length for the output wrapped key, pass zero as the nOutBytes parameter (Hint: an AES-wrapped key is exactly 8 bytes longer than the input; a triple-DES-wrapped key is 16 bytes longer). 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

abKeyData = cnvBytesFromHexStr("00112233 44556677 8899aabb ccddeeff")
abKek = cnvBytesFromHexStr("c17a44e8 e28d7d64 81d1ddd5 0a3b8914")
nKdLen = UBound(abKeyData) + 1
nKekLen = UBound(abKek) + 1

Debug.Print "INPUT:"
Debug.Print "KEK=" & cnvHexStrFromBytes(abKek)
Debug.Print "KD =" & cnvHexStrFromBytes(abKeyData)
Debug.Print "OUTPUT:"

nWkLen = CIPHER_KeyWrap(0, 0, abKeyData(0), nKdLen, abKek(0), nKekLen, API_BC_AES128)
If nWkLen <= 0 Then
    Debug.Print "CIPHER_KeyWrap returns " & nWkLen & ": " & apiErrorLookup(nWkLen)
    Exit Sub
End If
ReDim abWK(nWkLen - 1)
nWkLen = CIPHER_KeyWrap(abWK(0), nWkLen, abKeyData(0), nKdLen, abKek(0), nKekLen, API_BC_AES128)
Debug.Print "WK{AES-128}=" & cnvHexStrFromBytes(abWK)

abKeyData = cnvBytesFromHexStr("8cbedec4 8d063e1b a46be8e3 69a9c398 d8e30ee5 42bc347c 4f30e928 ddd7db49")
abKek = cnvBytesFromHexStr("9e84ee99 e6a84b50 c76cd414 a2d2ec05 8af41bfe 4bf3715b f894c8da 1cd445f6")
nKdLen = UBound(abKeyData) + 1
nKekLen = UBound(abKek) + 1

nWkLen = CIPHER_KeyWrap(0, 0, abKeyData(0), nKdLen, abKek(0), nKekLen, API_BC_AES256)
If nWkLen <= 0 Then
    Debug.Print "CIPHER_KeyWrap returns " & nWkLen & ": " & apiErrorLookup(nWkLen)
    Exit Sub
End If
ReDim abWK(nWkLen - 1)
nWkLen = CIPHER_KeyWrap(abWK(0), nWkLen, abKeyData(0), nKdLen, abKek(0), nKekLen, API_BC_AES256)
Debug.Print "WK{AES-256}=" & cnvHexStrFromBytes(abWK)

abKeyData = cnvBytesFromHexStr("84e7f2d8 78f89fcc cd2d5eba fc56daf7 3300f27e f771cd68")
abKek = cnvBytesFromHexStr("8ad8274e 56f46773 8edd83d4 394e5e29 af7c4089 e4f8d9f4")
nKdLen = UBound(abKeyData) + 1
nKekLen = UBound(abKek) + 1

Debug.Print "INPUT:"
Debug.Print "KEK=" & cnvHexStrFromBytes(abKek)
Debug.Print "KD =" & cnvHexStrFromBytes(abKeyData)
Debug.Print "OUTPUT:"

nWkLen = CIPHER_KeyWrap(0, 0, abKeyData(0), nKdLen, abKek(0), nKekLen, API_BC_3DES)
If nWkLen <= 0 Then
    Debug.Print "CIPHER_KeyWrap returns " & nWkLen & ": " & apiErrorLookup(nWkLen)
    Exit Sub
End If
ReDim abWK(nWkLen - 1)
nWkLen = CIPHER_KeyWrap(abWK(0), nWkLen, abKeyData(0), nKdLen, abKek(0), nKekLen, API_BC_3DES)
Debug.Print "WK(3DES}=" & cnvHexStrFromBytes(abWK)

' Now unwrap (decrypt)...
Debug.Print "Unwrap..."
Debug.Print "INPUT:"
Debug.Print "ALG=3DES"
Debug.Print "KEK=" & cnvHexStrFromBytes(abKek)
Debug.Print "WK =" & cnvHexStrFromBytes(abWK)
' In this case, we know that the Triple DES key will be exactly 24 bytes long, so
nKdLen = API_KEYSIZE_TDEA_BYTES
ReDim abKeyData(nKdLen - 1)
nKdLen = CIPHER_KeyUnwrap(abKeyData(0), nKdLen, abWK(0), nWkLen, abKek(0), nKekLen, API_BC_3DES)
If nKdLen <= 0 Then
    Debug.Print "CIPHER_KeyUnwrap returns " & nKdLen & ": " & apiErrorLookup(nKdLen)
    Exit Sub
End If
Debug.Print "OUTPUT:"
Debug.Print "KD =" & cnvHexStrFromBytes(abKeyData)
Debug.Print "OK =84E7F2D878F89FCCCD2D5EBAFC56DAF73300F27EF771CD68"

This should result in output as follows:

INPUT:
KEK=C17A44E8E28D7D6481D1DDD50A3B8914
KD =00112233445566778899AABBCCDDEEFF
OUTPUT:
WK{AES-128}=503D75C73630A7B02ECF51B9B29B907749310B77B0B2E054
WK{AES-256}=EAFB901F82B98D37F17497063DE3E5EC7246AB57200AE73EDDDDF24AA403DAFA0C5AE151D1746FA4
INPUT:
KEK=8AD8274E56F467738EDD83D4394E5E29AF7C4089E4F8D9F4
KD =84E7F2D878F89FCCCD2D5EBAFC56DAF73300F27EF771CD68
OUTPUT:
WK{3DES}=97BC2665A5E90185F8772B1EC4EDAB94879521CDFF896823E08ACBC26F620917D7071140C9D5C024
Unwrap...
INPUT:
ALG=3DES
KEK=8AD8274E56F467738EDD83D4394E5E29AF7C4089E4F8D9F4
WK =97BC2665A5E90185F8772B1EC4EDAB94879521CDFF896823E08ACBC26F620917D7071140C9D5C024
OUTPUT:
KD =84E7F2D878F89FCCCD2D5EBAFC56DAF73300F27EF771CD68
OK =84E7F2D878F89FCCCD2D5EBAFC56DAF73300F27EF771CD68

Note that the AES key wrap will always give the same result for the same input data, but the Triple DES result will be different each time.

Example (VBA wrapper function)

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

' Input for AES128-Wrap
lpKeyData = cnvBytesFromHexStr("8cbedec4 8d063e1b a46be8e3 69a9c398 d8e30ee5 42bc347c 4f30e928 ddd7db49")
lpKek = cnvBytesFromHexStr("9e84ee99 e6a84b50 c76cd414 a2d2ec05 8af41bfe 4bf3715b f894c8da 1cd445f6")
' Wrap the content encyption key
lpWK = cipherKeyWrap(lpKeyData, lpKek, API_BC_AES256)
Debug.Print "WK=" & cnvHexStrFromBytes(lpWK)
Debug.Print "OK=EAFB901F82B98D37F17497063DE3E5EC7246AB57200AE73EDDDDF24AA403DAFA0C5AE151D1746FA4"
' Unwrap
lpKD = cipherKeyUnwrap(lpWK, lpKek, API_BC_AES256)
Debug.Print "KD=" & cnvHexStrFromBytes(lpKD)
Debug.Print "OK=" & cnvHexStrFromBytes(lpKeyData)

See Also

CIPHER_KeyUnwrap

[Contents] [Index]

[PREV: CIPHER_KeyUnwrap...]   [Contents]   [Index]   
   [NEXT: CIPHER_StreamBytes...]
Copyright © 2001-24 D.I. Management Services Pty Ltd. All rights reserved. Generated 2024-01-07T07:42:00Z.