biscuit

Biscuit is a Rust library implementing the JOSE (JSON Object Signing and Encryption) family of specifications: JSON Web Tokens (JWT), JSON Web Signature (JWS), and JSON Web Encryption (JWE). It wraps ring’s audited cryptographic primitives in a strongly-typed API, giving Rust services a way to issue, sign, encrypt, and validate tokens without hand-rolling base64url encoding, claim validation, or algorithm negotiation.

The crate exposes both Compact and Flattened JSON serializations for JWS, RSA/EC/HMAC/oct key types via JWK and JWKSet, and a generic ClaimsSet<T>/Header<H> pair that lets callers attach their own typed private claims and header fields instead of working with loosely-typed JSON maps. Coverage of the underlying RFCs is intentionally partial and documented in a dedicated support matrix, and the project backs its cryptographic surface with over a hundred unit tests plus dedicated cargo-fuzz targets for decryption and signature verification.

What You Get

• Compact & Flattened JWS - sign and verify tokens in both the compact (header.payload.signature) and flattened JSON serialization formats defined by RFC 7515.
• JWE encryption - encrypt and decrypt JSON Web Encryption tokens, including key-wrapping and content-encryption algorithm support.
• JWK/JWKSet key handling - parse and construct RSA, EC, HMAC (oct), and OKP JSON Web Keys, plus JWK Thumbprint support (RFC 7638).
• Typed claims and headers - generic ClaimsSet<T> and Header<H> types let you attach your own private claims and header fields with compile-time type checking instead of raw JSON.
• Built-in registered claim validation - exp, nbf, and iat validation is provided out of the box, with iss/sub/aud/jti available for you to validate.

Common Use Cases

• Issuing signed API tokens - a Rust backend signs short-lived JWTs with HS256/RS256/ES256 to authenticate API clients without a session store.
• Verifying third-party JWTs - a service validates incoming JWTs (from an IdP or another internal service) against expiry, issuer, and audience claims before trusting the payload.
• Encrypting sensitive claims - an application uses JWE to encrypt token payloads end-to-end, not just sign them, when claims themselves shouldn’t be readable by intermediaries.
• Working with JWK Sets - a service fetches a provider’s JWKS endpoint and uses biscuit’s JWK/JWKSet types to select the right key for signature verification.

Under The Hood

Architecture biscuit is organized as a modular Rust crate with distinct top-level modules (jwa.rs, jwe.rs, jwk.rs, jws.rs, jws/compact.rs, jws/flattened.rs, errors.rs, digest.rs, serde_custom/) each mapping onto a JOSE RFC concept (JWA algorithms, JWE encryption, JWK keys, JWS signatures in both Compact and Flattened JSON serializations), with lib.rs acting as the crate root defining shared primitives (Compact, Base64Url, ClaimsSet, RegisteredClaims, ValidationOptions) and the JWT type alias that composes JWS + ClaimsSet for the common case. Validation and error handling are centralized (errors::{Error, ValidationError, DecodeError}) and threaded through every operation via Result, while helpers/ isolates small serde-adjacent utility functions from the cryptographic core. Changing the core Compact/CompactPart abstraction in lib.rs would ripple through jws/compact.rs and jwe.rs, since both compact serializations depend on it directly.

Tech Stack A crates.io library targeting Rust 2021 edition with MSRV 1.66. Core cryptography runs through ring ~0.17.13 rather than a bespoke implementation; serialization uses serde 1.0 and serde_json (with preserve_order), backed by a hand-written serde_custom module for base64url and byte-sequence (de)serialization. chrono (clock feature only) handles timestamps, data-encoding handles BASE64URL_NOPAD, and num-bigint/num-traits support RSA key material. There’s no async runtime or web framework dependency - it’s a synchronous library consumed directly via Cargo. CI (GitHub Actions) runs stable/beta/nightly/MSRV across Ubuntu, Windows, and macOS with cargo fmt, clippy -D warnings, build, test, and doc generation on every push.

Code Quality The crate has an unusually rigorous test setup for its size: over a hundred #[test] functions spread across jwa.rs, jwe.rs, jwk.rs, jws.rs, both jws submodules, lib.rs, and the serde_custom submodules, plus serde_test-based property tests and two dedicated cargo-fuzz targets that fuzz the decryption and signature-verification paths directly. Error handling is fully typed through a centralized Error enum wrapping DecodeError, ValidationError, and underlying serde_json/data_encoding/ring errors rather than strings or panics. The crate denies missing_docs and a long list of lint categories at the crate level, and CI enforces cargo fmt --check plus clippy -D warnings. Naming follows RFC terminology (JWA/JWE/JWK/JWS) consistently, which is precise once the domain vocabulary is known but raises the entry barrier for newcomers.

API Design The crate offers a convenience JWT type alias wrapping the common signed/unsecured Compact JWS + ClaimsSet<T> case, plus generic Header<H>/ClaimsSet<T> constructs so callers attach typed private headers and claims via generics rather than stringly-typed maps, giving compile-time shape guarantees over ad hoc JSON. The public API mirrors RFC vocabulary closely, which is exact for security work but has a real learning curve; a dedicated support matrix document exists specifically to help users navigate the crate’s intentionally partial RFC coverage. It doesn’t claim to reinvent cryptography - it’s a careful, typed Rust wrapper around ring for JOSE, valuable for correctness and safety rather than for novel technique.