jwt-simple: JSON Web Tokens for Rust

Symmetric authentication uses the same key for both creating and verifying tokens. This is suitable when both parties share a secret.

Key and Token Creation

1. Generate a key using HS256Key::generate() (or other HS* variants).
2. Create claims using Claims::create(duration).
3. Authenticate the claims using key.authenticate(claims).

Keys can be exported as bytes via key.to_bytes() and restored via HS256Key::from_bytes().

Token Verification

Verify a token using key.verify_token::<ClaimsType>(&token, options). By default, expiration, start time, and authentication tags are automatically verified.

use jwt_simple::prelude::*;

// 1. Key creation
let key = HS256Key::generate();

// 2. Token creation
let claims = Claims::create(Duration::from_hours(2));
let token = key.authenticate(claims)?;

// 3. Token verification
let claims = key.verify_token::<NoCustomClaims>(&token, None)?;

Asymmetric signatures use a secret key pair to sign tokens and a public key to verify them. This is recommended when the verifier should not be able to create tokens.

Key Pair Generation

• ECDSA: Use ES256KeyPair::generate() or ES384KeyPair::generate().
• ML-DSA (Post-Quantum): Use MLDSA44KeyPair::generate() (recommended), MLDSA65KeyPair::generate(), or MLDSA87KeyPair::generate().
• RSA: Keys can be imported from PEM-encoded data using RS384KeyPair::from_pem(content) and RS384PublicKey::from_pem(content).

Usage Pattern

1. Sign: Use the secret key pair with key_pair.sign(claims).
2. Verify: Use the public key with public_key.verify_token::<ClaimsType>(&token, options).

use jwt_simple::prelude::*;

// 1. Create key pair (e.g., ES256)
let key_pair = ES256KeyPair::generate();
let public_key = key_pair.public_key();

// 2. Sign token
let claims = Claims::create(Duration::from_hours(2));
let token = key_pair.sign(claims)?;

// 3. Verify token with public key
let claims = public_key.verify_token::<NoCustomClaims>(&token, None)?;

When targeting wasm32-wasip1, you can enable the wasi-crypto feature to offload heavy cryptographic operations (like RSA key generation, signing, verification, and AES-GCM encryption) to the host. This provides significant performance improvements and better protection against side-channel attacks by using the host's optimized, constant-time implementations.

Key behaviors:

• Target Specificity: The feature only has an effect on wasm32-wasip1. On all other targets, it is a no-op and safe to leave enabled.
• Fallback Mechanism: If the host does not provide the WASI-Crypto interface, the library transparently falls back to pure Rust implementations without runtime errors.
• Offloaded Operations: RSA (RS*, PS*) and AES-GCM (used in JWE tokens).

[dependencies]
jwt-simple = { version = "0.13", features = ["wasi-crypto"] }

cargo build --target wasm32-wasip1 --features wasi-crypto

Symmetric keys (like HS256) are vulnerable if the verifier's key is compromised. Salted keys mitigate this by using a secret 'signer salt' known only to the signer. The verifier uses a derived 'verifier salt' to check the token.

1. Generate a key with a salt: HS256Key::generate_with_salt().
2. The signer uses the full key. The verifier uses key.attach_salt(verifier_salt)? where the verifier_salt is derived from the signer's salt.

// Create a random key and a signer salt
let key = HS256Key::generate_with_salt();
let claims = Claims::create(Duration::from_secs(86400));
let token = key.authenticate(claims).unwrap();

// --- On the Verifier side ---
// 1. Get the verifier salt from the signer's salt
let verifier_salt_bytes = key.verifier_salt()?; 
let verifier_salt = Salt::Verifier(verifier_salt_bytes);

// 2. Attach it to the key before verification
key.attach_salt(verifier_salt)?;
let claims = key.verify_token::<NoCustomClaims>(&token, None)?;