2 posts tagged with "ml-kem"

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:

1. 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).

2. 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)

3. Encapsulation: The process of creating an encrypted "package" containing a shared secret key

4. 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:

npm install @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";

// Create an ML-KEM instance
const kem = new MlKem768();

// Generate a key pair
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:

1. Create a shared secret using the public key (encapsulation)
2. Use that shared secret to encrypt the message with AES-GCM

import { MLKEMCipherLayer } from "cryptography/CascadingCipher";

// Create the ML-KEM cipher layer
const layer = new MLKEMCipherLayer();

// The message we want to encrypt
const message = "Hello, Quantum-Resistant World!";
const plaintext = new TextEncoder().encode(message);

// Encrypt using the public key
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:

// Decrypt using the private key
const decrypted = await layer.decrypt(encrypted, {
  privateKey: keyPair.privateKey
});

// Convert back to text
const decryptedMessage = new TextDecoder().decode(decrypted);
console.log("Decrypted:", decryptedMessage);
// Output: "Hello, Quantum-Resistant World!"

What's happening during decryption?

1. ML-KEM extracts the shared secret from the encapsulated key using the private key (decapsulation)
2. The shared secret is used to derive the AES key
3. AES-GCM decrypts the ciphertext
4. 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() {
  // Step 1: Generate key pair
  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`);

  // Step 2: Encrypt a message
  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`);

  // Step 3: Decrypt the message
  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}"`);
  
  // Verify they match
  if (decryptedMessage === message) {
    console.log("\n🎉 Success! Round-trip encryption/decryption works perfectly!");
  }
}

// Run the example
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)​

// When you call layer.encrypt():
// Step 1: ML-KEM encapsulation
const { sharedSecret, enc } = await kem.encap({
  recipientPublicKey: publicKey
});
// Result: sharedSecret (64 bytes) + enc (1088 bytes)

// Step 2: Derive AES key from shared secret
const salt = crypto.getRandomValues(new Uint8Array(16));
const aesKey = await deriveAESKey(sharedSecret, salt);

// Step 3: Encrypt message with AES-GCM
const iv = crypto.getRandomValues(new Uint8Array(12));
const ciphertext = await aesGcmEncrypt(message, aesKey, iv);

// Final result:
// - ciphertext: encrypted message
// - encapsulated: enc (1088 bytes)
// - salt: for key derivation
// - iv: for AES-GCM

2. Key Decapsulation (Decryption Side)​

// When you call layer.decrypt():
// Step 1: ML-KEM decapsulation
const sharedSecret = await kem.decap({
  recipientKey: privateKey,
  enc: encrypted.parameters.encapsulated
});
// Result: sharedSecret (64 bytes) - same as encryption!

// Step 2: Derive AES key (same process as encryption)
const aesKey = await deriveAESKey(sharedSecret, encrypted.parameters.salt);

// Step 3: Decrypt message with AES-GCM
const plaintext = await aesGcmDecrypt(
  encrypted.ciphertext, 
  aesKey, 
  encrypted.parameters.iv
);

Key Sizes and Performance​

Understanding the sizes and performance characteristics helps you plan your application:

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:

1. Long-term data storage: Encrypt data that needs to stay secure for years
2. Secure messaging: Protect messages from future quantum attacks
3. File encryption: Encrypt files with quantum-resistant security
4. API security: Secure API communications with post-quantum cryptography
5. 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

// Example: Store private key encrypted
const encryptedPrivateKey = await encryptKey(
  privateKey.key, 
  userPassword
);
localStorage.setItem('mlkem_private_key', encryptedPrivateKey);

Security Best Practices​

1. Never share your private key: Keep it secret!
2. Use secure random number generation: Always use crypto.getRandomValues() for salts and IVs
3. Validate inputs: Check that keys and messages are the correct size
4. Handle errors securely: Don't leak information about why decryption failed
5. 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:

1. Explore the implementation: Check out the ML-KEM cipher layer source code

2. Learn about cascading ciphers: ML-KEM can be combined with other encryption layers for defense-in-depth security. Read our cascading cipher tutorial

3. Try it in your project: Use ML-KEM in your own applications for quantum-resistant security

4. 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.

⚠️ NOTE: This is an experimental implementation for testing purposes. Post-quantum cryptography is an active area of research. While ML-KEM is a NIST standard, this JavaScript implementation has not undergone formal security audits. Use responsibly.

We're excited to announce that our P2P messaging application now supports quantum-resistant encryption using ML-KEM (CRYSTALS-Kyber), a NIST-standardized post-quantum key encapsulation mechanism. This addition brings quantum-resistant security to our cascading cipher system, providing protection against future quantum computing attacks.

What is Post-Quantum Cryptography?​

Quantum computers pose a significant threat to current public-key cryptography. While quantum computers are still in early stages, they could eventually break widely used algorithms like RSA, ECC (Elliptic Curve Cryptography), and Diffie-Hellman using Shor's algorithm. Quantum-resistant cryptography uses mathematical problems that quantum computers struggle to solve.

Current Vulnerabilities​

🔴 Vulnerable to Quantum Attacks:

• RSA (Shor's algorithm)
• Elliptic Curve Cryptography (Shor's algorithm)
• Diffie-Hellman key exchange (Shor's algorithm)

🟢 Quantum-Resistant:

• AES-256 (Grover's algorithm only reduces to AES-128 equivalent)
• SHA-256/SHA-3 (quantum advantage limited)
• ML-KEM (CRYSTALS-Kyber) - Lattice-based KEM
• ML-DSA (CRYSTALS-Dilithium) - Lattice-based signatures

The ML-KEM (CRYSTALS-Kyber) Standard​

ML-KEM (Modular Lattice-based Key Encapsulation Mechanism) is one of the first post-quantum algorithms standardized by NIST in 2024. It's designed as a key encapsulation mechanism (KEM) rather than direct encryption, making it ideal for establishing shared secrets between parties.

📚 Learn More:

• Crash Course: ML-KEM Beginner Tutorial - Quick introduction to ML-KEM concepts
• In-Depth Tutorial: ML-KEM Research Tutorial - Comprehensive technical deep dive

Key Properties:

• ⚡ Fast: ~30-50ms for key encapsulation/decapsulation
• 📦 Compact: 1184-byte public keys, 1088-byte encapsulated keys
• 🔒 Security: Based on Learning With Errors (LWE) problem
• 🎯 Standard: NIST FIPS 203 compliant
• 🌐 Pure JavaScript: No native dependencies

Integration with Cascading Cipher​

The ML-KEM implementation is integrated as a cipher layer in our cascading cipher architecture:

import {
  CascadingCipherManager,
  MLSCipherLayer,
  SignalCipherLayer,
  AESCipherLayer,
  MLKEMCipherLayer,  // New post-quantum layer
} from 'cryptography/CascadingCipher';

How It Works​

ML-KEM functions as a key exchange layer in the encryption cascade:

Encryption Flow:

1. ML-KEM Layer: Receiver's public key → encapsulated shared key
2. Signal Layer: Double Ratchet adds forward secrecy
3. MLS Group Layer: Group messaging support
4. AES Layer: Fast symmetric encryption

Why This Approach?​

Defense in Depth:

• ML-KEM protects against quantum attacks
• Signal Protocol provides forward secrecy
• MLS enables group messaging
• AES adds fast symmetric encryption

Each layer provides independent protection. If ML-KEM is broken, other layers still protect data.

Implementation Details​

ML-KEM Cipher Layer Architecture​

The MLKEMCipherLayer class implements the standard CipherLayer interface:

class MLKEMCipherLayer implements CipherLayer {
  readonly name = "ML-KEM-768";
  readonly version = "1.0.0";

  async encrypt(data: Uint8Array, keys: MLKEMKeys): Promise<EncryptedPayload>;
  async decrypt(payload: EncryptedPayload, keys: MLKEMKeys): Promise<Uint8Array>;
}

Key Properties​

• Public Key Size: 1184 bytes (for KEM-768 parameter set)
• Private Key Size: 64 bytes
• Encapsulated Key: 1088 bytes
• Shared Secret: 32-64 bytes (used as AES key material)

Security Features​

✅ Zeroization:

• All sensitive buffers are cleared after use
• Shared secrets, private keys, IVs are zeroized

✅ Timing Attack Protection:

• Constant-time key validation
• No early returns in validation logic

✅ IV Reuse Protection:

• Tracks used IVs per public key
• Random IV generation with collision detection

✅ Input Validation:

• Maximum plaintext size: 10MB (prevents DoS)
• Strict parameter size checks

Example Usage​

import { MlKem768 } from '@hpke/ml-kem';
import { MLKEMCipherLayer } from 'cryptography/CascadingCipher';

// Generate ML-KEM key pair
const kem = new MlKem768();
const keyPair = await kem.generateKeyPair();

// Create cipher layer
const layer = new MLKEMCipherLayer();

// Encrypt plaintext
const plaintext = new TextEncoder().encode('Quantum-secure message!');
const encrypted = await layer.encrypt(plaintext, {
  publicKey: keyPair.publicKey
});

// Decrypt
const decrypted = await layer.decrypt(encrypted, {
  privateKey: keyPair.privateKey
});

console.log(new TextDecoder().decode(decrypted)); // "Quantum-secure message!"

Module Federation Integration​

The cryptography module is exposed via module federation for import in the P2P application:

// cryptography/webpack.config.js
module.exports = {
  // Module federation config
  name: 'cryptography',
  exposes: {
    './CascadingCipher': './src/crypto/CascadingCipher/index.ts',
    './MLKEMUtils': './src/crypto/MLKEMUtils.ts',
    // ... other exports
  }
};

The P2P app imports via remote:

// p2p/webpack.config.js
module.exports = {
  remotes: {
    cryptography: 'cryptography@http://localhost:8083/remoteEntry.js'
  }
};

Storybook Examples​

Interactive Storybook stories demonstrate ML-KEM functionality:

• MLKEMBeginnerTutorial.stories.js - Step-by-step ML-KEM basics
• MLKEMDemo.stories.js - Real encryption/decryption examples
• MLKEMTimingTests.stories.js - Performance benchmarks

Try the Live Demo:

• ML-KEM Standalone Demo - Interactive encryption/decryption playground

Examples available at:

• ML-KEM Demo Story: https://cryptography.positive-intentions.com/?path=/story/cascading-cipher-ml-kem-demo--mlkem-standalone
• P2P Messaging Demo: https://p2p.positive-intentions.com/iframe.html?globals=&id=demo-p2p-messaging--p-2-p-messaging&viewMode=story

Performance Characteristics​

Encryption Benchmarks:

• Key Generation: ~10-15ms
• Encapsulation: ~15-25ms
• Decapsulation: ~15-25ms
• Total Operation: ~30-50ms

Overhead Analysis:

• Message Size: Adds ~1100 bytes (encapsulated key + IV + salt)
• Processing Time: +30-50ms compared to classical-only encryption
• Memory: Minimal (key material cached)

Comparison: Classical vs Post-Quantum​

Security Considerations​

Current Status​

✅ Implemented:

• ML-KEM-768 key pair generation
• Key encapsulation/decapsulation
• Integration with cascading cipher
• Security hardening (zeroization, timing protection)

⚠️ Limitations:

• JavaScript implementation (not FIPS 140-2 validated)
• No formal security audit
• Experimental/educational use only
• Performance overhead vs classical algorithms

Recommendations​

✅ Suitable For:

• Long-term confidential data storage
• Future-proofing sensitive communications
• Experimental/educational projects
• Low-volume secure messaging

❌ Not Recommended For:

• Production without formal security review
• High-performance applications
• Regulatory compliance without validation

Future Roadmap​

Planned Enhancements:

1. ML-DSA Integration - Post-quantum digital signatures
2. Hybrid Key Exchange - Combine classical + post-quantum
3. FIPS 140-2 Validation - Formal certification
4. WASM Optimization - Improve performance
5. Multiple Parameter Sets - Support KEM-512/1024 variants
6. Self-Certified Public Keys - Simplified identity verification

Conclusion​

The addition of ML-KEM post-quantum cryptography brings quantum-resistant security to our P2P messaging platform. By integrating it within the cascading cipher architecture, we provide defense-in-depth protection against both classical and quantum attacks.

While this implementation is still experimental, it demonstrates that building quantum-resistant applications in JavaScript is feasible. As quantum computing capabilities evolve, having quantum-resistant layers in place positions the project for long-term security.

Resources​

• 🚀 Live Demo: ML-KEM Standalone Demo
• 📚 Crash Course: ML-KEM Beginner Tutorial
• 🔬 In-Depth Tutorial: ML-KEM Research Tutorial
• 💻 Code Examples: See the ML-KEM Storybook Demo and P2P Messaging Demo