Key Management

Creating keys

The signing and authentication keys are generated automatically the first time they’re needed — when gpg-agent sends LEARN, READKEY, or PKSIGN, scdaemon-se loads the existing key for that slot or generates a new P-256 key inside the Secure Enclave if none exists yet.

The encryption key is never auto-generated — it’s only created when SCDAEMON_SE_ALLOW_ENCRYPTION=1 is set. See Security Model for why.

Each key’s handle (an opaque dataRepresentation, not the key itself) is stored in the macOS Keychain under the service scdaemon-se. The primary card uses fixed tags: com.scdaemon-se.gpg.signing, .decrypt, .auth. Additional cards use a per-serial tag, com.scdaemon-se.card.<serial>.signing. See Architecture § Key storage and identity for how those handles are protected against tampering.

Multiple signing keys

You can back several signing keys with the Secure Enclave — for example, separate personal git-signing and release-signing identities. Each is a distinct virtual card:

scdaemon-se --add-signing-card --name "release-signing"   # create a new card (Touch ID)
scdaemon-se --list-cards                                   # list all cards
scdaemon-se --remove-card <serial> --yes                   # delete a card (irreversible)

Full walkthrough, including how to bind the new card’s key as a subkey: Guides → Multiple signing keys.

Exporting the public key

--export-public-key mints a standalone, Secure-Enclave-rooted master identity and is gated behind SCDAEMON_SE_ALLOW_MASTER=1 for exactly that reason. The recommended pattern is the opposite — an offline master with Secure Enclave subkeys — see Guides → Subkeys under an external master and Use Cases.

SCDAEMON_SE_ALLOW_MASTER=1 scdaemon-se --export-public-key --uid "Your Name <you@example.com>" | gpg --import

The exported key contains a primary public key (ECDSA P-256, signing + certification), a decryption subkey (ECDH P-256) if one exists, an authentication subkey (ECDSA P-256) if one exists, and the necessary self-signatures and subkey binding signatures.

Creating GPG shadow stubs

After importing a public key, gpg-agent needs shadow stubs — small files in ~/.gnupg/private-keys-v1.d/ that say “this key lives on a card” rather than containing key material — before it will use the Secure Enclave keys for signing or decryption:

gpg-connect-agent "LEARN --sendinfo --force" /bye

Regenerating keys

To start over with fresh keys:

./scripts/clear-secure-enclave.sh              # dry run: shows what would be removed
./scripts/clear-secure-enclave.sh --yes        # actually remove existing keys/metadata
gpgconf --kill gpg-agent
SCDAEMON_SE_ALLOW_MASTER=1 scdaemon-se --export-public-key --uid "Your Name <you@example.com>" | gpg --import
gpg-connect-agent "LEARN --sendinfo --force" /bye

scdaemon-se is licensed under the MIT License.

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