Crate jwt_compact[][src]

Expand description

Minimalistic JSON web token (JWT) implementation with focus on type safety and secure cryptographic primitives.

Design choices

  • JWT signature algorithms (i.e., cryptographic algorithms providing JWT integrity) are expressed via the Algorithm trait, which uses fully typed keys and signatures.
  • JWT header is represented by the Header struct. Notably, Header does not expose the alg field. Instead, alg is filled automatically during token creation, and is compared to the expected value during verification. (If you do not know the JWT signature algorithm during verification, you’re doing something wrong.) This eliminates the possibility of algorithm switching attacks.

Additional features

  • The crate supports more compact CBOR encoding of the claims. The compactly encoded JWTs have cty field (content type) in their header set to "CBOR".
  • The crate supports EdDSA algorithm with the Ed25519 elliptic curve, and ES256K algorithm with the secp256k1 elliptic curve.
  • Supports basic JSON Web Key functionality, e.g., for converting keys to / from JSON or computing a key thumbprint.

Supported algorithms

HS256, HS384, HS512-Uses pure Rust sha2 crate
EdDSA (Ed25519)exonum-cryptolibsodium binding
EdDSA (Ed25519)ed25519-dalekPure Rust implementation
EdDSA (Ed25519)ed25519-compactCompact pure Rust implementation, WASM-compatible
ES256Kes256kRust binding for libsecp256k1
ES256Kk256Pure Rust implementation
RS*, PS* (RSA)rsaUses pure Rust rsa crate with blinding

EdDSA and ES256K algorithms are somewhat less frequently supported by JWT implementations than others since they are recent additions to the JSON Web Algorithms (JWA) suit. They both work with elliptic curves (Curve25519 and secp256k1; both are widely used in crypto community and believed to be securely generated). These algs have 128-bit security, making them an alternative to ES256.

no_std support

The crate supports a no_std compilation mode. This is controlled by two features: clock and std; both are on by default.

  • The clock feature enables getting the current time using Utc::now() from chrono. Without it, some TimeOptions constructors, such as the Default impl, are not available. It is still possible to create TimeOptions with an excplicitly specified clock function, or to set / verify time-related Claims fields manually.
  • The std feature is propagated to the core dependencies and enables std-specific functionality (such as error types implementing the standard Error trait).

Some alloc types are still used in the no_std mode, such as String, Vec and Cow.

Note that not all crypto backends are no_std-compatible.


Basic JWT lifecycle:

use chrono::{Duration, Utc};
use jwt_compact::{prelude::*, alg::{Hs256, Hs256Key}};
use serde::{Serialize, Deserialize};

/// Custom claims encoded in the token.
#[derive(Debug, PartialEq, Serialize, Deserialize)]
struct CustomClaims {
    /// `sub` is a standard claim which denotes claim subject:
    #[serde(rename = "sub")]
    subject: String,

// Choose time-related options for token creation / validation.
let time_options = TimeOptions::default();
// Create a symmetric HMAC key, which will be used both to create and verify tokens.
let key = Hs256Key::new(b"super_secret_key_donut_steel");
// Create a token.
let header = Header::default().with_key_id("my-key");
let claims = Claims::new(CustomClaims { subject: "alice".to_owned() })
    .set_duration_and_issuance(&time_options, Duration::days(7))
    .set_not_before(Utc::now() - Duration::hours(1));
let token_string = Hs256.token(header, &claims, &key)?;
println!("token: {}", token_string);

// Parse the token.
let token = UntrustedToken::new(&token_string)?;
// Before verifying the token, we might find the key which has signed the token
// using the `Header.key_id` field.
assert_eq!(token.header().key_id, Some("my-key".to_owned()));
// Validate the token integrity.
let token: Token<CustomClaims> = Hs256.validate_integrity(&token, &key)?;
// Validate additional conditions.
// Now, we can extract information from the token (e.g., its subject).
let subject = &;
assert_eq!(subject, "alice");

Compact JWT

/// Custom claims encoded in the token.
#[derive(Debug, PartialEq, Serialize, Deserialize)]
struct CustomClaims {
    /// `sub` is a standard claim which denotes claim subject:
    /// The custom serializer we use allows to efficiently
    /// encode the subject in CBOR.
    #[serde(rename = "sub", with = "HexForm")]
    subject: [u8; 32],

let time_options = TimeOptions::default();
let key = Hs256Key::new(b"super_secret_key_donut_steel");
let claims = Claims::new(CustomClaims { subject: [111; 32] })
    .set_duration_and_issuance(&time_options, Duration::days(7));
let token = Hs256.token(Header::default(), &claims, &key)?;
println!("token: {}", token);
let compact_token = Hs256.compact_token(Header::default(), &claims, &key)?;
println!("compact token: {}", compact_token);
// The compact token should be ~40 chars shorter.

// Parse the compact token.
let token = UntrustedToken::new(&compact_token)?;
let token: Token<CustomClaims> = Hs256.validate_integrity(&token, &key)?;;
// Now, we can extract information from the token (e.g., its subject).
assert_eq!(, [111; 32]);



Implementations of JWT signing / verification algorithms. Also contains generic traits for signing and verifying keys.


Basic support of JSON Web Keys (JWK).


Prelude to neatly import all necessary stuff from the crate.



Claims encoded in a token.


A structure with no fields that can be used as a type parameter to Claims.


JWT header.


Algorithm that uses a custom name when creating and validating tokens.


Token together with the validated token signature.


Time-related options for token creation and validation.


Token with validated integrity.


Parsed, but unvalidated token.



Identifier of a claim in Claims.


Errors that can occur during token creation.


Errors that may occur during token parsing.


Errors that can occur during token validation.



JWT signing algorithm.


Automatically implemented extensions of the Algorithm trait.


Signature for a certain JWT signing Algorithm.