Skip to main content

Crate sealwd

Crate sealwd 

Source
Expand description

§sealwd

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

The crate is specifically designed for server-side authentication and secret management systems. It enforces a strict, type-level separation between user-provided passwords and system-generated tokens, ensuring that the correct cryptographic algorithms are applied to each.

§Core Primitives

  • Password: Represents a low-entropy user secret. Passwords are hashed using Argon2id, a slow and memory-hard algorithm designed to resist brute-force attacks.
  • Token: Represents a high-entropy, fixed-length generated secret (e.g., session IDs, API keys, refresh tokens). Tokens are hashed using BLAKE3 combined with a server-side pepper, optimizing for speed while maintaining security.

§Security Model

  1. Zeroization: Raw secret material (Password, Token) automatically zeroes its memory when dropped, reducing the risk of sensitive data lingering in RAM.
  2. Explicit Separation: Using fast token hashing (BLAKE3) for low-entropy passwords is insecure and intentionally unsupported. The API enforces Argon2id for passwords.
  3. Forward Compatibility: Serialized hashes (PasswordHash, TokenHash) are self-describing, embedding an algorithm identifier to allow seamless future upgrades.

§Example: Password Lifecycle

let policy = PasswordPolicy::with_sane_defaults();

// Generate a password that passes the policy
let password = Password::random(&policy).unwrap();

// Hash for storage (Argon2id)
let hash = password.to_default_hash().unwrap();

// Verify
assert!(hash.verify(&password).is_ok());

§Example: Token Lifecycle

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

// Convert to Base64 to give to the user
let b64 = token.to_base64();

// Hash with a server pepper for database storage (BLAKE3)
let pepper = b"server-side-secret-pepper";
let stored_hash = token.to_default_hash(pepper);

§Feature Flags

  • encryption: Enables the crypto module, providing authenticated encryption (AEAD) primitives for secrets that must be stored reversibly.
  • serde: Implements Serialize and Deserialize for the crate’s types.
  • sqlx: Implements database encoding/decoding, mapping hash and encrypted types transparently to database binary columns (e.g., BYTEA in PostgreSQL).

§Non-goals

This crate does not attempt to be a general-purpose key derivation framework, a secret storage engine, or a full authentication protocol implementation. It provides the cryptographic building blocks intended to be composed by higher-level systems.

Re-exports§

pub use password::Password;
pub use password::PasswordHash;
pub use password::PasswordPolicy;
pub use token::Token;
pub use token::TokenHash;

Modules§

crypto
password
range
token