rusty_paseto

A type-driven, ergonomic implementation of the PASETO protocol for secure stateless tokens.

PASETO: Platform-Agnostic Security Tokens

Paseto is everything you love about JOSE (JWT, JWE, JWS) without any of the many design deficits that plague the JOSE standards.

Roadmap and Current Feature Status

| APIs, Tests & Documentation | v1.
local| v1.
public | v2.
local | v2.
public |v3.
local | v3.
public | v4.
local | v4.
public | | ------------: | :-----------: | :----------: |:-----------: |:-----------: |:-----------: |:-----------: |:-----------: |:-----------: | | PASETO Token Builder | :greencircle: | :greencircle: | :greencircle: | :greencircle: | :greencircle: | :blackcircle: | :greencircle: | :greencircle: | | PASETO Token Parser | :greencircle: | :greencircle: | :greencircle: | :greencircle: | :greencircle: | :blackcircle: | :greencircle: | :greencircle: | | Flexible Claim Validation | :greencircle: | :greencircle: | :greencircle: | :greencircle: | :greencircle: | :blackcircle: | :greencircle: | :greencircle: | | Generic Token Builder | :greencircle: | :greencircle: | :greencircle: | :greencircle: | :greencircle: | :blackcircle: | :greencircle: | :greencircle: | | Generic Token Parser | :greencircle: | :greencircle: | :greencircle: | :greencircle: | :greencircle: | :blackcircle: | :greencircle: | :greencircle: | | Encryption/Signing | :greencircle: | :greencircle: | :greencircle: | :greencircle: | :greencircle: | :blackcircle: | :greencircle: | :greencircle: | | Decryption/Verification | :greencircle: | :greencircle: | :greencircle: | :greencircle: | :greencircle: | :blackcircle: | :greencircle: | :greencircle: | | PASETO Test vectors | :greencircle: | :greencircle: | :greencircle: | :greencircle: | :greencircle: | :blackcircle: | :greencircle: | :greencircle: | | Documentation | :blackcircle: | :blackcircle: | :orangecircle: | :blackcircle: | :blackcircle: | :blackcircle: | :blackcircle: | :blackcircle: |

| Feature | Status | | ------------: | :-----------: |
| Feature gates | :blackcircle: | | PASERK support | :blackcircle: |

# Usage

rust // at the top of your source file use rusty_paseto::prelude::*; # Examples: Building and parsing tokens

Here's a basic, default token: ```rust use rusty_paseto::prelude::*;

// create a key specifying the PASETO version and purpose let key = PasetoSymmetricKey::::from(Key::from(b"wubbalubbadubdubwubbalubbadubdub")); // use a default token builder with the same PASETO version and purpose let token = PasetoBuilder::::default().build(&key)?; // token is a String in the form: "v4.local.encoded-payload"

```

## A default token

• Has no footer
• Has no implicit assertion for V3 or V4 versioned tokens
• Expires in 1 hour after creation (due to an included default ExpirationClaim)
• Contains an IssuedAtClaim defaulting to the current utc time the token was created

• Contains a NotBeforeClaim defaulting to the current utc time the token was created

  You can parse and validate an existing token with the following: ```rust let key = PasetoSymmetricKey::::from(Key::from(b"wubbalubbadubdubwubbalubbadubdub")); // now we can parse and validate the token with a parser that returns a serdejson::Value let jsonvalue = PasetoParser::::default().parse(&token, &key)?;

  //the ExpirationClaim assert!(jsonvalue["exp"].isstring()); //the IssuedAtClaim assert!(jsonvalue["iat"].isstring());

  ```

  A default parser

• Validates the token structure and decryptes the payload or verifies the signature of the content

• Validates the footer if one was provided

• Validates the implicit assertion if one was provided (for V3 or V4 versioned tokens only)

  A token with a footer

  PASETO tokens can have an optional footer. In rustypaseto we have strict types for most things.
  So we can extend the previous example to add a footer to the token by using code like the following: ```rust use rustypaseto::prelude::*; let key = PasetoSymmetricKey::::from(Key::from(b"wubbalubbadubdubwubbalubbadubdub")); let token = PasetoBuilder::::default() // note how we set the footer here .set_footer(Footer::from("Sometimes science is more art than science")) .build(&key)?;

  // token is now a String in the form: "v4.local.encoded-payload.footer"

  And parse it by passing in the same expected footer rust // now we can parse and validate the token with a parser that returns a serdejson::Value let jsonvalue = PasetoParser::::default() .set_footer(Footer::from("Sometimes science is more art than science")) .parse(&token, &key)?;

  //the ExpirationClaim assert!(jsonvalue["exp"].isstring()); //the IssuedAtClaim assert!(jsonvalue["iat"].isstring());

  ```

  A token with an implicit assertion (V3 or V4 versioned tokens only)

  Version 3 (V3) and Version 4 (V4) PASETO tokens can have an optional implicit assertion. So we can extend the previous example to add an implicit assertion to the token by using code like the following: ```rust use rustypaseto::prelude::*; let key = PasetoSymmetricKey::::from(Key::from(b"wubbalubbadubdubwubbalubbadubdub")); let token = PasetoBuilder::::default() .setfooter(Footer::from("Sometimes science is more art than science")) // note how we set the implicit assertion here .setimplicitassertion(ImplicitAssertion::from("There’s a lesson here, and I’m not going to be the one to figure it out.")) .build(&key)?;

  // token is now a String in the form: "v4.local.encoded-payload.footer"

  And parse it by passing in the same expected implicit assertion at parse time rust // now we can parse and validate the token with a parser that returns a serdejson::Value let jsonvalue = PasetoParser::::default() .setfooter(Footer::from("Sometimes science is more art than science")) .setimplicit_assertion(ImplicitAssertion::from("There’s a lesson here, and I’m not going to be the one to figure it out.")) .parse(&token, &key)?;

  ```

  Setting a different expiration time

  As mentioned, default tokens expire 1 hour from creation time. You can set your own expiration time by adding an ExpirationClaim which takes an ISO 8601 (Rfc3339) compliant datetime string.

  Note: claims taking an ISO 8601 (Rfc3339) string use the TryFrom trait and return a Result<(),PasetoClaimError>

  ```rust use rusty_paseto::prelude::*; // must include use std::convert::TryFrom; let key = PasetoSymmetricKey::::from(Key::from(b"wubbalubbadubdubwubbalubbadubdub")); // real-world example using the time crate to expire 5 minutes from now

  let token = PasetoBuilder::::default() // note the TryFrom implmentation for ExpirationClaim //.setclaim(ExpirationClaim::tryfrom("2019-01-01T00:00:00+00:00")?) .setclaim(ExpirationClaim::tryfrom(in5minutes)?) .set_footer(Footer::from("Sometimes science is more art than science")) .build(&key)?;

  // token is a String in the form: "v4.local.encoded-payload.footer"

  ```

  Tokens that never expire

  A 1 hour ExpirationClaim is set by default because the use case for non-expiring tokens in the world of security tokens is fairly limited. Omitting an expiration claim or forgetting to require one when processing them is almost certainly an oversight rather than a deliberate choice.

  When it is a deliberate choice, you have the opportunity to deliberately remove this claim from the Builder. The method call required to do so ensures readers of the code understand the implicit risk. ```rust let token = PasetoBuilder::::default() .setclaim(ExpirationClaim::tryfrom(in5minutes)?) // even if you set an expiration claim (as above) it will be ignored // due to the method call below .setnoexpirationdangeracknowledged() .build(&key)?;

  ```

  Setting PASETO Claims

  The PASETO specification includes seven reserved claims which you can set with their explicit types: ```rust // real-world example using the time crate to prevent the token from being used before 2 // minutes from now let in2minutes = (time::OffsetDateTime::now_utc() + time::Duration::minutes(2)).format(&Rfc3339)?;

  let token = PasetoBuilder::::default() //json payload key: "exp" .setclaim(ExpirationClaim::tryfrom(in5minutes)?) //json payload key: "iat" // the IssueAtClaim is automatically set to UTC NOW by default // but you can override it here // .setclaim(IssuedAtClaim::tryfrom("2019-01-01T00:00:00+00:00")?) //json payload key: "nbf" //don't use this token before two minutes after UTC NOW .setclaim(NotBeforeClaim::tryfrom(in2minutes)?) //json payload key: "aud" .setclaim(AudienceClaim::from("Cromulons")) //json payload key: "sub" .setclaim(SubjectClaim::from("Get schwifty")) //json payload key: "iss" .setclaim(IssuerClaim::from("Earth Cesium-137")) //json payload key: "jti" .setclaim(TokenIdentifierClaim::from("Planet Music - Season 988")) .build(&key)?;

  ```

  Setting your own Custom Claims

  The CustomClaim struct takes a tuple in the form of (key: String, value: T) where T is any serializable type

  Note: CustomClaims use the TryFrom trait and return a Result<(), PasetoClaimError> if you attempt to use one of the reserved PASETO keys in your CustomClaim

  ```rust let token = PasetoBuilder::::default() .setclaim(CustomClaim::tryfrom(("Co-star", "Morty Smith"))?) .setclaim(CustomClaim::tryfrom(("Universe", 137))?) .build(&key)?;

  This throws an error: rust // "exp" is a reserved PASETO claim key, you should use the ExpirationClaim type let token = PasetoBuilder::::default() .setclaim(CustomClaim::tryfrom(("exp", "Some expiration value"))?) .build(&key)?;

  ```

  Validating claims

  rusty_paseto allows for flexible claim validation at parse time

  Checking claims

  Let's see how we can check particular claims exist with expected values. ```rust // use a default token builder with the same PASETO version and purpose let token = PasetoBuilder::::default() .setclaim(SubjectClaim::from("Get schwifty")) .setclaim(CustomClaim::tryfrom(("Contestant", "Earth"))?) .setclaim(CustomClaim::try_from(("Universe", 137))?) .build(&key)?;

  PasetoParser::::default() // you can check any claim even custom claims .checkclaim(SubjectClaim::from("Get schwifty")) .checkclaim(CustomClaim::tryfrom(("Contestant", "Earth"))?) .checkclaim(CustomClaim::try_from(("Universe", 137))?) .parse(&token, &key)?;

  // no need for the assertions below since the check_claim methods // above accomplish the same but at parse time!

  //asserteq!(jsonvalue["sub"], "Get schwifty"); //asserteq!(jsonvalue["Contestant"], "Earth"); //asserteq!(jsonvalue["Universe"], 137); ```

  Custom validation

  What if we have more complex validation requirements? You can pass in a reference to a closure which receives the key and value of the claim you want to validate so you can implement any validation logic you choose.

  Let's see how we can validate our tokens only contain universe values with prime numbers: ```rust // use a default token builder with the same PASETO version and purpose let token = PasetoBuilder::::default() .setclaim(SubjectClaim::from("Get schwifty")) .setclaim(CustomClaim::tryfrom(("Contestant", "Earth"))?) .setclaim(CustomClaim::try_from(("Universe", 137))?) .build(&key)?;

  PasetoParser::::default() .checkclaim(SubjectClaim::from("Get schwifty")) .checkclaim(CustomClaim::tryfrom(("Contestant", "Earth"))?) .validateclaim(CustomClaim::tryfrom("Universe")?, &|key, value| { //let's get the value let universe = value .asu64() .okor(PasetoClaimError::Unexpected(key.tostring()))?; // we only accept prime universes in this app if primes::isprime(universe) { Ok(()) } else { Err(PasetoClaimError::CustomValidation(key.tostring())) } }) .parse(&token, &key)?;

  ```

  This token will fail to parse with the validation code above: ```rust // 136 is not a prime number let token = PasetoBuilder::::default() .setclaim(CustomClaim::tryfrom(("Universe", 136))?) .build(&key)?;

  ```

  Acknowledgments

  If the API of this crate doesn't suit your tastes, check out the other PASETO implementations in the Rust ecosystem which inspired rusty_paseto:

• paseto - by Cynthia Coan

• pasetors - by Johannes

Questions?

File an issue or hit me up on Twitter!