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 sets | NIST round 4 | ISO |
|---|---|---|
mceliece348864, mceliece348864f | yes | no |
mceliece460896, mceliece6688128, mceliece6960119, mceliece8192128, and their f variants | yes | yes |
the pc and pcf variants of those four sizes | no | yes |
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.
| feature | effect |
|---|---|
keygen | KeyGen and SeededKeyGen, and recovering a public key from a private one |
encapsulate | Encap |
decapsulate | Decap |
kem | the kem crate traits; implies all three operations |
serde | serialization for every value type |
hazmat | makes the low-level layer public |
Modules§
- hazmat
- ⚠️ Low-level “hazmat” Classic McEliece API.
- kem
- Implementations of the traits from the
kemcrate.
Structs§
- Algorithm
Params - The parameters underlying an
Algorithm. - Ciphertext
- A Classic McEliece ciphertext.
- Decapsulation
Key - A Classic McEliece decapsulation (private) key.
- Encapsulation
Key - A Classic McEliece encapsulation (public) key.
- Prepared
Decapsulation Key - A
DecapsulationKeywith the message-independent part of decoding already computed. - Shared
Secret - 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§
- McEliece
Result - The result type for Classic McEliece.