[−][src]Crate jwt_compact
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 thealg
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, andES256K
algorithm with the secp256k1 elliptic curve.
Supported algorithms
Algorithm(s) | Feature | Description |
---|---|---|
HS256 , HS384 , HS512 | - | Uses pure Rust sha2 crate |
EdDSA (Ed25519) | exonum-crypto | libsodium binding. Enabled by default |
EdDSA (Ed25519) | ed25519-dalek | Pure Rust implementation |
EdDSA (Ed25519) | ed25519-compact | Compact pure Rust implementation, WASM-compatible |
ES256K | es256k | Rust binding for libsecp256k1 |
RS* , PS* (RSA) | rsa | Uses pure Rust rsa crate with blinding |
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
.
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 usingUtc::now()
fromchrono
. Without it, someTimeOptions
constructors, such as theDefault
impl, are not available. It is still possible to createTimeOptions
with an excplicitly specified clock function, or to set / verify time-relatedClaims
fields manually. - The
std
feature is propagated to the core dependencies and enablesstd
-specific functionality (such as error types implementing the standardError
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.
Examples
Basic JWT lifecycle:
use chrono::{Duration, Utc}; use jwt_compact::{prelude::*, alg::{Hs256, Hs256Key}}; use serde::{Serialize, Deserialize}; use core::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, } // 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::from(b"super_secret_key_donut_steel" as &[_]); // 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::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(&time_options)? .validate_maturity(&time_options)?; // 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 time_options = TimeOptions::default(); let key = Hs256Key::from(b"super_secret_key_donut_steel" as &[_]); 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::try_from(compact_token.as_str())?; let token: Token<CustomClaims> = Hs256.validate_integrity(&token, &key)?; token.claims().validate_expiration(&time_options)?; // 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. Also contains generic traits for signing and verifying keys. |
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 |
Header | JWT header. |
Renamed | Algorithm that uses a custom name when creating and validating tokens. |
SignedToken |
|
TimeOptions | Time-related options for token creation and validation. |
Token | Token with validated integrity. |
UntrustedToken | Parsed, but unvalidated token. |
Enums
Claim | Identifier of a claim in |
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 |
AlgorithmSignature | Signature for a certain JWT signing |