KDF_Bytes

CryptoSys PKI Pro Manual

KDF_Bytes

Generate a key-encryption key (KEK) from input keying material using a key derivation function (KDF).

VBA/VB6 Syntax


Public Declare Function KDF_Bytes Lib "diCrPKI.dll" (ByRef lpOutput As Byte, ByVal nOutBytes As Long, ByRef lpIKM As Byte, ByVal nIkmLen As Long, ByRef lpInfo As Byte, ByVal nInfoLen As Long, ByVal szParams As String, ByVal nOptions As Long) As Long

nRet = KDF_Bytes(lpOutput(0), nOutBytes, lpIKM(0), nIkmLen, lpInfo(0), nInfoLen, szParams, nOptions) ' Note the "(0)" after the byte array parameters

C/C++ Syntax


long __stdcall KDF_Bytes(unsigned char *lpOutput, long nOutBytes, const void *lpIKM, long nIkmLen, const void *lpInfo, long nInfoLen, const char *szParams, long nOptions);

Parameters

lpOutput

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

nOutputLen

[in] required size of the output key in bytes (must be greater than zero).

lpIKM

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

nIkmLen

[in] length of the input key material in bytes.

lpInfo

[in] byte array containing the optional SharedInfo (otherInfo/key derivation parameter/kdp).

nInfoLen

[in] length of the SharedInfo in bytes.

szParams

[in] (optional) parameters. Set as the empty string "" for defaults. Otherwise include a set of attribute-value pairs separated by a semi-colon ";" to set options from the following

salt=<hex-digits> to set the optional salt parameter for the HKDF algorithm encoded in hex format, e.g. "salt=606162636465666768696a6b6c6d6e6f;" [default=no salt]

nOptions

[in] Option flags. Select one of:
PKI_KDF_X963 to use the the ANSI-X9.63-KDF key derivation function (default)
PKI_KDF_HKDF to use the HMAC-based Key Derivation Function (HKDF) from RFC 5869
PKI_KDF_KDF2 to use KDF2 from ANSI-X9.44. New in [v23.0]
PKI_KDF_KDF3 to use KDF3 from ANSI-X9.44. New in [v23.0]
and select one hash algorithm to use with the key derivation function:
PKI_HASH_SHA1 (0) to use the SHA-1 hash algorithm (default - CAUTION)
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

Returns (VBA/C)

If successful, the return value is zero; otherwise it returns a nonzero error code.

VBA Wrapper Syntax

Public Function kdfBytes (nKekBytes As Long, lpIkm() As Byte, lpInfo() As Byte, Optional nOptions As Long = 0, Optional szParams As String = "") As Byte()

.NET Equivalent

Kdf.Bytes Method

C++ (STL) Equivalent

static bvec_t dipki::Kdf::Bytes (int dklen, const bvec_t &ikm, KdfAlg kdfAlg=KdfAlg::X963, HashAlg hashAlg=HashAlg::Sha1, const bvec_t &sharedInfo={}, const std::string &paramString="")

Python Equivalent

static Kdf.bytes(dklen, ikm, kdfalg, hashalg=HashAlg.SHA1, sharedinfo=None, paramstring="")

Remarks

The output buffer for the output key material lpOutput must exist and must have been dimensioned to at least the required length given in nOutBytes, which must be a positive number. Note that the return value on success is zero.

The ANSI-X9.63-KDF key derivation function is described in section 3.6.1 of [SEC1]. The HMAC-based Key Derivation Function (HKDF) is described in [RFC5869]. KDF2 and KDF3 are described in ANSI X9.44 [X9-44].

Example (VBA core function)

Dim nBytes As Long
Dim lpOutput() As Byte
Dim lpZZ() As Byte
Dim lpInfo() As Byte
Dim r As Long

' ansx963_2001.rsp
' # CAVS 12.0
' # 'ANS X9.63-2001' information for sample
' [SHA-256]
' [shared secret length = 192]
' [SharedInfo length = 0]
' [key data length = 128]
' COUNT = 0
' Z = 96c05619d56c328ab95fe84b18264b08725b85e33fd34f08
' SharedInfo =
' key_data = 443024c3dae66b95e6f5670601558f71
nBytes = 128 \ 8
ReDim lpOutput(nBytes - 1)
lpZZ = cnvFromHex("96c05619d56c328ab95fe84b18264b08725b85e33fd34f08")
r = KDF_Bytes(lpOutput(0), nBytes, lpZZ(0), cnvBytesLen(lpZZ), ByVal 0&, 0, "", PKI_KDF_X963 Or PKI_HASH_SHA256)
Debug.Print "KDF_Bytes returns " & r
Debug.Print "KEK=" & cnvToHex(lpOutput)
Debug.Print "OK =" & "443024c3dae66b95e6f5670601558f71"

' [RFC 5869] A.1.  Test Case 1 Basic test case with SHA-256
nBytes = 42
ReDim lpOutput(nBytes - 1)
lpZZ = cnvFromHex("0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b")   ' 22 octets
lpInfo = cnvFromHex("f0f1f2f3f4f5f6f7f8f9")  ' 10 octets
r = KDF_Bytes(lpOutput(0), nBytes, lpZZ(0), cnvBytesLen(lpZZ), lpInfo(0), cnvBytesLen(lpInfo), "salt=000102030405060708090a0b0c", PKI_KDF_HKDF Or PKI_HASH_SHA256)
Debug.Print "KDF_Bytes returns " & r
Debug.Print "KEK=" & cnvToHex(lpOutput)
Debug.Print "OK =" & "3cb25f25faacd57a90434f64d0362f2a2d2d0a90cf1a5a4c5db02d56ecc4c5bf34007208d5b887185865"

KDF_Bytes returns 0
KEK=443024C3DAE66B95E6F5670601558F71
OK =443024c3dae66b95e6f5670601558f71
KDF_Bytes returns 0
KEK=3CB25F25FAACD57A90434F64D0362F2A2D2D0A90CF1A5A4C5DB02D56ECC4C5BF34007208D5B887185865
OK =3cb25f25faacd57a90434f64d0362f2a2d2d0a90cf1a5a4c5db02d56ecc4c5bf34007208d5b887185865

Example (VBA wrapper function)

Dim lpKEK() As Byte
Dim lpZZ() As Byte
Dim lpInfo() As Byte

' ansx963_2001.rsp CAVS 12.0 'ANS X9.63-2001' information for sample
lpZZ = cnvFromHex("96c05619d56c328ab95fe84b18264b08725b85e33fd34f08")
lpKEK = kdfBytes(128 \ 8, lpZZ, lpInfo, PKI_HASH_SHA256)
Debug.Print "KEK = " & cnvHexStrFromBytes(lpKEK)
Debug.Print "OK  = 443024c3dae66b95e6f5670601558f71"

' [RFC 5869] A.1.  Test Case 1 Basic test case with SHA-256
lpZZ = cnvFromHex("0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b")
lpInfo = cnvFromHex("f0f1f2f3f4f5f6f7f8f9")
lpKEK = kdfBytes(42, lpZZ, lpInfo, PKI_KDF_HKDF Or PKI_HASH_SHA256, "salt=000102030405060708090a0b0c")
Debug.Print "KEK = " & cnvHexStrFromBytes(lpKEK)
Debug.Print "OK  = 3cb25f25faacd57a90434f64d0362f2a2d2d0a90cf1a5a4c5db02d56ecc4c5bf34007208d5b887185865"

KDF_Bytes

VBA/VB6 Syntax

C/C++ Syntax

Parameters

Returns (VBA/C)

VBA Wrapper Syntax

.NET Equivalent

C++ (STL) Equivalent

Python Equivalent

Remarks

Example (VBA core function)

Example (VBA wrapper function)

See Also