Skip to main content

EncryptParamProblem

Enum EncryptParamProblem 

Source
#[non_exhaustive]
pub enum EncryptParamProblem { OutsideSpecRange, UnsupportedByCipher, UnusableCombination, ExceedsImplementationLimit, }
Available on crate feature crypto-ops only.
Expand description

The two halves of Error::EncryptParams’s payload, gated with the variant that carries them. They are deliberately enums rather than strings so that a caller can match a rejected encryption parameter — which is unreachable if the types are not exported, so this re-export is part of that variant, not a convenience. The two halves of Error::EncryptParams’s payload, gated with the variant that carries them. They are deliberately enums rather than strings so that a caller can match a rejected encryption parameter — which is unreachable if the types are not exported, so this re-export is part of that variant, not a convenience. The two halves of Error::EncryptParams’s payload, gated with the variant that carries them. They are deliberately enums rather than strings so that a caller can match a rejected encryption parameter — which is unreachable if the types are not exported, so this re-export is part of that variant, not a convenience. Whose rule a rejected encryption parameter broke.

The other half of Error::EncryptParams’s payload, and the reason that variant is shaped as two enums rather than one. It is src/limits.rs’s spec / cipher / margin provenance taxonomy — see the table in that module’s header — turned into something a consumer can match on, plus a fourth case for two values that are each fine alone.

variantlabel in limits.rswas the request non-conforming?
Self::OutsideSpecRangespecyes
Self::UnsupportedByCiphercipherno — AES does not define it
Self::UnusableCombination—no, not value by value
Self::ExceedsImplementationLimitmarginno — this crate declines

Every Display string names whose rule it was, so that a consumer which forwards the message instead of matching on it still says something true. That is the whole point of the fourth variant: a margin reported as a spec violation is a typed lie, and a typed lie is worse than a vague one, because a consumer renders a typed fact as authoritative.

The fourth is also the one nothing currently produces, because this crate currently imposes no margin on a caller’s parameter. Self::ExceedsImplementationLimit’s own docs say why it is kept anyway.

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.
§

OutsideSpecRange

Outside the range [MS-OFFCRYPTO] states for the attribute.

The spec row of limits.rs’s table: the number the format itself states — §2.3.4.10’s simple types for the agile attributes, §2.3.4.5’s header table for EncryptParam::KeySize — so a request that trips it would produce a file no conforming reader need accept. The only one of the four that says the caller asked for something the format forbids.

§

UnsupportedByCipher

Inside the spec, outside AES as implemented here.

The cipher row: fixed by the algorithm rather than by the format. ST_KeyBits states no maximum precisely because it is generic across ciphers; AES defines three sizes, and this crate writes AES. A request refused for this reason is not non-conforming, and a message implying it was would be wrong.

§

UnusableCombination

Legal apart, unreadable together.

No row in limits.rs’s table, because a range check cannot see it: each value is inside its own bound and the combination is still not writable. Paired with EncryptParam::KeyBitsWithHash, whose docs give the case.

§

ExceedsImplementationLimit

Spec-legal, cipher-fine, and this crate declines anyway.

The margin row: this crate’s own defence, as the read caps and limits::crypto::PAYLOAD_CEILING are. A file built to the requested value could be perfectly valid and perfectly implementable, and this crate is choosing not to write it. It does not mean the format forbids the value, and its Display string says so in as many words — that distinction is why this variant exists separately from Self::OutsideSpecRange instead of being folded into it.

§Nothing produces it, and that is the design

No code path in this crate constructs this variant, and the docs that once said otherwise — a spin count “too weak to author”, a 65 536-byte salt “this crate declines to write” — described refusals EncryptParams::validate has never emitted. They are corrected at EncryptParam::SpinCount and EncryptParam::SaltSize. The only constructions left are the two exit-code tables’ synthetic payloads, in src/error.rs’s own exit_code_canary and in src/bin/msoffice-crypto_tests.rs, which pin a number rather than report a refusal.

The reason is simply that this crate presently imposes no margin on any caller-settable parameter. limits::SPIN_COUNT_MAX is the spec’s own 10 000 000, limits::AGILE_SALT_SIZE is ST_SaltSize whole, and both keyBits refusals belong to the format or to AES. The margins that do exist — the read caps, PAYLOAD_CEILING — bound what a file declares or how large a payload may be, and are reported by Error::BadParameters and its neighbours, never by Error::EncryptParams.

It is kept unproduced deliberately, as a design commitment rather than dead code, and the commitment is this: the first margin imposed on a caller’s parameter arrives wearing this variant. Without it the cheap thing to do is to reach for Self::OutsideSpecRange, which would tell a consumer the format forbids a value the format permits — a typed lie, and the precise failure the fourth variant was added to prevent. An unproduced variant with a stated reason costs a consumer one match arm that never fires; the alternative costs its users a false statement about [MS-OFFCRYPTO], rendered as authoritative.

Trait Implementations§

Source§

impl Clone for EncryptParamProblem

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Copy for EncryptParamProblem

Source§

impl Debug for EncryptParamProblem

Source§

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

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

impl Display for EncryptParamProblem

Source§

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

A predicate whose subject is the EncryptParam printed before it, naming whose rule was broken.

A consumer with no match arm forwards this sentence, so each one has to be honest standing alone: the spec case names [MS-OFFCRYPTO] as the authority, and the margin case says this crate declines without implying the format agrees.

The spec case names no section number, deliberately. Which clause states the range depends on the parameter printed before it — §2.3.4.10’s simple types for the agile attributes, §2.3.4.5’s header table for EncryptParam::KeySize — so a fixed citation here would be right for one and wrong for the other. It said “§2.3.4.10” until the standard writer learned its second and third key sizes, at which point the sentence would have cited the agile schema at a caller who never touched it. The section numbers live in the EncryptParam variants’ docs, where they can be per-parameter.

Each is phrased “was given …” rather than “is …” so that it reads correctly after a compound subject too — EncryptParam::KeyBitsWithHash names two attributes, and “keyBits together with hashAlgorithm is legal on its own” is not a sentence.

Source§

impl Eq for EncryptParamProblem

Source§

impl PartialEq for EncryptParamProblem

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for EncryptParamProblem

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> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. 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> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
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.