Enum PqfileError 

#[non_exhaustive]
pub enum PqfileError {
    Io(Error),
    InvalidMagic,
    UnsupportedVersion(u8),
    UnsupportedKem(u16),
    KemVariantMismatch {
        key: u16,
        file: u16,
    },
    EncryptionFailure,
    DecryptionFailure,
    InvalidPem(String),
    InvalidKeyLength {
        expected: usize,
        got: usize,
    },
    OutputExists(PathBuf),
    WrongPassphrase,
    PassphraseRequired,
    PassphraseMismatch,
    InvalidSignature,
    SignatureVerificationFailed,
    NoMatchingRecipient {
        slots_tried: usize,
    },
    KeyRevoked {
        fingerprint: String,
        reason: String,
    },
    CompressionNotSupported,
    LegacyKeyFormat,
    ShareVerificationFailed,
    KdfLimitExceeded {
        m_kib: u32,
        t: u32,
        max_m_kib: u32,
        max_t: u32,
    },
    Truncated,
    KeyfileRequired,
    KeyfileNotRequired,
    UnsupportedHeaderFlags(u8),
    Fido2Required,
    Fido2NotRequired,
    CertNotValid {
        not_before: u64,
        not_after: u64,
        now: u64,
    },
    CertUseNotPermitted {
        required: u8,
        allowed: u8,
    },
    CertRevoked {
        cert_id: String,
        reason: String,
    },
    WebauthnPrfRequired,
    WebauthnPrfNotRequired,
    SealedSenderAuthFailed,
}

Errors returned by all pqfile operations.

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.

Io(Error)

Underlying I/O error.

InvalidMagic

File does not begin with the PQFL magic bytes.

UnsupportedVersion(u8)

Version byte in the header is not recognized.

UnsupportedKem(u16)

KEM variant field in the header is not recognized.

KemVariantMismatch

The decryption key uses a different KEM variant than the file was encrypted with.

Fields

key: u16

KEM variant identifier of the supplied private key.

file: u16

KEM variant identifier recorded in the file header.

EncryptionFailure

An encryption or key-encapsulation operation failed.

DecryptionFailure

AEAD authentication tag did not verify; ciphertext is corrupt or tampered.

InvalidPem(String)

PEM data could not be parsed.

InvalidKeyLength

Key material has an unexpected byte length.

Fields

expected: usize

Expected byte length.

got: usize

Actual byte length encountered.

OutputExists(PathBuf)

Output file already exists and --force was not specified.

WrongPassphrase

Passphrase did not decrypt the key, or the encrypted key body is corrupt.

PassphraseRequired

Operation requires a passphrase but none was supplied.

PassphraseMismatch

New-passphrase confirmation did not match.

InvalidSignature

Signature bytes are malformed (wrong length or structure).

SignatureVerificationFailed

ML-DSA signature is well-formed but does not verify against the data.

NoMatchingRecipient

None of the recipient slots in a v4/v7/v8/v9 file matched the supplied private key.

Fields

slots_tried: usize

Number of recipient slots that were attempted during decryption.

KeyRevoked

The key has been explicitly revoked.

Fields

fingerprint: String

Colon-separated hex fingerprint of the revoked key.

reason: String

Human-readable reason supplied at revocation time.

CompressionNotSupported

v6 compressed files require the zstd feature, which is absent in this build.

LegacyKeyFormat

The private key was encrypted with legacy Argon2id parameters (p=1, pqfile < 4.0). Run pqfile repassphrase --from-legacy to upgrade it before use.

ShareVerificationFailed

Shamir share fingerprints did not agree; shares may be from different keys.

KdfLimitExceeded

Argon2id parameters in a v10 passphrase-only file exceed the configured ceiling.

A crafted file could specify extreme Argon2 parameters to force excessive memory or CPU use on decryption. The ceiling is checked before the KDF runs. Raise --max-kdf-mem / --max-kdf-time flags to accept a higher cost, or reject the file.

Fields

m_kib: u32

Memory cost (KiB) requested by the file.

t: u32

Time cost (iterations) requested by the file.

max_m_kib: u32

Maximum memory cost (KiB) the caller will allow.

max_t: u32

Maximum time cost the caller will allow.

Truncated

The .pqf stream ended without a terminal chunk (is_last flag never seen). The file was most likely truncated during download or transfer; re-downloading is the appropriate recovery action. Distinguished from [DecryptionFailure] which indicates bytes are present but the authentication tag is wrong.

KeyfileRequired

The v10 file was encrypted with a keyfile second factor but none was supplied.

KeyfileNotRequired

A keyfile was supplied but the v10 file was not encrypted with one. Failing loudly here avoids silently deriving a wrong key (which would surface as an opaque authentication failure) and tells the caller the keyfile is not protecting this file.

UnsupportedHeaderFlags(u8)

The v10 header carries feature flag bits this build does not understand. The file was likely produced by a newer pqfile; upgrade to decrypt it.

Fido2Required

The v10 file was encrypted with a FIDO2 hardware token second factor but none was supplied (or a keyfile was supplied instead).

Fido2NotRequired

A FIDO2 token was supplied but the v10 file was not encrypted with one (or was encrypted with a keyfile instead). Mirrors KeyfileNotRequired: failing loudly here avoids silently deriving a wrong key.

CertNotValid

A certificate’s signature verified, but now fell outside its validity window.

Fields

not_before: u64

Validity window start, Unix seconds (inclusive).

not_after: u64

Validity window end, Unix seconds (inclusive).

now: u64

The time the certificate was checked against, Unix seconds.

CertUseNotPermitted

A certificate was presented for a use its allowed_use bitmask does not permit.

Fields

required: u8

Bitmask of crate::cert::cert_use flags the caller required.

allowed: u8

Bitmask of crate::cert::cert_use flags the certificate allows.

CertRevoked

A certificate presented as a recipient or verifying key appears in a verified crate::cert::RevocationList the caller chose to consult.

Fields

cert_id: String

Colon-separated hex prefix of the revoked certificate’s crate::cert::cert_id.

reason: String

Human-readable reason supplied at revocation time.

WebauthnPrfRequired

The v10 file was encrypted with a WebAuthn prf extension second factor but none was supplied (or a different second factor was supplied instead). Browser-native equivalent of Fido2Required.

WebauthnPrfNotRequired

A WebAuthn prf output was supplied but the v10 file was not encrypted with one (or was encrypted with a different second factor instead). Mirrors Fido2NotRequired.

SealedSenderAuthFailed

A crate::sealed_sender deniable-authentication tag did not verify against the claimed sender’s identity key. Unlike SignatureVerificationFailed, this only means the specific recipient’s own key material could not reproduce the tag - by design, no third party (including one holding the sender’s identity public key) can distinguish “wrong sender” from “the true recipient forged this” after the fact.

Implementations

impl PqfileError

pub fn code(&self) -> u32

Stable numeric code for this error, as emitted in the CLI’s --json error output and documented in docs/ERROR_CODES.md.

Codes are append-only: new variants are always assigned new codes, and existing codes are never reused or reassigned. The match below is deliberately exhaustive (no _ arm) so adding a variant without assigning it a code is a compile error rather than a silent fallthrough.

Trait Implementations

impl Debug for PqfileError

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

Formats the value using the given formatter.

impl Display for PqfileError

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

Formats the value using the given formatter.

impl Error for PqfileError

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 From<Error> for PqfileError

fn from(source: Error) -> Self

Converts to this type from the input type.