keychainbreaker

keychainbreaker

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

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

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
}

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
}

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
}

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

License

Apache-2.0