sealwd

sealwd provides small, focused primitives for handling secrets safely in Rust.

Designed specifically for server-side authentication systems, it enforces a strict separation between low-entropy user passwords and high-entropy machine-generated tokens. It handles memory zeroization, secure generation, policy validation, forward-compatible hashing, and optional encryption at rest.

Core Philosophy & Security Model

Passwords and tokens serve different purposes and require different cryptographic treatments:

• Passwords are low-entropy secrets provided by users. They are hashed using Argon2id (slow, memory-hard) to resist brute-force attacks.
• Tokens are high-entropy, fixed-length secrets generated by the system (e.g., session IDs, API keys). They are hashed using BLAKE3 (fast) with a server-side pepper. Using token hashing for passwords is mathematically insecure and intentionally unsupported by this crate.

Features

• Explicit Secret Types: Strongly typed Password and Token<LEN> primitives.
• Memory Safety: Secrets are wrapped in containers that automatically zeroize memory on drop.
• Password Policies: Configurable rules for generation and validation (length, character classes).
• Self-Describing Hashes: Binary serializable hashes (PasswordHash, TokenHash) with embedded algorithm versions for forward compatibility.
• Encryption at Rest (Optional): AEAD encryption (XChaCha20-Poly1305 or AES-256-GCM-SIV) via the encryption feature.
• Framework Integrations (Optional): Direct BYTEA mappings for PostgreSQL via sqlx, and transparent serde serialization.

Usage

Managing Passwords

use sealwd::{Password, PasswordPolicy};

// 1. Define a policy
let policy = PasswordPolicy::with_sane_defaults();

// 2. Generate a secure random password satisfying the policy
let password = Password::random(&policy).unwrap();

// 3. Hash the password for storage (uses Argon2id automatically)
let hash = password.to_default_hash().unwrap();

// 4. Verify a login attempt
assert!(hash.verify(&password).is_ok());

Managing High-Entropy Tokens

use sealwd::Token;

// 1. Generate a 32-byte cryptographic token
let token = Token::<32>::random().unwrap();

// 2. Export to URL-safe Base64 to send to the client
let encoded = token.to_base64();

// 3. Hash with a server-side pepper for database storage (uses BLAKE3)
let pepper = b"my-secret-server-pepper-value";
let token_hash = token.to_default_hash(pepper);

// 4. Store `token_hash.to_bytes()` in your database

Encryption at Rest (Requires encryption feature)

When storing secrets that must be reversible (e.g., external API keys), you can encrypt them before storage.

use sealwd::{Token, crypto::CipherSuite};

let token = Token::<16>::random().unwrap();
let encryption_key = b"thisisa32bytekeyforrustcryptolib";

// Encrypt the token using XChaCha20-Poly1305
let encrypted_token = token.encrypt(encryption_key, CipherSuite::XChaCha20Poly1305).unwrap();

// Decrypt back to a strongly-typed Token<16>
let decrypted_token = encrypted_token.decrypt(encryption_key).unwrap();

Feature Flags

• encryption: Enables the crypto module, providing EncryptedPassword and EncryptedToken wrappers backed by AEAD ciphers.
• serde: Enables transparent serialization/deserialization for domain types.
• sqlx: Implements sqlx::Type, Encode, and Decode allowing hashes and encrypted types to be used directly with database queries (maps to BYTEA in Postgres).

License

Apache-2.0