Skip to main content

Classification

Struct Classification 

Source
#[non_exhaustive]
pub struct Classification { pub container: Container, pub document: Document, pub version: Option<(u16, u16)>, pub family: Family, pub key_data: Option<AlgorithmParams>, pub password_key: Option<AlgorithmParams>, pub data_integrity: IntegrityDeclaration, pub container_read: ContainerRead, }
Expand description

What classify() found. Never an error: an unreadable file is Unknown, not a failure.

§Examples

use msoffice_crypto::{classify, Container, Family, IntegrityDeclaration};

let class = classify(b"not an office file at all");
assert_eq!(class.container, Container::Unknown);
assert_eq!(class.family, Family::Unknown);
assert_eq!(class.data_integrity, IntegrityDeclaration::Unknown);
assert!(!class.is_encrypted());

Fields (Non-exhaustive)§

This struct is marked as non-exhaustive
Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.
§container: Container

The container shape.

§document: Document

The application format inside the container.

§version: Option<(u16, u16)>

EncryptionVersionInfo as (vMajor, vMinor): from the EncryptionInfo stream when one is present and at least 8 bytes long, and from the binary formats’ own CryptoAPI EncryptionHeader for a .doc / .xls / .ppt, which carry no such stream. None when neither could be read, and for the schemes that predate the header — XOR obfuscation names no version.

§family: Family

The encryption family the version pair — and, for vMinor = 2, the fAES flag — names.

§key_data: Option<AlgorithmParams>

Parameters governing the payload: agile <keyData>, standard encryption’s EncryptionHeader plus EncryptionVerifier.SaltSize, or — for a 97-2003 binary document — the keyBits its CryptoAPI EncryptionHeader exposes, which is the only member of the tuple those formats give up without decrypting. The rest stay None rather than being invented.

§password_key: Option<AlgorithmParams>

Parameters governing the password key encryptor: agile <p:encryptedKey>. None for standard encryption, which has a single parameter set.

§data_integrity: IntegrityDeclaration

Whether a dataIntegrity element is declared (D1).

§container_read: ContainerRead

Whether the container’s directory could be read from the bytes supplied.

Read this before trusting a Unknown in any field above it: ContainerRead::Unreadable means the bytes were too few or too damaged to look inside, which is a different fact from having looked and found nothing.

Implementations§

Source§

impl Classification

Source

pub fn is_encrypted(&self) -> bool

true when the file declares a password-to-open — an EncryptionInfo stream, or a 97-2003 binary document’s own encryption marker — including a family this crate cannot decrypt.

false also covers “nothing could be determined”: an EncryptionInfo too short to hold a version pair leaves Family::Unknown, which is not a claim that the file is plain.

Deliberately not “can I decrypt this”: see Classification::is_supported.

§Examples
use msoffice_crypto::classify;

assert!(classify(include_bytes!("../tests/fixtures/agile_encrypted.docx")).is_encrypted());
assert!(!classify(include_bytes!("../tests/fixtures/plain.docx")).is_encrypted());
Source

pub fn is_supported(&self) -> bool

true when a decrypt path of this crate implements the (document, family) pair — decrypt_ooxml for an OOXML package under crypto-ops, decrypt_binary_office for a .doc, .xls or .ppt under legacy-binary. In a build without the feature this still answers, and describes what enabling it would open.

Says nothing about whether the parameters are ones this crate accepts: a legal agile file with a spinCount over the ceiling classifies as Family::Agile, reports true here, and is refused at decrypt. Family-level, not tuple-level, by design — the tuple is in Classification::key_data. The document matters because the same family means different things in different containers: an EncryptionInfo stream naming RC4 CryptoAPI is refused, a .doc carrying it is read, and XOR obfuscation is read in a .xls and refused in a .doc.

§Examples
use msoffice_crypto::classify;

assert!(classify(include_bytes!("../tests/fixtures/agile_encrypted.docx")).is_supported());
assert!(!classify(include_bytes!("../tests/fixtures/plain.docx")).is_supported());

Trait Implementations§

Source§

impl Clone for Classification

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 Classification

Source§

impl Debug for Classification

Source§

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

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

impl Eq for Classification

Source§

impl PartialEq for Classification

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 Classification

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