A Rust implementation of Json Web Tokens
Installation
jsonwebtokens = "1"
serde_json = "1"
Then, in your code:
use json;
use Value;
use jsonwebtokens as jwt;
use ;
Usage
The main two types are Algorithm
and Verifier
. An Algorithm
encapsulates
a cryptographic function for signing or verifying tokens, and a Verifier
handles checking the signature and claims of a token, given an Algorithm
.
Creating an Algorithm
separately ensures any parsing of secrets or keys only
needs to happen once.
The builder pattern used for describing a Verifier
keeps code ergonimic no
matter if you have simple or elaborate verification requirements.
There is also a low-level (::raw
) API available in
case you need more control over splitting, decoding, deserializing and
verifying tokens.
Signing a token
with a symmetric secret:
let alg = new_hmac?;
let header = json!;
let claims = json!;
let token = encode?;
or if your secret is base64 encoded:
let alg = new_hmac_b64?;
with an RSA private key:
let alg = new_rsa_pem_signer?;
let header = json!;
let claims = json!;
let token = encode?;
Verifying tokens
with a symmetric secret:
let alg = new_hmac?;
let verifier = create
.issuer
.audience
.build?;
let claims: Value = verifier.verify?;
with an RSA private key:
let alg = new_rsa_pem_verifier?;
let verifier = create
.issuer
.audience
.build?;
let claims: Value = verifier.verify?;
Verifying standard claims
let alg = new_hmac?;
let verifier = create
.issuer
.audience
.subject
.nonce
.leeway // give this much leeway (in seconds) when validating exp, nbf and iat claims
.build?;
let claims: Value = verifier.verify?;
Verifying custom claims
let alg = new_hmac?;
let verifier = create
.string_equals
.string_matches
.string_equals_one_of
.string_matches_one_of
.claim_callback
.build?;
let claims: Value = verifier.verify?;
Verifying timestamps (or not)
let alg = new_hmac?;
let verifier = create
.leeway // give this much leeway when validating exp, nbf and iat claims
.ignore_exp // ignore expiry
.ignore_nbf // ignore 'not before time'
.ignore_iat // ignore issue time
.build?;
let claims: Value = verifier.verify?;
Low-level Usage
In case you need even more fine-grained control than is possible with the
above APIs, many of the lower-level details are exposed through the ::raw
module to allow you to manually split, decode and verify a JWT token.
Just split a token into component parts
let TokenSlices = split_token?;
Just parse the header
use Value;
let header: Value = decode_header_only;
Base64 decode header or claims and deserialize JSON
Equivalent to raw::decode_header_only()
:
let TokenSlices = split_token?;
let header = decode_json_token_slice?;
Or, decode and deserialize just the claims:
let TokenSlices = split_token?;
let claims = decode_json_token_slice?;
Manually split, decode and verify a token
let alg = new_hmac?;
let verifier = create
// snip
.build?;
let TokenSlices = split_token?;
let header = decode_json_token_slice?;
verify_signature_only?;
let claims = decode_json_token_slice?;
verifier.verify_claims_only?;
Algorithms Supported
Array of supported algorithms. The following algorithms are currently supported.
alg Parameter Value | Digital Signature or MAC Algorithm |
---|---|
HS256 | HMAC using SHA-256 hash algorithm |
HS384 | HMAC using SHA-384 hash algorithm |
HS512 | HMAC using SHA-512 hash algorithm |
RS256 | RSASSA-PKCS1-v1_5 using SHA-256 hash algorithm |
RS384 | RSASSA-PKCS1-v1_5 using SHA-384 hash algorithm |
RS512 | RSASSA-PKCS1-v1_5 using SHA-512 hash algorithm |
PS256 | RSASSA-PSS using SHA-256 hash algorithm |
PS384 | RSASSA-PSS using SHA-384 hash algorithm |
PS512 | RSASSA-PSS using SHA-512 hash algorithm |
ES256 | ECDSA using P-256 curve and SHA-256 hash algorithm (only PKCS#8 format PEM) |
ES384 | ECDSA using P-384 curve and SHA-384 hash algorithm (only PKCS#8 format PEM) |
none | No digital signature or MAC value included |
Based on
Originally this project started as a few small changes to
jsonwebtoken (without an 's'), to
meet the needs I had while building
jsonwebtokens-cognito but
eventually the design and implementation became substantially different with
the creation of the Algorithm
API and the customizable Verifier
API.
The project borrows design ideas from a variety of pre-existing Json Web Token libraries. In particular it shamelessly steals ideas from node-jsonwebtoken and java-jwt.