Module pqxdh 

Post-Quantum Extended Diffie-Hellman (PQXDH) Protocol Implementation

This module provides a complete, high-level implementation of the PQXDH protocol for secure, post-quantum resistant communication. It includes both client and service provider functionality with automatic session management.

Core Components

1. Inbox Management

• Publishing: Service providers can publish PQXDH inboxes to advertise their availability
• Discovery: Clients can discover and fetch service provider inboxes
• Privacy: Uses type-safe protocols and deterministic serialization with postcard

2. Session Establishment

• Initiation: Clients can establish secure sessions with service providers
• Privacy-Preserving: Uses randomized channel IDs for unlinkable communication
• Post-Quantum Security: Leverages PQXDH for quantum-resistant key exchange

3. Message Communication

• Session Messages: Encrypted communication over established sessions
• Channel Management: Automatic subscription handling for session channels
• Sequence Numbers: Built-in replay protection with sequence numbering

4. State Management

• Persistence: Serializable state for application restarts
• Session Tracking: Automatic management of multiple concurrent sessions
• Key Management: Secure handling of private keys and prekey bundles

Usage Patterns

Service Provider Pattern

// 1. Create handler and publish service
let mut handler = PqxdhProtocolHandler::new(
    &messages_manager,
    &keypair,
    PqxdhInboxProtocol::EchoService
);
handler.publish_service(false).await?;

// 2. Listen for incoming client connections
let mut inbox_stream = Box::pin(handler.inbox_stream::<String>().await?);
while let Some((session_id, message)) = inbox_stream.next().await {
    // Handle client messages
    println!("Received from {:?}: {}", session_id, message);
}

Client Pattern

// 1. Create handler and connect to service
let mut handler = PqxdhProtocolHandler::new(
    &messages_manager,
    &keypair,
    PqxdhInboxProtocol::EchoService
);
let mut response_stream = Box::pin(handler.connect_to_service::<String, String>(
    &service_key,
    &initial_message
).await?);

// 2. Send additional messages using session ID
handler.send_message(&session_id, &"follow up message".to_string()).await?;

// 3. Listen for responses
while let Some(response) = response_stream.next().await {
    println!("Received response: {}", response);
}

Security Features

• Post-Quantum Resistance: Uses CRYSTALS-Kyber for key encapsulation
• Forward Secrecy: Each session uses ephemeral keys
• Replay Protection: Sequence numbers prevent message replay attacks
• Unlinkability: Randomized channel IDs prevent traffic analysis
• Authentication: All messages are cryptographically signed

Error Handling

This module uses a custom PqxdhError type that provides structured error handling for all PQXDH operations. The error type includes specific variants for different failure modes:

• Connection Errors: InboxNotFound, ServiceNotPublished, NoInboxSubscription
• Session Errors: SessionNotFound, InvalidSender, NotInitialMessage
• Cryptographic Errors: Crypto, KeyGeneration, PqxdhProtocol
• Message Errors: InvalidContentType, NotPqxdhMessage, MessageCreation
• Infrastructure Errors: Rpc, MessagesService, Serialization

Error Handling Example

match handler.publish_service(false).await {
    Ok(tag) => println!("Service published with tag: {:?}", tag),
    Err(PqxdhError::InboxAlreadyPublished) => {
        println!("Service already published, use force_overwrite=true");
    }
    Err(PqxdhError::KeyGeneration(msg)) => {
        eprintln!("Failed to generate keys: {}", msg);
    }
    Err(e) => eprintln!("Unexpected error: {}", e),
}

Serialization

All data structures use postcard for efficient binary serialization, providing compact wire formats and deterministic encoding for cryptographic operations. This ensures compatibility with the project’s binary-first architecture and optimal network efficiency.

Modules

error 🔒

handler 🔒

message_listener 🔒

session 🔒

state 🔒

transport 🔒

Structs

PqxdhMessageListener

PqxdhProtocolHandler

A complete PQXDH protocol handler that encapsulates all session management, key observation, subscription handling, and message routing logic.

PqxdhProtocolState

Serializable state for a PQXDH protocol handler

PqxdhTarpcTransport

A tarpc transport that uses PQXDH for message delivery

Enums

PqxdhError

Error type for PQXDH protocol operations

Traits

PqxdhTarpcTransportSender

Type Aliases

PqxdhSessionId

Result

Result type for PQXDH protocol operations