HPKE_LabeledExpand

CryptoSys PKI Pro Manual

HPKE_LabeledExpand

Compute the output of the LabeledExpand function as defined in RFC9180.

VBA/VB6 Syntax


Public Declare Function HPKE_LabeledExpand Lib "diCrPKI.dll" (ByRef lpOutput As Byte, ByVal nOutBytes As Long, ByRef lpPrk As Byte, ByVal nPrkLen As Long, ByVal szLabel As String, ByRef lpInfo As Byte, ByVal nInfoLen As Long, ByVal szCurveName As String, ByVal strParams As String, ByVal nOptions As Long) As Long

nRet = HPKE_LabeledExpand(lpOutput(0), nOutBytes, lpPrk(0), nPrkLen, szLabel, lpInfo(0), nInfoLen, szCurveName, szParams, nOptions) ' Note the "(0)" after the byte array parameters

C/C++ Syntax


long __stdcall HPKE_LabeledExpand(unsigned char *lpOutput, long nOutBytes, const unsigned char *lpPrk, long nPrkLen, const char *szLabel, const unsigned char *lpInfo, long nInfoLen,
	const char *szCurveName, const char *szParams, long nOptions);

Parameters

lpOutput: [out] byte array to be filled with output keying material.
nOutputLen: [in] required size of the output key in bytes (L).
lpPrk: [in] byte array containing the pseudorandom key (prk).
nPrkLen: [in] length of prk in bytes.
szLabel: [in] label string.
lpInfo: [in] byte array containing optional string info
nInfoLen: [in] length of info in bytes (can be zero)
szCurveName: [in] name of ECDH curve used in scheme (required): 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. Use to specify the AEAD encryption algorithm used in the scheme (if applicable). Specify either:
Zero (0) to indicate that the KDF is being used inside a KEM algorithm
or, if used in the remainder of HPKE, one of:
PKI_AEAD_AES_128_GCM
PKI_AEAD_AES_256_GCM
PKI_AEAD_CHACHA20_POLY1305

Returns (VBA/C)

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

VBA Wrapper Syntax

Public Function hpkeLabeledExpand (nBytes As Long, lpPrk() As Byte, szLabel As String, lpInfo() As Byte, szCurveName As String, Optional nOptions As Long = 0) As Byte()

.NET Equivalent

Hpke.LabeledExpand Method

C++ (STL) Equivalent

static bvec_t dipki::Hpke::LabeledExpand (int numBytes, const bvec_t &prk, std::string label, const bvec_t &info, CurveName curve, AeadAlg aeadAlg=AeadAlg::None)

Python Equivalent

static Hpke.labeled_expand(numbytes, prk, label, info, curveName, aeadalg=AeadAlg.NONE)

Remarks

The output buffer for the output keying 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 LabeledExpand function is defined in section 4 of [RFC9180]. It uses the "expand" stage of the HKDF function [RFC5869].

Because this is a standalone function with no context, the ECDH curve group used in the scheme must be specified. This automatically fixes the KDF and associated HMAC algorithm to be used as per Table 2 of [RFC9180]. In the case where the KDF is being used inside a KEM algorithm, the AEAD algorithm is not used and nOptions must be set to zero (0). In the other case where the KDF is being used in the remainder of the HPKE scheme, an explicit AEAD algorithm must be specified in nOptions. For more details see Hybrid Public Key Encryption (HPKE).

Example (VBA wrapper function)

Dim lpKey() As Byte
Dim lpPrk() As Byte
Dim lpInfo() As Byte
Dim Nk As Long
Debug.Print "RFC9180 Appendix A.1 DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, AES-128-GCM"
Debug.Print "key = LabeledExpand(secret, 'key', key_schedule_context, Nk)"
Nk = 16
lpPrk = cnvFromHex("12fff91991e93b48de37e7daddb52981084bd8aa64289c3788471d9a9712f397")
lpInfo = cnvFromHex("00725611c9d98c07c03f60095cd32d400d8347d45ed67097bbad50fc56da742d07cb6cffde367bb0565ba28bb02c90744a20f5ef37f30523526106f637abb05449")
lpKey = hpkeLabeledExpand(Nk, lpPrk, "key", lpInfo, "X25519", PKI_AEAD_AES_128_GCM)
Debug.Print "key=" & cnvToHex(lpKey)
If cnvBytesLen(lpKey) = 0 Then Debug.Print errFormatErrorMessage()

key=4531685D41D65F03DC48F6B8302C05B0