Crate hpke_rs 

HPKE

An implementation of HPKE (RFC 9180) with flexible crypto backends.

From the RFC:

This scheme provides a variant of public-key encryption of arbitrary-sized plaintexts for a recipient public key. It also includes three authenticated variants, including one which authenticates possession of a pre-shared key, and two optional ones which authenticate possession of a KEM private key.

Supported HPKE modes

• Base
• PSK
• Auth
• AuthPSK

Supported cipher suites

KEM

• DH KEM x25519
• DH KEM P256
• DH KEM P384
• DH KEM P521
• DH KEM K256
• DH KEM 448
• X-Wing (draft-06)

AEAD

• AES GCM 128
• AES GCM 256
• ChaCha20 Poly1305
• Exporter only

KDF

• HKDF SHA-256
• HKDF SHA-384
• HKDF SHA-512

Crypto Backends

This crate does not implement the cryptographic primitives itself. Instead it expects an implementation of the HpkeCrypto trait.

Two backends are provided in this repository

• libcrux backend: a formally verified crypto backend but with limited ciphersuite support for now
• RustCrypto backend: a backend using well established crypto implementations

Examples

Oneshot HPKE encryption.

use hpke_rs::{*, hpke_types::*};
use hpke_rs_libcrux::HpkeLibcrux;
use hpke_rs_crypto::{HpkeCrypto, RngCore};

// Set up hpke mode.
let mut hpke = Hpke::<HpkeLibcrux>::new(Mode::Base, KemAlgorithm::DhKem25519,
   KdfAlgorithm::HkdfSha256, AeadAlgorithm::ChaCha20Poly1305);

// Generate keys. The other parties public key must be received in some way.
let (sk_r, pk_r) = hpke.generate_key_pair().unwrap().into_keys();
let (sk_s, pk_s) = hpke.generate_key_pair().unwrap().into_keys();

// Set the input. Only `plain_text` is required
let info = b"HPKE demo info";
let aad = b"HPKE demo aad";
let plaintext = b"HPKE demo plain text";
let exporter_context = b"HPKE demo exporter context";

// We don't use authentication or PSKs here.
let psk = None;
let psk_id = None;
let sk_s = None;
let pk_s = None;

// Encrypt the `plaintext` to the receiver.
let (enc, ctxt) = hpke
    .seal(&pk_r, info, aad, plaintext, psk, psk_id, sk_s)
    .unwrap();

// Decrypt the ciphertext on the receiver.
let ptxt = hpke
    .open(&enc, &sk_r, info, aad, &ctxt, psk, psk_id, pk_s)
    .unwrap();

assert_eq!(ptxt, plaintext);

Encryption context.

use hpke_rs::{*, hpke_types::*};
use hpke_rs_libcrux::HpkeLibcrux;
use hpke_rs_crypto::{HpkeCrypto, RngCore};

// Set up hpke mode.
let mut hpke = Hpke::<HpkeLibcrux>::new(Mode::Base, KemAlgorithm::DhKem25519,
   KdfAlgorithm::HkdfSha256, AeadAlgorithm::ChaCha20Poly1305);

// Generate keys. The other parties public key must be received in some way.
let (sk_r, pk_r) = hpke.generate_key_pair().unwrap().into_keys();
let (sk_s, pk_s) = hpke.generate_key_pair().unwrap().into_keys();

// Set the input. Only `plain_text` is required
let info = b"HPKE demo info";
let aad = b"HPKE demo aad";
let plaintext = b"HPKE demo plain text";
let exporter_context = b"HPKE demo exporter context";

// We don't use authentication or PSKs here.
let psk = None;
let psk_id = None;
let sk_s = None;
let pk_s = None;

// Set up the context on both sides.
let (enc, mut sender_context) = hpke
    .setup_sender(&pk_r, info, psk, psk_id, sk_s)
    .unwrap();

// Share `enc` with the receiver.
let mut receiver_context = hpke
    .setup_receiver(&enc, &sk_r, info, psk, psk_id, pk_s)
    .unwrap();

// Encrypt the plaintext to the receiver, using the context.
let ctxt = sender_context.seal(aad, plaintext).unwrap();

// Decrypt the ciphertext on the receiver, using the context.
let ptxt = receiver_context.open(aad, &ctxt).unwrap();

assert_eq!(ptxt, plaintext);

Modules

hpke_types

Re-export of the HPKE types from the hpke_rs_crypto crate.

prelude

Prelude for HPKE. Include this to get access to all the public functions of HPKE.

Structs

Context

The HPKE context. Note that the RFC currently doesn’t define this. Also see https://github.com/cfrg/draft-irtf-cfrg-hpke/issues/161.

Hpke

The HPKE configuration struct. This holds the configuration for HPKE but no state. To use HPKE first instantiate the configuration with let hpke = Hpke::new(mode, kem_mode, kdf_mode, aead_mode). Now one can use the hpke configuration.

HpkeKeyPair

An HPKE key pair has an HPKE private and public key.

HpkePrivateKey

An HPKE private key is a byte vector.

HpkePublicKey

An HPKE public key is a byte vector.

Enums

HpkeError

HPKE Error types.

Mode

HPKE supports four modes.

Type Aliases

HPKEKeyPairDeprecated

HPKEPrivateKeyDeprecated

HPKEPublicKeyDeprecated