ssh-agent, passphrases, and keyrings

What exactly is an agent?#

ssh-agent = an in-memory process dedicated to holding your unlocked private keys.

It does one thing: load private keys into memory and provide signing services to other programs over a socket (SSH_AUTH_SOCK). The standard agent signing interface does not hand private keys to clients requesting signatures. During authentication, a program sends the data to be signed to the agent; the agent signs it with a private key in memory and returns the result.

A comparison:

• Without an agent: each new connection using an encrypted private-key file usually requires reading the file and entering its passphrase; connection multiplexing and other ways of providing keys are separate cases
• With an agent: unlock the key once to load it into memory; subsequent uses of that key usually do not require entering the passphrase again, subject to lifetime limits and confirmation policies

Minimizing private-key exposure Signing happens in the agent's memory, so each process does not need to read the private-key file. This is the core security design of an agent: find it through the interface and select the matching key. The process neither knows nor cares what the private key looks like.

SSH_AUTH_SOCK: the ecosystem interface#

The agent does not inherently know "which process wants which password." Everything relies on a standard interface and a conventional environment variable:

SSH_AUTH_SOCK=/run/user/<uid>/gcr/ssh

Any SSH client (ssh, git, scp, rsync, and so on) reads this variable at startup to locate the socket: "ask the agent at the socket pointed to by SSH_AUTH_SOCK for a signature." This is ecosystem integration, rather than personal configuration: OpenSSH defines the agent protocol, gnome-keyring implements an agent compatible with it, and clients connect according to the standard.

The layers: gcr-ssh-agent vs ssh-agent vs gnome-keyring#

Keep these three layers distinct:

gnome-keyring-daemon  → 通用秘密存储（Secret Service 等）
gcr-ssh-agent        → 桌面 SSH agent 集成（版本与启动方式依发行版而异）
OpenSSH ssh-agent    → 标准 agent 签名进程
ssh / ssh-add       → 通过 SSH_AUTH_SOCK 访问 agent

GNOME's SSH agent components have moved over time, so gcr should not be treated as a fixed component embedded inside gnome-keyring-daemon in every version. Common gcr integrations combine the OpenSSH agent, password prompts, and the keyring. Check the actual services, sockets, and automatic key-loading behavior for your distribution version and user session.

ssh-keygen is part of OpenSSH and does not require gcr. Generating keys, running sshd, and automatically unlocking keys on the desktop are separate functions; how they are installed or enabled depends on the system configuration.

A passphrase is not "a password for a password"#

SSH involves two distinct ideas that are often both called "passwords":

① Identity = key: the private key id_ed25519 is not a password string; it is a mathematical signing tool. During authentication, your machine generates a signature with the private key → the remote side verifies it using your registered public key → access is granted if verification succeeds.

② Passphrase = a lock on the private-key file: a private key is a file. Without protection, anyone who can read it can impersonate you. The passphrase adds a password lock to that file: you need it only when opening the private-key file locally.

真正的认证：  GitHub ◄──签名── 你的私钥     ← 只有这一层是「认证」
                                    │
本地保护：                    私钥文件被 passphrase 锁着    ← 这只是「开文件」

The passphrase does not participate in network authentication; GitHub has no idea whether you have one. This is not a pointless extra layer. It closes the major security gap of leaving a private key unprotected.

Keyring + PAM: how the login password unlocks the keyring#

With matching PAM, keyring, and desktop agent integration enabled, the following chain may apply:

显示管理器登录输入密码
    │
    ▼
PAM 的 pam_gnome_keyring.so
    │  （实际登录服务的 PAM 栈，路径与内容依系统而异）
    ▼
gnome-keyring 用登录密码解锁 keyring
    │
    ▼
gcr-ssh-agent 从 keyring 取出 SSH passphrase
    │
    ▼
按集成策略解锁或按需加载私钥，减少 passphrase 提示

Keyring files are stored in ~/.local/share/keyrings/; filenames vary by version and keyring.

About "not setting a password" If the login keyring password matches the login password and PAM integration is working, the keyring can unlock automatically at login. Automatic login, fingerprint login, and other methods that do not provide the plaintext login password do not guarantee unlocking. A real pitfall is changing the system login password without updating the keyring password: the old keyring is encrypted with the old password, so the new password cannot unlock it, and you need to enter the old password manually once.

What if you forget the passphrase?#

Unrecoverable passphrases If you cannot obtain the private key's passphrase and have no recoverable copy, OpenSSH has no backdoor for resetting the passphrase to unlock the original private key. SSH login authorization can usually be replaced through another administrative channel. If the same key was used to encrypt data, the recovery conditions must be assessed separately.

Related#

• Authentication model → The SSH Authentication System
• Command-line operations → SSH Usage Guide
• References: ssh-agent manual | Debian ssh-agent manual

An agent is not a security boundary that isolates an entire account: processes running as the same user or as root may request signatures if they can access the socket. Agent forwarding also exposes signing capability to the remote machine, so assess your trust in it before use.