NewWe open-sourced 50+ Laravel packages
Custom AI apps, agents and automation — Roundly ConsultingRoundly
All packages

Everything the package throws extends RoundlyConsulting\Crypto\Exceptions\CryptoException, an abstract RuntimeException. Catch it broadly, or a subtype to react precisely — a common pattern is to re-wrap it as your own domain exception:

use RoundlyConsulting\Crypto\Exceptions\CryptoException;
use RoundlyConsulting\Crypto\Signature\Algorithm;

try {
    $claims = $jws->verify($token, $verifier, Algorithm::RS256);
} catch (CryptoException $e) {
    // any crypto failure — malformed token, algorithm mismatch, bad signature, weak key, …
    throw new TokenRejected(previous: $e);   // your own domain exception
}

Hierarchy

RuntimeException
└── CryptoException (abstract)
    ├── Codec\InvalidEncodingException
    ├── Aead\DecryptionFailedException
    ├── Aead\InvalidAeadParameterException
    ├── Random\InvalidLengthException
    ├── Signature\AlgorithmMismatchException
    ├── Signature\InvalidSignatureException
    ├── Signature\KeyLoadException
    ├── Signature\WeakKeyException
    ├── Jose\MalformedTokenException
    ├── Jose\MalformedJwkException
    ├── Jose\ClaimMismatchException
    │   ├── Jose\TokenExpiredException
    │   └── Jose\TokenNotYetValidException
    ├── X509\MalformedCertificateException
    ├── X509\InvalidChainException
    ├── X509\InvalidLeewayException
    ├── Asn1\MalformedDerException
    ├── Cose\MalformedCborException
    ├── Cose\UnsupportedAlgorithmException
    └── Otp\InvalidOtpParameterException

When each is thrown

ExceptionThrown when
Codec\InvalidEncodingExceptionA base64url, base64, base32 or hex string is invalid or non-canonical.
Aead\DecryptionFailedExceptionopen() or decrypt() cannot authenticate the input — a wrong key, nonce or associated data, a changed ciphertext or tag, or input too short to hold a tag. One fixed message for every cause.
Aead\InvalidAeadParameterExceptionAn AES-256-GCM key is not 32 bytes or a nonce not 12 bytes — a programming error, never a property of the data — or OpenSSL refuses the cipher.
Random\InvalidLengthExceptionA requested random length is out of range, or an alphabet is empty or not valid UTF-8.
Signature\AlgorithmMismatchExceptionA key type does not match the algorithm, or a token’s alg does not match the pinned one.
Signature\InvalidSignatureExceptionA signature fails to verify, or ECDSA DER cannot be normalised.
Signature\KeyLoadExceptionOpenSSL cannot load, parse or generate a key, a key is the wrong type, or a loader cannot find its file, disk or config value or cannot write a generated key.
Signature\WeakKeyExceptionKey material is too weak or out of range — HMAC secret (or one shorter than the HS384 / HS512 hash size), RSA size or exponent, unsupported curve.
Jose\MalformedTokenExceptionA compact JWS is structurally invalid — segments, JSON, a header or payload that is not a JSON object, oversize, crit.
Jose\MalformedJwkExceptionA JWK is malformed, oversized, or carries private or unknown members.
Jose\ClaimMismatchExceptionA claim is absent or has the wrong type (base class of the two below).
Jose\TokenExpiredExceptionassertTemporal() finds that exp has passed.
Jose\TokenNotYetValidExceptionassertTemporal() finds nbf or iat in the future.
X509\MalformedCertificateExceptionA certificate cannot be read or parsed, is oversized, carries bytes after its DER, or has an unsupported key type.
X509\InvalidChainExceptionA chain is empty, longer than 10 certificates, or indexed out of range.
X509\InvalidLeewayExceptionA validity predicate receives a negative leeway.
Asn1\MalformedDerExceptionDER input violates X.690’s canonical rules or the decoder’s caps.
Cose\MalformedCborExceptionCBOR or authenticator data is malformed or non-canonical, or a COSE key field has the wrong CBOR type.
Cose\UnsupportedAlgorithmExceptionAn unknown COSE algorithm, key type or curve — or EdDSA without ext-sodium.
Otp\InvalidOtpParameterExceptionOTP digits, period or window are out of range.

Catching ClaimMismatchException also catches both temporal failures. Es, Rs and EdDSA verification return false for a wrong-length or malformed signature rather than throwing; inside Jws::verify() a failed signature surfaces as InvalidSignatureException.

Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

More ways to support, including crypto

By donating, you agree to our donation terms.

Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.