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
X25519Kemx25519
X22519 Diffie-Hellman KEM adapter.

Traits§

Decapsulator
Trait for decapsulators, which is a supertrait bound of both Decapsulate and TryDecapsulate.
DhKem
This is a trait that all KEM models should implement, and should probably be promoted to the kem crate itself. It specifies the types of encapsulating and decapsulating keys created by key generation, the shared secret type, and the encapsulated key type
Encapsulate
Encapsulator for shared secrets.
Generate
Secure random generation.
KemParams
Key encapsulation mechanism parameters: sizes of the ciphertext and decrypted plaintext.
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.
NistP384DecapsulationKeyp384
NIST P-384 ECDH Decapsulation Key.
NistP384EncapsulationKeyp384
NIST P-384 ECDH Encapsulation Key.
NistP521DecapsulationKeyp521
NIST P-521 ECDH Decapsulation Key.
NistP521EncapsulationKeyp521
NIST P-521 ECDH Encapsulation Key.
Secp256k1DecapsulationKeyk256
secp256k1 ECDH Decapsulation Key.
Secp256k1EncapsulationKeyk256
secp256k1 ECDH Encapsulation Key.
X25519DecapsulationKeyx25519
Elliptic Curve Diffie-Hellman Decapsulation Key (i.e. secret decryption key)
X25519EncapsulationKeyx25519
Elliptic Curve Diffie-Hellman Encapsulation Key (i.e. public encryption key)