keychain

Check for a running ssh-agent, and start one if needed

$ keychain

$ keychain --agents "[gpg,ssh]"

$ keychain --list

$ keychain --list-fp

$ keychain --timeout [minutes]

keychain [options] [program...]

--agents
    Specify which agents to start and manage (e.g., 'ssh', 'gpg', 'all').

--eval
    Print shell commands to set up the agent environment variables for the current session.

--clear
    Remove old agent files before starting new ones, effectively resetting the agent.

--confirm
    Require user confirmation (via x11-ssh-askpass) before allowing new SSH connections.

--timeout
    Set a timeout in minutes for passphrase caching by the agent.

--quiet
    Suppress verbose startup messages from keychain.

--shell
    Explicitly specify the shell type (e.g., 'sh', 'csh', 'fish') for correct output formatting.

[keys...]
    One or more SSH/GPG key files to load into the agent(s). Defaults to ~/.ssh/id_rsa, ~/.ssh/id_dsa, etc.

keychain is a utility that manages ssh-agent and gpg-agent instances persistently across login sessions. It ensures that your SSH keys and GPG keys are loaded automatically without needing to enter passphrases repeatedly for each new terminal or graphical login.

When you first log in, keychain starts ssh-agent and/or gpg-agent if they are not already running, and stores their environment variables (like SSH_AUTH_SOCK and SSH_AGENT_PID) in files. Subsequent login sessions then read these files, allowing all your sessions to share a single, long-running agent instance. This approach significantly enhances convenience by eliminating redundant passphrase entries and improves security by preventing multiple, short-lived agent processes. It can automatically add default keys or specified keys to the agent, providing a seamless and secure experience for managing cryptographic keys.

Security Implications: While convenient, keychain causes your decrypted keys to remain in memory for extended periods within the agent process. If an attacker gains root access or exploits a memory vulnerability, they could potentially extract your keys.
Shared Sessions: All your sessions sharing a single agent means that if one session is compromised, the keys loaded into the agent could be exposed to the attacker through that session.
Proper Setup: Incorrect integration into shell startup files (~/.bashrc, ~/.zshrc) can lead to agents not starting correctly or environment variables not being set, diminishing its intended benefits.

Users typically integrate keychain into their shell startup files, such as ~/.bashrc or ~/.zshrc, to ensure it runs automatically upon every new shell session. A common pattern involves:

eval `keychain --agents ssh --eval`

This command runs keychain, which then outputs shell commands to set up the necessary environment variables. The eval command executes these, connecting the current session to the persistent ssh-agent (and potentially gpg-agent if specified). If keys need to be added, they can be listed after options, e.g., keychain id_rsa. The first time a session connects, you might be prompted for passphrases, which are then cached by the agent.

keychain was created by Dwayne C. Litzenberger to simplify the management of ssh-agent by providing a more robust and user-friendly wrapper. Its primary goal was to ensure agent persistence across multiple login sessions without manual intervention, a common challenge with raw ssh-agent usage. Over time, it evolved to also support gpg-agent and gained widespread adoption as a de-facto standard tool for persistent key management on Unix-like systems, solving the repetitive passphrase entry problem for many users.

ssh-agent(1), gpg-agent(1), ssh(1), ssh-add(1)