Accepts tokens whose times are off by up to this much, for when the clocks of the servers that make and check tokens differ a little. It applies to exp, nbf and iat. A negative duration counts as none. By default no difference is allowed.

gaseto.new_rules() |> gaseto.allow_clock_skew(duration.seconds(30))

Accepts tokens without an exp (expiration) claim. If a token has one, it is still checked.

Refuses tokens longer than this many bytes, before any cryptography. A token can come from anyone, and checking it takes time in proportion to its length, so a very long token could be used to waste CPU time. The default is 8192 bytes, Gaseto’s own choice, which is more than most tokens need and matches a common limit for HTTP headers.

gaseto.new_rules() |> gaseto.allow_token_length(up_to: 16_384)

The aud (audience) claim: who the token is meant for. See with_audience.

Checks exp, nbf and iat against this time instead of the current time. Useful in tests.

Decodes a JSON footer, after checking it against the rules. The check protects the JSON parser from footers that are very large, deeply nested, or have many keys. The spec requires libraries to offer such a check for JSON footers (Storing JSON in the Footer).

let key_identifier_decoder = decode.at(["kid"], decode.string)
gaseto.decode_footer(footer, gaseto.default_footer_rules, key_identifier_decoder)

Decrypts a local token and checks it against the rules. The key must have the same version as the token. Tokens longer than 8192 bytes are refused unless the rules allow more, see allow_token_length.

case gaseto.decrypt(token, key, gaseto.new_rules()) {
  Ok(token) -> Ok(gaseto.subject(token))
  Error(error.Expired(_)) -> Error("Please log in again")
  Error(_) -> Error("Invalid token")
}

At most 8192 bytes and 512 keys, with no nested objects or arrays. No nesting is the spec’s recommended default (Storing JSON in the Footer). The length and key limits are Gaseto’s own.

Creates an encrypted local token.

let assert Ok(token) = gaseto.encrypt(claims, key)
// token == "v4.local.…"

Requires the token to have been made with this implicit assertion. An implicit assertion is data that is covered by the tag or signature but not stored in the token, so the reader has to know it already. See with_implicit_assertion (Implicit Assertions).

The exp (expiration) claim: when the token stops being valid. See with_expires_at.

Sets exp (expiration) to this long after the token is created (RFC 7519, exp). After that, the token is refused (Validators).

The footer, as raw bytes. It has been checked along with the token, unlike unverified_footer. It is often JSON text: decode it with decode_footer, or turn it into a String with bit_array.to_string. It is empty if the token has none. See with_footer.

Requires aud (audience) to be this value, so tokens meant for someone else are refused. See with_audience.

Requires sub (subject) to be this value, so only tokens about this subject are accepted. See with_subject.

Generates a new shared key. Generate a key once and keep it: a key generated each time your app starts would change on every restart, which makes all earlier tokens invalid. To store it, see local_key_to_hex.

let key = gaseto.generate_local_key(gaseto.PasetoV4)

Generates a new secret key. Get its public key with secret_key_to_public_key. Generate a key once and keep it, as with generate_local_key. To store it, see secret_key_to_hex.

let secret_key = gaseto.generate_secret_key(gaseto.PasetoV4)
let public_key = gaseto.secret_key_to_public_key(secret_key)

Requires jti (token identifier) to be this value. See with_token_identifier.

The iat (issued at) claim: when the token was made. See with_issued_at.

Requires iss (issuer) to be this value, so only tokens made by this issuer are accepted. See with_issuer.

The iss (issuer) claim: who made the token. See with_issuer.

Makes a shared key from 32 bytes written as hex.

let assert Ok(key) = gaseto.local_key_from_hex(gaseto.PasetoV4, key_hex)

The key as hex, as local_key_from_hex reads it. For how to manage keys, see Keys.

Leaves out exp (expiration), so the token never expires. Only use this when you really need it. new_rules refuses such tokens unless the reader uses allow_no_expiration.

New claims for a token. By default the token expires one hour after it is created, as the spec recommends (Default Expiration Claims), and iat is set to the time it is created.

let claims =
  gaseto.new_claims()
  |> gaseto.with_subject("user-42")
  |> gaseto.expires_in(duration.minutes(15))

Rules that require an exp claim, as the spec recommends (Default Expiration Claims), and check the times against the current time. A token is refused after its exp (expiration), before its nbf (not before), or if its iat (issued at) is in the future.

let rules =
  gaseto.new_rules()
  |> gaseto.issued_by("auth.example.com")
  |> gaseto.for_audience("api")

The nbf (not before) claim: when the token starts being valid. See with_not_before.

The whole payload, a JSON object. Read your own claims from it with a decoder.

json.parse(gaseto.payload(token), decode.at(["role"], decode.string))

Makes a public key from hex. Version 3 takes a 49-byte compressed P-384 point. Version 4 takes a 32-byte Ed25519 public key.

let assert Ok(public_key) = gaseto.public_key_from_hex(gaseto.PasetoV4, public_key_hex)

Makes a public key from a PEM file, as openssl pkey -pubout writes it.

let assert Ok(public_key) =
  gaseto.public_key_from_pem(gaseto.PasetoV4, public_key_pem)

The key as hex, as public_key_from_hex reads it.

Whether the token is local or public.

Makes a secret key from hex. Version 3 takes a 48-byte P-384 secret. Version 4 takes a 64-byte Ed25519 key: the seed followed by the public key.

let assert Ok(secret_key) = gaseto.secret_key_from_hex(gaseto.PasetoV4, secret_key_hex)

Makes a secret key from a PEM file: an Ed25519 key in PKCS #8 for version 4, or a P-384 key in SEC1 or PKCS #8 for version 3. openssl genpkey writes PKCS #8, and openssl ecparam -genkey writes SEC1.

let assert Ok(secret_key) =
  gaseto.secret_key_from_pem(gaseto.PasetoV4, secret_key_pem)

The key as hex, as secret_key_from_hex reads it. For how to manage keys, see Keys.

The public key that checks tokens signed with this secret key.

Creates a signed public token. Anyone can read its claims.

let assert Ok(token) = gaseto.sign(claims, secret_key)
// token == "v4.public.…"

The sub (subject) claim: who or what the token is about. See with_subject.

The jti (token identifier) claim: a unique identifier for the token. See with_token_identifier.

Reads the footer without checking the token. Use it to find which key to use, for example from a kid (key identifier) field. Do not trust anything else in it until the token has been decrypted or verified. It is empty if the token has no footer.

let key_identifier_decoder = decode.at(["kid"], decode.string)
let assert Ok(footer) = gaseto.unverified_footer(token)
let assert Ok(key_identifier) =
  gaseto.decode_footer(footer, gaseto.default_footer_rules, key_identifier_decoder)

Verifies a public token and checks it against the rules. The key must have the same version as the token. Tokens longer than 8192 bytes are refused unless the rules allow more, see allow_token_length.

let assert Ok(token) = gaseto.verify(token, public_key, rules)
gaseto.subject(token)

The token’s version.

Sets aud (audience): who the token is meant for, such as the service that should accept it. Readers require it with for_audience, so a token made for one service is refused by another (RFC 7519, aud).

Adds a claim of your own. The registered names (iss, sub, aud, exp, nbf, iat and jti) are refused when the token is created, because the spec reserves them (Registered Claims). Use their own functions instead.

Adding a claim with the same name again replaces the first value.

gaseto.new_claims() |> gaseto.with_claim("role", json.string("admin"))

Sets exp (expiration) to this time (RFC 7519, exp). After it, the token is refused (Validators). Fractions of a second are left out, as the spec recommends (Registered Claims).

Adds a footer: data stored in the token next to the claims. It is not encrypted, so anyone can read it, even in a local token, but it cannot be changed without breaking the token. A common use is a key identifier (kid), so the reader knows which key to use (Optional Footer, Key-ID Support). It can be any bytes, and is often JSON text. An empty footer means no footer.

gaseto.new_claims() |> gaseto.with_footer(<<"{\"kid\":\"key-1\"}":utf8>>)

Adds an implicit assertion: data that is covered by the tag or signature but not stored in the token. The reader must give the same value with expect_implicit_assertion, or the token is refused. Use it to tie a token to something both sides already know, such as a user identifier, without putting it in the token (Implicit Assertions).

Sets iat (issued at), when the token was made, to this time instead of the time the token is created (RFC 7519, iat). A token issued in the future is refused (Validators). Fractions of a second are left out, as the spec recommends (Registered Claims).

Sets iss (issuer): who made the token, such as your login service. Readers can require it with issued_by (RFC 7519, iss).

Sets nbf (not before): the token is refused before this time. Use it for a token that should only start working later (RFC 7519, nbf). Fractions of a second are left out, as the spec recommends (Registered Claims).

Sets sub (subject): who or what the token is about, usually a user identifier. Readers can require it with for_subject (RFC 7519, sub).

Sets jti (token identifier): a unique identifier for this token. A server can use it to remember tokens it has cancelled or already seen. Readers can require it with identified_by (RFC 7519, jti).