Development

Project layout

Sources/
  SCDaemonLib/
    Assuan.swift              # AssuanServer actor: line-based stdin/stdout protocol loop
    AuthPrompts.swift         # LAContext / Touch ID reason strings
    CardInspection.swift      # --inspect / scdaemon-se-inspect data collection
    CardRegistry.swift        # multi-card registry: serials, labels, active-card selection
    KeyPinStore.swift         # TOFU key-substitution pinning (pure struct)
    Keygrip.swift             # keygrip computation (SHA-1 of canonical S-expression)
    Logger.swift              # stderr logging, gated by SCDAEMON_SE_DEBUG
    OpenPGPCard.swift         # OpenPGPCardHandler: Assuan command dispatch, DangerConfig
    OpenPGPPacket.swift       # RFC 4880 packet builder (used only by --export-public-key)
    SecureEnclave.swift       # SecureEnclaveManager: CryptoKit + Keychain wrapper
  scdaemon-se/
    main.swift                 # CLI argument parsing, daemon entry point
Tests/
  scdaemon-seTests/            # 15 test files (153 tests) + TestSafety.swift, a shared helper
scripts/                        # setup, wrapper, inspection, e2e test scripts (see CLI Reference)
Formula/
  scdaemon-se.rb                # Homebrew formula (Tap: not yet published, see Installation)

See Architecture for how these pieces call into each other, and Assuan Reference for exactly which commands OpenPGPCard.swift’s dispatcher implements.

Building

swift build              # debug
swift build -c release   # what setup.sh and the Homebrew formula install

Requires a full Xcode installation (not just the Command Line Tools) — CryptoKit’s Secure Enclave APIs need the Xcode SDK, and the package targets macOS.

Running tests

swift test                                        # safe by default, see below
SCDAEMON_SE_ALLOW_DESTRUCTIVE_TESTS=1 swift test   # also runs the Keychain-touching tests

Needs to run on a real Mac with a Secure Enclave (T2 or Apple Silicon) either way — even the default run creates a small number of real (if throwaway) Secure Enclave keys.

swift test’s output ends with a second, separate block — ◇ Test run started. / ✔ Test run with 0 tests in 0 suites passed. That’s the newer Swift Testing framework (@Test/#expect, distinct from XCTestCase), which swift test runs automatically alongside XCTest as of Swift 6 regardless of whether a project uses it. Every test in this project is an XCTestCase subclass, so Swift Testing finds nothing of its own and reports success by definition. The real result is the XCTest-style Test Suite '...' passed/Executed N tests... block just above it.

swift test is safe to run on a machine with real production Secure Enclave keys, by default and even with the flag above set. Every test that creates, signs with, or deletes a Secure Enclave key does so against a dedicated, isolated Keychain service (com.scdaemon-se.test.<uuid>, a fresh one per test), never the real "scdaemon-se" production service — a Keychain item’s identity is the pair (service, account), so an isolated service can reuse any tag name with zero collision risk. Each isolated service is torn down automatically when its test finishes; if a run is interrupted before that (Ctrl-C, a crash), scripts/clear-test-artifacts.sh sweeps up what’s left (see CLI Reference).

That teardown deletes by service alone (no account), which needs kSecMatchLimit: kSecMatchLimitAll explicitly set. On macOS’s file-based keychain, SecItemDelete with no match limit defaults to kSecMatchLimitOne — it silently deletes only the first matching item, not every item under the service (unlike iOS’s data-protection keychain, where no limit means “all”). Any new raw SecItemDelete call added to the test suite that’s meant to clear more than one item needs this set explicitly, or cleanup will silently leave items behind — exactly the bug SecureEnclaveIsolationTests.testDeletingByServiceAloneRemovesMultipleTagsUnderIt exists to catch.

SCDAEMON_SE_ALLOW_DESTRUCTIVE_TESTS=1 additionally runs 76 tests — spread across DangerousGuardTests.swift (3 of 7), RegressionTests.swift (2 of 4), and all of MultiCardTests.swift, OpenPGPCardTests.swift, RoleSeparationTests.swift, and SecurityTests.swift — that exercise GENKEY, real PKSIGN/PKAUTH signing, and other flows that construct a default (non-isolated-by-default) handler internally; they’re gated behind the flag as defense-in-depth (the isolation above is enforced by convention at each call site, not by the type system) and because some need Touch ID/ passcode approval, not because they’re unsafe once run. Off by default, the suite runs 77 tests without the flag.

Test files, by area:

File Covers
AssuanTests.swift Line protocol, percent-encoding, status/data/error framing
AuthPromptsTests.swift Touch ID reason-string construction
CardInspectionTests.swift --inspect data collection
CardRegistryTests.swift Multi-card registry, active-card selection, protection rules
DangerousGuardTests.swift SCDAEMON_SE_ALLOW_ENCRYPTION / SCDAEMON_SE_ALLOW_MASTER gates (3 of 7 tests also gated behind SCDAEMON_SE_ALLOW_DESTRUCTIVE_TESTS)
KeyPinStoreTests.swift TOFU pinning: first-use, match, mismatch
KeygripTests.swift Keygrip computation against known values
MultiCardTests.swift End-to-end multi-card scenarios (gated behind SCDAEMON_SE_ALLOW_DESTRUCTIVE_TESTS)
OpenPGPCardTests.swift Assuan command dispatch, the largest suite (gated behind SCDAEMON_SE_ALLOW_DESTRUCTIVE_TESTS)
OpenPGPPacketTests.swift RFC 4880 packet construction
RegressionTests.swift Fixed-bug regressions (2 of 4 tests also gated behind SCDAEMON_SE_ALLOW_DESTRUCTIVE_TESTS)
RoleSeparationTests.swift Signing-vs-auth role-key resolution (gated behind SCDAEMON_SE_ALLOW_DESTRUCTIVE_TESTS)
SecureEnclaveIsolationTests.swift Proves the isolation primitive itself: two isolated services never share a key under the same tag, the default service matches production, deleting by service alone removes every tag under it
SecureEnclaveStorageTests.swift Keychain storage round-trips, on an isolated service
SecurityTests.swift Security-review-driven cases, the suite’s most destructive tests (GENKEY 1/2/3) — gated behind SCDAEMON_SE_ALLOW_DESTRUCTIVE_TESTS

TestSafety.swift isn’t a test file itself — it’s a shared helper providing the SCDAEMON_SE_ALLOW_DESTRUCTIVE_TESTS skip check and makeIsolatedEnclave(), the isolated-Keychain-service constructor every Keychain-touching test above uses.

End-to-end tests

scripts/test-e2e.sh and scripts/test-e2e-multicard.sh drive a real gpg/gpg-agent against a built scdaemon-se binary, using a throwaway GNUPGHOME. Like the unit tests, they create real Secure Enclave keys and will prompt for Touch ID / passcode.

Do not run test-setup.sh, test-cleanup.sh, or test-e2e*.sh against a machine whose Secure Enclave keys you actually rely on — see CLI Reference for exactly what each script touches and why.


scdaemon-se is licensed under the MIT License.

This site uses Just the Docs, a documentation theme for Jekyll.