Have you ever wondered how to protect your data from future quantum computers? What if I told you there's a way to encrypt messages that even quantum computers can't break?
In this beginner-friendly tutorial, we'll explore ML-KEM (Module-Lattice Key Encapsulation Mechanism), a quantum-resistant encryption algorithm that's becoming the new standard for secure communication. By the end of this guide, you'll understand what ML-KEM is, how it works, and how to use it in your own applications.
What is ML-KEM?
ML-KEM (formerly known as CRYSTALS-Kyber) is a post-quantum cryptographic algorithm standardized by NIST (National Institute of Standards and Technology). It's designed to be secure against attacks from both classical computers and quantum computers.
Why Do We Need Quantum-Resistant Encryption?
Most encryption algorithms used today (like RSA and ECC) rely on mathematical problems that are hard for classical computers but easy for quantum computers to solve. When quantum computers become powerful enough, they could break current encryption methods.
ML-KEM solves this problem by using mathematical structures (lattices) that are believed to be hard for both classical and quantum computers to break.
Key Concepts for Beginners
Before we dive into code, let's understand a few key concepts:
-
Key Encapsulation Mechanism (KEM): Instead of directly encrypting data, ML-KEM creates a shared secret key that can then be used with symmetric encryption (like AES).
-
Public Key vs Private Key:
- Public key: Anyone can use this to encrypt messages to you (like a mailbox address)
- Private key: Only you have this, and you use it to decrypt messages (like a mailbox key)
-
Encapsulation: The process of creating an encrypted "package" containing a shared secret key
-
Decapsulation: The process of extracting the shared secret key from the encrypted package
How ML-KEM Works: The Big Picture
Here's a simplified overview of how ML-KEM encryption works:
Getting Started: Installation
To use ML-KEM in your JavaScript/TypeScript project, you'll need the ML-KEM library. In our implementation, we use @hpke/ml-kem:
Step-by-Step Tutorial
Let's walk through a complete example of using ML-KEM, step by step.
Step 1: Generate a Key Pair
First, we need to generate a public/private key pair. The public key can be shared with anyone, while the private key must be kept secret.
import { MlKem768 } from "@hpke/ml-kem";
const kem = new MlKem768();
const keyPair = await kem.generateKeyPair();
console.log("Public key:", keyPair.publicKey);
console.log("Private key:", keyPair.privateKey);
What's happening here?
MlKem768 creates an ML-KEM instance using the 768-bit security level (equivalent to AES-192)generateKeyPair() creates two keys:
- Public key: 1184 bytes - safe to share publicly
- Private key: 64 bytes - must be kept secret
Step 2: Encrypt a Message
Now let's encrypt a message using the public key. In ML-KEM, we don't encrypt the message directly. Instead, we:
- Create a shared secret using the public key (encapsulation)
- Use that shared secret to encrypt the message with AES-GCM
import { MLKEMCipherLayer } from "cryptography/CascadingCipher";
const layer = new MLKEMCipherLayer();
const message = "Hello, Quantum-Resistant World!";
const plaintext = new TextEncoder().encode(message);
const encrypted = await layer.encrypt(plaintext, {
publicKey: keyPair.publicKey
});
console.log("Encrypted:", encrypted);
What's in the encrypted result?
ciphertext: The encrypted message (AES-GCM encrypted)parameters.encapsulated: The ML-KEM encapsulated key (1088 bytes)parameters.iv: Initialization vector for AES (12 bytes)parameters.salt: Salt for key derivation (16 bytes)
Step 3: Decrypt the Message
To decrypt, we use the private key to extract the shared secret, then use it to decrypt the message:
const decrypted = await layer.decrypt(encrypted, {
privateKey: keyPair.privateKey
});
const decryptedMessage = new TextDecoder().decode(decrypted);
console.log("Decrypted:", decryptedMessage);
What's happening during decryption?
- ML-KEM extracts the shared secret from the encapsulated key using the private key (decapsulation)
- The shared secret is used to derive the AES key
- AES-GCM decrypts the ciphertext
- We get back the original message!
Complete Working Example
Here's a complete example that puts it all together:
import { MlKem768 } from "@hpke/ml-kem";
import { MLKEMCipherLayer } from "cryptography/CascadingCipher";
async function mlkemExample() {
console.log("🔑 Generating ML-KEM key pair...");
const kem = new MlKem768();
const keyPair = await kem.generateKeyPair();
console.log("✅ Key pair generated!");
console.log(` Public key size: ${keyPair.publicKey.key.length} bytes`);
console.log(` Private key size: ${keyPair.privateKey.key.length} bytes`);
console.log("\n🔒 Encrypting message...");
const layer = new MLKEMCipherLayer();
const message = "This is a secret message!";
const plaintext = new TextEncoder().encode(message);
const encrypted = await layer.encrypt(plaintext, {
publicKey: keyPair.publicKey
});
console.log("✅ Message encrypted!");
console.log(` Encapsulated key size: ${encrypted.parameters.encapsulated.length} bytes`);
console.log(` Ciphertext size: ${encrypted.ciphertext.length} bytes`);
console.log("\n🔓 Decrypting message...");
const decrypted = await layer.decrypt(encrypted, {
privateKey: keyPair.privateKey
});
const decryptedMessage = new TextDecoder().decode(decrypted);
console.log("✅ Message decrypted!");
console.log(` Original: "${message}"`);
console.log(` Decrypted: "${decryptedMessage}"`);
if (decryptedMessage === message) {
console.log("\n🎉 Success! Round-trip encryption/decryption works perfectly!");
}
}
mlkemExample().catch(console.error);
Output:
🔑 Generating ML-KEM key pair...
✅ Key pair generated!
Public key size: 1184 bytes
Private key size: 64 bytes
🔒 Encrypting message...
✅ Message encrypted!
Encapsulated key size: 1088 bytes
Ciphertext size: 48 bytes
🔓 Decrypting message...
✅ Message decrypted!
Original: "This is a secret message!"
Decrypted: "This is a secret message!"
🎉 Success! Round-trip encryption/decryption works perfectly!
Understanding the Encryption Process in Detail
Let's break down what happens under the hood when you encrypt with ML-KEM:
1. Key Encapsulation (Encryption Side)
const { sharedSecret, enc } = await kem.encap({
recipientPublicKey: publicKey
});
const salt = crypto.getRandomValues(new Uint8Array(16));
const aesKey = await deriveAESKey(sharedSecret, salt);
const iv = crypto.getRandomValues(new Uint8Array(12));
const ciphertext = await aesGcmEncrypt(message, aesKey, iv);
2. Key Decapsulation (Decryption Side)
const sharedSecret = await kem.decap({
recipientKey: privateKey,
enc: encrypted.parameters.encapsulated
});
const aesKey = await deriveAESKey(sharedSecret, encrypted.parameters.salt);
const plaintext = await aesGcmDecrypt(
encrypted.ciphertext,
aesKey,
encrypted.parameters.iv
);
Understanding the sizes and performance characteristics helps you plan your application:
| Component | Size | Notes |
|---|
| Public Key | 1184 bytes (~1.16 KB) | Safe to share publicly |
| Private Key | 64 bytes | Must be kept secret |
| Encapsulated Key | 1088 bytes (~1.06 KB) | Sent with each encrypted message |
| Shared Secret | 64 bytes | Used to derive AES key |
Performance (typical values on modern hardware):
- Key generation: ~5-15ms
- Encryption (encapsulation): ~10-25ms
- Decryption (decapsulation): ~10-25ms
Real-World Use Cases
ML-KEM is perfect for:
- Long-term data storage: Encrypt data that needs to stay secure for years
- Secure messaging: Protect messages from future quantum attacks
- File encryption: Encrypt files with quantum-resistant security
- API security: Secure API communications with post-quantum cryptography
- IoT devices: Protect devices that will be in use for many years
Common Questions
Q: Why is ML-KEM called a "Key Encapsulation Mechanism"?
A: ML-KEM doesn't encrypt your data directly. Instead, it creates an encrypted "package" (encapsulation) containing a shared secret key. This shared secret is then used with symmetric encryption (AES) to actually encrypt your data. This two-step process is more efficient than encrypting large amounts of data directly with public-key cryptography.
Q: Is ML-KEM slower than RSA or ECC?
A: ML-KEM operations are generally faster than RSA but slightly slower than ECC. However, the security benefit against quantum computers makes it worth the small performance cost. For most applications, the difference is negligible.
Q: Can I use ML-KEM with existing encryption?
A: Yes! ML-KEM works great alongside traditional encryption. Many systems use "hybrid" encryption: ML-KEM for key exchange + AES for data encryption. This provides defense-in-depth security.
Q: How do I store the keys securely?
A:
- Public key: Can be stored anywhere (it's public!)
- Private key: Should be stored encrypted, ideally in a hardware security module (HSM) or secure key storage
const encryptedPrivateKey = await encryptKey(
privateKey.key,
userPassword
);
localStorage.setItem('mlkem_private_key', encryptedPrivateKey);
Security Best Practices
- Never share your private key: Keep it secret!
- Use secure random number generation: Always use
crypto.getRandomValues() for salts and IVs
- Validate inputs: Check that keys and messages are the correct size
- Handle errors securely: Don't leak information about why decryption failed
- Rotate keys periodically: Generate new key pairs periodically for long-term security
Interactive Demo: Try It Yourself
Try encrypting and decrypting your own messages with this interactive demo:
What's Next?
Now that you understand the basics of ML-KEM, you can:
-
Explore the implementation: Check out the ML-KEM cipher layer source code
-
Learn about cascading ciphers: ML-KEM can be combined with other encryption layers for defense-in-depth security. Read our cascading cipher tutorial
-
Try it in your project: Use ML-KEM in your own applications for quantum-resistant security
-
Read the NIST standard: Learn more about the official ML-KEM specification (FIPS 203)
Summary
In this tutorial, we've learned:
- ✅ What ML-KEM is: A quantum-resistant key encapsulation mechanism
- ✅ Why it's important: Protects against future quantum computer attacks
- ✅ How to use it: Generate keys, encrypt, and decrypt messages
- ✅ How it works: Key encapsulation + AES-GCM encryption
- ✅ Best practices: Security considerations and key management
ML-KEM is the future of secure encryption, and now you know how to use it! Whether you're building a messaging app, encrypting files, or securing API communications, ML-KEM provides the quantum-resistant security you need.
Have questions or want to learn more? Check out our cryptography repository or join our Discord community!
This tutorial is part of our ongoing research into post-quantum cryptography. For more technical deep-dives, check out our ML-KEM security audit documentation.
