指南 · SSH 代理程式

你的 SSH 金鑰，
放在保險庫裡。

Triwarden 使用保險庫中的 SSH 金鑰，為 ssh 與 git 提供代理服務。簽署在 App 內完成，用戶端取得簽署，不會取得私鑰；核准頻率可自行設定。

ssh 請求簽署。Triwarden 檢查核准狀態，必要時要求 Touch ID 或 Mac 密碼，完成後回傳簽署。

設定

四個步驟，
設定 SSH 代理程式。

01
開啟代理程式
打開 Triwarden › 設定 › 開發者，開啟 使用 Triwarden 作為 SSH 代理程式。App 開著時它就會運作，而且只在保險庫解鎖時提供金鑰。
02
加入金鑰
新增一個 SSH 金鑰項目。按 產生 Ed25519 金鑰建立新的，或貼上你已有的私鑰 — 未加密的 OpenSSH 金鑰（-----BEGIN OPENSSH PRIVATE KEY-----）。Ed25519、ECDSA（P-256、P-384、P-521）與 RSA 都支援，其他 Bitwarden App 存的 SSH 金鑰也會出現。
金鑰有密語？代理程式無法使用加密的金鑰。先做一份未加密的副本，貼進項目後刪除副本 — 之後由保險庫替它加密。
Remove a passphrase (on a copy)
```
$ cp ~/.ssh/id_ed25519 /tmp/key
$ ssh-keygen -p -N "" -f /tmp/key
# paste /tmp/key into the item, then:
$ rm /tmp/key
```
03
讓 ssh 找到它
把代理程式加入 ~/.ssh/config — 設定 › 開發者 › SSH 設定有個複製按鈕，路徑已幫你填好。也可以只對單一 Shell 設定。
建議用設定檔：從 Dock 開啟的 App（VS Code、Tower、Fork、Xcode）讀不到 Shell 的變數，但每個 ssh 都會讀設定檔。
~/.ssh/config
```
Host *
  IdentityAgent "~/Library/Group Containers/…/agent.sock"
```
zsh
```
$ export SSH_AUTH_SOCK="$HOME/Library/Group Containers/…/agent.sock"
```
04
確認可以用
ssh-add -L 會列出代理程式提供的公鑰。什麼都沒有？請看下方的解決方法。
Terminal
```
$ ssh-add -L
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKx…Qx9 GitHub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIM2…7mK homelab
```

日常使用

所有用到 ssh
的地方。

GitHub 與 GitLab

把項目的公鑰貼到 GitHub › Settings › SSH and GPG keys，類型選 Authentication key（GitLab：User settings › SSH keys）。然後測試：

Terminal

$ ssh -T [email protected]
# Triwarden asks: allow “ssh” to sign with “GitHub”
Hi alexchen! You've successfully authenticated, but GitHub does not provide shell access.

你的伺服器

把公鑰加入伺服器的 ~/.ssh/authorized_keys，再以 ssh 連線。Triwarden 代理程式回傳簽署，不會把私鑰傳給 ssh。

Terminal

$ ssh [email protected] 'cat >> ~/.ssh/authorized_keys' < homelab.pub
$ ssh [email protected]

簽署的 git commit

在金鑰頁面上，Git 簽署 › 複製設定會給你這三行。把同一把公鑰加到 GitHub 作為 Signing key，你的 commit 就會顯示 Verified。

Git signing › Copy Setup

$ git config --global gpg.format ssh
$ git config --global user.signingkey "key::ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKx…Qx9 GitHub"
$ git config --global commit.gpgsign true

也想在本機驗證簽署，就列出你信任的金鑰：

Terminal

$ echo "[email protected] ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKx…Qx9" >> ~/.ssh/allowed_signers
$ git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers
$ git log --show-signature -1
Good "git" signature for [email protected] with ED25519 key SHA256:…

多把金鑰

金鑰很多時，伺服器可能在試到正確那把之前就回報「Too many authentication failures」。把那把金鑰的公開部分存成檔案，並指定給該主機：

~/.ssh/config

Host github.com
  IdentityFile ~/.ssh/github.pub
  IdentitiesOnly yes

只用於部分主機

其他主機想繼續用別的代理程式？只讓指定的主機使用 Triwarden：

~/.ssh/config

Host github.com gitlab.com nas.home.arpa
  IdentityAgent "~/Library/Group Containers/…/agent.sock"

Git App 與編輯器

VS Code、Tower、Fork、Xcode 以及任何使用系統 ssh 的 App 都會讀 ~/.ssh/config，完成第 3 步後就能用，核准提示也一樣會出現。

核准

由你決定，
何時核准簽署。

每個請求都會寫明程式與金鑰 —「允許 ssh 以 SSH 金鑰 GitHub 簽署」。在設定 › 開發者 › 簽署前詢問 選擇多久問一次：

每次: 預設：每次簽署都會詢問
每個 App 每分鐘一次: 適合連續好幾次 git fetch
每個 App 每 10 分鐘一次: 適合長時間工作；鎖定後就會忘記

Touch ID 無法使用時，macOS 可改用 Mac 密碼核准。選擇拒絕即可拒絕請求。「設定 › 開發者」會列出近期核准與拒絕紀錄。

解決方法

如果它
不能用。

「The agent has no identities.」

保險庫已鎖定、代理程式沒開、沒有 SSH 金鑰項目，或項目裡的金鑰有密語（加密的金鑰不會被提供）。

「Could not open a connection to your authentication agent」

這個 Shell 不知道代理程式在哪。把 IdentityAgent 那行加入 ~/.ssh/config，或在該 Shell 執行第 3 步的 export。

「agent refused operation」

請求被拒絕，或提示放著直到逾時。重新執行指令並核准即可。

「Too many authentication failures」

伺服器在試到正確的金鑰前就放棄了。把金鑰指定給該主機（見上方「多把金鑰」）。

隨時可以開始。

個人免費使用也包含 SSH 代理程式。工作用途需購買授權。

下載 Mac 版

四個步驟，設定 SSH 代理程式。

開啟代理程式

加入金鑰

讓 ssh 找到它

確認可以用

所有用到 ssh的地方。

GitHub 與 GitLab

你的伺服器

簽署的 git commit

多把金鑰

只用於部分主機

Git App 與編輯器

由你決定，何時核准簽署。

如果它不能用。

隨時可以開始。

四個步驟，
設定 SSH 代理程式。

所有用到 ssh
的地方。

由你決定，
何時核准簽署。

如果它
不能用。