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 RFC9180 §4.
InvalidLength
Structure for InvalidLength, used for output error handling.
X25519Kemx25519
X22519 Diffie-Hellman KEM adapter.

Enums§

Error
Error type.

Traits§

Decapsulator
Decapsulator with an associated encapsulation key which can be used for encrypting shared keys that this decapsulator can decrypt.
EagerHash
Trait implemented by eager hashes which expose their block-level core.
Encapsulate
Encapsulator for shared secrets.
Generate
Secure random generation.
HpkeKemId
Associates a given HPKE KEM ID with the given type.
Kem
Key encapsulation mechanism.
TryDecapsulate
Decapsulator for encapsulated keys with failure handling, with an associated Encapsulator bounded by the Encapsulate trait.

Type Aliases§

Ciphertext
Ciphertext message (a.k.a. “encapsulated key”) produced by Encapsulate::encapsulate which is an encrypted SharedKey that can be decrypted using Decapsulate::decapsulate.
EcdhDecapsulationKeyecdh
Elliptic Curve Diffie-Hellman Decapsulation Key (i.e. secret decryption key)
EcdhEncapsulationKeyecdh
Elliptic Curve Diffie-Hellman Encapsulation Key (i.e. public encryption key)
NistP256DecapsulationKeyecdh and p256
NIST P-256 ECDH Decapsulation Key.
NistP256EncapsulationKeyecdh and p256
NIST P-256 ECDH Encapsulation Key.
NistP256Kemecdh and p256
NIST P-256 DHKEM.
NistP384DecapsulationKeyecdh and p384
NIST P-384 ECDH Decapsulation Key.
NistP384EncapsulationKeyecdh and p384
NIST P-384 ECDH Encapsulation Key.
NistP384Kemecdh and p384
NIST P-384 DHKEM.
NistP521DecapsulationKeyecdh and p521
NIST P-521 ECDH Decapsulation Key.
NistP521EncapsulationKeyecdh and p521
NIST P-521 ECDH Encapsulation Key.
NistP521Kemecdh and p521
NIST P-521 DHKEM.
Secp256k1DecapsulationKeyecdh and k256
secp256k1 ECDH Decapsulation Key.
Secp256k1EncapsulationKeyecdh and k256
secp256k1 ECDH Encapsulation Key.
Secp256k1Kemecdh and k256
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)