Skip to main content

Crate pq_mceliece

Crate pq_mceliece 

Source
Expand description

A pure Rust implementation of the Classic McEliece key encapsulation mechanism.

Every enabled parameter set is available at once. Unlike implementations that bake a single parameter set into the crate through cargo features, this crate makes choosing between mceliece348864 and mceliece8192128pcf a runtime decision.

§Usage

The straightforward path is Algorithm, which carries the parameter set as a value:

use pq_mceliece::Algorithm;
use rand::SeedableRng;
use rand::rngs::{StdRng, SysRng};

// A cryptographically secure generator, seeded once from the operating system.
let mut rng = StdRng::try_from_rng(&mut SysRng).unwrap();

let alg = Algorithm::McEliece348864f;
let (ek, dk) = alg.generate_keypair(&mut rng);
let (ct, sent) = alg.encapsulate(&ek, &mut rng).unwrap();
let received = alg.decapsulate(&dk, &ct).unwrap();

assert_eq!(sent, received);

Key generation is deterministic in a 32-byte seed, so a key pair can be reproduced from backed-up seed material:

use pq_mceliece::Algorithm;

// Any enabled parameter set works; `default` picks the first one.
let alg = Algorithm::default();
let seed = [0x42u8; 32];
let first = alg.generate_keypair_from_seed(seed).unwrap();
let second = alg.generate_keypair_from_seed(seed).unwrap();
assert_eq!(first, second);

When the parameter set is known at compile time, the hazmat layer offers the same operations with the parameter set in the type, so a key from one parameter set cannot be passed to another:

use pq_mceliece::hazmat::{Kem, McEliece348864};
use rand::SeedableRng;
use rand::rngs::{StdRng, SysRng};

let mut rng = StdRng::try_from_rng(&mut SysRng).unwrap();

let (ek, dk) = McEliece348864::generate_keypair(&mut rng);
let (ct, sent) = McEliece348864::encapsulate(&ek, &mut rng).unwrap();
let received = McEliece348864::decapsulate(&dk, &ct).unwrap();

assert_eq!(sent, received);

Implementations of the kem crate traits live in the kem module.

§Standards

parameter setsNIST round 4ISO
mceliece348864, mceliece348864fyesno
mceliece460896, mceliece6688128, mceliece6960119, mceliece8192128, and their f variantsyesyes
the pc and pcf variants of those four sizesnoyes

The pc parameter sets add plaintext confirmation: the ciphertext carries an extra 32-byte hash of the error vector, which decapsulation checks before deriving the session key. They are part of the ISO standard published in June 2026 and are not in the NIST submission.

Implementation choices follow the narrowly decoded reading of the specification: encapsulation keys and ciphertexts with nonzero padding bits are rejected rather than ignored. This only ever applies to mceliece6960119, the one standardized parameter set whose mt and k are not multiples of eight.

§Choosing a parameter set

Use Algorithm::RECOMMENDED (mceliece6960119f) unless something else decides for you. The Classic McEliece team recommends the mceliece6* sizes for long-term security, and the f variants generate keys faster while drawing them from the same distribution.

mceliece348864 is for research, testing, and interop only — not production. It exists because NIST asked for a Category 1 (lowest security floor) parameter set, and it has the thinnest security margin of the family: the team’s CryptAttackTester analysis puts the best known attacks — message recovery by information-set decoding — at about 2^150.59 bit operations, versus 2^190.50 for mceliece460896 and above 2^257 for the mceliece6* sizes. The ISO standard requires at least 128 bits of security in its quantum model, which assumes a square-root Grover speedup; mceliece348864 does not clear that bar and is excluded from the ISO standard, while mceliece460896 was admitted because Grover’s speedup is limited by attack latency. (Key-recovery attacks are not the concern: the team’s analysis finds them far slower than message recovery for every standardized set.)

In between, mceliece460896 (NIST Category 3, ISO-standardized) is the smallest production-appropriate set, and mceliece8192128 trades a larger key for power-of-two dimensions and no padding. The pc variants add plaintext confirmation where a protocol requires it.

§Conformance

Every NIST parameter set is checked bit for bit against the published kat_kem.rsp known answer tests. See CONFORMANCE.md for what is verified and how.

§Features

Parameter sets and operations are selected independently.

Each parameter set has its own feature, and the nist, iso and pc groups enable the corresponding sets.

The three operations are keygen, encapsulate and decapsulate. At least one must be enabled, and a build only carries the code and dependencies the enabled ones reach. Encapsulation is by far the lightest: Encode is pure bit manipulation over the public key, so an encapsulate-only build contains no field arithmetic, no polynomial arithmetic, no matrix reduction, no sorting networks and no Beneš network.

featureeffect
keygenKeyGen and SeededKeyGen, and recovering a public key from a private one
encapsulateEncap
decapsulateDecap
kemthe kem crate traits; implies all three operations
serdeserialization for every value type
hazmatmakes the low-level layer public

Modules§

hazmat
⚠️ Low-level “hazmat” Classic McEliece API.
kem
Implementations of the traits from the kem crate.

Structs§

AlgorithmParams
The parameters underlying an Algorithm.
Ciphertext
A Classic McEliece ciphertext.
DecapsulationKey
A Classic McEliece decapsulation (private) key.
EncapsulationKey
A Classic McEliece encapsulation (public) key.
PreparedDecapsulationKey
A DecapsulationKey with the message-independent part of decoding already computed.
SharedSecret
A Classic McEliece shared secret.

Enums§

Algorithm
A Classic McEliece parameter set, selected at run time.
Error
The errors that can occur when using Classic McEliece.

Type Aliases§

McElieceResult
The result type for Classic McEliece.