#[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),
}crypto-ops only.Expand description
Failures from decrypt.
Variants (Non-exhaustive)§
This enum is marked as non-exhaustive
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&strpassword 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
classifyalready 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: AllocationSiteWhich allocation could not be made.
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: u64The 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
impl Debug for DecryptError
Source§impl Display for DecryptError
impl Display for DecryptError
Source§impl Error for DecryptError
impl Error for DecryptError
Source§fn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
1.0.0 · Source§fn description(&self) -> &str
fn description(&self) -> &str
use the Display impl or to_string()
Source§impl From<DecryptError> for ReencryptError
impl From<DecryptError> for ReencryptError
Source§fn from(e: DecryptError) -> Self
fn from(e: DecryptError) -> Self
Source§impl From<DetectError> for DecryptError
impl From<DetectError> for DecryptError
Source§fn from(source: DetectError) -> Self
fn from(source: DetectError) -> Self
Auto Trait Implementations§
impl !RefUnwindSafe for DecryptError
impl !UnwindSafe for DecryptError
impl Forget for DecryptError
impl Freeze for DecryptError
impl Move for DecryptError
impl Send for DecryptError
impl Sync for DecryptError
impl Unpin for DecryptError
impl UnsafeUnpin for DecryptError
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
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 moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
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