Skip to main content

Crate dhkem

Crate dhkem 

Source
Expand description

§RustCrypto: Diffie-Hellman-Based KEM

crate Docs Build Status Apache2/MIT licensed Rust Version Project Chat

Pure Rust implementation of the Diffie-Hellman-Based Key-Encapsulation Mechanism as described in the RFC9180 § 4.1.

Documentation

§About

Key Encapsulation Mechanisms (KEMs) provide a common API for establishing a symmetric key using public-key cryptography.

This crate implements a KEM-based API for elliptic curve Diffie-Hellman as specified for Hybrid Public Key Encryption (HPKE) which is described in RFC9180.

§⚠️ Security Warning

The implementation contained in this crate has never been independently audited!

USE AT YOUR OWN RISK!

§Minimum Supported Rust Version (MSRV) Policy

MSRV increases are not considered breaking changes and can happen in patch releases.

The crate MSRV accounts for all supported targets and crate feature combinations, excluding explicitly unstable features.

§License

Licensed under either of:

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

§Diffie-Hellman (DH) based Key Encapsulation Mechanisms (KEM)

This crate provides a KEM interface for DH protocols as specified in RFC9180 without the shared secret extraction process.

In particular, Encaps(pk) in the RFC returns the encapsulated key and an extracted shared secret, while our implementation leaves the extraction process up to the user.

This type of KEM construction is currently being used in HPKE, as per the RFC, and in the current draft of the TLS KEM combiner.

§Supported elliptic curves

Support for specific elliptic curves is gated behind the following features:

  • k256: secp256k1
  • p256: NIST P-256
  • p384: NIST P-384
  • p521: NIST P-521

Re-exports§

pub use kem;

Structs§

DecapsulationKey
Newtype for a piece of data that may be decapsulated
EcdhKemecdh
Generic Elliptic Curve Diffie-Hellman KEM adapter compatible with curves implemented using traits from the elliptic-curve crate.
EncapsulationKey
Newtype for a piece of data that may be encapsulated
Expander
Expander: wrapper for RFC5869 HKDF-Expand operation which can be used for HPKE’s LabeledExtract and LabeledExpand as described in RFC9810 §4.
InvalidLength
Structure for InvalidLength, used for output error handling.
X25519Kemx25519
X22519 Diffie-Hellman KEM adapter.

Traits§

Decapsulator
Decapsulator with an associated encapsulation key which can be used for encrypting shared keys that this decapsulator can decrypt.
Encapsulate
Encapsulator for shared secrets.
Generate
Secure random generation.
Kem
Key encapsulation mechanism.
TryDecapsulate
Decapsulator for encapsulated keys with failure handling, with an associated Encapsulator bounded by the Encapsulate trait.

Type Aliases§

EcdhDecapsulationKeyecdh
Elliptic Curve Diffie-Hellman Decapsulation Key (i.e. secret decryption key)
EcdhEncapsulationKeyecdh
Elliptic Curve Diffie-Hellman Encapsulation Key (i.e. public encryption key)
NistP256DecapsulationKeyp256
NIST P-256 ECDH Decapsulation Key.
NistP256EncapsulationKeyp256
NIST P-256 ECDH Encapsulation Key.
NistP256Kemp256
NIST P-256 DHKEM.
NistP384DecapsulationKeyp384
NIST P-384 ECDH Decapsulation Key.
NistP384EncapsulationKeyp384
NIST P-384 ECDH Encapsulation Key.
NistP384Kemp384
NIST P-256 DHKEM.
NistP521DecapsulationKeyp521
NIST P-521 ECDH Decapsulation Key.
NistP521EncapsulationKeyp521
NIST P-521 ECDH Encapsulation Key.
NistP521Kemp521
NIST P-521 DHKEM.
Secp256k1DecapsulationKeyk256
secp256k1 ECDH Decapsulation Key.
Secp256k1EncapsulationKeyk256
secp256k1 ECDH Encapsulation Key.
Secp256k1Kemp521
secp256k1 DHKEM.
X25519DecapsulationKeyx25519
Elliptic Curve Diffie-Hellman Decapsulation Key (i.e. secret decryption key)
X25519EncapsulationKeyx25519
Elliptic Curve Diffie-Hellman Encapsulation Key (i.e. public encryption key)