tholos-pq

A pure Rust implementation of post-quantum multi-recipient encryption with a stable, versioned wire format.

Overview

tholos-pq provides a complete solution for encrypting messages to multiple recipients using post-quantum cryptographic algorithms. The library uses ML-KEM-1024 (Kyber-1024) for key encapsulation, XChaCha20-Poly1305 for symmetric encryption, and Dilithium-3 for sender authentication.

Features

• Multi-recipient encryption: Encrypt once for N recipients efficiently
• Post-quantum security: All cryptographic primitives are quantum-resistant
• Sender authentication: Verify sender identity using Dilithium-3 signatures
• Stable wire format: Versioned CBOR format for interoperability
• Pure Rust: No C dependencies, safe Rust throughout
• Comprehensive testing: Unit tests, integration tests, and property-based tests

Algorithm Suite

• Key Encapsulation: ML-KEM-1024 (Kyber-1024) for per-recipient key wrapping
• Symmetric Encryption: XChaCha20-Poly1305 for payload and CEK encryption
• Digital Signatures: Dilithium-3 for sender authentication
• Wire Format: Canonical CBOR with versioning (suite = Kyber1024+XChaCha20P1305+Dilithium3)

Installation

Add this to your Cargo.toml:

[dependencies]
tholos-pq = "0.1.0"

Usage

Basic Example

use tholos_pq::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Generate recipient keypairs
    let (pub_a, priv_a) = gen_recipient_keypair("alice");
    let (pub_b, priv_b) = gen_recipient_keypair("bob");

    // Generate sender keypair
    let sender = gen_sender_keypair("server1");

    // Build allowed sender list
    let allowed = vec![(sender.sid.clone(), sender_pub(&sender).pk_dilithium)];

    // Encrypt message for multiple recipients
    let message = b"Hello, post-quantum world!";
    let wire = encrypt(message, &sender, &[pub_a.clone(), pub_b.clone()])?;

    // Each recipient can decrypt
    let decrypted_a = decrypt(&wire, "alice", &priv_a.sk_kyber, &allowed)?;
    let decrypted_b = decrypt(&wire, "bob", &priv_b.sk_kyber, &allowed)?;

    assert_eq!(decrypted_a, message);
    assert_eq!(decrypted_b, message);
    Ok(())
}

Multi-Recipient Encryption

use tholos_pq::*;

let sender = gen_sender_keypair("server1");
let (pub_a, priv_a) = gen_recipient_keypair("alice");
let (pub_b, priv_b) = gen_recipient_keypair("bob");
let (pub_c, priv_c) = gen_recipient_keypair("charlie");

let allowed = vec![(sender.sid.clone(), sender_pub(&sender).pk_dilithium)];

// Encrypt once for all three recipients
let wire = encrypt(
    b"Message for A, B, and C",
    &sender,
    &[pub_a.clone(), pub_b.clone(), pub_c.clone()]
)?;

// Each recipient can decrypt independently
let pt_a = decrypt(&wire, "alice", &priv_a.sk_kyber, &allowed)?;
let pt_b = decrypt(&wire, "bob", &priv_b.sk_kyber, &allowed)?;
let pt_c = decrypt(&wire, "charlie", &priv_c.sk_kyber, &allowed)?;

Sender Authentication

use tholos_pq::*;

let sender1 = gen_sender_keypair("server1");
let sender2 = gen_sender_keypair("server2");
let (pub_key, priv_key) = gen_recipient_keypair("recipient");

// Only allow sender1
let allowed = vec![(sender1.sid.clone(), sender_pub(&sender1).pk_dilithium)];

// Message from sender1 succeeds
let wire1 = encrypt(b"Hello", &sender1, &[pub_key.clone()])?;
let pt1 = decrypt(&wire1, "recipient", &priv_key.sk_kyber, &allowed)?;

// Message from sender2 is rejected
let wire2 = encrypt(b"Hello", &sender2, &[pub_key.clone()])?;
let result = decrypt(&wire2, "recipient", &priv_key.sk_kyber, &allowed);
assert!(matches!(result, Err(TholosError::BadSignature)));

API Reference

Key Generation

• gen_recipient_keypair(kid: &str) -> (RecipientPub, RecipientPriv): Generate a new ML-KEM-1024 keypair for a recipient
• gen_sender_keypair(sid: &str) -> SenderKeypair: Generate a new Dilithium-3 keypair for a sender
• sender_pub(sender: &SenderKeypair) -> SenderPub: Extract public key information from a sender keypair

Encryption and Decryption

• encrypt(plaintext: &[u8], sender: &SenderKeypair, recipients: &[RecipientPub]) -> Result<Vec<u8>, TholosError>: Encrypt a message for multiple recipients
• decrypt(wire_cbor: &[u8], my_kid: &str, my_sk: &<MlKem1024 as KemCore>::DecapsulationKey, allowed_senders: &[(String, Vec<u8>)]) -> Result<Vec<u8>, TholosError>: Decrypt a message as a recipient

Error Types

The TholosError enum includes:

• BadSignature: Signature verification failed or sender not allowed
• MissingEnvelope: No recipient envelope found for the specified recipient ID
• Malformed: A field in the wire format is malformed
• Aead: AEAD encryption or decryption operation failed
• Ser: CBOR serialization or deserialization error

Security Considerations

• All cryptographic operations use secure random number generation via OsRng
• Private keys should be stored securely and never exposed
• The allowed sender list must be managed carefully to prevent unauthorized access
• Wire formats should be validated before decryption
• This library provides cryptographic primitives; key management and distribution are the application's responsibility

Testing

The library includes comprehensive test coverage:

• Unit tests for individual functions
• Integration tests for round-trip encryption/decryption
• Property-based tests using proptest for correctness validation
• Error path testing for malformed inputs

Run tests with:

cargo test

Run property tests with:

cargo test --test property

Wire Format

The wire format is a versioned CBOR structure (BundleSigned) containing:

• Header: Version, suite identifier, sender ID, recipient IDs, message ID, timestamp
• Payload: Encrypted plaintext using XChaCha20-Poly1305
• Recipient Envelopes: Per-recipient ML-KEM ciphertexts and wrapped CEKs
• Signature: Dilithium-3 signature over the unsigned bundle

The format is designed for interoperability and includes versioning to support future algorithm updates.

Dependencies

• ml-kem: Pure Rust ML-KEM-1024 implementation
• pqcrypto-dilithium: Dilithium-3 signature implementation
• chacha20poly1305: XChaCha20-Poly1305 AEAD encryption
• serde_cbor: CBOR serialization
• hkdf: Key derivation

License

Licensed under the Apache License, Version 2.0.

Contributing

Contributions are welcome. Please ensure all tests pass and code follows Rust conventions.