bitlocker/lib.rs
1//! # bitlocker-core — a from-scratch BitLocker (BDE) reader and decryptor
2//!
3//! Parses the BitLocker Drive Encryption on-disk format (the `-FVE-FS-` /
4//! BitLocker To Go volume header, the FVE metadata block, and its key-protector
5//! entries) and decrypts a volume from a password or recovery password, exposing
6//! a plaintext `Read + Seek` view.
7//!
8//! Scope of this build: the **password** (`0x2000`) and **recovery-password**
9//! (`0x0800`) protectors over **five of the six** BitLocker ciphers, each
10//! validated by a `pybde` oracle — AES-128-CBC ± Elephant Diffuser (`0x8000` /
11//! `0x8002`), AES-256-CBC (`0x8003`), and XTS-AES-128/256 (`0x8004` / `0x8005`).
12//! Only AES-256-CBC + Elephant Diffuser (`0x8001`) is recognized-but-refused (no
13//! oracle yet); startup-key and TPM protectors are out of scope for *unlock*.
14//! The metadata parser still *reports* every protector and cipher it finds.
15//!
16//! Every primitive comes from an audited crate — `aes`, `cbc`, `ccm`, `sha2`,
17//! and `xts-mode` for the XTS methods — except the Elephant Diffuser, for which
18//! no ecosystem crate exists; it lives in our own [`elephant_diffuser`] crate
19//! (extracted from here) and is validated **in situ** by this repo's Tier-1
20//! oracle (never a self-authored round-trip, which would prove nothing).
21//!
22//! ```no_run
23//! use std::fs::File;
24//! use bitlocker::BitLockerVolume;
25//!
26//! let image = File::open("bdetogo.raw")?;
27//! let mut volume = BitLockerVolume::unlock_with_password(image, "bde-TEST")?;
28//! let mut boot = [0u8; 512];
29//! volume.read_at(0, &mut boot)?;
30//! # Ok::<(), Box<dyn std::error::Error>>(())
31//! ```
32
33#![forbid(unsafe_code)]
34#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
35
36mod bytes;
37mod crypto;
38mod error;
39mod guid;
40mod header;
41mod metadata;
42mod method;
43mod volume;
44
45pub use error::{BdeError, Result};
46pub use guid::format_guid;
47pub use header::{BdeVariant, VolumeHeader};
48pub use metadata::{FveMetadata, MetadataEntry};
49pub use volume::{BitLockerVolume, DecryptedVolume};