Skip to main content

keychain_core/
lib.rs

1//! Pure-Rust, byte-oriented **offline** reader for macOS `login.keychain-db`.
2//!
3//! `keychain-core` parses Apple's `AppleDatabase` keychain container and, given
4//! the account login password, decrypts generic-password secrets — the macOS
5//! analogue of Windows DPAPI offline recovery. This includes the Chromium
6//! **Safe Storage** key (service `Chrome Safe Storage`), which unlocks Chrome /
7//! Edge cookie and login databases on a mounted, acquired disk.
8//!
9//! Every entry point takes `&[u8]` and performs no I/O, so the same code serves
10//! a live file, a file carved from a disk image, or a byte buffer from memory.
11//!
12//! The unlock chain (all via audited RustCrypto crates — no hand-rolled math):
13//!
14//! 1. `master = PBKDF2-HMAC-SHA1(password, DbBlob.salt, 1000, dklen=24)`;
15//! 2. `DBKey` = 3DES-EDE3-CBC-decrypt of the `DbBlob` ciphertext under `master`;
16//! 3. each per-record key is CMS-unwrapped from the symmetric-key table;
17//! 4. each secret is 3DES-CBC-decrypted with its per-record key.
18//!
19//! A wrong or absent password is reported as [`KeychainError::Locked`] — the
20//! store is present-but-locked, never a fabricated secret.
21//!
22//! Format reference: the community `chainbreaker` tool (n0fate) and Apple's
23//! open-source `securityd` / `libsecurity_cdsa_*`.
24
25#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
26
27pub mod container;
28pub mod crypto;
29pub mod error;
30pub mod keychain;
31
32pub use container::{
33    Container, DbBlob, GenericRecord, KeyBlobRecord, SsgpBlob, COMMON_BLOB_MAGIC,
34    KEYCHAIN_SIGNATURE, RECORD_GENERIC_PASSWORD, RECORD_METADATA, RECORD_SYMMETRIC_KEY,
35};
36pub use crypto::{
37    derive_master_key, kcdecrypt, unwrap_key_blob, MAGIC_CMS_IV, MASTER_KEY_LEN, PBKDF2_ROUNDS,
38};
39pub use error::KeychainError;
40pub use keychain::{GenericSecret, Keychain, UnlockedKeychain};