Enum AescryptError 

pub enum AescryptError {
    Io(Error),
    Crypto(String),
    Header(String),
    UnsupportedVersion(u8),
}

The error type returned by every fallible AES Crypt operation in this crate.

AescryptError is non-exhaustive in spirit: it discriminates four classes of failure (I/O, cryptographic, header/format, unsupported version) but the human-readable message inside Crypto and Header is part of the error display, not the structured API, and may be refined in patch releases.

Errors

All four variants are constructed by code inside this crate; downstream callers generally pattern-match on the variant and surface a friendly message based on the Display impl provided by thiserror.

See the variant → API table at the module level for which public APIs produce each variant.

Security

Error messages are written for human diagnostics. They never embed the password, derived keys, IVs, salts, or plaintext. Untrusted callers may safely log the Display form. Wrap-and-? is the recommended pattern; do not attempt to recover from Header by retrying with different inputs.

Variants

Io(Error)

An I/O operation on the underlying reader or writer failed.

This variant wraps std::io::Error verbatim and is produced by every public function that performs streaming reads or writes — including crate::encrypt(), crate::decrypt(), crate::read_version, and the lower-level helpers in crate::encryption / crate::decryption. Common causes: file not found, permission denied, broken pipe, premature EOF inside the header / session block / payload.

Crypto(String)

A cryptographic primitive returned an error.

Produced by:

• crate::derive_pbkdf2_key / crate::Pbkdf2Builder::derive_secure when the underlying pbkdf2 crate rejects its parameters.
• crate::derive_ackdf_key when the password is not valid UTF-8 (forwarded from crate::utilities::utf8_to_utf16le).
• crate::utilities::utf8_to_utf16le for non-UTF-8 password bytes.

The wrapped String is a short human-readable description and is part of the Display output only — it is not a stable machine-readable code.

Header(String)

A header, extension, or trailer in the AES Crypt file failed validation.

Triggered by, for example:

• Invalid magic bytes (header is not b"AES").
• Reserved byte after the version is not 0x00 for v1–v3.
• More than 256 extension blocks in a v2/v3 header (DoS guard).
• PBKDF2 iteration count outside PBKDF2_MIN_ITER ..= PBKDF2_MAX_ITER.
• Empty password supplied to crate::encrypt().
• Session-block HMAC mismatch (“session data corrupted or tampered”).
• Payload HMAC mismatch (“HMAC verification failed”).
• v3 PKCS#7 padding malformed (“v3: invalid PKCS#7 padding”).
• v0/v1/v2/v3 trailer length wrong (“expected … trailer”).

Security note: an HMAC failure is reported as Header(...) for historical reasons; treat it as authenticated-decryption failure and discard any plaintext already written to the output.

UnsupportedVersion(u8)

The file declares an AES Crypt format version this crate cannot handle.

Returned by crate::decryption::read_file_version when the version byte is > 3, and by the encryption-side crate::encryption::write_header / write_extensions / write_iterations when callers request a version < 3 (this crate writes v3 only). The contained u8 is the rejected version number.

Trait Implementations

impl Debug for AescryptError

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

Formats the value using the given formatter.

impl Display for AescryptError

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

Formats the value using the given formatter.

impl Error for AescryptError

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<&'static str> for AescryptError

fn from(msg: &'static str) -> Self

Converts to this type from the input type.

impl From<Error> for AescryptError

fn from(source: Error) -> Self

Converts to this type from the input type.