dipki::Hpke Class Reference

Hybrid Public Key Encryption functions (HPKE). More...

Public Types
enum class	AeadAlg
	AEAD functions supported for HPKE. More...
enum class	CurveName
	Supported ECDH curves for HPKE. More...
enum class	OutputOpts
	Options to format or re-encode output. More...

Static Public Member Functions
static std::string	DerivePrivateKey (const bvec_t &ikm, CurveName curve, OutputOpts opts=OutputOpts::Default)
	Derive an EC private key in a deterministic manner from input keying material using the DeriveKeyPair algorithm in RFC9180. More...
static bvec_t	LabeledExpand (int numBytes, const bvec_t &prk, std::string label, const bvec_t &info, CurveName curve, AeadAlg aeadAlg=AeadAlg::None)
	Compute the output of the LabeledExpand function as defined in RFC9180. More...
static bvec_t	LabeledExtract (const bvec_t &salt, std::string label, const bvec_t &ikm, CurveName curve, AeadAlg aeadAlg=AeadAlg::None)
	Compute the output of the LabeledExtract function as defined in RFC9180. More...

Detailed Description

Hybrid Public Key Encryption functions (HPKE).

Member Enumeration Documentation

AeadAlg

enum dipki::Hpke::AeadAlg

strong

AEAD functions supported for HPKE.

Enumerator
Aes_128_Gcm	AEAD_AES_128_GCM from RFC5116.
Aes_256_Gcm	AEAD_AES_256_GCM from RFC5116.
ChaCha20_Poly1305	AEAD_CHACHA20_POLY1305 from RFC8439.

CurveName

enum dipki::Hpke::CurveName

strong

Supported ECDH curves for HPKE.

Enumerator
P_256	NIST curve P-256 (secp256r1)
P_384	NIST curve P-384 (secp384r1)
P_521	NIST curve P-521 (secp521r1)
X25519	ECDH curve X25519 from RFC7748.
X448	ECDH curve X448 from RFC7748.

OutputOpts

enum dipki::Hpke::OutputOpts

strong

Options to format or re-encode output.

Enumerator
Default	Default output as ephemeral "internal" key string.
KeyAsHex	Output key in hex format compatible with test vectors in [RFC9180].

Member Function Documentation

DerivePrivateKey()

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

static

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

Parameters

ikm	Input key material (ikm). This must have length in bytes at least as long as the key to be produced.
curve	Curve name.
opts	Output options (default=internal key format).

Returns

Derived private key in string form.

std::string ikmhex = "7268600d403fce431561aef583ee1613527cff655c1343f29812e66706df3234";
std::string skhex = dipki::Hpke::DerivePrivateKey(dipki::Cnv::FromHex(ikmhex), dipki::Hpke::CurveName::X25519, dipki::Hpke::OutputOpts::KeyAsHex);
// 52c4a758a802cd8b936eceea314432798d5baf2d7e9235dc084ab1b9cfa2f736

LabeledExpand()

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  )

static

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

Parameters

numBytes	Required number of bytes (L) of output keying material.
prk	Pseudorandom key (prk).
label	Label string.
info	Byte string info.
curve	ECDH curve used in scheme.
aeadAlg	AEAD encryption algorithm used in the scheme or AeadAlg::None (default) to indicate KDF is being used inside a KEM algorithm..

Returns

L bytes of output keying material.

Remarks

The LabeledExpand function is defined in section 4 of [RFC9180]. It uses the "expand" stage of the HKDF function [RFC5869]. The ECDH curve group used in the scheme must be specified, which automatically fixes the KDF and associated HMAC algorithm to be used.

int Nk = 16
dipki::bvec_t secret = dipki::Cnv::FromHex("12fff91991e93b48de37e7daddb52981084bd8aa64289c3788471d9a9712f397");
dipki::bvec_t key_schedule_context = dipki::Cnv::FromHex("00725611c9d98c07c03f60095cd32d400d8347d45ed67097bbad50fc56da742d07cb6cffde367bb0565ba28bb02c90744a20f5ef37f30523526106f637abb05449");
dipki::bvec_t key = dipki::Hpke::LabeledExpand(Nk, secret, "key", key_schedule_context, dipki::Hpke::CurveName::X25519, dipki::Hpke::AeadAlg::Aes_128_Gcm);
// key: 4531685d41d65f03dc48f6b8302c05b0

LabeledExtract()

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

static

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

Parameters

salt	Byte string salt.
label	Label string.
ikm	Input key material (ikm).
curve	ECDH curve used in scheme.
aeadAlg	AEAD encryption algorithm used in the scheme or AeadAlg::None (default) to indicate KDF is being used inside a KEM algorithm.

Returns

A pseudorandom key of fixed length Nh bytes.

Remarks

The LabeledExtract function is defined in section 4 of [RFC9180]. It uses the "extract" stage of the HKDF function [RFC5869] and outputs a fixed value of bytes equal to the length (Nh) of the underlying HMAC function used by the KDF algorithm. The ECDH curve group used in the scheme must be specified, which automatically fixes the KDF and associated HMAC algorithm to be used.

// Used inside KEM
std::string ikmhex = "7268600d403fce431561aef583ee1613527cff655c1343f29812e66706df3234";
dipki::bvec_t prk = dipki::Hpke::LabeledExtract(dipki::bvec_t(), "dkp_prk", dipki::Cnv::FromHex(ikmhex), dipki::Hpke::CurveName::X25519);
// 7B8BFE1D6F3D0CB45C585E133299C64AC998BF46CAF2DC13BA874F23413EC23A
// Used outside KEM (so AEAD alg must be specified)
dipki::bvec_t prk_id_hash = dipki::Hpke::LabeledExtract(dipki::bvec_t(), "psk_id_hash", dipki::bvec_t(), dipki::Hpke::CurveName::X25519, dipki::Hpke::AeadAlg::Aes_128_Gcm);
// 725611C9D98C07C03F60095CD32D400D8347D45ED67097BBAD50FC56DA742D07