Crate jwt_compact_preview[][src]

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.

Supported algorithms

Algorithm(s)FeatureDescription
HS256, HS384, HS512-Uses pure Rust sha2 crate
EdDSA (Ed25519)exonum-cryptolibsodium binding. Enabled by default
EdDSA (Ed25519)ed25519-dalekPure Rust implementation
EdDSA (Ed25519)ed25519-compactCompact pure Rust implementation, WASM-compatible
ES256Ksecp256k1Binding for libsecp256k1
RS*, PS* (RSA)rsaUses pure Rust rsa crate with blinding

StandardES* algorithm is not (yet?) implemented. The main reason (besides laziness and non-friendly APIs in the relevant crypto backends) is:

  • Elliptic curves in ES* algs use a maybe-something-up-my-sleeve generation procedure and thus may be backdoored

EdDSA and ES256K algorithms are non-standard. 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.

Examples

Basic JWT lifecycle:

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

/// Custom claims encoded in the token.
#[derive(Debug, PartialEq, Serialize, Deserialize)]
struct CustomClaims {
    /// `sub` is a standard claim which denotes claim subject:
    /// https://tools.ietf.org/html/rfc7519#section-4.1.2
    #[serde(rename = "sub")]
    subject: String,
}

// Create a symmetric HMAC key, which will be used both to create and verify tokens.
let key = Hs256Key::from(b"super_secret_key_donut_steel" as &[_]);
// Create a token.
let header = Header {
    key_id: Some("my-key".to_owned()),
    ..Default::default()
};
let claims = Claims::new(CustomClaims { subject: "alice".to_owned() })
    .set_duration_and_issuance(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::try_from(token_string.as_str())?;
// 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.
token
    .claims()
    .validate_expiration(TimeOptions::default())?
    .validate_maturity(TimeOptions::default())?;
// Now, we can extract information from the token (e.g., its subject).
let subject = &token.claims().custom.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:
    ///     https://tools.ietf.org/html/rfc7519#section-4.1.2
    /// The custom serializer we use allows to efficiently
    /// encode the subject in CBOR.
    #[serde(rename = "sub", with = "HexForm")]
    subject: [u8; 32],
}

let key = Hs256Key::from(b"super_secret_key_donut_steel" as &[_]);
let claims = Claims::new(CustomClaims { subject: [111; 32] })
    .set_duration_and_issuance(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::try_from(compact_token.as_str())?;
let token: Token<CustomClaims> = Hs256.validate_integrity(&token, &key)?;
token.claims().validate_expiration(TimeOptions::default())?;
// Now, we can extract information from the token (e.g., its subject).
assert_eq!(token.claims().custom.subject, [111; 32]);

Modules

alg

Implementations of JWT signing / verification algorithms.

prelude

Prelude to neatly import all necessary stuff from the crate.

Structs

Claims

Claims encoded in a token.

Empty

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

Header

JWT header.

Renamed

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

SignedToken

Token together with the validated token signature.

TimeOptions

Time-related validation options.

Token

Token with validated integrity.

UntrustedToken

Parsed, but unvalidated token.

Enums

CreationError

Errors that can occur during token creation.

ParseError

Errors that may occur during token parsing.

ValidationError

Errors that can occur during token validation.

Traits

Algorithm

JWT signing algorithm.

AlgorithmExt

Automatically implemented extensions of the Algorithm trait.

AlgorithmSignature

Signature for a certain JWT signing Algorithm.