Repository navigation
feat(age): support hardware-backed keyring unlocking - #3648
Conversation
Protect the local identity keyring with independent age recipients and bootstrap identities. Cache decrypted keyring identities in source-bound agent sessions, invalidating them on lock, timeout and source changes. Use single-use unlock tokens to prevent pending authentication from reopening a locked or stopped agent. Verify replacement keyrings before atomic migration and retain passphrase compatibility. Refs #3644 Signed-off-by: ermengchao <zhangchao050530@gmail.com>
Signed-off-by: ermengchao <zhangchao050530@gmail.com>
dominikschulz
left a comment
There was a problem hiding this comment.
Overall this looks very nice, but it's a lot of non-trivial changes. Could we add a little more documentation (code comments, maybe an overview in markdown)?
| | `age.agent-enabled` | `bool` | Enable the persistent Agent for caching of age identities. This will remove the need to repeatedly enter the passphrase. EXPERIMENTAL. | | ||
| | `age.agent-timeout` | `int` | Automatically lock the agent after this many seconds of inactivity. | `0` | | ||
| | `age.identities` | `string` | Comma-separated list of age recipients (`age1...`) in the preferred order for decryption. Identities whose recipient is listed here are tried first, in the given order, before all remaining identities. Only public recipient strings are stored, never secret key material. Can be set interactively with `gopass age identities sort`. | `` | | ||
| | `age.keyring-identities` | `string` | Path to an independent, plaintext age identity file used to unlock a recipient-encrypted identity keyring. Supports age plugin identities for hardware authentication. A leading `~/` is expanded. | `` | |
There was a problem hiding this comment.
Are these two config options possible attack vectors?
The gopass security model basically gives up if an attacker has local filesystem access, but we don't want to open additional attack vectors. I think this is fine, but I'd still like to raise this question here.
There was a problem hiding this comment.
Thanks for raising this. These options introduce additional trusted inputs, and I should document their security implications more clearly.
age.keyring-identities selects the bootstrap identity file and may cause the corresponding age plugin to run. That file and the plugin executable therefore need to be trusted.
If age.keyring-recipients is modified to include an attacker-controlled recipient, a subsequent keyring write or re-encryption could grant access to the software identities. Changing the configuration alone does not grant access to the existing ciphertext. The decryptability check prevents accidental lockout, but does not detect an additional unauthorized recipient.
This falls within the trusted-local-machine assumption documented in docs/security.md, but that assumption alone does not eliminate the concern. I'll document these boundaries and limitations. Would you prefer an explicit recipient review and confirmation when changing keyring protection?
There was a problem hiding this comment.
No strong preference, but explicit recipient review sounds good.
There was a problem hiding this comment.
Implemented in b1babce.
Recipient-protected keyring writes now require manual review when the recipient set is new or changes. The prompt shows the target recipients and, when a valid previous record exists, additions and removals. Automatic yes cannot bypass it, and noninteractive writes require an already reviewed set.
Approval is recorded locally and bound to the keyring ciphertext. Missing or stale records require another review. Cancellation preserves the existing keyring, and replacement still requires successful decryption verification.
I also added an overview and security-boundary documentation, clarified the cleanup comments, and removed the duplicate lock log.
All GitHub CI checks passed. As before, I used AI to write the documentation and test code, and personally reviewed both.
Signed-off-by: ermengchao <zhangchao050530@gmail.com>
Fixes #3644.
Hardware age plugins authenticate each entry decryption when store entries are encrypted directly to hardware recipients. Caching the plugin identity alone does not provide a single authentication for an unlocked session.
Allow hardware recipients to protect the local age identity keyring instead. After authentication, load the decrypted software identities into the agent so subsequent entry reads reuse the session.
Add two configuration options:
age.keyring-identities: path to an independent identity file used to unlock the keyring, including hardware plugin identities.age.keyring-recipients: comma-separated public recipients used to encrypt the keyring, allowing both hardware protection and recovery recipients.Add
gopass age identities reencryptto migrate existing passphrase-protected keyrings without changing store entries or recipients. Verify the replacement keyring can be unlocked before atomically replacing it. Preserve passphrase compatibility and refuse silent protection downgrades.Bind cached sessions to the keyring, bootstrap file, and relevant configuration. Clear credentials on lock, timeout, or shutdown, and reject stale authentication responses after a lock or restart. Keep authentication failures fatal without password fallback, and prevent external SSH uploads from modifying protected sessions.
The implementation uses the generic age plugin interface. Secure Enclave support through
age-plugin-sehas been manually tested on macOS. YubiKey and TPM plugins should be able to use the same mechanism, but compatibility with those devices has not yet been tested.I used AI assistance to develop the test code and reviewed the resulting code myself.
Validation
make fmt: passed with no tracked changes.make test: passed with isolated configuration and runtime directories.go test -race ./internal/backend/crypto/age/...: passed.origin/master: passed with 0 issues.make test-integration: passed on Arch Linux, 34 passed and 0 failed.make codequality: license-lint, golangci-lint, and keep-sorted passed. Blocked by capslock capability-baseline drift. Base and patched versions have identical package-capability sets and report the same 79 additional pairs against the tracked baseline. Unmodifiedorigin/masteralso passes golangci-lint with 0 issues.govulncheck ./...: passed with no reachable vulnerabilities.