gaseto/error

ClaimFormatError

What is wrong with a registered claim in a token.

pub type ClaimFormatError {
  NotAString
  NotAnRfc3339Time
}

Constructors

```
NotAString
```
The spec defines the registered claims as strings (Registered Claims).
```
NotAnRfc3339Time
```
The spec requires times in RFC 3339, with an uppercase “T” and “Z” (Registered Claims).

FooterDecodingError

</>

Why decode_footer could not decode a footer: it broke a limit in FooterRules, or the decoder failed.

pub type FooterDecodingError {
  FooterTooLong(length: Int, max_length: Int)
  FooterTooDeep(depth: Int, max_depth: Int)
  FooterHasTooManyKeys(key_count: Int, max_keys: Int)
  FooterIsMalformed
  FooterDecodeFailed(error: json.DecodeError)
}

Constructors

FooterTooLong(length: Int, max_length: Int)

The footer is longer than FooterRules allows.

```
FooterTooDeep(depth: Int, max_depth: Int)
```
The footer is nested deeper than FooterRules allows.

FooterHasTooManyKeys(key_count: Int, max_keys: Int)

The footer has more keys than FooterRules allows.

```
FooterIsMalformed
```
The brackets or quotes do not match, so the footer is not valid JSON.
```
FooterDecodeFailed(error: json.DecodeError)
```
The footer passed the checks, but the decoder failed.

KeyLoadingError

</>

Why a key could not be loaded from hex or PEM.

pub type KeyLoadingError {
  NotHex
  WrongLength(expected: Int, found: Int)
  OutsideCurveRange
  NotACompressedPoint
  NotOnCurve
  PublicHalfDoesNotMatchSeed
  SmallOrderPublicKey
  InvalidPem
  UnexpectedKeyFailure(reason: String)
}

Constructors

```
NotHex
```
The key is not written as hex.
```
WrongLength(expected: Int, found: Int)
```
The key has the wrong number of bytes. The spec sets the size of a local key (version 3, Encrypt, version 4, Encrypt) and of a version 3 secret key (version 3, Sign) and public key (version 3, Verify). The version 4 key sizes come from Ed25519.
```
OutsideCurveRange
```
The version 3 secret key is out of range. Version 3 uses the P-384 elliptic curve (NIST SP 800-186, section 3.2.1.4), and a secret key is a number that must be at least 1 and less than the curve’s order, a fixed number that comes with the curve (FIPS 186-5, section 6.4.1).
```
NotACompressedPoint
```
A version 3 public key must start with 02 or 03, because the spec requires a compressed point (version 3, Verify).
```
NotOnCurve
```
The version 3 public key is not a point on the P-384 elliptic curve (NIST SP 800-186, section 3.2.1.4), so it cannot be a real public key.
```
PublicHalfDoesNotMatchSeed
```
The second half of a version 4 secret key is not the public key of its first half.
```
SmallOrderPublicKey
```
The version 4 public key is one of a few special values that would let anyone forge tokens for it. The spec writes the check as libsodium’s crypto_sign_verify_detached, which refuses these keys (version 4, Verify).
```
InvalidPem
```
The text is not one PEM key of the kind needed: an Ed25519 key for version 4, or a P-384 key for version 3. Keys protected by a password are not read.
```
UnexpectedKeyFailure(reason: String)
```
This should never happen. It means a bug in Gaseto or a library it uses. reason says which step failed.

TokenCreationError

</>

Why encrypt or sign could not create a token.

pub type TokenCreationError {
  ReservedClaimName(name: String)
  RepeatedKeyInClaim(name: String)
  UnexpectedCreationFailure(reason: String)
}

Constructors

```
ReservedClaimName(name: String)
```
A claim of your own uses one of the registered names (iss, sub, aud, exp, nbf, iat or jti). The spec reserves these names (Registered Claims).
```
RepeatedKeyInClaim(name: String)
```
A claim of your own holds an object that repeats a key. The spec requires unique key names (Payload Processing).
```
UnexpectedCreationFailure(reason: String)
```
This should never happen. It means a bug in Gaseto or a library it uses. reason says which step failed.

TokenFormatError

</>

Why a token’s format cannot be read. unverified_footer returns it directly; decrypt and verify wrap it in InvalidFormat.

pub type TokenFormatError {
  UnknownVersion(version: String)
  UnsupportedVersion(version: String)
  UnknownPurpose(purpose: String)
  WrongNumberOfSegments
  EmptyFooterSegment
  NotBase64Url
  BodyTooShort
}

Constructors

```
UnknownVersion(version: String)
```
The version is not one the spec defines (Message Format).
```
UnsupportedVersion(version: String)
```
The token uses version 1 or 2. The spec defines them, but Gaseto does not support them because the spec deprecates them (version 1, version 2).
```
UnknownPurpose(purpose: String)
```
The purpose is not local or public, the only ones the spec allows (Message Format).
```
WrongNumberOfSegments
```
A token has three or four parts separated by dots (Message Format).
```
EmptyFooterSegment
```
The token ends with a dot but no footer. The spec only adds the dot when there is a footer (version 4, Encrypt).
```
NotBase64Url
```
A part is not strict, unpadded base64url, as the spec requires (Base64 Decoding).
```
BodyTooShort
```
The token is too short to hold its nonce, tag or signature.

TokenValidationError

</>

Why decrypt or verify refused a token.

pub type TokenValidationError {
  TokenTooLong(length: Int, max_length: Int)
  InvalidFormat(error: TokenFormatError)
  UnexpectedVersion(expected: String, found: String)
  UnexpectedPurpose(expected: String, found: String)
  TokenNotAuthentic
  InvalidPayload
  InvalidClaim(name: String, error: ClaimFormatError)
  MissingExpiration
  Expired(expired_at: timestamp.Timestamp)
  NotYetValid(valid_from: timestamp.Timestamp)
  IssuedInTheFuture(issued_at: timestamp.Timestamp)
  UnexpectedClaim(
    name: String,
    expected: String,
    found: option.Option(String),
  )
  UnexpectedValidationFailure(reason: String)
}

Constructors

```
TokenTooLong(length: Int, max_length: Int)
```
The token is longer than the rules allow. See allow_token_length.
```
InvalidFormat(error: TokenFormatError)
```
The token cannot be read.
```
UnexpectedVersion(expected: String, found: String)
```
The token’s version is not the key’s version, for example "v4" and "v3". The spec requires a key to be used only with its own version (Algorithm Lucidity).
```
UnexpectedPurpose(expected: String, found: String)
```
A "local" token was given where a "public" one was expected, or the other way around. The spec requires a key to be used only for its own purpose (Algorithm Lucidity).
```
TokenNotAuthentic
```
The tag or signature does not match. Either the token was changed, or the key or implicit assertion is wrong. On purpose, it does not say which.
```
InvalidPayload
```
The payload is not UTF-8 text, is not a JSON object, or repeats a key. The spec requires a JSON object with unique key names (Payload Processing).

InvalidClaim(name: String, error: ClaimFormatError)

A registered claim has the wrong format.

```
MissingExpiration
```
The token has no exp claim. The spec recommends requiring one by default (Default Expiration Claims), so new_rules does. Use allow_no_expiration to accept such tokens.

Expired(expired_at: timestamp.Timestamp)

The token expired at this time.

```
NotYetValid(valid_from: timestamp.Timestamp)
```
The token is not valid until this time (its nbf claim).
```
IssuedInTheFuture(issued_at: timestamp.Timestamp)
```
The token says it was issued in the future (its iat claim).

UnexpectedClaim(
  name: String,
  expected: String,
  found: option.Option(String),
)

A claim does not have the value the rules expect.

```
UnexpectedValidationFailure(reason: String)
```
This should never happen. It means a bug in Gaseto or a library it uses. reason says which step failed.

gaseto - v1.0.0

Types

ClaimFormatError

Constructors

FooterDecodingError

Constructors

KeyLoadingError

Constructors

TokenCreationError

Constructors

TokenFormatError

Constructors

TokenValidationError

Constructors