Crate paseto_pq 

PASETO-PQ: Post-Quantum PASETO Tokens

A pure post-quantum implementation of PASETO-inspired tokens using ML-DSA (CRYSTALS-Dilithium) for digital signatures. This crate provides quantum-safe authentication tokens that are resistant to attacks by quantum computers.

Design Principles

• Post-Quantum Only: Uses ML-DSA-65 (NIST FIPS 204) for all signatures
• PASETO-Inspired: Follows PASETO’s security model but with PQ algorithms
• Greenfield: No legacy compatibility, designed for quantum-safe future
• Memory Safety: Automatic zeroization of sensitive keys on drop
• Cryptographic Hygiene: Proper HKDF key derivation and secure random generation

⚠️ Non-Standard Token Format

IMPORTANT: This crate uses a non-standard token versioning scheme that diverges from the official PASETO specification. The tokens use pq1 to clearly indicate post-quantum algorithms and avoid confusion with standard PASETO versions.

Token Format

paseto.pq1.public.<base64url-encoded-payload>.<base64url-encoded-ml-dsa-signature>
paseto.pq1.local.<base64url-encoded-encrypted-payload>

Interoperability Warning

These tokens are NOT compatible with standard PASETO libraries or tooling. If you need interoperability with existing PASETO ecosystems, this crate is not suitable. The pq1 versioning scheme clearly indicates “post-quantum era” tokens, distinguishing them from the classical algorithms defined in the PASETO specification.

Consider this crate for:

• Greenfield applications requiring post-quantum security
• Internal systems where PASETO compatibility is not required
• Future migration paths when post-quantum PASETO standards emerge

Example Usage

use paseto_pq::{PasetoPQ, Claims, KeyPair};
use time::OffsetDateTime;

// Generate a new key pair
let mut rng = rand::thread_rng();
let keypair = KeyPair::generate(&mut rng);

// Create claims
let mut claims = Claims::new();
claims.set_subject("user123")?;
claims.set_issuer("my-service")?;
claims.set_audience("api.example.com")?;
claims.set_expiration(OffsetDateTime::now_utc() + time::Duration::hours(1))?;
claims.add_custom("tenant_id", "org_abc123")?;
claims.add_custom("roles", &["user", "admin"])?;

// Sign the token
let token = PasetoPQ::sign(keypair.signing_key(), &claims)?;

// Verify the token
let verified = PasetoPQ::verify(keypair.verifying_key(), &token)?;
let verified_claims = verified.claims();
assert_eq!(verified_claims.subject(), Some("user123"));

Re-exports

pub use pae::pae_encode;

Modules

pae

Pre-Authentication Encoding (PAE) for PASETO RFC compliance

Structs

Claims

Claims contained within a token

DecapsulationKey

A decapsulation key for ML-KEM key exchange

EncapsulationKey

An encapsulation key for ML-KEM key exchange

Footer

Footer data for additional authenticated metadata

KemKeyPair

A post-quantum key encapsulation key pair for key exchange

KeyPair

A post-quantum key pair for signing and verification

ParsedToken

Parsed token structure for inspection without cryptographic operations

PasetoPQ

Post-quantum PASETO implementation using ML-DSA-65

SigningKey

A signing key for creating tokens

SymmetricKey

A symmetric key for local token encryption/decryption

TokenSizeBreakdown

Token size breakdown showing individual components

TokenSizeEstimator

Token size estimator for planning and optimization

VerifiedToken

Verified token containing validated claims and optional footer

VerifyingKey

A verifying key for validating tokens

Enums

PqPasetoError

Errors that can occur during token operations

Constants

TOKEN_PREFIX_LOCAL

Token prefix for local (symmetric encryption) post-quantum tokens

TOKEN_PREFIX_PUBLIC

Token prefix for public (signature-based) post-quantum tokens

Traits

CryptoRng

A marker trait over RngCore for securely unpredictable RNGs

RngCore

Implementation-level interface for RNGs