Skip to main content

keychain_core/
error.rs

1//! Error type shared across the keychain container parser, the crypto layer,
2//! and the high-level decryptor.
3
4/// A failure decoding or decrypting a `login.keychain-db` artifact.
5///
6/// Every variant that reports something *unrecognized* carries the offending
7/// value (magic, offset, length) so an examiner can diagnose it — an "unknown"
8/// without the bytes is a dead end (Fail-loud / show-the-value discipline).
9#[derive(Debug, thiserror::Error, PartialEq, Eq)]
10pub enum KeychainError {
11    /// A read ran past the end of the buffer.
12    #[error("data too short at offset {offset}: need {needed} more bytes, have {available}")]
13    TooShort {
14        offset: usize,
15        needed: usize,
16        available: usize,
17    },
18    /// The file does not begin with the `kych` AppleDatabase signature.
19    #[error("not a keychain: signature {found:#010x} != 'kych' (0x6b796368)")]
20    BadSignature { found: u32 },
21    /// The `DbBlob` metadata record was not found or is malformed.
22    #[error("DbBlob (schema metadata) table not found or malformed")]
23    DbBlobMissing,
24    /// A `CommonBlob` magic did not match the expected `0xFADE0711`.
25    #[error("bad blob magic {found:#010x} at offset {offset}: expected 0xFADE0711")]
26    BadBlobMagic { found: u32, offset: usize },
27    /// A required table type is absent from the schema.
28    #[error("keychain schema has no table of type {table_type:#010x}")]
29    MissingTable { table_type: u32 },
30    /// 3DES decryption produced invalid PKCS#7 padding — almost always a wrong
31    /// login password (the master key did not unwrap the DBKey).
32    #[error("decryption failed: invalid padding (wrong password or corrupt blob)")]
33    DecryptionFailed,
34    /// A key or IV had the wrong length for the cipher.
35    #[error("invalid key/IV length")]
36    InvalidKeyLength,
37    /// The DBKey could not be unwrapped with the derived master key: the store
38    /// is present but locked. The login password is wrong or absent.
39    #[error("keychain is LOCKED: the DBKey did not unwrap (wrong or missing login password)")]
40    Locked,
41}