A dependency-free, pure Java implementation of ML-KEM (FIPS 203, the module-lattice key encapsulation mechanism standardised by NIST) with an authenticated hybrid encryption layer and first-class Spring Boot support.
PostQuantum implements all three standardised parameter sets — ML-KEM-512, ML-KEM-768 and ML-KEM-1024 — and validates the implementation against the official NIST ACVP test vectors. It has no runtime dependencies beyond the JDK: no BouncyCastle, no native code, no JNI.
MlKem mlKem = MlKem.getInstance(MlKemParameterSet.ML_KEM_768);
MlKemKeyPair keyPair = mlKem.generateKeyPair();
MlKemEncapsulation encapsulation = mlKem.encapsulate(keyPair.publicKey());
byte[] sharedSecret = mlKem.decapsulate(keyPair.privateKey(), encapsulation.getCiphertext());- Why this library
- Features
- Requirements
- Installation
- Quick start: ML-KEM
- Encrypting data: the hybrid cipher
- Envelope format
- Spring Boot integration
- Security notes
- Performance
- Building and testing
- Releasing
- Project layout
- Compatibility
- Contributing
- License
ML-KEM is a key encapsulation mechanism, not a cipher. It produces a 32 byte shared secret that two parties can use, but it does not encrypt application data. Using it correctly means combining it with a symmetric authenticated cipher, deriving the key properly and binding the KEM ciphertext to the resulting key.
PostQuantum packages both pieces:
- a complete, readable implementation of FIPS 203 (
MlKem), and - a ready-to-use envelope cipher (
HybridCipher) built from ML-KEM + HKDF-SHA256 + AES-256-GCM,
plus a Spring Boot auto-configuration so applications can inject either one as a bean.
- All FIPS 203 parameter sets: ML-KEM-512, ML-KEM-768 and ML-KEM-1024.
- Validated against NIST ACVP vectors: key generation, encapsulation, decapsulation (including implicit rejection) and the encapsulation/decapsulation key checks — 240 test cases in total.
- Pure Java 17+: no external dependencies, no native libraries, no reflection tricks at runtime.
- Constant-time conscious: implicit rejection uses a branch-free mask, ciphertext comparison does not short-circuit, and secret buffers are wiped after use.
- Authenticated hybrid encryption: self-describing envelopes with AES-256-GCM, HKDF-SHA256, optional associated data and parameter-set binding.
- Spring Boot auto-configuration:
MlKemandHybridCipherbeans, externalised configuration, and an Actuator health indicator that runs a real crypto self-test. - Interoperable: keys and ciphertexts are the raw FIPS 203 encodings, deterministic key
generation is available from the 64 byte seed, and the test suite cross-checks both against the
ML-KEM implementation in JDK 24 and JDK 25 (
javax.crypto.KEM). - MIT licensed and documented for reuse.
| Component | Version |
|---|---|
| Java | 17 or newer |
| Spring Boot (optional) | 3.x for the beans, 4.x for the health indicator |
| Build | Maven 3.9+ or the bundled ./mvnw |
The ML-KEM core has no framework dependency at all; it can be used from plain Java, Jakarta EE,
Quarkus, Micronaut or any other runtime. Spring is only needed for the autoconfigure package and
is declared as an optional dependency, so it is never pulled in transitively.
The library is published as com.manalejandro:postquantum on Maven Central. Declare the
dependency:
Maven
<dependency>
<groupId>com.manalejandro</groupId>
<artifactId>postquantum</artifactId>
<version>0.1.1</version>
</dependency>Gradle
implementation("com.manalejandro:postquantum:0.1.1")To build from source instead, clone the repository and install it into your local repository:
git clone https://github.com/manalejandro/postquantum.git
cd postquantum
./mvnw installBecause the artifact is a library, do not add spring-boot-maven-plugin to it; the jar contains
no Main-Class and is meant to be consumed as a normal dependency.
import com.manalejandro.postquantum.core.MlKem;
import com.manalejandro.postquantum.core.MlKemKeyPair;
import com.manalejandro.postquantum.core.MlKemParameterSet;
MlKem mlKem = MlKem.getInstance(MlKemParameterSet.ML_KEM_768);
MlKemKeyPair keyPair = mlKem.generateKeyPair();
byte[] publicKey = keyPair.publicKey().getEncoded(); // 1184 bytes, publish this
byte[] privateKey = keyPair.privateKey().getEncoded(); // 2400 bytes, keep this secretKeys are plain FIPS 203 encodings. They can be persisted, sent over the wire or stored in a
keystore; wrap them again with MlKemPublicKey.fromEncoded(...) and
MlKemPrivateKey.fromEncoded(...) when you need them back.
// Sender: derive a secret for the owner of the public key
MlKemEncapsulation encapsulation = mlKem.encapsulate(keyPair.publicKey());
byte[] ciphertext = encapsulation.getCiphertext(); // 1088 bytes for ML-KEM-768
byte[] senderSecret = encapsulation.getSharedSecret();
// Receiver: recover the same secret
byte[] receiverSecret = mlKem.decapsulate(keyPair.privateKey(), ciphertext);The shared secret is 32 bytes. Treat it as opaque key material and feed it into a KDF before
using it with a symmetric cipher — or let HybridCipher do that for you.
| Parameter set | NIST category | Public key | Private key | Ciphertext | Shared secret |
|---|---|---|---|---|---|
ML_KEM_512 |
1 | 800 B | 1632 B | 768 B | 32 B |
ML_KEM_768 |
3 | 1184 B | 2400 B | 1088 B | 32 B |
ML_KEM_1024 |
5 | 1568 B | 3168 B | 1568 B | 32 B |
ML-KEM-768 is the recommended default: it matches the security level of AES-192 and is the
parameter set used by most deployed protocols. Use ML-KEM-1024 when you need the highest
margin, and ML-KEM-512 only for constrained environments or legacy compatibility.
FIPS 203 mandates implicit rejection: when a ciphertext does not decrypt to a valid
encapsulation, the implementation does not fail — it returns a pseudorandom secret derived from
the rejection value z and the ciphertext. This prevents an attacker from using decapsulation
failures as an oracle.
byte[] tampered = encapsulation.getCiphertext();
tampered[0] ^= 0x01;
// Returns a deterministic but unrelated 32 byte secret; it does not throw.
byte[] secret = mlKem.decapsulate(keyPair.privateKey(), tampered);This means you must authenticate the result. HybridCipher does that with AES-GCM: a
tampered envelope fails with HybridDecryptionException.
IllegalArgumentException is reserved for structurally invalid input: a ciphertext of the wrong
length, a key from another parameter set, or a key that fails the FIPS 203 modulus/hash checks.
Use MlKem#isValidEncapsulationKey and MlKem#isValidDecapsulationKey to validate untrusted
key material before using it.
Keys and ciphertexts are the raw FIPS 203 byte strings, so any conforming implementation can
exchange them. MlKem#generateKeyPair(byte[]) also accepts the 64 byte FIPS 203 seed (d || z),
which is what you need to import a key from a KMS, restore a backup or replay a test vector:
MlKemKeyPair keyPair = mlKem.generateKeyPair(seed); // 64 bytes: d followed by zThe JDK changed how it stores ML-KEM private keys between releases. Java 24 wraps the expanded
decapsulation key in the PKCS#8 structure, so its trailing bytes can be passed straight to
MlKemPrivateKey.fromEncoded. Java 25 wraps the 64 byte seed instead; hand that seed to
generateKeyPair to rebuild the pair. Public keys did not change: the trailing
encapsulationKeyLength() bytes of the X.509 encoding are the raw encapsulation key.
HybridCipher turns ML-KEM into authenticated public key encryption:
import com.manalejandro.postquantum.hybrid.HybridCipher;
HybridCipher cipher = HybridCipher.forParameterSet(MlKemParameterSet.ML_KEM_768);
MlKemKeyPair keyPair = cipher.generateKeyPair();
byte[] envelope = cipher.encrypt(keyPair.publicKey(), "attack at dawn".getBytes(UTF_8));
byte[] plaintext = cipher.decrypt(keyPair.privateKey(), envelope);Associated data is authenticated but not encrypted, which is useful for binding an envelope to a tenant, a message id or a protocol version:
byte[] aad = "tenant-42".getBytes(UTF_8);
byte[] envelope = cipher.encrypt(keyPair.publicKey(), payload, aad);
// Decryption only succeeds with the exact same associated data.
byte[] payload = cipher.decrypt(keyPair.privateKey(), envelope, aad);Any modification to the header, the KEM ciphertext, the AES-GCM ciphertext, the tag or the
associated data is detected and reported as HybridDecryptionException.
Useful helpers:
HybridCipher.isEnvelope(bytes); // magic check
HybridCipher.inspectParameterSet(bytes); // route without a private key
HybridCipher.envelopeLength(MlKemParameterSet.ML_KEM_768, 42); // 18 + 1088 + 42 + 16HybridCipher instances are stateless apart from their SecureRandom and are safe for
concurrent use.
offset size field
------ ---- ---------------------------------------------------------------
0 4 magic: "PQH1" (0x50 0x51 0x48 0x01), the last byte is the version
4 1 parameter set id: 1 = ML-KEM-512, 2 = ML-KEM-768, 3 = ML-KEM-1024
5 1 reserved flags, must be 0
6 12 AES-GCM nonce, fresh for every envelope
18 n ML-KEM ciphertext (768, 1088 or 1568 bytes)
18+n m AES-256-GCM ciphertext followed by the 16 byte authentication tag
The first 18 bytes are passed to AES-GCM as associated data, so the parameter set id and the nonce are authenticated. The ML-KEM ciphertext is used as the HKDF salt, which binds the derived AES key to it; tampering with the KEM ciphertext therefore changes the key and the tag check fails.
Key derivation:
shared_secret = ML-KEM.Decaps(dk, kem_ciphertext)
aes_key = HKDF-SHA256(ikm = shared_secret,
salt = kem_ciphertext,
info = "postquantum-hybrid-v1:" + parameter_set_name,
length = 32)
plaintext = AES-256-GCM-Decrypt(aes_key, nonce, aad = header, ciphertext)
The format is versioned through the magic bytes; future revisions will use a different version byte rather than silently changing the layout.
The auto-configuration registers the following beans when they are not already defined:
| Bean | Type | Description |
|---|---|---|
mlKem |
MlKem |
ML-KEM instance for the configured parameter set |
hybridCipher |
HybridCipher |
Envelope cipher backed by mlKem |
mlKemHealthIndicator |
MlKemHealthIndicator |
Actuator health check (optional) |
postquantum:
enabled: true # false disables every bean
parameter-set: ML-KEM-768 # ML-KEM-512, ML-KEM-768 or ML-KEM-1024
health-indicator-enabled: true| Property | Default | Description |
|---|---|---|
postquantum.enabled |
true |
Master switch for the auto-configuration |
postquantum.parameter-set |
ML-KEM-768 |
Parameter set used by the beans |
postquantum.health-indicator-enabled |
true |
Registers the Actuator health indicator |
Relaxed names are accepted, so ML_KEM_768, ml-kem-768 and mlkem768 all work.
@Service
public class MessageService {
private final HybridCipher cipher;
private final MlKemKeyPair keyPair; // load or generate your own key pair
public MessageService(HybridCipher cipher) {
this.cipher = cipher;
this.keyPair = cipher.generateKeyPair();
}
public byte[] seal(byte[] payload) {
return cipher.encrypt(keyPair.publicKey(), payload);
}
}Declare your own bean and the auto-configuration backs off:
@Configuration
class CryptoConfiguration {
@Bean
MlKem mlKem() {
return MlKem.getInstance(MlKemParameterSet.ML_KEM_1024);
}
}When Spring Boot Actuator is on the classpath, mlKemHealthIndicator runs a complete round trip
on every health check: key generation, encapsulation, decapsulation and a hybrid
encrypt/decrypt. It reports UP with the parameter set and key sizes, or DOWN with the reason.
This catches broken or restricted JCE providers before the first real request fails.
The indicator is built on the Spring Boot 4 health API (org.springframework.boot.health).
On Spring Boot 3.x the beans are still auto-configured, but the indicator is not registered.
- Not a FIPS validated module. The implementation follows FIPS 203 and passes the NIST ACVP vectors, but it has not been submitted to the NIST CMVP programme. If you need a validated module, use a certified provider.
- Constant-time behaviour is a best effort on the JVM. The implementation avoids secret-dependent branches and table lookups in the decapsulation path, but the JIT can introduce optimisations that a native implementation would not. For the strongest side-channel guarantees, use a native provider.
- Randomness matters. Key generation and encapsulation use
SecureRandom. Do not inject a predictableSecureRandomin production; the overloads that accept one exist for testing and for integration with HSM-backed sources. - ML-KEM alone is not encryption. Always combine it with an authenticated cipher (as
HybridCipherdoes) and always authenticate the derived key. - This is not a classical/post-quantum hybrid.
HybridCiphercombines ML-KEM with HKDF-SHA256 and AES-256-GCM; it does not perform an X25519 or ECDH exchange. Its security rests on ML-KEM and AES-256-GCM alone. If your threat model requires defence in depth against a future break of ML-KEM, add a classical KEM at the protocol layer. - Key management is your responsibility. Private keys are returned as raw bytes. Store them
encrypted, rotate them, and never log them.
toString()implementations redact key material and shared secrets. - Imported keys are validated.
MlKemPublicKey.fromEncodedandMlKemPrivateKey.fromEncodedrun the FIPS 203 input checks (length, modulus check and, for decapsulation keys, the hash check) and reject malformed keys withIllegalArgumentException. - Envelope size. ML-KEM public keys and ciphertexts are large. Budget roughly 1.2 KB of overhead per envelope for ML-KEM-768 (18 byte header + 1088 byte KEM ciphertext + 16 byte tag) before the payload.
Please report security issues privately as described in SECURITY.md.
Indicative throughput on a modern x86-64 machine (OpenJDK 24, single thread, after JIT warm-up):
| Parameter set | Key generation | Encapsulation | Decapsulation | Hybrid decrypt (1 KiB) |
|---|---|---|---|---|
| ML-KEM-512 | ~13,000 ops/s | ~12,000 ops/s | ~9,100 ops/s | ~8,400 ops/s |
| ML-KEM-768 | ~8,900 ops/s | ~8,000 ops/s | ~6,000 ops/s | ~5,700 ops/s |
| ML-KEM-1024 | ~5,900 ops/s | ~5,500 ops/s | ~4,200 ops/s | ~4,100 ops/s |
Treat these as orders of magnitude, not benchmarks: results depend on the CPU, the JDK version and the JIT. For context, ML-KEM-768 encapsulation costs a fraction of a millisecond, so per-request key establishment is usually cheaper than the network round trip that carries it.
./mvnw verify # compile, run all tests and package the jar
./mvnw test # tests only
./mvnw -DskipTests packageThe test suite contains:
AcvpMlKemTest— 240 official NIST ACVP cases for key generation, encapsulation, decapsulation and key validation.KeccakTest— SHA3-256, SHA3-512, SHAKE128 and SHAKE256 known-answer tests.HkdfTest— RFC 5869 HKDF-SHA256 test vectors.MlKemTest— public API behaviour, implicit rejection, input validation, immutability.HybridCipherTest— round trips, tamper detection, AAD binding, envelope parsing.JdkMlKemInteropTest— cross-checks raw keys and ciphertexts against the ML-KEM implementation in JDK 24 and JDK 25 (javax.crypto.KEM), covering both private key encodings (skipped on older JDKs).PostQuantumAutoConfigurationTestandMlKemHealthIndicatorTest— Spring wiring, property binding, bean back-off and health reporting.
The ACVP vectors live in src/test/resources/acvp/ml-kem-fips203.json.gz and can be regenerated
with python3 tools/fetch-acvp-vectors.py.
Releases are cut from a tag and published by the Release workflow. It signs every artifact with
GPG, deploys the bundle to Maven Central through the Sonatype Central Portal, waits for Central to
accept it, and then creates the GitHub release with the jars, the POM, their .asc signatures and
SHA256SUMS.
-
Bump
<version>inpom.xmland updateCHANGELOG.md. -
Commit and push
main, then create and push the tag:git tag -a v0.1.1 -m "PostQuantum 0.1.1" git push origin main git push origin v0.1.1 -
The workflow verifies that the tag matches the project version before doing anything else. It can also be re-run from the Actions tab with
workflow_dispatch, passing the tag as input.
The workflow expects four repository secrets:
| Secret | Purpose |
|---|---|
CENTRAL_USERNAME |
Sonatype Central Portal user token name |
CENTRAL_PASSWORD |
Sonatype Central Portal user token password |
GPG_PRIVATE_KEY |
ASCII-armored private key used to sign the artifacts |
TOKEN |
GitHub token used to create the release |
Add GPG_PASSPHRASE only if the signing key is protected; the plugin reads it from that variable
and falls back to an unprotected key. The public half of the signing key must be published on a
keyserver (keys.openpgp.org or keyserver.ubuntu.com) for Central to validate the signatures.
To reproduce a release locally, with the key in your keyring and the central server credentials
in ~/.m2/settings.xml:
./mvnw -Pcentral clean deploy -Dgpg.keyname=<fingerprint>The central profile is opt-in, so a plain ./mvnw verify never needs a signing key.
src/main/java/com/manalejandro/postquantum/
├── core/ public ML-KEM API (MlKem, keys, parameter sets)
│ └── internal/ FIPS 203 primitives (Keccak, NTT, sampling, encoding, K-PKE)
├── hybrid/ HybridCipher, HKDF, decryption exception
├── autoconfigure/ Spring Boot auto-configuration and properties
└── health/ Actuator health indicator
The internal package is an implementation detail and is not part of the public API. It is
public only so that tests can reach deterministic entry points; do not depend on it.
| Java 17 | Java 21 | Java 24+ | |
|---|---|---|---|
| ML-KEM core | ✅ | ✅ | ✅ |
| Spring auto-configuration | ✅ (Boot 3.x / 4.x) | ✅ | ✅ |
| Actuator health indicator | ✅ (Boot 4.x) | ✅ | ✅ |
| JDK interop test | skipped | skipped | ✅ |
The core library is framework agnostic. The auto-configuration works with Spring Boot 3.x and
4.x; the Actuator health indicator uses the Spring Boot 4 health API
(org.springframework.boot.health) and is only registered when that API is present. On Spring
Boot 3.x the beans are still created, and you can add your own health indicator against the
org.springframework.boot.actuate.health API if you need one.
Issues and pull requests are welcome. Please:
- Keep the code dependency-free and Java 17 compatible.
- Add tests for every behavioural change; cryptographic changes must keep the ACVP suite green.
- Run
./mvnw verifybefore opening a pull request. - Follow the existing style: no wildcard imports, explicit null checks at API boundaries, and Javadoc on every public type and method.
MIT — see LICENSE. Copyright (c) 2026 manalejandro.