Crate hpke_dispatch

Hybrid public key encryption with algorithms dispatched at runtime

This crate provides a generic-free interface to the hpke crate, a rust implementation of the draft RFC9180 hybrid public key encryption scheme. If you know the specific (aead, kdf, kem) triple at compile time, you should use the hpke crate directly.

Currently, this crate only exposes interfaces for the Base mode (0) described in the hpke draft, and within base mode, only stateless single-shot message encryption/decryption, as defined in RFC9180§6

WebAssembly ready

This crate is also published to npm as hpke as a typescript/javascript package, and can also be custom built for specific wasm use cases (omitting unused algorithms) with wasm-pack. For an example of using the library from node, see examples/example.ts

Nightly-only feature to work around a wasm-bindgen bug: cfg_eval

In order to opt out of algo-all for a wasm build, you must use nightly and enable the cfg_eval cargo feature. This is due to wasm-bindgen#2058. This is not necessary for use from rust, even when opting out of algo-all.

Available cargo features:

• cfg_eval: allows this crate to be built on nightly rust for wasm without algo-all. Note that algo-all (all algorithms) will build for wasm on any channel without this feature. disabled by default. Attempting to build for wasm with a subset.

• base-mode-open: Enables hpke base-mode one-shot open behavior (receiver functionality). Enabled by default.

• base-mode-seal: Enables hpke base-mode one-shot seal behavior (sender functionality). Enabled by default.

• algo-all: enables all aead, kdf, and kem algorithms. enabled by default.

• aead-all: Enables aead-aes-gcm-128, aead-aes-gcm-256, and aead-chacha-20-poly-1305 algorithm features. Enabled by default.

• kdf-all: Enables kdf-sha256, kdf-sha384, kdf-sha512 algorithm features. Enabled by default.

• kem-all: Enables both kem-dh-p256-hkdf-sha256 and kem-x25519-hkdf-sha256 algorithm features. Enabled by default.

• serde: enables derived serde serialization and deserialization for all public structs and enums. Disabled by default.

Example feature usage:

To depend on this crate from rust with all algorithms, base-mode-open, and base-mode-seal, use default features.

To depend on this crate from rust with all algorithms and serde enabled, but without base-mode-seal: default-features = false, features = ["algo-all", "base-mode-open", "serde"]

To build for wasm without kem-x25519-hkdf-sha256 or base-mode-open: wasm-pack build --no-default-features --features aead-all,kdf-all,kem-dh-p256-hkdf-sha256,base-mode-seal,cfg_eval

To build for wasm with all algorithms but without base-mode-open: wasm-pack build --no-default-features --features algo-all,base-mode-seal

Structs

• Config
  Config is an open struct that contains an (Aead, Kdf, Kem) algorithmic triple. This can be used with Config::base_mode_seal, Config::base_mode_open, [base_mode_seal], or [base_mode_open].
• EncappedKeyAndCiphertext
  a simple struct to return the combined encapsulated key and ciphertext from seal
• IdLookupError
  A simple error type for failed id lookups
• Keypair
  An encoded keypair

Enums

• Aead
  Aead represents an authenticated encryption with additional data encryption function, as per RFC9180§7.3
• HpkeError
  Describes things that can go wrong in the HPKE protocol
• Kdf
  Kdf represents an key derivation function, as per RFC9180§7.2
• Kem
  Kem represents an asymmetric key encapsulation mechanism, as per RFC9180§7.1. Currently only two of options listed in the hpke draft are available.

Constants

• AEAD_ALL
  An iterable slice of Aead variants
• KDF_ALL
  An iterable slice of Kdf variants
• KEM_ALL
  An iterable slice of Kem variants

Functions

• base_mode_open
  base_mode_open provides an interface to hpke::single_shot_open that does not require compile time selection of an algorithm. Instead, the selected algorithm is provided through the Config passed as the first argument.
• base_mode_seal
  base_mode_seal provides an interface to hpke::single_shot_seal that does not require compile time selection of an algorithm. Instead, the selected algorithm is provided through the Config passed as the first argument.
• gen_keypair
  generate a Keypair for the provided asymmetric key encapsulation mechanism (Kem)