Exceptions

AegisQ defines a hierarchy of exceptions that map to specific cryptographic failure modes. All exceptions can be imported from the top-level aegisq package.

Exception Hierarchy

AegisQError(Exception)                                Base exception
├── DecapsulationError(AegisQError)                   Exported structural decapsulation error type
├── DecryptionError(AegisQError)                      AES-GCM auth tag failed (tampered or wrong key)
├── InvalidParameterError(AegisQError)                Incorrect parameter sizes
├── KeySerializationError(AegisQError)                Malformed PEM / JSON / magic / version
├── RngError(AegisQError)                             OS CSPRNG unavailable
└── SessionExpiredError(AegisQError)                  Use of a closed EphemeralSession

Exception Details

AegisQError

The base exception for all AegisQ errors. Catch this to handle any AegisQ-specific error.

DecapsulationError

Exported for structural decapsulation failures. The current core reports incorrect key/capsule sizes as InvalidParameterError, not DecapsulationError. Neither exception is raised solely for invalid contents of a correctly sized capsule — see implicit rejection below.

DecryptionError

Raised when AES-GCM authentication tag verification fails. This means either:

• The encrypted payload was tampered with in transit
• The wrong secret key was used for decryption
• The capsule was invalid, causing ML-KEM to return a pseudorandom key (implicit rejection), which in turn causes AES-GCM to fail

InvalidParameterError

Raised when parameter sizes don’t match the expected values for the security level (e.g., providing a 768-byte public key when ML-KEM-1024 expects 1568 bytes). Inherits from AegisQError, not ValueError. Catch it explicitly or catch AegisQError.

KeySerializationError

Raised by the file-based key persistence helpers in aegisq.keys when a PEM, JSON, magic, or version header is malformed or missing. Distinguished from DecryptionError (which fires when the password is wrong): KeySerializationError means the structure of the file is invalid, regardless of password correctness.

RngError

Raised when the operating system’s CSPRNG (Cryptographically Secure Pseudo-Random Number Generator) is unavailable. This is extremely rare and typically indicates a system-level issue.

SessionExpiredError

Raised by EphemeralSession when encrypt() or decrypt() is called after the session has been closed (either explicitly via close() or implicitly via context-manager exit). The ephemeral secret key has been discarded at that point, so the operation cannot proceed.

Error Handling Example

from aegisq import (
    AegisCipher,
    SecurityLevel,
    AegisQError,
    DecryptionError,
    InvalidParameterError,
)

cipher = AegisCipher(level=SecurityLevel.ML_KEM_768)
keypair = cipher.generate_keypair()

# Encrypt some data
package = cipher.encrypt(b"Sensitive data", keypair.public_key)

# --- Handling decryption errors ---
try:
    plaintext = cipher.decrypt(package, keypair.secret_key)
except DecryptionError:
    # AES-GCM auth tag failed: payload was tampered with or wrong key
    print("Decryption failed: data integrity check failed")
except InvalidParameterError:
    # Wrong key/package size for this security level
    print("Invalid parameter: check key and package sizes")
except AegisQError:
    # Catch-all for any other AegisQ error
    print("An unexpected cryptographic error occurred")

Implicit Rejection

ML-KEM’s decapsulate() never raises an exception for invalid capsule contents. Instead, it silently returns a pseudorandom key (FIPS 203, Algorithm 17). When using AegisCipher, this pseudorandom key causes AES-GCM decryption to fail, which surfaces as a DecryptionError. This design prevents Chosen Ciphertext Attacks (CCA) by not revealing whether a capsule was valid or invalid.

Importing Exceptions

All exceptions are available from the top-level package:

from aegisq import (
    AegisQError,
    DecapsulationError,
    DecryptionError,
    InvalidParameterError,
    KeySerializationError,
    RngError,
    SessionExpiredError,
)