Skip to main content

DecryptError

Enum DecryptError 

Source
#[non_exhaustive]
pub enum DecryptError {
Show 13 variants Classify(DetectError), NotEncrypted, EmptyPassword, UnsupportedPgp, Odf12Fatal, WrongPassword, BadParameters(BadParameter), Internal(String), HostCannotAllocate { site: AllocationSite, requested_bytes: usize, }, Inflate(String), Zip(String), OutputLimit { limit: u64, }, Io(Error),
}
Available on crate feature crypto-ops only.
Expand description

Failures from decrypt.

Variants (Non-exhaustive)§

This enum is marked as 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.
§

Classify(DetectError)

classify refused the package before decryption began.

§

NotEncrypted

The package classified as Mode::Plain — there is nothing to decrypt.

A malformed META-INF/manifest.xml also arrives here rather than as a parse error: LibreOffice discards every row on an XML failure and still opens the package, so this crate classifies it plain.

§

EmptyPassword

The password was empty. Checked before classify runs, so it implies nothing about whether bytes is a valid or encrypted package.

§

UnsupportedPgp

The package is PGP-wrapped. Screened across every encrypted row, not only the latch row. The wrapped key material is available from crate::Classification::pgp_keys for handing to an OpenPGP implementation.

Not “a later arc”. The plans said that for a while and it was the wrong reason, because it implies the work is merely unscheduled. Two things make it infeasible in this function rather than unscheduled:

  • There is no surface to pass a key through. The signature is decrypt(bytes: &[u8], password: &str). A PGP-wrapped package is opened with a private key, which arrives as a keyring path, a passphrase over that key, an agent socket, or a smartcard PIN prompt – none of which a &str password can carry, and none of which a library should invent a side channel for.
  • The cost is the crate’s whole premise. Detection-only is about two dozen crates and the point of the default; an OpenPGP implementation is a dependency tree of a different order, for a path classify already reports without it.

So the honest scope statement is this API shape cannot express it, and the honest offer is the one above: classify surfaces the wrapped key material, and a caller who has an OpenPGP stack does the unwrap.

§

Odf12Fatal

LibreOffice LookForUnexpectedODF12Streams plus a root version >= 1.2. classify reports the flag without failing; decrypt refuses so it does not return a zip LO would not open.

§

WrongPassword

The key did not open the package.

Cannot distinguish a wrong password from corrupted ciphertext. On AES-CBC and Blowfish it is decided by a checksum over only the first 1 KiB of the decrypted stream, so damage past that window surfaces as DecryptError::Inflate instead.

§

BadParameters(BadParameter)

The package’s own encryption settings were refused: which setting, the value the file declares, and what was allowed (BadParameter). It carries no text from the file, so a caller may match on it and quote its numbers. Changed in 0.1.0-rc.13 from a String, which could carry a row’s manifest:full-path unbounded.

A verdict on the manifest, and the same verdict on every machine. A cost this crate accepted and the host then could not meet is DecryptError::HostCannotAllocate, not a bad parameter.

§

Internal(String)

Deliberately NOT the BadParameters analogue: that reports a hostile value read out of the manifest, and this reports an invariant of our own that something upstream was supposed to have enforced. Reaching it means a guard moved, not that the input was bad.

It exists for the same reason EncryptError::Internal does: a library must not abort its caller’s process to report a condition it could return.

§

HostCannotAllocate

This host could not allocate the working memory key derivation needs.

Not a statement about the package. The manifest may be entirely legal, and the same bytes may decrypt on a machine with more free memory — so retrying, or retrying elsewhere, is meaningful, and re-downloading the file is not. Deliberately not DecryptError::BadParameters, which reports a manifest field this crate refuses to act on at all, and deliberately not DecryptError::Internal, which reports an invariant of ours; how much memory this machine had free at this moment is neither.

The shortfall is returned rather than aborted on because an abort skips unwinding, and Drop is this crate’s only zeroizing primitive — the allocation happens with the password digest and the derived key both live.

Key derivation was the first allocation here to become fallible, and an earlier version of this doc predicted that when the others followed, the variant would want a field naming which one failed. They followed in 0.1.0-rc.5, and AllocationSite is that field. It was a breaking change to the variant and was accepted.

DecryptError itself is #[non_exhaustive], but the variant is not, deliberately: a variant nobody outside the crate can construct is a variant nobody outside the crate can write a test against, and the binary’s own exit-code test needs to construct it.

Fields

§site: AllocationSite

Which allocation could not be made.

§requested_bytes: usize

The size that could not be obtained — in every case a number the package itself supplied, not a ceiling of this crate’s: manifest:argon2-memory rounded to whole blocks, manifest:size, manifest:key-size, or a member’s own length.

§

Inflate(String)

The decrypted stream was not valid DEFLATE, or did not inflate to the length manifest:size promised.

Never means “wrong password”: it is reached only after a GCM tag or a checksum has already accepted the key. It means the ciphertext is damaged past the point those checks cover.

§

Zip(String)

A zip failure, either reading the input or writing the rebuilt package — plus the manifest rewrite’s parse failure, which is the one thing here that is not a zip error.

The rewrite’s serialization failures are no longer among them: they are DecryptError::Internal as of 0.1.0-rc.5, because they can only ever report a broken invariant of ours, never anything about the package. The doc used to say this variant carried “every quick-xml failure”, and that sentence is what prompted the split — a name needing a disclaimer is usually a name covering two things. The string is a diagnostic; do not match on it.

It may quote package-controlled text, so treat it as untrusted when logging or displaying it. The zip half cannot: those are rendered by an internal helper that quotes only text this crate chose, never the zip crate’s own Display. The quick-xml half can — IllFormedError::UnmatchedEndTag carries an element name taken from the manifest — and unlike crate::DetectError::Inconsistent it is not elided to a bound.

§Why it is not elided

Because the path is unreachable, and an elision would imply a live threat where there is none. The argument, since a claim of unreachability has to carry one:

strip_manifest can only return this from its read side — its writer is a Vec<u8>, whose write_all cannot fail. So a Zip from the rewrite means read_event_into errored. But manifest::parse_manifest maps any read error to an empty row list, plus three more conditions strip_manifest does not have, so parse_manifest returning rows means no read error occurred. Empty rows means classify reports Mode::Plain, and decrypt refuses that with DecryptError::NotEncrypted long before the rewrite runs.

The two readers are configured differently — parse_manifest sets expand_empty_elements, the rewrite leaves it at its default — which is the only way they could disagree about what is ill-formed. They cannot: in quick-xml 0.38.4 an expanded empty element pushes onto opened_starts and is popped by the next read without consuming input, so the stack every end-tag check consults is identical in both modes at every byte boundary.

That argument is version-scoped to quick-xml 0.38.4, which is why classify_accepting_a_manifest_implies_the_rewrite_accepts_it pins it rather than leaving it as prose a dependency bump could quietly falsify. If that test ever fails, this variant needs the elision crate::DetectError::Inconsistent already has.

§

OutputLimit

The plaintext inflated from encrypted members would exceed DecryptLimits::max_output_bytes.

Raised before key derivation when manifest:size already says so, and otherwise as the running count passes the limit. Members stored unencrypted are copied, not inflated by this crate, and do not count: they are bounded by the input.

A policy of this crate, not a rule of the format. ODF bounds no size; the limit exists because a few kilobytes of DEFLATE can claim gigabytes, and a caller writing to disk wants that refused rather than discovered. Raise it with DecryptLimits::with_max_output_bytes.

Fields

§limit: u64

The limit in force, from DecryptLimits::max_output_bytes.

§

Io(Error)

The caller’s reader or writer failed. Nothing is implied about the package. The error is the caller’s own value, so a cancellation can be recognized in it.

Trait Implementations§

Source§

impl Debug for DecryptError

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Display for DecryptError

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Error for DecryptError

Source§

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

Returns the lower-level source of this error, if any. Read more
1.0.0 · Source§

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

1.0.0 · Source§

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

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

Source§

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. Read more
Source§

impl From<DecryptError> for ReencryptError

Source§

fn from(e: DecryptError) -> Self

Converts to this type from the input type.
Source§

impl From<DetectError> for DecryptError

Source§

fn from(source: DetectError) -> Self

Converts to this type from the input type.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToString for T
where T: Display + ?Sized,

Source§

fn to_string(&self) -> String

Converts the given value to a String. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.