skip to content

Key Agent & Forwarding

ssh-agent holds decrypted keys behind SSH_AUTH_SOCK so a passphrase is typed once; forwarding lends that socket to the remote host. Interviewers ask why ProxyJump beats -A through a bastion.

on this pageshow

questions

5

What does OpenSSH's ssh-agent hold for you, and how do ssh and ssh-add find it through SSH_AUTH_SOCK?

level: juniorimportance: must knowfreq 55%

answer

  1. passphrase typed once
  2. signatures out, keys never
  3. a Unix-domain socket path
  4. eval output exports two variables
  5. socket directory moved in 10.1

basics

~20 s

ssh-agent keeps private keys decrypted in memory, so each passphrase is typed once, and signs authentication data on request without ever handing a key out. ssh and ssh-add reach it through the Unix-domain socket named in SSH_AUTH_SOCK.

solid answer

~40 s

`ssh-agent` is a small long-running process that holds unwrapped private keys. `ssh-add` asks for a key's passphrase once and loads it; from then on `ssh` sends the agent the data that public key authentication must sign and gets back only a signature, so the private key never leaves the agent. Programs find the agent through the Unix-domain socket whose path is in `SSH_AUTH_SOCK`: `eval "$(ssh-agent -s)"` starts it and exports that variable together with `SSH_AGENT_PID`. Since OpenSSH 10.1 the socket is created under `~/.ssh/agent/` rather than in `/tmp`. The socket is accessible only to its owner, but root on the same machine can still connect to it, so the agent contains the key material, not every use of it.

code

bash · 6 lines
bash
eval "$(ssh-agent -s)"          # start; exports SSH_AUTH_SOCK and SSH_AGENT_PID
echo "$SSH_AUTH_SOCK"            # a path under ~/.ssh/agent/ on OpenSSH 10.1+
ssh-add ~/.ssh/id_ed25519        # passphrase asked once
ssh-add -l                       # fingerprints of loaded keys
ssh [email protected]  # signs through the agent, no prompt
ssh-add -D                       # remove every key

go deeper

for a junior

Recall the split: ssh-add loads a key once, ssh-agent keeps it in memory and signs, and SSH_AUTH_SOCK tells every tool where the agent's socket is.

for a middle

Explain that only signatures cross the socket, how eval of ssh-agent -s sets the environment, and what ssh does when the variable points at a dead socket.

for a senior

Show you know what the agent does not protect: anyone who reaches the socket, root included, can use the keys, and lifetimes are off unless you set them.

for a principal

Frame the agent as a trade between passphrase fatigue and standing signing power, and say which keys belong in a long-lived agent at all.

## What the agent is for An SSH **private key** on disk is normally encrypted with a **passphrase**. Without help, every `ssh` login would ask for that passphrase again. **`ssh-agent`** solves this by holding the decrypted ("unwrapped") key in its own memory for the length of a desktop or login session. It is deliberately a simple program: it can add keys, delete keys, list the public halves of the keys it holds and, the operation that matters, **produce a signature** with one of them. That last point is the whole design. During public key authentication the SSH client must prove it holds the private key by signing data supplied by the protocol. With an agent, `ssh` passes that data to the agent and receives the signature back. The private key itself is never sent to `ssh`, never written back to disk and never crosses the network. ## The life of a key in the agent 1. **Start the agent.** `eval "$(ssh-agent -s)"` launches it and evaluates the shell commands it prints, which set `SSH_AUTH_SOCK` (the socket path) and `SSH_AGENT_PID` (its process ID). Many desktop sessions start one for you. 2. **Load keys.** `ssh-add` with no arguments loads the default identity files from `~/.ssh/`; `ssh-add <file>` loads a specific one. The passphrase is asked for once. Alternatively the client directive `AddKeysToAgent` (default `no`) makes `ssh` add a key the first time it is used. 3. **Use keys.** Every later `ssh`, `scp` or `sftp` login asks the agent to sign; no prompt appears. 4. **Inspect and remove.** `ssh-add -l` lists fingerprints, `ssh-add -L` the public keys, `ssh-add -d <file>` removes one key and `ssh-add -D` removes all of them. 5. **Stop.** `ssh-agent -k` kills the agent named by `SSH_AGENT_PID`; the keys vanish with the process. ## How clients find the agent The agent listens on a **Unix-domain socket**, a file-system object that local processes connect to. Nothing about it is network-facing. Three names decide how clients find it: | Mechanism | Where it is set | Effect | |---|---|---| | `IdentityAgent` | the client configuration file | overrides the environment; `none` disables agent use | | `SSH_AUTH_SOCK` | environment, exported by `ssh-agent` | the path every OpenSSH tool tries by default | | `SSH_AGENT_PID` | environment, exported by `ssh-agent` | identifies the process for `ssh-agent -k`; not used to connect | If `SSH_AUTH_SOCK` is empty or points at a dead socket, `ssh-add` exits with status 2 (unable to contact the agent) and `ssh` falls back to reading key files, prompting for passphrases again. ## Where the socket lives For most of OpenSSH's history the agent created its socket in a randomly named directory under `/tmp`. **OpenSSH 10.1** moved agent listener sockets, for both `ssh-agent` and the forwarded sockets `sshd` creates, to **`~/.ssh/agent/`**, with names matching `s.*`. The release notes give the reason: a process whose sandbox still allows `/tmp` should not, by that fact alone, be able to reach an agent and use its keys. The move has side effects worth knowing: - the operating system no longer sweeps stale sockets out of `/tmp`, so `ssh-agent` now cleans up old sockets itself (`-U` suppresses that, `-u` only cleans and exits); - the path includes a truncated hash of the host name, so a home directory shared over NFS does not mix sockets from different machines; - `ssh-agent -T` restores the old behaviour, a random directory under `$TMPDIR`; - scripts that hunted for agents by globbing `/tmp` stop finding them. ## What the agent protects, and what it does not - **Protected:** the key material. A program that can talk to the agent gets signatures, not keys. - **Not protected:** use of the keys. Anyone who can connect to the socket can ask for signatures. The manual is blunt: the socket is accessible only to the current user, "but is easily abused by root or another instance of the same user". - **Not protected:** keys after the agent's lifetime controls, which are off by default; a key added without a lifetime stays until it is removed or the agent exits. That gap between holding a key and using it is why lending the socket to another machine, agent forwarding, is the subject interviewers press on next.

  • Why did OpenSSH 10.1 move agent sockets out of /tmp?
    Processes with restricted file-system access usually keep `/tmp`, so a socket there was reachable by them and its keys usable by default. Putting `ssh-agent`'s socket, and the forwarded sockets `sshd` creates, under `~/.ssh/agent/` removes that ambient access. Because the OS no longer cleans that directory, `ssh-agent` now removes stale sockets itself; `-T` puts the socket back under `$TMPDIR`.
  • Can root on the same machine use your agent?
    Yes. The socket's permissions stop other ordinary users, but root bypasses file permissions and can connect to it, list your keys and request signatures. The `ssh-agent` manual says the socket is "easily abused by root or another instance of the same user". The agent keeps the key material inside its process; it cannot stop a privileged local user from asking it to sign.
  • How do you point ssh at a different agent than the one in SSH_AUTH_SOCK?
    Set `IdentityAgent` in the client configuration: it overrides `SSH_AUTH_SOCK`, accepts a socket path or a `$VARIABLE`, and `none` disables agent use for that host. That lets one host use a second agent that holds only the key it needs.

  • ssh-agent hands the decrypted private key to ssh at login time.
  • ssh-agent writes the unlocked keys to a file on disk.
  • SSH_AUTH_SOCK contains the passphrase or the key itself.
  • Agent sockets always live under /tmp on current OpenSSH.
  • The socket's file permissions stop root from using your agent.

Assumes OpenSSH 10.5; since 10.1 ssh-agent and sshd create agent sockets under ~/.ssh/agent instead of /tmp.

open as a page

Root on a shared SSH bastion logged in to production as an SRE who had used ssh -A; what had agent forwarding lent it?

level: middleimportance: must knowfreq 42%

basics

~20 s

Agent forwarding lent root on the bastion a socket into the SRE's laptop agent: while her session was open, root could have the agent sign logins to any host her keys open. It could not copy the private keys.

open as a page

Why is OpenSSH's ProxyJump (ssh -J) safer than agent forwarding for reaching hosts behind an SSH bastion?

level: middleimportance: should knowfreq 36%

basics

~20 s

With ProxyJump the bastion only relays an encrypted connection; the laptop runs the inner SSH session and authenticates to the target itself, so neither keys nor an agent socket reach the bastion. Agent forwarding lends that socket to the bastion.

open as a page

What do OpenSSH ssh-add's -t, -c and -x options each limit about agent-held keys, and what does each leave exposed?

level: middleimportance: should knowfreq 22%

basics

~20 s

ssh-add -t deletes a key after a lifetime, -c makes each use wait for an ssh-askpass confirmation, and -x locks the whole agent until -X. Each narrows when keys can be used, not who may ask or where.

open as a page

How do OpenSSH ssh-add -h destination constraints limit where a forwarded agent key can be used, and what can they not prevent?

level: seniorimportance: nice to knowfreq 12%

basics

~20 s

Since OpenSSH 8.9, ssh-add -h names, by host key, where a key may authenticate and through which hops; the agent checks each request's bound session path and refuses others. Root on a permitted hop can still use it.

open as a page