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}