KDF_ForCms

Generate a key-encryption key (KEK) for ECDH key exchange in a CMS EnvelopedData object.

VBA/VB6 Syntax

nRet = KDF_ForCms(lpOutput(0), nOutBytes, lpZZ(0), nZzLen, lpUkm(0), nUkmLen, szParams, nOptions) ' Note the "(0)" after the byte array parameters

C/C++ Syntax

Parameters

lpOutput

[out] byte array to be filled with output key material (OKM/KEK).

nOutputLen

[in] required size of the output key in bytes.

lpZZ

[in] byte array containing the input key material/shared secret value (denoted variously as ZZ/Z/K/IKM).

nZzLen

[in] length of the shared secret material in bytes.

lpUkm

[in] (optional) byte array containing user key material (ukm)

nUkmLen

[in] length of user key material (ukm) in bytes.

szParams

[in] (optional) parameters. Not used in this version. Set as the empty string "".

nOptions

[in] Option flags. Select one of:
PKI_KDF_X963 to use the the ANSI-X9.63-KDF key derivation function (default) or
PKI_KDF_HKDF to use the HMAC-based Key Derivation Function (HKDF) from RFC 5869;
and select one hash algorithm to use with the key derivation function:
PKI_HASH_SHA1 (0) to use the SHA-1 hash algorithm (default)
PKI_HASH_SHA224 to use the SHA-224 algorithm
PKI_HASH_SHA256 to use the SHA-256 algorithm [minimum recommended]
PKI_HASH_SHA384 to use the SHA-384 algorithm
PKI_HASH_SHA512 to use the SHA-512 algorithm
and select one option to specify the key wrap algorithm (no default):
PKI_KWRAP_3DES to use cms3DESwrap
PKI_KWRAP_AES128 to use aes128-wrap
PKI_KWRAP_AES192 to use aes192-wrap
PKI_KWRAP_AES256 to use aes256-wrap

Returns (VBA/C)

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

VBA Wrapper Syntax

.NET Equivalent

Kdf.ForCms Method

C++ (STL) Equivalent

Python Equivalent

Remarks

This is a specialist function using the key definition algorithms described in [RFC5753] and [RFC8418] when used for key agreement with ECDH in a CMS EnvelopedData object using the ECC-CMS-SharedInfo structure.

Note the behaviour of this function is different from KDF_KeyBytes as the length of the output is fixed by the key wrap algorithm and is not an arbitrary number. The function returns the number of bytes in the output key material, not zero on success. Specify a zero nOutChars or NULL for szOutput to find the required number of bytes for the given key wrap algorithm. The output buffer for the output key material lpOutput must have been dimensioned to at least the required length in nOutBytes.

When using ECDH with EnvelopedData, the key-encryption keys are derived using the ECC-CMS-SharedInfo type, described in section 7.2 of [RFC5753] (the SharedInfo input to the KDF is the DER-encoded ECC-CMS-SharedInfo structure). The processing of the ukm with the HKDF key derivation function is described in section 2.2 of [RFC8418] (TL;DR if provided, the ukm is included in the entityUInfo field of the ECC-CMS-SharedInfo structure and is used as the salt, otherwise no salt is provided).

Example (VBA core function)

Dim nBytes As Long
Dim lpOutput() As Byte
Dim lpZZ() As Byte
Dim lpUkm() As Byte

lpZZ = cnvFromHex("160E3F5588C6FB4E9CEE8BC3C1C5000AB86396468C3D1CAEC0CB6E21536B5513")
' How many bytes for specified key wrap algorithm?
nBytes = KDF_ForCms(ByVal 0&, 0, lpZZ(0), cnvBytesLen(lpZZ), ByVal 0&, 0, "", PKI_KWRAP_AES128 Or PKI_KDF_X963 Or PKI_HASH_SHA1)
Debug.Print "KDF_ForCms returns " & nBytes
Debug.Assert (nBytes > 0)
ReDim lpOutput(nBytes - 1)
nBytes = KDF_ForCms(lpOutput(0), nBytes, lpZZ(0), cnvBytesLen(lpZZ), ByVal 0&, 0, "", PKI_KWRAP_AES128 Or PKI_KDF_X963 Or PKI_HASH_SHA1)
Debug.Print "KEK=" & cnvToHex(lpOutput)
Debug.Print "OK =" & "04D616C654CDF62BB186A5A088B60FB5"

lpUkm = cnvFromHex("616263")    ' "abc"
nBytes = KDF_ForCms(ByVal 0&, 0, lpZZ(0), cnvBytesLen(lpZZ), lpUkm(0), cnvBytesLen(lpUkm), "", PKI_KWRAP_AES256 Or PKI_KDF_HKDF Or PKI_HASH_SHA256)
Debug.Print "KDF_ForCms returns " & nBytes
Debug.Assert (nBytes > 0)
ReDim lpOutput(nBytes - 1)
nBytes = KDF_ForCms(lpOutput(0), nBytes, lpZZ(0), cnvBytesLen(lpZZ), lpUkm(0), cnvBytesLen(lpUkm), "", PKI_KWRAP_AES256 Or PKI_KDF_HKDF Or PKI_HASH_SHA256)
Debug.Print "KEK=" & cnvToHex(lpOutput)
Debug.Print "OK =" & "1D06D6FD5C1EBFB33CAD875E6B99781D3D750875F573C9093CECBFBA6937ACC5"

KDF_ForCms returns 16
KEK=04D616C654CDF62BB186A5A088B60FB5
OK =04D616C654CDF62BB186A5A088B60FB5
KDF_ForCms returns 32
KEK=1D06D6FD5C1EBFB33CAD875E6B99781D3D750875F573C9093CECBFBA6937ACC5
OK =1D06D6FD5C1EBFB33CAD875E6B99781D3D750875F573C9093CECBFBA6937ACC5

Example (VBA wrapper function)

Dim lpKEK() As Byte
Dim lpZZ() As Byte
Dim lpUkm() As Byte

lpZZ = cnvFromHex("160E3F5588C6FB4E9CEE8BC3C1C5000AB86396468C3D1CAEC0CB6E21536B5513")
lpKEK = kdfForCms(lpZZ, lpUkm, PKI_KWRAP_AES128 Or PKI_KDF_X963 Or PKI_HASH_SHA1)
Debug.Print "KEK = " & cnvHexStrFromBytes(lpKEK)
Debug.Print "OK  = 04D616C654CDF62BB186A5A088B60FB5"

lpUkm = cnvFromHex("616263")    ' "abc"
lpKEK = kdfForCms(lpZZ, lpUkm, PKI_KWRAP_AES256 Or PKI_KDF_HKDF Or PKI_HASH_SHA256)
Debug.Print "KEK = " & cnvHexStrFromBytes(lpKEK)
Debug.Print "OK  = 1D06D6FD5C1EBFB33CAD875E6B99781D3D750875F573C9093CECBFBA6937ACC5"

See Also

KDF_Bytes

[Contents] [Index]