SSH Agent¶

Automatic SSH agent management with Bitwarden-first fallback to ssh-agent.

Config file: ~/.config/zsh/tools/94_ssh_agent.zsh

Concepts¶

What is an SSH key pair?¶

SSH uses asymmetric cryptography — a private key (kept secret) and a public key (shared freely).

~/.ssh/id_ed25519      ← private key  (never share this)
~/.ssh/id_ed25519.pub  ← public key   (paste into servers / GitHub)

When you connect to a server, SSH proves your identity by doing a cryptographic challenge using your private key. The server verifies it with your public key in ~/.ssh/authorized_keys.

Key types (prefer ed25519 for new keys):

Type	Strength	Notes
`ed25519`	Modern, recommended	Small key, fast, secure
`rsa` (4096-bit)	Widely compatible	Older; still fine if already in use
`ecdsa`	Good	Less common

Generate a new key:

ssh-keygen -t ed25519 -C "your@email.com"
# Saves to ~/.ssh/id_ed25519 and ~/.ssh/id_ed25519.pub

What is a passphrase?¶

A passphrase encrypts your private key file on disk. Without it, anyone who gets the file can use it.

Trade-off: - No passphrase: convenient, but risky if your machine is compromised - With passphrase: secure, but SSH asks for it every time you use the key — unless you use an SSH agent

What is an SSH agent?¶

An SSH agent is a background process that holds your decrypted private keys in memory. When SSH needs to sign a challenge, it asks the agent — so you only enter the passphrase once per login session, not every connection.

┌───────────┐  challenge  ┌───────────────┐  sign  ┌─────────────┐
│  ssh/git  │ ──────────▶ │   ssh-agent   │ ──────▶ │  decrypted  │
│  client   │ ◀────────── │  (in memory)  │         │   key copy  │
└───────────┘  signature  └───────────────┘         └─────────────┘
        ↑
        └── "Connected!"

Communication happens through a Unix socket pointed to by SSH_AUTH_SOCK:

echo $SSH_AUTH_SOCK    # e.g. /run/user/1000/ssh-agent/agent.sock
ssh-add -l             # list keys currently held by the agent
ssh-add ~/.ssh/id_rsa  # manually add a key (will ask for passphrase once)

How auto-loading keys works (and the passphrase prompt)¶

When the fallback ssh-agent starts and has no keys, _maybe_add_keys in 94_ssh_agent.zsh tries to add common key files automatically:

# key_names list: id_ed25519, id_rsa, id_ecdsa, jingle
SSH_ASKPASS_REQUIRE=never ssh-add -q "$kf" 2>/dev/null

SSH_ASKPASS_REQUIRE=never tells ssh-add: "don't prompt for a passphrase at all — if you need one, just fail silently." This means:

Keys without a passphrase → auto-loaded into the agent silently
Keys with a passphrase → skipped (no prompt at login)

**Why not `