Crate hpke_dispatch
source ·Expand description
§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 withoutalgo-all
. Note thatalgo-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
, andaead-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
kem-dh-p256-hkdf-sha256
,kem-dh-p384-hkdf-sha384
,kem-dh-p521-hkdf-sha512
, andkem-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 is an open struct that contains an (
Aead
,Kdf
,Kem
) algorithmic triple. This can be used withConfig::base_mode_seal
,Config::base_mode_open
, [base_mode_seal
], or [base_mode_open
]. - a simple struct to return the combined encapsulated key and ciphertext from seal
- A simple error type for failed id lookups
- An encoded keypair
Enums§
- Aead represents an authenticated encryption with additional data encryption function, as per RFC9180§7.3
- Describes things that can go wrong in the HPKE protocol
- Kdf represents an key derivation function, as per RFC9180§7.2
- Kem represents an asymmetric key encapsulation mechanism, as per RFC9180§7.1. Currently only four of the options listed in the hpke draft are available.
Constants§
- An iterable slice of
Aead
variants - An iterable slice of
Kdf
variants - An iterable slice of
Kem
variants
Functions§
base_mode_open
provides an interface tohpke::single_shot_open
that does not require compile time selection of an algorithm. Instead, the selected algorithm is provided through theConfig
passed as the first argument.base_mode_seal
provides an interface tohpke::single_shot_seal
that does not require compile time selection of an algorithm. Instead, the selected algorithm is provided through theConfig
passed as the first argument.- generate a Keypair for the provided asymmetric key encapsulation mechanism (
Kem
)