指南 · SSH 代理

你的 SSH 密钥，
放在保险库里。

Triwarden 能像 ssh-agent 一样响应 ssh 和 git，密钥来自保险库中的 SSH 密钥项目。私钥永远不会离开 App，每一次签名都会先问你。

ssh 请代理签名。Triwarden 先问你（触控 ID 或 Mac 密码），在 App 内完成签名，只把签名发回去。

设置

四个步骤，
大约两分钟。

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"
```

确认可以用

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 git@github.com
# 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 登录。网络上传输的只有签名。

Terminal

$ ssh alex@nas.home.arpa 'cat >> ~/.ssh/authorized_keys' < homelab.pub
$ ssh alex@nas.home.arpa

签名的 git 提交

在密钥页面上，Git 签名 › 复制设置会给你这三行。把同一个公钥添加到 GitHub 作为 Signing key，你的提交就会显示 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 "alex@example.com 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 alex@example.com 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 分钟一次: 适合长时间工作；锁定后就会忘记

没有触控 ID — Mac mini、Mac Studio，或合上屏幕？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的地方。

GitHub 和 GitLab

你的服务器

签名的 git 提交

多个密钥

只用于部分主机

Git App 和编辑器

没有你，什么都不会签名。

如果它不能用。

随时可以开始。

四个步骤，
大约两分钟。

所有用到 ssh
的地方。

没有你，
什么都不会签名。

如果它
不能用。