CryptoSys PKI Pro Manual

HPKE_LabeledExtract

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

VBA/VB6 Syntax

Public Declare Function HPKE_LabeledExtract Lib "diCrPKI.dll" (ByRef lpOutput As Byte, ByVal nOutBytes As Long, ByRef lpSalt As Byte, ByVal nSaltLen As Long, ByVal strLabel As String, ByRef lpIkm As Byte, ByVal nIkmLen As Long, ByVal strCurveName As String, ByVal strParams 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 HPKE_LabeledExtract(unsigned char *lpOutput, long nOutBytes, const unsigned char *lpSalt, long nSaltLen, const char *szLabel, const unsigned char *lpIkm, long nIkmLen, const char *szCurveName, const char *szParams, long nOptions);

Parameters

lpOutput
[out] byte array to be filled with a pseudorandom key of fixed length.
nOutputLen
[in] length of the output array in bytes.
lpSalt
[in] byte array containing the optional salt.
nSaltLen
[in] length of salt in bytes (can be zero).
szLabel
[in] label string.
lpIkm
[in] byte array containing input keying material (ikm).
nIkmLen
[in] length of ikm in bytes.
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 the number of bytes in or required for the output; otherwise it returns a negative error code. otherwise it returns a negative error code.

VBA Wrapper Syntax

Public Function hpkeLabeledExtract (lpSalt() As Byte, szLabel As String, lpIkm() As Byte, szCurveName As String, Optional nOptions As Long = 0) As Byte()

.NET Equivalent

Hpke.LabeledExtract Method

C++ (STL) Equivalent

static bvec_t dipki::Hpke::LabeledExtract (const bvec_t &salt, std::string label, const bvec_t &ikm, CurveName curve, AeadAlg aeadAlg=AeadAlg::None)

Python Equivalent

static Hpke.labeled_extract(salt, label, ikm, curveName, aeadalg=AeadAlg.NONE)

Remarks

The LabeledExtract function is defined in section 4 of [RFC9180]. It uses the "extract" stage of the HKDF function [RFC5869]. It outputs a fixed value of bytes equal to the length (Nh) of the underlying HMAC function used by the KDF algorithm.

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 lpExtracted() As Byte
Dim lpSalt() As Byte
Dim lpIkm() As Byte
Debug.Print "RFC9180 Appendix A.1 DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, AES-128-GCM"
Debug.Print "prk = LabeledExtract('', 'dkp_prk', ikm)"
lpSalt = vbNullString
lpIkm = cnvFromHex("7268600d403fce431561aef583ee1613527cff655c1343f29812e66706df3234")
lpExtracted = hpkeLabeledExtract(lpSalt, "dkp_prk", lpIkm, "X25519")
Debug.Print "prk=" & cnvToHex(lpExtracted)
If cnvBytesLen(lpExtracted) = 0 Then Debug.Print errFormatErrorMessage()
prk=7B8BFE1D6F3D0CB45C585E133299C64AC998BF46CAF2DC13BA874F23413EC23A

See Also

HPKE_LabeledExpand

[Contents] [Index]

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

Copyright © 2004-24 D.I. Management Services Pty Ltd. All rights reserved. Generated 2024-09-23T07:52:09Z.