CryptoSys PKI Pro Manual


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


[out] string of sufficient length to receive the derived private key.
[in] maximum number of characters to be received.
[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.
[in] length of the input key material in bytes.
[in] name of ECDH curve: Specify one of:
"P-256" | "P-384" | "P-521" | "X25519" | "X448"
[in] (optional) parameters. Not used in this version. Set as the empty string "".
[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)


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 groupNsk

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 "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

See Also

[Contents] [Index]

[PREV: HMAC_HexFromHex...]   [Contents]   [Index]   
   [NEXT: HPKE_LabeledExpand...]

Copyright © 2004-23 D.I. Management Services Pty Ltd. All rights reserved. Generated 2023-10-22T11:11:11Z.