Skip to content

keyring-cache.md

Latest commit

 

History

History
131 lines (105 loc) · 5.75 KB

keyring-cache.md

File metadata and controls

131 lines (105 loc) · 5.75 KB
Raw

System keyring credential cache

Gitsign can cache signing credentials (the ephemeral private key and the Fulcio-issued certificate) in the operating system keyring:

  • macOS Keychain
  • Windows Credential Manager
  • Linux Secret Service (GNOME Keyring, etc.) or KWallet

Unlike the gitsign-credential-cache daemon, no long-running helper process is required. Credentials are cached for the lifetime of the certificate (~10 minutes on the public Sigstore instance), so you only need to complete the OIDC browser flow once per certificate lifetime instead of once per signature.

Setup

git config --global gitsign.credentialCacheMode system

or via environment variable:

export GITSIGN_CREDENTIAL_CACHE_MODE=system

The first git commit -S runs the normal OIDC flow and stores the resulting credential; subsequent signatures reuse it until the certificate expires. Expired or invalid entries are treated as a cache miss: the new credential obtained afterwards replaces them, and their data is cleaned up then. If the keyring is unavailable (e.g. locked, or no D-Bus session on a headless Linux host), gitsign falls back to the normal OIDC flow.

Platform notes

  • macOS: the Keychain is accessed via Security.framework, which requires gitsign to be built with cgo (CGO_ENABLED=1, the default for go build / go install on macOS). Builds without cgo report the keyring as unavailable and fall back to the normal OIDC flow. Entries are created with an access control list that trusts only the gitsign binary that created them - other applications (and other gitsign binaries) trigger a Keychain prompt. Since unsigned binaries are identified by their contents, expect a one-time "Always Allow" prompt after upgrading or rebuilding gitsign. Entries are never synced to iCloud.
  • Linux: requires a running Secret Service (GNOME Keyring, etc.) or KWallet with a D-Bus session. Headless hosts should use the daemon or no cache.
  • Windows: uses Credential Manager; credentials are chunked to stay under its per-credential size limits.

Multiple identities

Credentials are cached per identity. Because the OIDC identity is only known after the auth flow completes, the cache key is derived from the configuration used to obtain it:

  • Fulcio URL (gitsign.fulcio)
  • OIDC issuer (gitsign.issuer)
  • OIDC client ID (gitsign.clientID)
  • Connector ID (gitsign.connectorID)
  • Committer email (user.email)

Repositories that share the same configuration share a cached credential; repositories with a different user.email (or issuer, connector, etc.) get their own entry. Multiple identities can be cached at the same time.

Note that the key is derived from configuration, not from the identity in the issued certificate. If you authenticate as a different account without changing any of the config values above, the previously cached credential is reused until it expires (use gitsign credentials clear to evict it immediately; gitsign.matchCommitter can also be used to reject certificates that don't match user.email).

Managing cached credentials

# List cached credentials.
$ gitsign credentials list
EMAIL             ISSUER                            CLIENTID  CONNECTOR  FULCIO                       EXPIRES                    STATUS
you@example.com   https://oauth2.sigstore.dev/auth  sigstore  -          https://fulcio.sigstore.dev  2026-08-04T12:10:00-04:00  valid

# Remove the credential for the current configuration.
$ gitsign credentials clear

# Remove all cached credentials.
$ gitsign credentials clear --all

Entries can also be inspected/removed with the platform's native tools — they are stored under the service/label gitsign (e.g. Keychain Access on macOS, secret-tool/Seahorse on Linux, Credential Manager on Windows).

gitsign credentials operates on whichever backend gitsign.credentialCacheMode selects — the commands also work against the gitsign-credential-cache daemon in socket mode (or when GITSIGN_CREDENTIAL_CACHE is set).

Security considerations

⚠️ The cached private key and certificate are only as secure as your OS keyring.

  • Any process running in your user session that can access the keyring (any process on Linux once the Secret Service collection is unlocked; on macOS, the gitsign binary that created the entry or any application you grant access to via the Keychain prompt) can read the cached private key and sign artifacts as you. This is comparable to the gitsign-credential-cache daemon's threat model, where any process that can open the socket can use your credentials.
  • Unlike the in-memory daemon, keyring entries are persisted (encrypted at rest by the OS) and survive reboots. The exposure window is bounded by the certificate lifetime — expired entries are useless for signing and are cleaned up the next time a credential is stored for that identity — but entries for identities you stop using may linger until then (or until you run gitsign credentials clear --all).
  • Do not use credential caching on shared systems.
  • Environments with ambient OIDC credentials (e.g. CI providers) generally don't need credential caching.

When to prefer the daemon instead

  • You want credentials to live in memory only and never touch disk.
  • You want to forward a credential cache over SSH (RemoteForward of the socket — see the daemon docs).
  • Headless Linux hosts without a Secret Service / D-Bus session.
  • SSH sessions to macOS hosts, where keychain access may require unlocking the login keychain.