Enum Error 

#[non_exhaustive]
pub enum Error {
    InvalidBase64,
    InvalidJson(&'static str),
    InvalidHeader(&'static str),
    UnsupportedAlgorithm,
    AlgorithmNotAllowed,
    InvalidKey(&'static str),
    KeyAlgorithmMismatch,
    InvalidSignature,
    DecryptionFailed,
    UnknownCritical,
    TokenExpired,
    TokenNotYetValid,
    InvalidClaim(&'static str),
    RandomnessUnavailable,
    InvalidFormat(&'static str),
    NoMatchingKey,
    MultipleMatchingKeys,
}

Errors returned by polyjose.

Each variant has a stable code. The code is the contract shared by every binding and every conformance vector (ADR 0007), so it never changes once released. New variants may be added (the enum is #[non_exhaustive]).

No variant carries key material or bytes from the input being processed. Any detail is a &'static str written into polyjose itself, so Debug and Display never echo untrusted input or secrets (ADR 0007).

use polyjose::Error;

let err = Error::InvalidClaim("aud");
assert_eq!(err.code(), "InvalidClaim");
assert!(Error::CODES.contains(&err.code()));

// Match on the code (or the variant), never on the message text.
assert_eq!(Error::DecryptionFailed.code(), "DecryptionFailed");

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

InvalidBase64

Input is not valid unpadded base64url (RFC 7515 §2, RFC 4648 §5).

Raised when decoding any base64url-encoded JOSE component (RFC 7515 §5.2 steps 2, 6 and 7; RFC 7516 §5.2) or JWK member.

In JWS verification the payload’s base64url (skipped for b64: false, RFC 7797 §3) is checked after the protected header is decoded and before the whole-header checks (ADR 0048, clarifying ADR 0026 §2).

InvalidJson(&'static str)

Input is not a valid JSON object of the expected shape.

A JOSE Header must be a completely valid JSON object (RFC 7515 §5.2 step 3, RFC 7516 §5.2 step 3), and so must a JWT Claims Set (RFC 7519 §7.2 step 10) and a JWK (RFC 7517 §4). That includes a member name occurring twice in one object, a JOSE Header included (RFC 7515 §5.2 step 4, RFC 7516 §5.2 step 4; ADR 0041 §1). The detail names the failure category only, never the offending input.

InvalidHeader(&'static str)

The JOSE Header is structurally invalid.

For example: a required parameter such as alg is missing (RFC 7515 §4.1.1, RFC 7516 §4.1.1–§4.1.2), a registered parameter has the wrong type, the protected and unprotected headers share a name (RFC 7515 §5.2 step 4, §7.2.1; RFC 7516 §5.2 step 4), crit is malformed or not in the protected header (RFC 7515 §4.1.11, RFC 7516 §4.1.13), or b64 breaks the RFC 7797 §3/§6 rules.

A member name that occurs twice inside one header object is not this error: the JSON layer rejects it first, as Error::InvalidJson (ADR 0041 §1, amending ADR 0026 §2 step 4).

In JWS verification (ADR 0026 §2 as clarified by ADR 0048), the per-parameter type checks and the crit syntax checks run while the protected header is decoded, so before the payload’s base64url is checked. The whole-header checks (crit naming an absent parameter, a missing alg, overlapping protected and unprotected headers, b64 placement) run after it.

UnsupportedAlgorithm

The alg or enc value does not name an algorithm polyjose implements.

The JWS is invalid if alg is not a supported algorithm (RFC 7515 §4.1.1); the same holds for JWE alg and enc (RFC 7516 §4.1.1–§4.1.2). The rejected value is not echoed.

Also a well-formed key or key encoding that polyjose does not support, e.g. encrypted PKCS#8 (RFC 5958 §3) or multi-prime RSA keys (ADR 0018, ADR 0067 §3).

AlgorithmNotAllowed

The algorithm is supported but not in the caller’s allow-list.

Libraries must let the caller specify the accepted algorithms and must not use any other (RFC 8725 §3.1, §2.1; ADR 0007). none is never allowed.

InvalidKey(&'static str)

The key is malformed or too weak for any use.

For example: missing or malformed JWK members (RFC 7517 §4, RFC 7518 §6), an RSA modulus under 2048 bits (RFC 7518 §3.3, §3.5, §4.2), an HMAC key shorter than the hash output (RFC 7518 §3.2), or an EC point that is not on its curve (RFC 8725 §3.4), and malformed or non-canonical DER/PEM key encodings (ADR 0018). The detail never contains key material.

KeyAlgorithmMismatch

The key is valid but not for this algorithm or operation.

Each key must be used with exactly one algorithm (RFC 8725 §3.1), which blocks the RS256→HS256 confusion attack (RFC 8725 §2.1). Also raised when the JWK alg, use or key_ops members forbid the operation (RFC 7517 §4.2–§4.4).

InvalidSignature

A JWS signature or MAC did not validate (RFC 7515 §5.2 step 8).

DecryptionFailed

JWE decryption failed.

Every decryption failure maps to this one variant, whatever the internal cause, and it deliberately carries no detail. The recipient must not distinguish format, padding and length errors (RFC 7516 §11.5), so no padding or key-unwrap oracle is exposed (RFC 7516 §5.2, ADR 0007).

UnknownCritical

crit lists an extension polyjose does not understand.

Recipients must reject the JWS/JWE in that case (RFC 7515 §4.1.11, RFC 7516 §4.1.13). The unknown name is not echoed.

TokenExpired

The JWT exp time has passed, allowing for the configured clock skew (RFC 7519 §4.1.4).

TokenNotYetValid

The JWT nbf time has not been reached yet, allowing for the configured clock skew (RFC 7519 §4.1.5).

InvalidClaim(&'static str)

A JWT claim is missing, malformed or failed validation.

The detail names the claim (for example "aud"), never its value. Covers RFC 7519 §4.1 and §7.2 and the RFC 8725 §3.8–§3.9 issuer and audience checks.

RandomnessUnavailable

The operating-system CSPRNG could not supply random bytes.

Keys, IVs and CEKs require a cryptographically secure source (RFC 7515 §10.1, RFC 8725 §3.5); polyjose never falls back to a weaker one (ADR 0005).

InvalidFormat(&'static str)

The serialization does not have the shape its RFC requires, or the input exceeds a configured limit (ADR 0026 §1, §7).

For JWS: a compact JWS without exactly three dot-separated parts (RFC 7515 §7.1, §5.2 step 1); a JSON JWS that is not an object of the RFC 7515 §7.2.1/§7.2.2 shape (for example a missing or non-string signature, an empty signatures array, signatures mixed with top-level signature members, or an empty-string protected); a payload that is present or absent against the detached-content mode (RFC 7515 Appendix F); a b64: false payload that the serialization cannot carry (RFC 7797 §5.2, §5.3); or an input over the size or signature-count limits.

For JWE (RFC 7516 §5.2 step 1, §7.1, §7.2): a compact JWE without exactly five dot-separated parts (§7.1, §5.2 step 1); a JSON JWE that is not an object of the §7.2.1/§7.2.2 shape (for example a missing ciphertext, an empty recipients array, a flattened JWE with recipients, or a member of the wrong JSON type); an input over the size or recipient-count limits; and, on encrypt, a request the chosen serialization cannot carry (compact with more or fewer than one recipient, with AAD or with an unprotected header, §7.1).

JSON syntax errors stay Error::InvalidJson and base64url errors stay Error::InvalidBase64. The detail names the rule, never the input.

NoMatchingKey

No key of the caller’s JWK Set may verify this JWS (ADR 0029 §4).

Raised by JWT verification against a JWK Set when no member is a candidate for the JWS Protected Header’s alg and kid: none has a matching key type and curve, JWK alg, use, key_ops and kid (RFC 7515 §4.1.4, §6; RFC 7517 §4.2–§4.5, §5; RFC 8725 §3.1), or more members match than the policy’s candidate bound, which is checked before any signature is computed (ADR 0029 §4). Neither the kid nor any key is echoed.

MultipleMatchingKeys

More than one key of a JWK Set matches the caller’s selector (ADR 0054 §4, §5).

A JWK Set’s keys have no order of preference (RFC 7517 §5.1), and distinct kid values within a set are only a SHOULD (RFC 7517 §4.5), so two members can share a kid. polyjose refuses to guess between two equally valid members.

Only JwkSet::select (and the bindings’ jwks_select) raises it. JWT verification against a set never does: it tries every candidate in order, and more candidates than its bound is Error::NoMatchingKey (ADR 0029 §4). Neither the selector nor any key is echoed.

Implementations

impl Error

pub const CODES: &'static [&'static str]

Every stable error code, in declaration order.

Bindings and the conformance harness use this to check that an expected error value names a real code.

pub fn code(&self) -> &'static str

The stable, cross-platform code for this error (ADR 0007).

Match on this, not on the Display text: the code never changes, while the message may be reworded.

Trait Implementations

impl Clone for Error

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

Human-readable text: a fixed phrase per variant, followed by the &'static str detail for the variants that carry one.

The text holds nothing but string literals from polyjose, so it never contains input or key material (ADR 0007). It is not stable: match on Error::code instead.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Error

impl Error for Error

No variant has a source: an error never wraps a dependency’s error, whose message could quote input (ADR 0007). In particular Error::DecryptionFailed exposes no cause, so callers cannot tell decryption failures apart (RFC 7516 §11.5).

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl PartialEq for Error

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Error