keychain-db — macOS keychain files without the Security framework
Rust library for reading and writing macOS .keychain / .keychain-db
databases directly: no securityd, no Security framework, no entitlements.
The package is published as keychain-db; its Rust library target remains
keychain, so existing use keychain::... imports do not change. Versions
through 0.2.6 were also published under the former package name keychain-rs;
future releases use keychain-db.
The companion CLI is kc-cli (binary kc).
[]
= "0.2"
# optional: resolve ACL trusted apps from code signatures
# keychain-db = { version = "0.2", features = ["trust-apps"] }
use ;
let mut file = create?;
file.add_password?;
file.save?;
let mut file = open?;
file.unlock?;
let query = parse?;
let item = file.select?.remove;
assert_eq!;
// References are opaque and bound to this exact database revision.
let encoded = file.item_ref?.encode;
let reference = decode?;
assert_eq!;
# Ok::
Expression, Predicate, Comparison, and MatchOptions are the public query
model. Expression::parse accepts the same typed predicates as kc get;
Expression::new supports programmatic construction. KeychainFile::select
queries password, certificate, private-key, public-key, and item-key records.
ItemRef deliberately exposes accessors rather than writable fields so callers
cannot accidentally manufacture mutation identities.
Identity import/export uses one high-level type for combined PEM and PKCS#12.
Combined PEM accepts unencrypted PKCS#8 PRIVATE KEY and traditional PKCS#1
RSA PRIVATE KEY blocks:
use ;
// Auto-detect combined PEM or PEM/DER PKCS#12.
let identity = decode_identity?;
let combined_pem = identity.to_pem;
let pfx_der = identity.to_pkcs12?;
let pfx_pem = identity.to_pkcs12_pem?;
# let _: = ;
# let _: = None;
# Ok::
Keychain-wide policy is separate from Apple's per-item ACL representation:
use ;
let policy = AccessPolicy ;
assert!;
assert!;
assert_eq!;
The library returns an AccessDecision; it never owns terminal interaction.
Use KeychainFile::set_item_access and set_private_key_access to project a
policy to native ACLs, and item_application_access /
private_key_application_access to distinguish allow-any, prompt, and trusted
applications when auditing. The older *_trust methods retain their
empty-means-allow-any behavior.
KeychainLocator supplies the CLI-compatible bare-name contract without
implicitly reading CLI configuration:
use KeychainLocator;
let locator = new?;
assert_eq!;
# Ok::
Interoperable with Apple's security tool in both directions. For the kc
command reference, see kc-cli.
Beyond creating and reading, the library changes keychains in place — updating an item, deleting one, rewriting its access control, changing the keychain's password and its lock settings:
use ;
use ;
let mut file = open?;
file.unlock?;
let number = file.items.number;
file.update_item?;
file.set_settings?;
file.change_password?;
file.save?;
# Ok::
File format
The container format is documented in dtformats: MacOS keychain database file format. Multibyte values are big-endian.
file header (20 bytes: "kych", version, tables offset)
tables array: size, count, count × offset
table: header (28 bytes), record-slot array, records, index region
record: header (24 bytes), attribute offsets, key data, attributes
commit counter (u32 following the tables array)
A keychain is a CSSM database with a self-describing schema. Four schema tables
define the attributes of the remaining relations. kc reads that schema rather
than hard-coding password and key-record layouts.
Several format details are particularly important:
| Detail | Representation |
|---|---|
| Attribute order | The attribute-offset array follows schema-table order, not attribute-ID order. |
| Attribute names | Password relations generally use four-character codes such as acct, svce, and srvr; PrintName and Alias use string names. |
| Offsets | Attribute offsets are relative to the record and have their low bit set. Index offsets are relative to the table. |
Integers are stored as four raw bytes. Dates use the fixed 16-byte form
YYYYMMDDhhmmssZ, followed by a NUL and no length prefix. Other values use a
four-byte length followed by data padded to a four-byte boundary.
Record slots and free lists
A table's slot array is indexed by record number — a record's number is the slot it occupies:
| Slot value | Meaning |
|---|---|
| Even and nonzero | Record offset relative to the table |
| Odd | Free-list link: `(28 + 4 × slot) |
0 |
Free, and the end of the free-list chain |
The table header's sixth word (Table::free_list_head) is the head of that
chain. It points at the highest free slot, which links down to the next, and
so on to a slot holding 0; a table with no free slot carries 0. A freshly
created table carries 0x1d — the link to its single free slot 0.
Deleting frees a slot without shortening the array, unless the freed slot is the
last one, in which case that entry is dropped and the count falls by one — never
cascading past other trailing free slots, and never below one slot. Inserting
takes the head of the chain, reuses that slot's record number, and appends the
record's bytes at the end of the records region. Table maintains all of this,
including the record layout order, so a keychain that macOS has deleted from and
re-added to re-serializes byte for byte.
Blob versions and signatures
Apple keychains use more than one blob version. Keychains written by Apple's
tools commonly use 0x100 for legacy files and 0x200 for partition-aware
files. The blob version determines the signature algorithm:
| Version | Signature |
|---|---|
0x100 |
Legacy BSafe-compatible HMAC behavior |
0x101, 0x200 |
HMAC-SHA1 |
Apple's dbcrypto.cpp selects the legacy algorithm only for 0x100. A blob
must therefore be signed according to its declared version.
Encryption
The container specification does not describe all cryptographic details. The
implementation follows Apple's published ssblob.h, dbcrypto.cpp, and
HmacSha1Legacy.c sources and is checked against keychains produced by macOS.
password
└─ PBKDF2-HMAC-SHA1(salt, 1000 iterations, 24 bytes) → master key
master key
└─ 3DES-EDE3-CBC(DbBlob.iv) → encryption key (24) + signing key (20)
encryption key
└─ unwrap(KeyBlob) → item key (24)
item key
└─ 3DES-EDE3-CBC(ssgp.iv) → item secret
Each item stores its encrypted secret in an ssgp payload containing a
four-byte magic value, a 16-byte label, an eight-byte IV, and ciphertext. The
label identifies the symmetric-key record containing that item's wrapped key.
Apple's custom key wrapping uses two CBC passes with a byte reversal between them:
inner = 3DES-CBC(db key, iv, descriptive_data_length(0) || item key)
blob = 3DES-CBC(db key, MAGIC_CMS_IV, reverse(iv || inner))
The ssgp payload carries its own IV. Its label matches the Label attribute
of the key record that protects it, forming the link between the item and its
key.
Version 0x100 blobs use Apple's legacy HMAC behavior for compatibility. The
implementation reproduces that behavior when the version requires it; later
blob versions use standard HMAC-SHA1.
Indexes
Each table ends with an index region:
region := size, count, count × index offset
index := size, id, kind, attribute count, attribute ids,
entry count, entry offsets, record numbers, entries
entry := payload size, key values
Offsets are relative to the table. Entries are sorted by key, and the
record-number array follows the same order. Because inserting a record changes
table-relative offsets, kc rebuilds index regions from records whenever it
writes the database.
Unique-index attributes must be present even when their values are empty. For
example, an internet-password item without a port stores port = 0 and an
empty path. This matches the records written by macOS and keeps the item
represented in the relation's unique index.
Evidence and interoperability testing
The implementation combines three sources of evidence:
- the dtformats container specification;
- Apple's published source and CSSM/CDSA headers; and
- byte-level comparison with keychains written by macOS.
The test suite checks, among other things:
- byte-identical parsing and serialization of existing keychains;
- preservation of record slots, free-list links, unknown fields, and ACLs;
- signature selection by blob version;
- schema-defined attribute order and naming;
- key derivation, wrapping, and secret decryption;
- index reconstruction and ordering;
- duplicate detection through relation unique indexes;
- identity records and on-demand relation creation; and
- interoperability in both directions with Apple's
securitytool.
Values that remain unknown are named accordingly — for example
AclEntry::subject_words — and preserved rather than inferred.
Running the tests
The suite covers keychains created by both kc and security. System-generated
fixtures are created during the test run instead of being committed as binary
files. Tests that require security skip when it is unavailable.
End-to-end CLI interop lives in the kc-cli crate's tests/keychain_interop.rs.
To extract the schema from another macOS version:
Security considerations
The legacy keychain format uses cryptography that is weak by current standards: PBKDF2-HMAC-SHA1 with 1,000 iterations protects 3DES key material. Anyone who obtains a keychain file can attempt password guesses offline. Use a strong, random password and protect the file as secret material.
Additional considerations:
kccreates files with mode0600and preserves the mode of existing files.- 3DES and SHA-1 are properties of the format and are retained for interoperability.
- Secret buffers are cleared when dropped where supported by the implementation.
- Passing an item secret with
-wexposes it through process arguments; prefer an interactive prompt or standard input. kcpreserves ACL forms it does not model instead of rewriting them.- Direct file access bypasses
securitydand therefore bypasses its ACL enforcement. Anyone with both the file and its password can decrypt its secrets.
Access control
An item's key blob contains an owner entry and authorization entries. kc
supports both unrestricted and application-restricted forms:
A restricted entry stores one subject block per application:
subject type 116, then for each application:
20-byte legacy CDSA code hash
binary path
designated requirement
When built with --features trust-apps, -T obtains the application's
designated requirement with
macho-codesign. A requirement can
also be supplied explicitly:
The requirement stored in the ACL matches the application's signed designated
requirement. The accompanying 20-byte value is a legacy CDSA code hash rather
than the modern cdhash. Testing confirms that macOS accepts a zero value on
the allowed access path, so kc uses zeros instead of synthesizing an
unsupported value.
macOS applies the application restriction to the six-tag authorization entry
(24, 28, 37, 38, 59, 115) while leaving the single-tag entry (35)
unrestricted. kc follows that structure when generating restricted ACLs.
These ACLs govern access through securityd. They do not restrict kc
itself, because kc decrypts the database directly.
Source layout
src/format.rs kych tables, records, and attribute values
src/schema.rs relations and attributes read from the file
src/index.rs index parsing, rebuilding, and sorting
src/crypto.rs key derivation, signatures, and key wrapping
src/cssm.rs typed CSSM key headers, GUIDs, and dates
src/acl.rs ACL blob structures
src/records.rs typed item, key, and certificate attributes
src/requirement.rs designated requirements for trusted applications
src/der.rs certificate DER field location
src/db.rs open, unlock, query, and decrypt operations
src/write.rs keychain creation and item insertion
src/edit.rs update, delete, re-key, re-seal, and ACL rewriting
src/secret.rs cleared key material and CSPRNG support
src/output.rs text and JSON helpers
src/apple_schema.rs generated Apple schema data
xtask/extract-schema.py schema extraction from a macOS keychain
License
MIT. The format documentation draws on the GFDL-licensed dtformats specification and Apple's APSL-licensed source. No code from either is included.