SSH Agent¶

Terminology rule (zh-TW pages)

技術名詞首次出現以「中文 (English original)」格式呈現，例：依賴注入 (dependency injection)。不自創翻譯——若無公認譯名直接保留英文（如 embedding、tokenizer）。代碼、API 名、CLI flag、套件名、檔名一律不翻。

自動化的 SSH agent 管理：以 Bitwarden 為優先，並 fallback 到 ssh-agent。

設定檔：~/.config/zsh/tools/94_ssh_agent.zsh

觀念¶

什麼是 SSH 金鑰對 (key pair)？¶

SSH 採用非對稱加密 (asymmetric cryptography) —— 一把私鑰 (private key)（必須保密）與一把公鑰 (public key)（可自由分享）。

~/.ssh/id_ed25519      ← 私鑰（絕對不要外流）
~/.ssh/id_ed25519.pub  ← 公鑰（貼到伺服器／GitHub）

當你連線到伺服器 (server) 時，SSH 會用私鑰完成一次密碼學挑戰 (challenge) 來證明身分；伺服器則用 ~/.ssh/authorized_keys 中的公鑰來驗證。

金鑰類型（新建議使用 ed25519）：

類型	強度	備註
`ed25519`	現代且建議	金鑰短、速度快、安全
`rsa`（4096-bit）	相容性廣	較舊；若已在使用仍可接受
`ecdsa`	良好	較少見

產生新金鑰：

ssh-keygen -t ed25519 -C "your@email.com"
# 會儲存至 ~/.ssh/id_ed25519 與 ~/.ssh/id_ed25519.pub

什麼是 passphrase？¶

passphrase 會把磁碟上的私鑰檔案加密。沒有它的話，任何拿到檔案的人都能直接使用。

取捨： - 沒有 passphrase：方便，但機器一旦被入侵就有風險 - 有 passphrase：安全，但每次使用金鑰都要輸入 —— 除非搭配 SSH agent

什麼是 SSH agent？¶

SSH agent 是一個背景行程 (background process)，在記憶體中持有你已解密的私鑰。當 SSH 需要簽署挑戰時，會請 agent 代簽 —— 因此你只需在每次登入工作階段 (session) 輸入一次 passphrase，而不是每次連線都要輸入。

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

通訊是透過 SSH_AUTH_SOCK 指向的 Unix socket：

echo $SSH_AUTH_SOCK    # 例如 /run/user/1000/ssh-agent/agent.sock
ssh-add -l             # 列出 agent 目前持有的金鑰
ssh-add ~/.ssh/id_rsa  # 手動加入金鑰（會問一次 passphrase）

自動載入金鑰的運作方式（以及 passphrase 提示）¶

當 fallback 的 ssh-agent 啟動且尚未持有任何金鑰時，94_ssh_agent.zsh 中的 _maybe_add_keys 會嘗試自動加入常見的金鑰檔：

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

SSH_ASKPASS_REQUIRE=never 是告訴 ssh-add：「完全不要詢問 passphrase —— 如果需要，就靜默失敗。」這意味著：

沒有 passphrase 的金鑰 → 自動靜默載入到 agent
有 passphrase 的金鑰 → 跳過（登入時不會跳出提示）

**為什麼不用 `