FreeBSD Keychain — porting / alternatives plan Scoping

What macOS Keychain actually is, what's open vs closed, and the full set of options for giving NextBSD/gershwin a local secret store with Apple's SecItem API — from porting Apple's Security.framework wholesale, to wrapping gnome-keyring, to a clean-room secd-equivalent. Companion to the WiFi management, PAM port, and configd plans.

1. What the macOS keychain actually is

Four layers, only the top two of which are app-visible:

Critically for us, the daemon half is a textbook launchd-on-demand Mach service, the same pattern as configd / notifyd: a .plist declares a Mach service name, the library does a bootstrap_look_up, launchd starts the daemon on first use. That maps directly onto the infrastructure the launchd and libxpc/DO work already provides.

1.1 The architecture

1.2 What a "keychain item" is

Each item has a class (kSecClassGenericPassword, kSecClassInternetPassword, kSecClassCertificate, kSecClassKey, kSecClassIdentity), a set of attributes (account, service, server, protocol, label, …) used as search keys, an encrypted secret payload, and an access-control policy (which apps may read it, whether unlock/biometric is required). WiFi passwords, for example, are kSecClassGenericPassword / kSecClassInternetPassword items in the System keychain. Replicating this data model is the real work — the crypto is the easy part.

2. Open-source status — published, not buildable

3. What we actually need (and what we can drop)

4. Alternatives

Seven options, from most-Apple to least-effort. Verdicts summarized in §4.8.

4.A — Port Apple's Security.framework + securityd wholesale

Vendor the published source, reconstruct the missing build glue, swap corecrypto for libcrypto, stub the SEP.

• Pros: Real API/ABI fidelity — every SecItem/SecKeychain caller works unchanged; closest to "it's literally macOS."
• Cons: The tree doesn't build; corecrypto is unusable and threaded throughout; SEP paths must be torn out; decades of CDSA/iCloud/code-signing code comes along for the ride; deep CoreFoundation + Security-Transforms + MIG coupling. Realistically a 6–12+ person-month slog with permanent maintenance of a non-buildable upstream. You'd end up rewriting the crypto and storage layers anyway — i.e. most of option B — while carrying all of Apple's legacy.

Rejected Highest fidelity, worst effort/maintenance. The closed crypto + SEP mean you can't actually ship Apple's security guarantees regardless.

4.B — Clean-room native secd-equivalent recommended

Write a new launchd-managed Mach/DO daemon (com.apple.securityd) exposing the public SecItem API, backed by our own encrypted store and base crypto. Implement the published API contract, not Apple's implementation.

• Pros: Scope we control; BSD-licensable; reuses the project's launchd + CoreFoundation + Mach substrate; gives apps the real Apple API surface; no closed deps. Honest about its threat model (software-only unless TPM2 added).
• Cons: We own the security design (storage format, key hierarchy, ACL semantics); must track the SecItem attribute vocabulary carefully for compat; no hardware backing by default.

Chosen Best balance. Detail in §5.

4.C — Wrap gnome-keyring / libsecret (freedesktop Secret Service)

Run gnome-keyring-daemon as the storage backend; put a SecItem→Secret-Service translation shim in our Security-shim library.

• Pros: A mature, audited secret store for nearly free; the Secret Service item/collection model is conceptually close to keychain items.
• Cons: Drags in D-Bus — a foreign IPC the project deliberately avoided in favor of Mach/DO — plus glib. LGPL-2.1 (linkable, but not the base-system fit BSD code is). Impedance mismatch translating ACLs/access-groups onto Secret Service. You inherit someone else's daemon lifecycle, not launchd-native. Ends up being "option B's shim layer anyway, but on top of a D-Bus stack we don't otherwise want."

Fallback only Reasonable if a working store is needed fast and D-Bus is already present; otherwise the dependency cost outweighs the saved daemon work.

4.D — Wrap KWallet

• Pros: Mature, good UX, encrypted store.
• Cons: Qt/KDE + D-Bus weight, even further from the Cocoa/CoreFoundation world the desktop targets. All of C's downsides, heavier.

Rejected Strictly worse fit than C for this project.

4.E — pass / gpg-agent backend

• Pros: Dead simple, file-per-secret, gpg-audited crypto, trivially scriptable.
• Cons: CLI/file-shaped, not a daemon with an API; no attribute search model, no per-app ACLs, no Apple API surface. Fine for a developer's personal secrets, not a system keychain apps can call.

Rejected Wrong shape — can't present SecItem semantics.

4.F — PKCS#11 (p11-kit + SoftHSM / OpenSC)

• Pros: Standard token API; good for certs/keys and smartcards; could back the kSecClassKey/Identity classes.
• Cons: PKCS#11 is a key/token API, not a general password store; awkward for GenericPassword items; another semantic translation layer. Better seen as an optional backend for the key classes under option B than as the store itself.

Complementary Not a standalone answer; a possible plug-in backend for cert/key items later.

4.G — Status quo: plaintext Network.plist / flat files

• Pros: Zero work; already how WiFi creds would land today.
• Cons: No encryption at rest, no API, no access control. Acceptable as an interim, not as a destination.

Interim The honest current state until a consumer justifies B.

4.8 Verdict matrix

5. Recommended design — com.apple.securityd

1. Daemon. Launchd job labelled com.apple.securityd (file com.apple.securityd.plist) — the same string for the job Label and the advertised Mach service (legacy alias com.apple.SecurityServer); started on demand. Per-user instances in the user's launchd domain (keychains are per-user); one system instance (root) for the System keychain. Mirrors the per-user/per-session domain handling the launchd port already supports.
2. Library. A Security-compatible shim exporting SecItemAdd/CopyMatching/Update/Delete (+ legacy SecKeychain* shims) that marshal CFDictionary queries over DO/Mach to secd. CoreFoundation types are already available.
3. Store. One encrypted SQLite (or flat) DB per keychain: ~/Library/Keychains/login.keychain-db and /Library/Keychains/System.keychain, matching Apple paths so muscle memory / tooling line up. Items carry class + attributes (searchable, plaintext) + encrypted secret blob + access policy.
4. Key hierarchy. A per-keychain master key derived from the unlock secret (login password) via Argon2/scrypt; the master key wraps per-item content-encryption keys (AES-256-GCM). Locking drops the master key from memory; unlocking re-derives it. (See §6.)
5. Unlock. A PAM module (pam_secd, analog of pam_keychain/pam_gnome_keyring) unlocks the login keychain at login using the same password — direct tie-in to the just-completed PAM port. Manual lock/unlock via a CLI (security(1)-equivalent) and an Agent callback for GUI prompts when an app needs an item from a locked keychain.
6. Access control. v1: uid + executable-path policy ("which program asked"). v2: stronger identity (code-signing/Mach audit-token-based, if/when code signing exists). Never weaker than gnome-keyring's model.

5.1 Naming — follow the shipped system's convention

This is settled by what the running image actually does, not by what earlier draft plans guessed. A live launchctl list on a NextBSD box shows the system daemons keeping Apple's exact labels — the job Label, the .plist filename, and the advertised Mach service are all the one com.apple.* string:

launchd% list
PID   Status  Label
 54   -       com.apple.syslogd
 53   -       com.apple.notifyd
 52   -       com.apple.mDNSResponder
 51   -       com.apple.kextd
 50   -       com.apple.hostnamed
 48   -       com.apple.configd
 47   -       com.apple.aslmanager
 46   -       com.apple.IPConfiguration
 45   -       com.apple.DiskArbitration
 55   -       com.openssh.sshd          # third-party → upstream's own reverse-DNS

So a daemon that models or replaces an Apple service takes Apple's own name outright. For the keychain that is com.apple.securityd (modern data-protection alt: com.apple.secd; legacy bootstrap alias: com.apple.SecurityServer). There is no separate "our identity" label — that was a wrong inference; the shipped daemons don't do it. A clean-room Security.framework has bootstrap_look_up("com.apple.securityd") baked in, and using Apple's label for the job too keeps everything aligned with the rest of the running stack.

6. Crypto & storage — the honest threat model

• No corecrypto. Use base libcrypto (OpenSSL) or libsodium — AES-256-GCM for item secrets, Argon2id/scrypt for password-derived keys, HKDF for subkeys.
• No SEP. Default deployment is software-only: the master key lives in secd's (ideally mlock'd, non-swappable) memory while unlocked. This is the same guarantee gnome-keyring/KWallet give on commodity Linux — root, or a debugger on the unlocked process, can read live secrets. State this plainly; don't imply Apple-equivalent hardware protection.
• Optional TPM2 backing. FreeBSD has tpm(4) and security/tpm2-tss in ports. The keychain master key can be sealed to the TPM (optionally to PCR state), so the on-disk DB can't be decrypted off-box without the TPM. This is the closest analog to SEP key-wrapping and is the recommended hardening once the core works — but strictly optional and gated on TPM presence.
• At rest: attributes may be plaintext (needed for search) but secret payloads are always encrypted; whole-DB encryption optional on top.

7. API surface to implement (v1)

/* Modern data-protection API — the priority surface */
OSStatus SecItemAdd(CFDictionaryRef attributes, CFTypeRef *result);
OSStatus SecItemCopyMatching(CFDictionaryRef query, CFTypeRef *result);
OSStatus SecItemUpdate(CFDictionaryRef query, CFDictionaryRef attributesToUpdate);
OSStatus SecItemDelete(CFDictionaryRef query);

/* Classes to support first */
kSecClassGenericPassword     // app/daemon secrets, WiFi PSKs
kSecClassInternetPassword    // server creds (has protocol/server/port attrs)
kSecClassKey / kSecClassCertificate / kSecClassIdentity   // later; PKCS#11 backend option

/* Common attributes (search keys) */
kSecAttrAccount  kSecAttrService  kSecAttrServer  kSecAttrProtocol
kSecAttrLabel    kSecAttrAccessGroup  kSecAttrAccessible

/* Legacy shims (thin, mapped onto the modern store) */
SecKeychainAddGenericPassword(...);
SecKeychainFindGenericPassword(...);
SecKeychainAddInternetPassword(...);

Getting GenericPassword + InternetPassword CRUD correct covers WiFi creds, network shares, and the vast majority of app needs. Key/cert/identity classes and a possible PKCS#11 (§4.F) backend come later.

8. Open questions

9. References

• Apple Security framework source: github.com/apple-oss-distributions/Security
• Apple securityd source: github.com/apple-oss-distributions/securityd
• Keychain Services API: developer.apple.com/documentation/security/keychain_services
• freedesktop Secret Service / libsecret: specifications.freedesktop.org/secret-service
• FreeBSD TPM2 stack: freshports.org/security/tpm2-tss, man 4 tpm
• Companion plans: WiFi management, PAM port, OpenDirectory scoping, configd, launchd, libCoreFoundation