HPKE_DerivePrivateKey

CryptoSys PKI Pro Manual

HPKE_DerivePrivateKey

Derive an EC private key in a deterministic manner from input keying material using the DeriveKeyPair algorithm in RFC9180.

VBA/VB6 Syntax


Public Declare Function HPKE_DerivePrivateKey Lib "diCrPKI.dll" (ByVal szOutput As String, ByVal nOutChars As Long, ByRef lpIkm As Byte, ByVal nIkmLen As Long, ByVal szCurveName As String, ByVal szParams As String, ByVal nOptions As Long) As Long

nRet = HPKE_DerivePrivateKey(szOutput, nOutChars, lpIkm(0), nIkmLen, szCurveName,, szParams, nOptions) ' Note the "(0)" after the byte array parameters

C/C++ Syntax


long __stdcall HPKE_DerivePrivateKey(char *szOutput, long nOutChars, const unsigned char *lpIkm, long nIkmLen, const char *szCurveName, const char *szParams, long nOptions);

Parameters

szOutput: [out] string of sufficient length to receive the derived private key.
nOutChars: [in] maximum number of characters to be received.
lpIkm: [in] byte array containing the input key material (ikm). This must have length in bytes at least as long as the key to be produced.
nIkmLen: [in] length of the input key material in bytes.
szCurveName: [in] name of ECDH curve: Specify one of:
"P-256" | "P-384" | "P-521" | "X25519" | "X448"
szParams: [in] (optional) parameters. Not used in this version. Set as the empty string "".
nOptions: [in] Option flags. Select one of:
Zero (0) to output the private key in ephemeral "internal" key format (default); or
PKI_ENCODE_HEX to output the private key in serialized hex form.

Returns (VBA/C)

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

VBA Wrapper Syntax

Public Function hpkeDerivePrivateKey (lpIkm() As Byte, szCurveName As String, Optional nOptions As Long = 0) As String

.NET Equivalent

Hpke.DerivePrivateKey Method

C++ (STL) Equivalent

static std::string dipki::Hpke::DerivePrivateKey (const bvec_t &ikm, CurveName curve, OutputOpts opts=OutputOpts::Default)

Python Equivalent

static Hpke.derive_private_key(ikm, curveName, opts=0)

Remarks

By default the key is output as an ephemeral "internal" key string, which can be used directly with ECC_SaveKey, ECC_SaveEncKey, ECC_PublicKeyFromPrivate, ECC_DHSharedSecret and ECC_QueryKey. If nOptions is set to PKI_ENCODE_HEX then the key is output in serialized hexadecimal form in the same manner as the test vectors in [RFC9180] (without the clamping).

For the "raw" VBA/C function, the user must allocate an output string buffer szOutput of the required length. Specify a zero nOutChars or an empty string for szOutput to find the required length. ANSI C users must add one to this value when allocating memory.

This function derives an ECDH private key in the deterministic manner described in [RFC9180] using user-provided input key material (ikm). There is very, very small chance that a valid key cannot be generated from the ikm; in which case the function will return a negative KEYGEN_FAILED_ERROR error code.

The input key material must have length in bytes at least as long as the key to be produced (Nsk) or a BAD_LENGTH_ERROR error code will be returned. The values of Nsk (the length in bytes of a Diffie-Hellman private key) for the supported EC curves are as follows:

EC curve group	Nsk
P-256	32
P-384	48
P-521	66
X25519	32
X448	56

The KDF to be used is fixed by the EC curve group. See Hybrid Public Key Encryption (HPKE).

Example (VBA wrapper function)

Dim ikmhex As String
Dim skokhex As String
Dim pkokhex As String
Dim skhex As String
Dim pkhex As String
Dim prikeystr As String
Debug.Print "TESTING HPKE DERIVEPRIVATEKEY..."
Debug.Print "RFC9180 A.1. DHKEM(X25519, HKDF-SHA256)"
ikmhex = "7268600d403fce431561aef583ee1613527cff655c1343f29812e66706df3234"
skokhex = "52c4a758a802cd8b936eceea314432798d5baf2d7e9235dc084ab1b9cfa2f736"
pkokhex = "37fda3567bdbd628e88668c3c8d7e97d1d1253b6d4ea6d44c150f741f1bf4431"
' A. Derive private key in hex format
skhex = hpkeDerivePrivateKey(cnvFromHex(ikmhex), "X25519", PKI_ENCODE_HEX)
Debug.Print "skEm: " & skhex
' B. Derive key in ephemeral internal private key format (NB different each time)
prikeystr = hpkeDerivePrivateKey(cnvFromHex(ikmhex), "X25519")
' C. Get public key in hex format from internal key string
pkhex = eccQueryKey(prikeystr, "publicKey")
Debug.Print "pkEm: " & pkhex

skEm: 52c4a758a802cd8b936eceea314432798d5baf2d7e9235dc084ab1b9cfa2f736
pkEm: 37fda3567bdbd628e88668c3c8d7e97d1d1253b6d4ea6d44c150f741f1bf4431