1021 字
5 分钟
页面浏览--访问次数--
Windows 11 下配置 gpg-agent 作为 SSH Agent

目标#

把 GPG 密钥的 Authentication 子密钥([A])通过 gpg-agent 提供给 SSH 使用,实现:

  • 所有 SSH 客户端(系统 OpenSSH、Tabby、MobaXterm、Git)统一走 gpg-agent。
  • 私钥由 GPG 管理,连接时弹 Pinentry 输入 passphrase,之后凭 agent 缓存免输。

需求#

  • 一把 GPG 密钥对,需要有一个带有认证能力的子密钥。
  • Windows 11,GnuPG 2.5.24。
  • Windows OpenSSH 客户端

标准配置流程#

启用 gpg-agent 的 SSH 支持#

在 %APPDATA%\gnupg\gpg-agent.conf 中,开启能力。

enable-ssh-support
enable-putty-support
enable-win32-openssh-support

enable-win32-openssh-support 将指示 GPG 监听 Named Pipe 而不是 gpgconf --list-dirs agent-ssh-socket 返回的 UNIX Socket。

如果你想要少输入密码,可以将输入密码的缓存时间适当延长。

default-cache-ttl 14400
default-cache-ttl-ssh 28800
max-cache-ttl 72000
max-cache-ttl-ssh 72000

设置环境变量#

Terminal window
[Environment]::SetEnvironmentVariable("SSH_AUTH_SOCK", "\\.\pipe\openssh-ssh-agent", "User")

把认证子密钥的 keygrip 写进 sshcontrol#

Terminal window
gpg -K --with-keygrip

输出密钥

[keyboxd]
---------
sec rsa4096 2021-05-22 [SCA] [expires: 2027-05-22]
F3AB96E458C8098D8330A9FB52B66523B085EE81
Keygrip = 1E5E9B37B291487D1F2D0070F98DCF02239097EB
uid [ultimate] Ariel Yu <ariel@ariels.xyz>
uid [ultimate] Ariel Heleneto <ArielHeleneto@outlook.com>
uid [ unknown] Ariel Yu <ariel@sipeed.com>
ssb rsa4096 2021-05-22 [E]
1DEAF49B1B2E7FA77E8B1D15123F96538D31559F
Keygrip = A1D08BCEE369FEC16ACEA73BFEB387A4BEC8A8CF
ssb cv25519 2021-05-22 [E]
0020215B0920884992D35E9D4D8F38B92E5248B7
Keygrip = 23534D04877E7D4B6A1E4C9FECE541150CB810C5
ssb rsa4096 2021-05-22 [S]
69DE13641447AA65AC447F4ABCB2CD7D1AFB6F88
Keygrip = 8577BF1D983F1A6C6D9267CE63B188C29C9CDCF9
ssb ed25519 2021-05-22 [S]
5D3B0C69DBF558427A448E9FF501EDC3B220DA49
Keygrip = 1FBB2BE44F9C6E0558A32DC3E4ECADCF3333DF09
ssb rsa4096 2021-05-22 [A]
63FE25CF6BE1F409E25E63F2D9E17E6F3E0DEA6D
Keygrip = 9B72088D1C1447FF7557951C31EF2DEF3E05DED2
ssb ed25519 2021-05-22 [A]
BC48CE5A121FEEC0CB967D3313158EEB7B25AAEA
Keygrip = B9CD8C3C12089F2E440374ECE0CAC2FF680F348A

选择其中带有 [A] 标签的密钥,将它的 Keygrip 复制到 %APPDATA%\gnupg\sshcontrol,一行一个。最后必须包含一个空行(即只有换行符)。在 Keygrip 前添加一个 ! 以禁止它提供给 SSH。

sshcontrol
# List of allowed ssh keys. Only keys present in this file are used
# in the SSH protocol. The ssh-add tool may add new entries to this
# file to enable them; you may also add them manually. Comment
# lines, like this one, as well as empty lines are ignored. Lines do
# have a certain length limit but this is not serious limitation as
# the format of the entries is fixed and checked by gpg-agent. A
# non-comment line starts with optional white spaces, followed by the
# keygrip of the key given as 40 hex digits, optionally followed by a
# caching TTL in seconds, and another optional field for arbitrary
# flags. Prepend the keygrip with an '!' mark to disable it.
B9CD8C3C12089F2E440374ECE0CAC2FF680F348A
!9B72088D1C1447FF7557951C31EF2DEF3E05DED2

重启并验证#

Terminal window
gpgconf --kill gpg-agent
gpg-connect-agent /bye
ssh-add -L

最后应该输出

PS C:\Users\ariel> gpgconf --kill gpg-agent
PS C:\Users\ariel> gpg-connect-agent /bye
gpg-connect-agent: no running gpg-agent - starting 'D:\\GnuPG\\bin\\gpg-agent.exe'
gpg-connect-agent: waiting for the agent to come up ... (8s)
gpg-connect-agent: connection to the agent established
PS C:\Users\ariel> ssh-add -L
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIECLIlTqktMnrpa9RM9KDyOoV4FYYVztKj1a6vG8TwBi (none)
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQCeDSOFF45EL/Gin8mJk1oB9LPM3F44p28MDtvtSvF2Q/X8nxjO0j2S17o1ljsMIH2pFEWIczVQbmk2eA6sm5eu6bzeI9mav1cq2ivQHPHlE5qCe6HhczqdUITf/C8i390QWati7dCOSkziqcoo0n8PLxu4A6IB2V5ZXdmORxm/QuxqvmiV9LUTc0EQLpcpH14ti2JquZWnm4p/+r7tgQUPjB8TCqNjx1QMivCnSfnthn2yKIv5aBP8WevmPO9gagsW6EjPE2hOBdywYxvOuZEZbcKty2gB18ImRM2NJ15AqS25psmKMcFmu68OdE23BqqhA2KwYF6VjbXk3nTRR7AK5pNw3NtWOyMh9tbLaST25omoihaIbfr1nRC5WmQQAMQtaojoAGVKs435PgjIRL03g6fj7tjI13gtmjL3qDYWYOrG9uXaQsdoobhyd8j04KCRY4UfccAIJVRlNPrnbSsrZEXp66oM0NtoiNnm+CAWnHZ/OqI6uoyDlZhA7R/l26PMhOuY4NiLj5UwGKKEwDWAoI4UsFGdBirOkdIjbSRk5K35oZur4Px/bmiWfRTjx9Bstnp8jfnFV7fV1CTbAQ69g3K9ndF2zF2wAA0s38fNt4wrxUDN/Tt9H4n9Rg9mBI7YjeLtFbQWeERlutFS3UlzSotZHwIvOPI5h4FC8R4wvQ== (none)

常见问题#

The agent has no identities#

ssh-add -L 能连上 agent,但列表是空的。

原因:sshcontrol 还是安装时的默认模板,里面只有注释,没有任何 Keygrip。或者你的私钥不存在于设备上(常见于智能卡未连接)

排查手法:直接读文件内容确认。这类”agent 行为异常”问题,第一步永远是确认输入文件的真实内容,而不是假设自己配置过。

error fetching identities: agent refused operation#

补上 keygrip 之后,错误变了。这次 agent 拒绝执行操作,说明它收到了请求但处理不了。

排查手法:开 debug 日志。在 gpg-agent.conf 里加:

log-file %APPDATA%\gnupg\gpg-agent.log
debug 1024

1024 是 SSH 协议的调试类别。然后 gpgconf --kill gpg-agent 重启,再执行 ssh-add -L,日志里出现了关键一行:

ssh request identities failed: Line too long <GPG Agent>

Line too long —— agent 解析 sshcontrol 时某一行超过了行长度限制。

排查手法: 文件末尾没有换行符(EOF 直接截断在最后一个字符)

后来搜到一篇同病相怜的博文,作者也是同样的 Line too long,原因同样是 sshcontrol 里混入了杂散字符。sshcontrol 必须是干净的纯文本,keygrip 行必须以换行符结尾。

经验总结#

  1. 指纹(fingerprint)和 keygrip 是两个东西。gpg --with-keygrip 输出里每个密钥有三行:密钥行、指纹行、Keygrip = 行。sshcontrol、PGP 命令的 keygrip 参数都要用最后一行。
  2. sshcontrol 是脆弱的:纯 ASCII、keygrip 独占一行、必须以换行符结尾、不要混入禁用行。推荐用 Set-Content -Encoding Ascii 生成,而不是手动编辑。
  3. gpg-agent 的很多错误是静默的:key 加载失败只会跳过,不报错。keyinfo 和日志文件是唯一的窗口。
  4. Windows 下 SSH_AUTH_SOCK 必须是 \\.\pipe\openssh-ssh-agent**,并确保 Windows 的 ssh-agent 服务被禁用,否则两个 agent 抢同一个 pipe。
  5. Pinentry 弹窗失败/私钥操作卡住时,检查 gpg-agent 是不是以管理员身份运行的(会以你的用户身份找不到钥匙串)。

参考文献#

Windows 11 下配置 gpg-agent 作为 SSH Agent
https://www.ariels.xyz/posts/gpg-ssh-windows/
作者
Ariel
发布于
2026-11-15
许可协议
CC BY-NC-ND 4.0

分享文章

生成精美分享图或复制链接,与更多人分享本文。

继续阅读

沿着主题读

基于共同的标签与分类

换条路线

从其他文章中稳定抽取