macOS Keychain Files: Metadata for Forensics

What it is

The keychain is Apple's credential store: passwords, Wi-Fi keys, tokens, certificates, private keys and secure notes. macOS runs two families side by side. The legacy file-based keychains (login.keychain-db, System.keychain) are unlocked with the login password. The data protection keychain, the same design as iOS and shown as "Local Items" or "iCloud", is an SQLite database whose item keys are protected by class keys tied to the Secure Enclave on T2 and Apple Silicon Macs.

For most investigations the useful part is the metadata: which items exist, their service and account attributes, and when they were created or changed. This page covers that metadata only. It does not describe credential extraction.

Where it lives

A migrated profile can contain several UUID folders: only the one matching the current Hardware UUID (System Information) is active. Collect as root with a Full Disk Access collector to avoid gaps.

What it proves

• Websites and servers with saved credentials (internet password items: server, account, protocol, port, path).
• Apps that stored tokens or passwords (generic password items: service, account, access group).
• Saved Wi-Fi networks, where stored as keychain items.
• Presence of client certificates, private keys and unexpected root certificates (interception proxies, rogue profiles).
• When an item was first saved and last changed.

It does not prove a person typed or used a credential, only that an app stored it. A sparse login keychain is normal on recent macOS: most items live in the data protection keychain, iCloud Keychain or third-party managers.

Key fields

File-based keychain attributes (as printed by security dump-keychain):

keychain-2.db tables genp, inet, cert, keys share columns such as rowid, cdat, mdat, acct, svce, labl, agrp (access group), pdmn (protection class), sync (synchronizable), tomb (tombstone), musr, UUID and persistref. On recent releases many attribute values are stored encrypted, so offline queries may show structure and dates but not names. Always inspect .schema and actual column population.

Timestamps

• File-based keychains: cdat/mdat stored as text YYYYMMDDhhmmssZ plus a null byte, UTC.
• keychain-2.db: cdat/mdat are REAL Mac absolute time (seconds since 2001-01-01 UTC).

SELECT rowid, agrp, pdmn, sync, tomb,
       datetime(cdat + 978307200, 'unixepoch') AS created_utc,
       datetime(mdat + 978307200, 'unixepoch') AS modified_utc
FROM genp ORDER BY mdat DESC;

Retention

Items remain until deleted by the user or the owning app, or until the keychain file is reset. Deletions of synchronizable items propagate to the user's other devices through iCloud Keychain. The data protection tables have a tomb (tombstone) column: check it before assuming a deleted item left no row. Older versions of keychain files may survive in local APFS snapshots and Time Machine backups.

Collection

# Files (root, collector with Full Disk Access); keep WAL/SHM with keychain-2.db
sudo ditto /Library/Keychains ./case/keychains_system
for u in /Users/*; do [ -d "$u/Library/Keychains" ] && \
  sudo ditto "$u/Library/Keychains" "./case/keychains_$(basename "$u")"; done

• UAC files/system/keychain.yaml collects /Library/Keychains and every ~/Library/Keychains; macos_keychain_devicelist.yaml collects devicelist.db.
• On T2 and Apple Silicon Macs, copied data protection keychains stay unreadable off the original device. Decide on live steps before shutdown.
• For volatile memory on macOS, use a dedicated acquisition tool such as mac-dump, within your legal authority.

Parsing

Metadata only, in the user's own context, on a live system:

security list-keychains
security show-keychain-info ~/Library/Keychains/login.keychain-db
security dump-keychain ~/Library/Keychains/login.keychain-db > login_attrs.txt   # no -d
security find-certificate -a /Library/Keychains/System.keychain | grep -E '"labl"|"alis"'

Offline, inspect keychain-2.db read-only with sqlite3 -readonly <copy> ".tables" and .schema genp, then the query above. Options that reveal secrets (-d, -g, -w) are out of scope without explicit authorization.

Investigator tips

• Unexpected root certificates in the System or login keychain point to proxies, adware or a malicious profile; cross-check sudo profiles list.
• Items created at the same time as a new LaunchAgent or TCC grant (TCC.db) can reveal malware storing its own tokens.
• Correlate internet password servers with Safari history and Wi-Fi items with known networks.
• Live security commands can trigger prompts on screen and change access state: document every command.
• agrp values identify the storing app or team, not the person.
• Stored credentials often belong to third parties: confirm that your authority covers them before looking beyond metadata. See the keychain concepts guide.