Keychain 3.0.0 beta3

Third public beta of Keychain 3.x, collecting changes made after the
3.0.0_beta2 tag.

This release focuses on feature additions and robustness. It makes Keychain
more dependable during shell startup, easier to configure,
supports smartcards or other PKCS#11-backed SSH tokens, closes
a known .keychainrc documentation gap, and significantly enhances
the integrated documentation and documentation rendering.

Highlights:

• More reliable agent startup. Keychain now keeps its managed ssh-agent
  socket in a stable location under ~/.keychain/ instead of depending on
  temporary /tmp/ssh-* paths. This helps avoid cases where the agent is
  still running but its socket directory has been cleaned up, a problem that
  showed up clearly under WSL but is not unique to it.

• Better smartcard and hardware-token support. You can now ask Keychain to
  load a PKCS#11 provider directly with pkcs11:/path/to/provider.so. This is
  useful for SSH keys stored on smartcards, security keys, and similar devices.
  This addresses issue #216.

• Improved Documentation Formatting. Significant improvements in the
  embedded documentation renderer used by keychain man. Pager support
  integrated. Supported .keychainrc config settings are now fully
  documented, streamlined and available. Addresses issue #217.

• Improved 2.9.8 compatibility details. A few legacy command-line edge
  cases with --stop and --wipe now print a more accurate error message.

• Copyright has been updated to reflect assignment/ownership by Daniel
  Robbins, the person, removing reference to BreezyOps / Funtoo Solutions,
  Inc.

Keychain 3.0.0 beta2

Second public beta of Keychain 3.x, collecting all changes made after the
3.0.0_beta1 tag.

This release transforms the multi-terminal experience and strengthens GPG key
handling. The headline feature is a coordinated unlock protocol that eliminates
the frustrating "could not acquire lock" errors when multiple shells start
simultaneously -- a common occurrence when Visual Studio Code reconnects to
WSL and restores several terminals at once.

Highlights:

• Coordinated multi-terminal initialization (solves issue #214). Keychain
  now uses an elegant coordination protocol instead of the classic lock-timeout
  race. When multiple terminals detect missing SSH keys:

  • All terminals display: Press Enter to initialize keys
  • Pressing Enter in any terminal runs ssh-add in that terminal
  • Other terminals wait automatically and are notified when initialization completes
  • Waiting terminals print Keys initialized by another terminal. and configure
    their environment without prompting

  This eliminates the could not acquire lock errors that plagued earlier
  versions. The technical implementation uses a short-lived state lock for
  metadata updates, a dedicated activation lock to elect the loader, and FIFO
  endpoints for instant kernel-level notification (no polling). A takeover
  mechanism allows any waiting terminal to cancel a stuck ssh-add by typing
  takeover, ensuring you're never blocked by a hidden or inaccessible prompt.
  Internal coordination is quiet -- no more Waiting N seconds for lock...
  messages during interactive key loading.

• Improved startup and key-loading output.

  • Multi-key ssh-add prompts render as compact lists instead of long inline
    messages
  • Common stale pidfile/socket cases (especially in WSL restart scenarios) are
    folded into the Starting ssh-agent... context instead of producing
    separate noisy notes
  • Empty gpg-agent wipe diagnostics no longer render awkward (output: )
    text; non-actionable no-agent details are debug output
  • Successful remote initialization is reported as Keys initialized by another terminal.

• Reliable GPG warm-up with explicit verification. The gpge:KEYID and
  gpga:KEYID extended key syntax now perform a complete encrypt-then-decrypt
  verification cycle instead of relying on signing warm-up side effects. A tiny
  temporary payload is encrypted to the requested key and immediately decrypted
  through gpg-agent. If this verification cannot be completed, add fails
  rather than reporting success. This is significantly more reliable across
  different GnuPG versions and key configurations, where signing warm-up may
  not populate the decryption passphrase cache. The legacy gpgk:KEYID alias
  remains equivalent to gpgs:KEYID (signing warm-up only).

• Enhanced documentation. The embedded man page now includes comprehensive
  coverage of the coordination model (keychain man topic:coordination),
  updated guidance for --lockwait and --no-lock options, and clearer
  explanations of GPG warm-up guarantees. New design documents and a formal
  UX acceptance checklist support manual multi-terminal testing.

• Focused test coverage. New tests validate the coordination state file,
  waiter FIFO registration, activation lock handoff, takeover/cancel mechanics,
  and GPG end-to-end warm-up for both signing and encryption/decryption paths.
  Test infrastructure improvements ensure the checkout's source code is tested
  rather than any installed version, and CI coverage now includes macOS GPG
  validation.

Beta notes:

• The coordinated unlock flow applies to SSH key loading only. GPG keys use
  explicit warm-up paths (gpgs:, gpge:, gpga:) and do not participate
  in multi-terminal coordination.
• Terminal prompt erasing is best-effort: used on ANSI-capable terminals,
  falling back to ordinary line output when stderr is redirected, TERM=dumb,
  or the prompt would wrap.

Keychain 3.0.0 beta1

Initial public beta of Keychain 3.x.

Keychain 3 is a ground-up Python 3 rewrite of Daniel Robbins' long-running
SSH/GPG agent manager. The release preserves the traditional single-file
deployment model through keychain.pyz, while replacing the historical
Bourne shell implementation with a tested, auditable Python package.

Highlights:

• Ships as a standalone keychain.pyz with no third-party runtime
  dependencies.
• Requires Python 3.9 or newer at runtime; the zipapp bootstrap can re-exec
  into a newer python3.NN on systems where /usr/bin/env python3 is below
  the floor.
• Adds an action-oriented command surface such as keychain add,
  keychain agent start, keychain agent stop, keychain list,
  keychain env, keychain inspect, keychain help, and keychain man.
• Keeps keychain 2.x-style invocations working through an explicit
  compatibility layer.
• Embeds documentation in the zipapp; use keychain man and
  keychain man --list to browse it.
• Uses a default-deny model for KEYCHAIN_* environment variables; pass
  --allow-env / -E when legacy environment-variable behavior is desired.
• Releases under GPLv3 for the 3.x series. Keychain 2.x remains GPLv2.

Known beta notes:

• WSL login-shell startup can run keychain in a noninteractive/no-TTY context
  when invoked by automation. This may fall through to ssh_askpass; stale
  WSL /tmp/ssh-* sockets and hostname-specific pidfiles are tracked for
  follow-up polish.

keychain 2.9.8

keychain 2.9.8 (2 Nov 2025)

This release fixes the release tarball to include all necessary files for building and using keychain.

Bug fixes:

• Fixed release tarball generation to include bash completion script (completions/keychain.bash),
  Makefile, source files, and other essential components. Previous release (2.9.7) tarball was
  missing these files.
• Improved tarball generation to use git archive as source of truth, eliminating manual file
  inventory and preventing future omissions.
• Updated release logic to use dist/ directory for archive generation. GitHub workflow plumbing
  work for new /dist tarball location, associated Makefile and CI fixes.

Documentation:

• Added bash completion information to keychain man page (NOTES section).

---

Build Provenance

Artifact	SHA256
keychain	f8b4e8a2a630907bb81737d455a2dec2cb8308e3210840665239ef9c49bbeadb
keychain.1	3e5150c23ad27ce45e1f77d5f72be3098e6383bb18937e2babffbe39af13f2a2

Tag commit SHA1: 2b3c181eaa73ca27b0cfa3fd12148d6b69e35311

keychain 2.9.7

keychain 2.9.7 (31 Oct 2025)

This release fixes critical issues with spaces in HOME directories and usernames, and adds official Git Bash on Windows compatibility.

Bug fixes:

• Fixed keychain failures when HOME directory path contains spaces (e.g., C:\Users\John Doe).
  (#188)
• Fixed username detection for usernames containing spaces (e.g., "Mathew Binkley" on Windows).
  Implemented portable get_owner() function using POSIX-defined ls -ld output format with
  intelligent field parsing to distinguish space-in-username from normal owner/group fields.
• Fixed pidfile generation to properly quote SSH_AUTH_SOCK paths containing spaces while
  leaving SSH_AGENT_PID unquoted (numeric value). Rewrote write_pidfile() to use robust
  eval-in-subshell approach for extracting variable values from ssh-agent output.
• All pidfile formats (sh/csh/fish) now correctly handle paths with spaces.
• Fixed ssh-agent invocation to always use -s option for Bourne-compatible output, simplifying
  pidfile generation and improving compatibility across different environments.
  (#185)

Testing and quality improvements:

• Added scripts/test-space-home.sh - automated test harness that simulates HOME directories
  with spaces and validates proper handling. Returns proper exit codes for CI integration.
• Integrated space-in-home test into GitHub Actions release workflow to prevent regressions.
• Added ShellCheck disable comments with justification for intentional POSIX ls usage.
• Fixed Unicode arrow characters in comments that caused ShellCheck errors.

New features:

• Added bash completion support (completions/keychain.bash) with intelligent context-aware
  completion for command-line options, SSH keys, GPG keys, and full --extended mode support.
  Based on work by @mikkoi with significant enhancements for keychain 2.9.x features:
  • Dynamically parses keychain --help for up-to-date option completion
  • Completes SSH key names from ~/.ssh/*.pub files
  • Completes GPG key IDs (8-character short format)
  • --extended mode: sshk:<tab>, gpgk:<tab>, host:<tab> with prefix completion
  • Detects hostnames from ~/.ssh/config for host: completion
  • ShellCheck compliant
    (#186)
• Added Makefile targets: install-completions and uninstall-completions for optional
  bash completion installation (separate from default install target).
• Updated RPM spec file (keychain.spec.in) for modern distributions:
  • Modernized description to focus on OpenSSH and GnuPG (removed obsolete ssh.com/Sun SSH)
  • Updated dependencies: sh-utils → coreutils, added Recommends: bash-completion
  • Added bash completion installation to RPM package

Documentation:

• Updated keychain.pod with detailed implementation notes for space handling, POSIX compliance,
  and the robust eval approach used in pidfile generation.
• Standardized option ordering in keychain.pod to follow Unix convention (short option first,
  then long option), ensuring compatibility with bash completion regex patterns.
• Added comprehensive COMPATIBILITY section to keychain.pod documenting:
  • Minimum OpenSSH version (7.3+) and supported features
  • GnuPG 2.1+ requirements for gpg-agent integration
  • Shell compatibility (Bourne/POSIX, csh/tcsh, fish)
  • Git Bash (MSYS2) for Windows - officially documented as supported platform
  • Legacy SSH implementation status (SunSSH, ssh.com)
  • Systemd user environment integration
  • Spaces in HOME and paths handling details
• Updated README.md with bash completion installation instructions for both system-wide
  and user-only installations.

---

Build Provenance

Artifact	SHA256
keychain	ccf51b708de94905403966c467fb7df965016c12b8e30aca458cf5e14129b9ce
keychain.1	ffccaa49f5b8136df211256f0607c440d80957302a079a2c6c6a928cf3404a1d

Tag commit SHA1: dd1ebe4f546bb2088541ae28725f9d2ea2c87325

keychain 2.9.6

keychain 2.9.6 (06 Sep 2025)

Documentation/branding release (no functional code changes):

• Updated references in wiki to reflect the new official home of Keychain at
  https://github.com/danielrobbins/keychain.
• Consolidate historical references; retain only intentional archival note(s).

Additional release engineering improvements:

• Add release automation helpers: Makefile release (create) and
  release-refresh (asset replace), plus scripts under scripts/ and
  GitHub Actions workflow to build artifacts on tag push (staging only).
• Add docs/release-steps.md to formalize release process (numeric tags only,
  assets: tarball, wrapper script, man page).
• Orchestrated release flow (make release / make release-refresh) now enforces:
  • Mandatory CI (Debian container) artifact fetch for the tag.
  • Normalized comparisons:
    • keychain – raw sha256.
    • keychain.1 – raw sha256; on mismatch, re-compare with Pod::Man first line stripped.
    • Tarball – internal file list + per-file sha256 (man page internally normalized) ignoring tar/gzip metadata.
  • If (and only if) all artifacts match (raw or normalized) CI artifacts are used DIRECTLY for publication; local artifacts are never overwritten (kept for audit).
  • Any real content mismatch aborts unless KEYCHAIN_FORCE_LOCAL=1 is explicitly set (single override; KEYCHAIN_ADOPT_CI removed).
  • Copy/paste diff command hints emitted on mismatch for rapid investigation.
  • Asset path indirection via exported variables prevents local file mutation, improving auditability.
• Release notes body automatically extended with a Build Provenance table (sha256 for keychain and keychain.1) plus the tag commit SHA1.
• Workflow continues to only stage artifacts; publication requires explicit maintainer action (no auto-release on tag push).

---

Build Provenance

Artifact	SHA256
keychain	1146dbd0ba94828e3d2b5eeedf1a9037bc466bbb9f2c53451b3bd8b36ec7604e
keychain.1	2b7a5c1e0cdab1bdf35e07be188f8e8ed98525f9c168dfb5ea41581ef073e656

Tag commit SHA1: c6ecde08fe7de3ab51eef0e5ca424ae1b005dd6f

Keychain 2.9.5

ChangeLog for Keychain

https://www.funtoo.org/Funtoo:Keychain

keychain 2.9.5 (16 May 2025)

This is a bugfix release.

• Hardening checks were failing on Android and some MacOS environments. Make them
  more compatible and lower to warnings instead of aborting the script, until
  they have been tested in more environments.
  (#177)

• Fixed issues with indentation of note(), warn(), mesg().

• Convert SSH_AUTH_SOCK in pidfile is invalid; ignoring it into a debug message,
  as this is normal when rebooting your system so is not really useful to show
  typically. (#176)

Keychain 2.9.4

ChangeLog for Keychain

https://www.funtoo.org/Funtoo:Keychain

keychain 2.9.4 (14 May 2025)

This is a minor bugfix release.

• Fix minor regression which allowed some warnings to display with --quiet.
  (#175)

• "Cannot find separate public key" turned into a note() rather than warn(),
  along with several other non-critical notices. note() can be suppressed with
  --quiet, unlike warn(). (#157)

• Minor improvement when wiping GnuPG keys with --wipe option so keychain output
  is more understandable when gpg-agent is not running.

Keychain 2.9.3

ChangeLog for Keychain

https://www.funtoo.org/Funtoo:Keychain

keychain 2.9.3 (14 May 2025)

This is a security and bug fix release. Many thanks to those who have reported
issues to GitHub, send in pull requests, and tested out fixes. 2.9.3 includes
the following updates:

• The --quick option logic had several bugs which have been resolved. Thanks
  to Filipe Fernandes (@ffernand) for reporting the issue and for assistance
  testing fixes. (#167)

• Fix keychain --query exit code when no pidfile exists.
  (#171)

• --systemd option should now be fixed.
  ([#168])

• Harden keychain so the use of the --dir and --absolute options cannot be
  used to instruct keychain to write pidfiles into insecure areas.
  (#174)

  Prior to this release, it was possible to use these options in combination
  with bad (empty) default umask to write pidfiles into a public area on disk
  where they were writable by other users. In the worst case, this could allow
  arbitrary execution of the contents of the malicious pidfile by keychain.

  This hardening now makes it difficult for a user to configure their keychain
  in a way that would allow this to happen. Note that if you are not using the
  --dir or --absolute options, keychain will use the $HOME/.keychain
  directory by default, which is typically under the full control of the
  current user and thus not exploitable.

  The hardening changes include:

  • Setting a global restrictive umask in the script.
  • Remove pidfiles before redirecting data to them to ensure they are created
    with restrictive permissions from the umask.
  • Check the keychain pidfile directory to ensure it is owned by the current
    user, and only the current user can access it (mode 700). If not, abort
    with an informative error message.
  • Check any existing pidfiles prior to use to make sure they are owned by the
    current user, and only the current user can access them. If not, abort with
    an informative error message.

  Thanks to Eisuke Kawashima (@e-kwsm) for reporting this issue, the --systemd
  issue, as well as for the --query fix.

Keychain 2.9.2

ChangeLog for Keychain

http://www.funtoo.org/Funtoo:Keychain

keychain 2.9.2 (2 May 2025)

This is primarily a bug fix release, but also introduces the new --extended option -- see below:

• Deprecate --confhost option and replace with --extended option. The old --confhost myhost would now be --extended host:myhost. This also allows specifying SSH keys (sshk: prefix), GPG keys ( gpgk: prefix) and hosts (host: prefix) together without confusion.
• Well, I became intimately familiar with IFS the hard way. Fix 2.9.1 bug #159 by reworking IFS settings and adding proper documentation to the right places. This fixes the --timeout option and also now allows --stop to work properly which was broken.
• Improve --agents deprecation warning.
• Have keychain properly adopt a currently-running gpg-agent providing ssh-agent functionality when --ssh-use-gpg is specified.
• Explicitly clean up known-bad pidfiles during processing.
• Deprecate --confhost option and replace with new --extended option.
• Improve host-based key processing by using ssh -G to officially extract host-based keys.
• Make Makefile BSD-compatible.