OxiToken

oxitoken strives to be the fastest JWT encoding/decoding/validation library while simulteneously providing the best developer experience and extensibility.

• Custom header and claims structs, no stringly-typed extras HashMap here
• Custom KeyProvider support
  • A LocalKeystore implementation is provided that resolves keys via kid
  • If that doesn't fit your use-case, implement your own KeyProvider, which can resolve keys via any abitrary header or claim field, even custom ones
• Crypto backend agnostic
  • Reference implementations using aws-lc-rs and openssl are provided
    • Signer and VerificationKey traits permit using your own crypto backend (e.g. botan-rs, ring, HSMs, etc.)
    • Built-in providers can be fully disabled with feature flags
• Supports all the IANA registered JWS algorithms
  • HMAC: HS256, HS384, HS512
  • RSA: RS256, RS384, RS512, PS256, PS384, PS512
  • ECDSA: ES256, ES384, ES512
  • EdDSA: EdDSA (i.e. Ed25519) and Ed448
  • Post-Quantum algorithms: ML-DSA-44, ML-DSA-65, ML-DSA-87

Benchmarks

Encoding Performance

Validation Performance

Comparative benchmarks above were ran with aws-lc-rs backend for both oxitoken and jsonwebtoken. openssl is slightly slower than aws-lc-rs across the board, and rust_crypto is substantially slower.

Example

use aws_lc_rs::signature::{
    ED25519,
    Ed25519KeyPair,
    KeyPair,
    ParsedPublicKey,
};
use oxitoken::{
    Algorithm,
    claims::{
        Exp,
        Iss,
    },
    encoding::encode,
    header::Alg,
    validation::{
        StaticKeyProvider,
        ValidationPipeline,
    },
};

// NOTE: Debug, PartialEq, and Eq are only required for the assertions in this
// example code and are not a requirement of oxitoken.
#[derive(Debug, serde::Deserialize, serde::Serialize, PartialEq, Eq)]
struct Header {
    alg: Algorithm,
}
impl Header {
    const fn new(alg: Algorithm) -> Self {
        Self { alg }
    }
}
impl Alg for Header {
    fn alg(&self) -> Algorithm {
        self.alg
    }
}

// NOTE: Debug, PartialEq, and Eq are only required for the assertions in this
// example code and are not a requirement of oxitoken.
#[derive(Debug, serde::Deserialize, serde::Serialize, PartialEq, Eq)]
struct Claims {
    iss: String,
    exp: i64,
}
impl Claims {
    fn new(iss: impl Into<String>) -> Self {
        Self {
            iss: iss.into(),
            exp: 0,
        }
    }
}
impl Iss for Claims {
    fn iss(&self) -> &str {
        &self.iss
    }
}
impl Exp for Claims {
    fn exp(&self) -> i64 {
        self.exp
    }
}

fn make_key() -> Ed25519KeyPair {
    Ed25519KeyPair::generate().unwrap()
}

fn make_parsed_public_key(key: &Ed25519KeyPair) -> ParsedPublicKey {
    ParsedPublicKey::new(&ED25519, key.public_key().as_ref()).unwrap()
}

fn main() {
    let header = Header::new(Algorithm::EdDSA);
    let claims = Claims::new("oxitoken.example.org");
    let key = make_key();
    let jwt = encode(&key, &header, &claims).unwrap();
    println!("JWT: {jwt}");

    let pubkey = make_parsed_public_key(&key);
    let validator =
        ValidationPipeline::<Header, Claims, StaticKeyProvider<_>>::builder(pubkey.into())
            .with_issuer_validator("oxitoken.example.org")
            .with_expiration_validator()
            .build();

    let (decoded_header, decoded_claims) = validator.verify(jwt.as_bytes()).unwrap();

    assert_eq!(decoded_header, header);
    assert_eq!(decoded_claims, claims);

    println!("JWT validated successfully");

    // an alternative that allows the compiler to infer the generic types,
    // permitting omittance of the turbofish.
    let pubkey = StaticKeyProvider::from(make_parsed_public_key(&key));
    let validator = ValidationPipeline::builder(pubkey)
        .with_issuer_validator("oxitoken.example.org")
        .build();
    let (decoded_header, decoded_claims): (Header, Claims) =
        validator.verify(jwt.as_bytes()).unwrap();

    assert_eq!(decoded_header, header);
    assert_eq!(decoded_claims, claims);
}