Skip to content

About

A Go library for parsing and decrypting macOS Keychain files (login.keychain-db)

Topics

Resources

Stars

29 stars

Watchers

1 watching

Forks

Latest commit

 

History

20 Commits

Folders and files

Repository files navigation

keychainbreaker

Go CI codecov Go Reference License

Go library for reading and decrypting macOS Keychain files (login.keychain-db). Supports OS X 10.6 (Snow Leopard) through macOS 26 (Tahoe).

What It Does

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.

CLI Tool

Install

Homebrew

brew tap moond4rk/tap
brew install moond4rk/tap/keychainbreaker

Go install (requires Go 1.26+)

go install github.com/moond4rk/keychainbreaker/cmd/keychainbreaker@latest

Binary

Download from GitHub Releases.

Usage

$ 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)

dump

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"

hash

# Export hash for offline cracking (no password needed)
keychainbreaker hash
# $keychain$*<salt_hex>*<iv_hex>*<ciphertext_hex>

Go Library

Install

go get github.com/moond4rk/keychainbreaker

Requires Go 1.20+.

Quick Start

// 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)
}

Usage

Open a Keychain

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 memory

Unlock

err = kc.Unlock(keychainbreaker.WithPassword("macos-login-password"))   // with password
err = kc.Unlock(keychainbreaker.WithKey("hex-encoded-24-byte-key"))     // with master key

macOS 26.4+ (login keychain v2): freshly re-keyed login keychains report blob version 0x200. Offline password unlock no longer works for them: WithPassword returns ErrUnsupportedBlobVersion instead of a misleading "wrong password" error. Recover the 24-byte master key on the originating machine and use WithKey. Version 1 (0x100) keychains are unaffected.

Recover the master key on macOS 26.4+ (v2)

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-db

2. 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-db

4. 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 (partial extraction)

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
}

Extract Records

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)

Record Types

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
}

How It Works

macOS Keychain uses a three-layer encryption scheme:

Password --> PBKDF2 --> Master Key --> DB Key --> Per-Record Keys --> Plaintext
  1. Master key derived from password via PBKDF2-HMAC-SHA1
  2. Database key decrypted from the keychain's metadata blob
  3. Per-record keys unwrapped using RFC 3217 Triple-DES Key Wrap
  4. 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.

Compatibility

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)

License

Apache-2.0

About

A Go library for parsing and decrypting macOS Keychain files (login.keychain-db)

Topics

Resources

Stars

29 stars

Watchers

1 watching

Forks

Releases

Contributors

Languages