MetaMUI Post-Quantum Cryptography Implementation Guide

Side-channel claim limit. Nothing on this page claims constant-time behaviour or side-channel resistance for any target: the side-channel harness covers nothing (finding A48) and no measurement exists. The Rust and C cores are designed for constant time and unmeasured; managed runtimes (JIT, GC, bounds checks) make no timing claim. Where this page names constant-time or side-channel techniques, in prose or in code, they are design intent or recommendations, not measured properties.

Overview

This document provides comprehensive guidance for implementing and using Post-Quantum Cryptographic (PQC) algorithms across all MetaMUI crypto primitive platforms. Our implementations follow NIST standardized algorithms to ensure quantum-resistant security.

Supported Algorithms

1. ML-KEM (Module Lattice Key Encapsulation Mechanism)

Standard: NIST FIPS 203
Purpose: Key encapsulation for secure key exchange
Security Levels:

2. ML-DSA (Module Lattice Digital Signature Algorithm)

Standard: NIST FIPS 204
Purpose: Digital signatures
Security Levels:

3. Falcon

Standard: Round 3 NIST PQC Finalist
Purpose: Digital signatures with compact size
Security Levels:

Platform-Specific Implementation Status

Rust (Reference Implementation)

// ML-KEM Example
use metamui_mlkem768::{MLKem768, generate_keypair, encapsulate, decapsulate};

let (pk, sk) = generate_keypair();
let (ct, ss1) = encapsulate(&pk);
let ss2 = decapsulate(&sk, &ct);
assert_eq!(ss1, ss2);

Status: ✅ Complete

Python

from metamui_crypto.mlkem768 import MLKem768

mlkem = MLKem768()
pk, sk = mlkem.keygen()
ct, ss1 = mlkem.encapsulate(pk)
ss2 = mlkem.decapsulate(sk, ct)
assert ss1 == ss2

Status: 🔧 In Progress

Go

import "github.com/SovereignWallet-Network/metamui-crypto-go/pqc/mlkem"

mlkem := mlkem.NewMLKEM768()
pk, sk, _ := mlkem.GenerateKeyPair()
ct, ss1, _ := mlkem.Encapsulate(pk)
ss2, _ := mlkem.Decapsulate(sk, ct)

Status: 🔧 In Progress

Java

import id.metamui.crypto.pqc.mlkem.MLKem768;

MLKem768 mlkem = new MLKem768();
MLKem768.KeyPair kp = mlkem.generateKeyPair();
MLKem768.EncapsulationResult result = mlkem.encapsulate(kp.getPublicKey());
byte[] sharedSecret = mlkem.decapsulate(kp.getSecretKey(), result.getCiphertext());

Status: 🔧 In Progress

TypeScript

import { MLKem768 } from '@metamui/mlkem';

const mlkem = new MLKem768();
const { publicKey, secretKey } = mlkem.generateKeyPair();
const { ciphertext, sharedSecret: ss1 } = mlkem.encapsulate(publicKey);
const ss2 = mlkem.decapsulate(secretKey, ciphertext);

Status: 🔧 In Progress

Swift

import MetaMUICryptoPQC

let (publicKey, secretKey) = MLKem768.generateKeyPair()
let (ciphertext, sharedSecret1) = MLKem768.encapsulate(publicKey: publicKey)
let sharedSecret2 = MLKem768.decapsulate(secretKey: secretKey, ciphertext: ciphertext)

Status: 🔧 In Progress

C

#include <metamui/mlkem.h>

mlkem768_keypair_t kp;
mlkem768_generate_keypair(&kp);

mlkem768_ciphertext_t ct;
uint8_t ss1[32], ss2[32];
mlkem768_encapsulate(&kp.public_key, &ct, ss1);
mlkem768_decapsulate(&kp.secret_key, &ct, ss2);

Status: 📋 Planned

Key Sizes and Performance

ML-KEM Parameters

| Variant | Public Key | Secret Key | Ciphertext | Shared Secret | |———|————|————|————|—————| | ML-KEM-512 | 800 bytes | 1,632 bytes | 768 bytes | 32 bytes | | ML-KEM-768 | 1,184 bytes | 2,400 bytes | 1,088 bytes | 32 bytes | | ML-KEM-1024 | 1,568 bytes | 3,168 bytes | 1,568 bytes | 32 bytes |

ML-DSA Parameters

| Variant | Public Key | Secret Key | Signature | |———|————|————|———–| | ML-DSA-44 | 1,312 bytes | 2,560 bytes | 2,420 bytes | | ML-DSA-65 | 1,952 bytes | 4,032 bytes | 3,309 bytes | | ML-DSA-87 | 2,592 bytes | 4,896 bytes | 4,627 bytes |

Falcon Parameters

| Variant | Public Key | Secret Key | Signature (avg) | |———|————|————|—————–| | Falcon-512 | 897 bytes | 1,281 bytes | 666 bytes | | Falcon-1024 | 1,793 bytes | 2,305 bytes | 1,280 bytes |

Security Considerations

1. Side-Channel Resistance

All implementations include countermeasures against:

2. Random Number Generation

3. Key Management

4. Hybrid Approaches

For transitional security, consider hybrid schemes:

Hybrid_KEM = Classical_ECDH + PQC_MLKEM
Hybrid_Signature = Classical_ECDSA + PQC_MLDSA

Testing and Validation

Cross-Platform Validation

Run the validation script to test all implementations:

python3 tests/validate_pqc_cross_platform.py

Test Vectors

Official test vectors are available in:

Performance Benchmarks

Run platform-specific benchmarks:

# Rust
cargo bench -p metamui-mlkem768

# TypeScript
npm run bench

# Go
go test -bench=. ./pqc/...

Migration from Classical Cryptography

Step 1: Assessment

Evaluate current cryptographic usage:

Step 2: Hybrid Implementation

Implement hybrid schemes first:

// Hybrid key exchange
let classical_secret = ecdh_exchange(classical_pk, classical_sk);
let pqc_secret = mlkem_encapsulate(pqc_pk);
let final_secret = kdf(classical_secret || pqc_secret);

Step 3: Full Migration

Transition to pure PQC when:

Common Pitfalls and Solutions

1. Incorrect Parameter Sets

Problem: Using incompatible key/ciphertext sizes
Solution: Always use predefined parameter sets

2. Seed Reuse

Problem: Reusing randomness in key generation
Solution: Use fresh random seeds for each keypair

3. Memory Leaks

Problem: Sensitive data remaining in memory
Solution: Implement secure memory clearing:

// Rust example
use zeroize::Zeroize;
secret_key.zeroize();

4. Incompatible Implementations

Problem: Different platforms producing incompatible outputs
Solution: Use standardized test vectors for validation

Future Roadmap

Q1 2025

Q2 2025

Q3 2025

Resources

Standards and Specifications

Implementation References

Security Analysis

Support

For questions or issues:

Last Updated: January 2025
Version: 1.0.0
Author: Phantom Seokgu Yun