Go library for reading and decrypting macOS Keychain files (login.keychain-db). Supports OS X 10.6 (Snow Leopard) through macOS 26 (Tahoe).
Open a macOS Keychain file, unlock it with the user's password, and extract:
- Generic passwords -- app-stored credentials (Chrome Safe Storage, Wi-Fi, etc.)
- Internet passwords -- web and network credentials (GitHub tokens, Docker registry, SMB shares, etc.)
- Private keys -- RSA/EC private keys stored in the keychain
- X.509 certificates -- DER-encoded certificates
Works on any OS (Linux, macOS, Windows). No CGO. No macOS APIs. Just reads the binary file.
Homebrew
brew tap moond4rk/tap
brew install moond4rk/tap/keychainbreakerGo install (requires Go 1.26+)
go install github.com/moond4rk/keychainbreaker/cmd/keychainbreaker@latestBinary
Download from GitHub Releases.
$ keychainbreaker -h
Commands:
dump Export all keychain data to a JSON file
hash Print password hash for offline cracking (no unlock needed)
version Print version information
Flags:
-f, --file string Keychain file path (default: ~/Library/Keychains/login.keychain-db)
-p, --password string Keychain password (omit to be prompted)
-k, --key string Hex-encoded 24-byte master key
-o, --output string Output file path (default: ./keychain_dump.json)
Export all keychain data (passwords, keys, certificates) to a single JSON file. Passwords are output in three formats: plaintext, hex, and base64.
$ keychainbreaker dump
Keychain: /Users/user/Library/Keychains/login.keychain-db
Enter keychain password:
Extracted:
Generic passwords: 42
Internet passwords: 15
Private keys: 2
Certificates: 8
Output: keychain_dump.json
# Specify keychain file and password
keychainbreaker dump -f /path/to/login.keychain-db -p "password"
# Export to a specific file
keychainbreaker dump -o result.json
# Wrong password: still exports metadata (service, account, timestamps, certs)
keychainbreaker dump -p "wrong"# Export hash for offline cracking (no password needed)
keychainbreaker hash
# $keychain$*<salt_hex>*<iv_hex>*<ciphertext_hex>go get github.com/moond4rk/keychainbreakerRequires Go 1.20+.
// Open the default macOS login keychain
kc, err := keychainbreaker.Open()
// Unlock with the user's macOS login password
err = kc.Unlock(keychainbreaker.WithPassword("your-macos-login-password"))
// Extract all saved passwords
passwords, err := kc.GenericPasswords()
for _, p := range passwords {
fmt.Printf("Service: %s, Account: %s, Password: %s\n",
p.Service, p.Account, p.Password)
}kc, err := keychainbreaker.Open() // default system keychain
kc, err := keychainbreaker.Open(keychainbreaker.WithFile("/path/to")) // specific file
kc, err := keychainbreaker.Open(keychainbreaker.WithBytes(buf)) // from memoryerr = kc.Unlock(keychainbreaker.WithPassword("macos-login-password")) // with password
err = kc.Unlock(keychainbreaker.WithKey("hex-encoded-24-byte-key")) // with master keymacOS 26.4+ (login keychain v2): freshly re-keyed login keychains report blob version
0x200. Offline password unlock no longer works for them:WithPasswordreturnsErrUnsupportedBlobVersioninstead of a misleading "wrong password" error. Recover the 24-byte master key on the originating machine and useWithKey. Version 1 (0x100) keychains are unaffected.
A v2 keychain can't be decrypted offline from the file and password alone, but its 24-byte master key can be captured on the machine that created it and then replayed offline with WithKey / --key. securityd still derives that key through CSSM_DeriveKey, so an lldb breakpoint on the running daemon exposes it.
Requirements: macOS 26.4+ on Apple Silicon, an admin account, the login password, and SIP temporarily disabled (re-enable it as soon as you're done).
1. Lock the keychain so the next unlock re-derives the key:
security lock-keychain ~/Library/Keychains/login.keychain-db2. Attach lldb to securityd and break on the deriver. Attaching to the root-owned daemon needs sudo; if pgrep returns more than one PID (e.g. with the iOS Simulator installed), pick the one from your login session:
sudo lldb -p "$(pgrep -x securityd)"(lldb) expression -l objective-c -- @import Security
(lldb) breakpoint set -n CSSM_DeriveKey
(lldb) continue
3. Trigger a derive from another shell (enter your login password when prompted):
security unlock-keychain ~/Library/Keychains/login.keychain-db4. Read the master key. When the breakpoint hits, $x6 holds the DerivedKey output pointer; step out so it gets filled in, then read 24 bytes of its KeyData:
(lldb) expr void *$derived = (void *)$x6
(lldb) thread step-out
(lldb) p *(CSSM_KEY *)$derived
(lldb) memory read --format x --size 1 --count 24 `((CSSM_KEY *)$derived)->KeyData.Data`
The p line is a sanity check: expect HeaderVersion = 2, KeyData.Length = 24, and BlobType = 0 -- any other BlobType means you captured the wrong key. Concatenate the 24 printed bytes into a 48-character hex string.
5. Replay it offline (re-enable SIP first):
keychainbreaker dump --key=<48-char-hex> # or in Go: kc.Unlock(keychainbreaker.WithKey("<hex>"))The master key is stable per machine + password + keychain, so one capture is reusable. A worked demo with sample output is in issue #18, where this method was contributed by @gmazzola.
TryUnlock attempts to decrypt but does not block extraction on failure. When the password is wrong or unavailable, metadata (service, account, timestamps, etc.) is still returned with encrypted fields set to nil.
// Wrong password: metadata still available, passwords nil
err = kc.TryUnlock(keychainbreaker.WithPassword("maybe-wrong"))
passwords, _ := kc.GenericPasswords() // passwords[0].Service = "moond4rk.com"
// passwords[0].Password = nil
// No credential: just metadata
kc.TryUnlock()
passwords, _ := kc.GenericPasswords()
// Check if decryption succeeded
if kc.Unlocked() {
// full data available
}genericPasswords, err := kc.GenericPasswords() // app credentials
internetPasswords, err := kc.InternetPasswords() // web/network credentials
privateKeys, err := kc.PrivateKeys() // encrypted private keys
certificates, err := kc.Certificates() // X.509 certificates
hash, err := kc.PasswordHash() // offline cracking hash (no unlock needed)GenericPassword
type GenericPassword struct {
Service string
Account string
Password []byte // raw bytes; caller decides encoding
Description string
Comment string
Creator string
Type string
PrintName string
Alias string
Created time.Time
Modified time.Time
}InternetPassword
type InternetPassword struct {
Server string
Account string
Password []byte
SecurityDomain string
Protocol string // "htps", "smb ", etc.
AuthType string
Port uint32
Path string
Description string
Comment string
Creator string
Type string
PrintName string
Alias string
Created time.Time
Modified time.Time
}PrivateKey
type PrivateKey struct {
Name string // first 12 bytes of decrypted data
Data []byte // raw key material (PKCS#8)
PrintName string
Label string
KeyClass uint32
KeyType uint32
KeySize uint32
}Certificate
type Certificate struct {
Data []byte // raw DER-encoded certificate
Type uint32
Encoding uint32
PrintName string
Subject []byte
Issuer []byte
Serial []byte
}macOS Keychain uses a three-layer encryption scheme:
Password --> PBKDF2 --> Master Key --> DB Key --> Per-Record Keys --> Plaintext
- Master key derived from password via PBKDF2-HMAC-SHA1
- Database key decrypted from the keychain's metadata blob
- Per-record keys unwrapped using RFC 3217 Triple-DES Key Wrap
- Passwords/keys decrypted using per-record keys with 3DES-CBC
The library dynamically discovers table schemas from the keychain file itself, making it robust across macOS versions (10.6 through 26).
See RFC 001 for the full encryption specification.
| Supported | Not Supported |
|---|---|
.keychain and .keychain-db files |
keychain-2.db (iCloud Keychain) |
| OS X 10.6 through macOS 26 (Tahoe) | Secure Enclave protected keys |
| Linux, macOS, Windows (cross-compile) |