Skip to main content

Crate x_wing

Crate x_wing 

Source
Expand description

§RustCrypto: X-Wing KEM

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

Pure Rust implementation of X-Wing, a general-purpose post-quantum/traditional hybrid key encapsulation mechanism (PQ/T KEM) built on X25519 and ML-KEM-768. Built on the ml-kem and x25519-dalek crates.

Current implementation matches the draft RFC version 06.

The original paper: X-Wing The Hybrid KEM You’ve Been Looking For

Documentation

§Features

The following features are provided by this crate:

  • getrandom — Enables generate_key_pair (generate without an explicit RNG)
  • zeroize — Enables memory zeroing for all cryptographic secrets
  • hazmat — Enables EncapsulationKey::encapsulate_deterministic. Useful for testing purposes. Do NOT enable unless you know what you are doing.

The default features are [] (nothing).

§⚠️ 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.

§Usage

This crate implements the X-Wing Key Encapsulation Method (X-Wing-KEM) algorithm. X-Wing-KEM is a KEM in the sense that it creates an (decapsulation key, encapsulation key) pair, such that anyone can use the encapsulation key to establish a shared key with the holder of the decapsulation key. X-Wing-KEM is a general-purpose hybrid post-quantum KEM, combining x25519 and ML-KEM-768.

// NOTE: requires the `getrandom` feature is enabled
use x_wing::{
    XWingKem,
    kem::{Decapsulate, Encapsulate, Kem}
};

let (sk, pk) = XWingKem::generate_keypair();
let (ct, sk_sender) = pk.encapsulate();
let sk_receiver = sk.decapsulate(&ct);
assert_eq!(sk_sender, sk_receiver);

Re-exports§

pub use kem;

Structs§

CiphertextMessage
X-Wing ciphertext.
DecapsulationKey
X-Wing decapsulation key or private key.
EncapsulationKey
X-Wing encapsulation or public key.
InvalidKey
Error type for TryKeyInit for cases where the provided bytes do not correspond to a valid key.
XWingKem
X-Wing Key Encapsulation Method (X-Wing-KEM).

Constants§

CIPHERTEXT_SIZE
Size in bytes of the Ciphertext.
DECAPSULATION_KEY_SIZE
Size in bytes of the DecapsulationKey.
ENCAPSULATION_KEY_SIZE
Size in bytes of the EncapsulationKey.
ENCAPSULATION_RANDOMNESS_SIZE
Number of bytes necessary to encapsulate a key

Traits§

Decapsulate
Decapsulator for encapsulated keys, with an associated Encapsulator bounded by the Encapsulate trait.
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.
KeyExport
Serialize a key to a byte array.
KeyInit
Types which can be initialized from a key.
KeySizeUser
Types which use key for initialization.
TryKeyInit
Types which can be fallibly initialized from a key.

Type Aliases§

Ciphertext
Serialized ciphertext.
Key
Key used by KeySizeUser implementors.
SharedKey
Shared secret key.