把 SSH 私钥放进 YubiKey：一套更安全、可迁移的密钥管理方案

前言

近期供应链投毒事件频发，针对开发者工作流的攻击也越来越常见。无论是 Apifox、LiteLLM 这类事件，还是其他面向本地开发环境、依赖链和工具链的攻击，防范起来都不容易。一个更稳妥的思路，是尽量不要让私钥以普通文件的形式长期留在本地设备中；如果把私钥放进独立的硬件里，即使本机环境被入侵，也能在一定程度上降低密钥失窃的风险。

YubiKey 是 Yubico 推出的一种硬件安全密钥，通常是一个小型的 USB 设备，也有支持 USB-A、USB-C、NFC 等不同接口和连接方式的型号。它本质上是一块专门用于保存和使用敏感凭据的安全硬件，可以用于网站登录的双重验证，也可以承载 OpenPGP、PIV、FIDO 等类型的密钥材料。

在 SSH 的场景下，使用 YubiKey 的核心价值在于：让私钥尽量不离开硬件设备本身。相比将私钥长期保存在电脑磁盘里，这种方式可以显著降低因主机被入侵、文件被窃取、备份泄露或误拷贝而造成的风险。日常使用时，你仍然可以像平时一样完成 GitHub 认证和服务器登录，但真正的签名操作是在 YubiKey 内部完成的，外部能够获取的只有公钥，而无法直接导出私钥。

本文介绍一套基于 OpenPGP 子钥的实践方案：通过离线保存主密钥、将子钥写入 YubiKey、准备多把备用设备，并结合定期续期与轮换机制，在提升 SSH 密钥安全性的同时，也兼顾多设备使用、硬件损坏后的恢复能力，以及日常认证的可维护性。限于篇幅，本文不会深入介绍过多背景知识，目的是让读者迅速走通流程，把自己的密钥保护起来。

前期准备

首先你需要准备一个 Yubikey 或者类似的硬件安全密钥。建议购买 Yubikey，型号为 Yubikey 5 NFC 和 Yubikey 5c NFC，区别是前者是 USB-A 接口而后者是 USB-C 接口。另一个值得关注的点是固件版本，Yubikey 的固件出厂之后就不可升级，不同固件对加密算法的支持不同，功能特性也有差别，详见Firmware Overview。常见可以购买到的版本一般为 5.4.3（前两年活动有优惠，我也囤了几个）和 5.7.x（最新版本），在日常使用和本文所使用的功能来说区别不大。

另外，也有一些国产的平替可供选择（例如 CanoKey），但是这类产品的兼容性以及对应的文档、社区支持相对都比较差，不建议选择。

接下来的操作，有观点建议使用虚拟机或者干净安装的系统甚至无网的终端来完成，如果有条件，可以自行折腾。便捷来说，断网操作也可以了。

安装依赖

brew install gnupg yubikey-personalization ykman pinentry-mac wget

准备 Yubikey

$ gpg --edit-card

Reader ...........: Yubico YubiKey OTP FIDO CCID
Application ID ...: [MASKED]
Application type .: OpenPGP
Version ..........: 3.4
Manufacturer .....: Yubico
Serial number ....: [MASKED]
Name of cardholder: [not set]
Language prefs ...: [not set]
Salutation .......:
URL of public key : [not set]
Login data .......: [not set]
Signature PIN ....: not forced
Key attributes ...: rsa2048 rsa2048 rsa2048
Max. PIN lengths .: 127 127 127
PIN retry counter : 3 0 3
Signature counter : 0
KDF setting ......: off
UIF setting ......: Sign=off Decrypt=off Auth=off
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]
General key info..: [none]

接下来先设置两个 pin，一个是平常解锁用的 pin，另一个是管理 pin（用于 --edit-card 的）。

gpg/card> admin
Admin commands are allowed

gpg/card> passwd
gpg: OpenPGP card no. [MASKED] detected

1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit

Your selection?

分别输入 1 和 3，根据提示来修改 pin，默认的 pin 为 123456，管理 pin 为 12345678，4 的恢复代码按需求设置（不是必须的）。然后也可以设置一下 name lang url 之类，如果你设置了会在 gpg --card-status 展示对应的信息，这个不是必须的。如果你有多个 Yubikey，重复以上操作即可，当然也可以不在一开始先设置好全部 Yubikey 的信息，在后面换卡的时候再设置也行。

生成密钥

$ gpg --expert --full-generate-key
gpg (GnuPG) 2.4.9; Copyright (C) 2025 g10 Code GmbH
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Please select what kind of key you want:
   (1) RSA and RSA
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
   (7) DSA (set your own capabilities)
   (8) RSA (set your own capabilities)
   (9) ECC (sign and encrypt) *default*
  (10) ECC (sign only)
  (11) ECC (set your own capabilities)
  (13) Existing key
  (14) Existing key from card
Your selection? 9
Please select which elliptic curve you want:
   (1) Curve 25519 *default*
   (2) Curve 448
   (3) NIST P-256
   (4) NIST P-384
   (5) NIST P-521
   (6) Brainpool P-256
   (7) Brainpool P-384
   (8) Brainpool P-512
   (9) secp256k1
Your selection? 9
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0)
Key does not expire at all
Is this correct? (y/N) y

GnuPG needs to construct a user ID to identify your key.

Real name: user
Email address: user@example.com
Comment:
You selected this USER-ID:
    "user <user@example.com>"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O

输入 O 回车之后会弹出一个 passphrase 的框，建议设置一个密码。

We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: /tmp/gpg-5gJAI/trustdb.gpg: trustdb created
gpg: directory '/tmp/gpg-5gJAI/openpgp-revocs.d' created
gpg: revocation certificate stored as '/tmp/gpg-5gJAI/openpgp-revocs.d/EF5D701CAEB2283BB8D10305F43A691EE48B10EC.rev'
public and secret key created and signed.

pub   secp256k1 2026-03-26 [SC]
      EF5D701CAEB2283BB8D10305F43A691EE48B10EC
uid                      user <user@example.com>
sub   secp256k1 2026-03-26 [E]

这时候主密钥就生成好了，这里的 EF5D701CAEB2283BB8D10305F43A691EE48B10EC 就是你的主密钥的指纹，或者叫 key id。

$ PRIMARY_FPR=EF5D701CAEB2283BB8D10305F43A691EE48B10EC

这时候，可以执行一次备份：

$ gpg -a --export-secret-keys "$PRIMARY_FPR" > secret-master-only.asc
$ gpg -a --export "$PRIMARY_FPR" > public-master-only.asc

现在继续生成签名、加密和鉴权使用的子钥。

$ gpg --quick-add-key "$PRIMARY_FPR" ed25519 sign 1y
（会提示你输入 passphrase）
We need to generate a lot of random bytes. It is a good idea to perform some other action (type on the keyboard, move the mouse, utilize the disks) during the prime generation; this gives the random number generator a better chance to gain enough entropy.
$ gpg --quick-add-key "$PRIMARY_FPR" cv25519 encr 1y
$ gpg --quick-add-key "$PRIMARY_FPR" ed25519 auth 1y

执行完后，可以看到新建的带有效期的子钥：

$ gpg --list-keys --with-subkey-fingerprint --keyid-format LONG "$PRIMARY_FPR"
pub   secp256k1/F43A691EE48B10EC 2026-03-26 [SC]
      EF5D701CAEB2283BB8D10305F43A691EE48B10EC
uid                 [ultimate] user <user@example.com>
sub   secp256k1/291AE24AD1CC737D 2026-03-26 [E]
      6CFBDCCF3B478466149FE7E0291AE24AD1CC737D
sub   ed25519/0202CC8049E2FB80 2026-03-26 [S] [expires: 2027-03-26]
      D3C948F3854FF25B339294140202CC8049E2FB80
sub   cv25519/B936CF741340882E 2026-03-26 [E] [expires: 2027-03-26]
      C86408158C50D2C68A0C50D0B936CF741340882E
sub   ed25519/8472C3F353CD9B06 2026-03-26 [A] [expires: 2027-03-26]
      C1B5CC41426C03A0CC0DAFF78472C3F353CD9B06

到这一步我们再备份一次，这次的备份文件需要长期、保密妥善保管，尤其是 secret-full-with-subkeys.asc，最好可以写入一个离线存储里。

$ gpg -a --export-secret-keys "$PRIMARY_FPR" > secret-full-with-subkeys.asc
$ gpg -a --export "$PRIMARY_FPR" > public-full-with-subkeys.asc
$ gpg --export-ownertrust > ownertrust.txt

写入 Yubikey

接下来就是把刚才生成的密钥写入 Yubikey。这里的主要操作有两个，一个是 key n，选中的 key 会用星号标识，再输入一次 key n 取消选择；另一个是 keytocard ，会把私钥写入 Yubikey 对应的槽中。

$ gpg --edit-key "$PRIMARY_FPR"
gpg (GnuPG) 2.4.9; Copyright (C) 2025 g10 Code GmbH
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Secret key is available.

sec  secp256k1/F43A691EE48B10EC
     created: 2026-03-26  expires: never       usage: SC
     trust: ultimate      validity: ultimate
ssb  secp256k1/291AE24AD1CC737D
     created: 2026-03-26  expires: never       usage: E
ssb  ed25519/0202CC8049E2FB80
     created: 2026-03-26  expires: 2027-03-26  usage: S
ssb  cv25519/B936CF741340882E
     created: 2026-03-26  expires: 2027-03-26  usage: E
ssb  ed25519/8472C3F353CD9B06
     created: 2026-03-26  expires: 2027-03-26  usage: A
[ultimate] (1). user <user@example.com>

gpg> key 2

sec  secp256k1/F43A691EE48B10EC
     created: 2026-03-26  expires: never       usage: SC
     trust: ultimate      validity: ultimate
ssb  secp256k1/291AE24AD1CC737D
     created: 2026-03-26  expires: never       usage: E
ssb* ed25519/0202CC8049E2FB80
     created: 2026-03-26  expires: 2027-03-26  usage: S
ssb  cv25519/B936CF741340882E
     created: 2026-03-26  expires: 2027-03-26  usage: E
ssb  ed25519/8472C3F353CD9B06
     created: 2026-03-26  expires: 2027-03-26  usage: A
[ultimate] (1). user <user@example.com>

gpg> keytocard
Please select where to store the key:
   (1) Signature key
   (3) Authentication key
Your selection? 1
(按照提示输入 passphrase 和 admin pin)

在这里依次选择 key、keytocard、反选 key，直到全部 key 都写入成功。

注意，如果你需要把这一份密钥写入多个 Yubikey 中，在全部写完之后，直接按 Ctrl + C 退出，如果在这一步保存了，本地就不会再有私钥，只会留存一个 stub，实际的私钥已经在 Yubikey 里了，是无法导出的。这时候，拔出第一把 Yubikey，插入第二把 Yubikey，前面说的设置 pin 和信息可以在这一步来做，然后重复上面的流程即可，更多的 Yubikey 也同理。当你写到最后一张，确定可以继续了，就执行 save。

gpg> save

现在再执行 gpg --card-status，就会看到对应的 key 前面有个 ssb>，代表密钥已经转移到 Yubikey 上；同时对应的签名、加密、鉴权三个 slot 都有对应的 key。

Reader ...........: Yubico YubiKey OTP FIDO CCID
Application ID ...: [masked]
Application type .: OpenPGP
Version ..........: 3.4
Manufacturer .....: Yubico
Serial number ....: [masked]
Name of cardholder: Leslie Leung
Language prefs ...: en
Salutation .......:
URL of public key : https://github.com/leslieleung.gpg
Login data .......: [not set]
Signature PIN ....: not forced
Key attributes ...: ed25519 cv25519 ed25519
Max. PIN lengths .: 127 127 127
PIN retry counter : 3 0 3
Signature counter : 0
KDF setting ......: off
UIF setting ......: Sign=off Decrypt=off Auth=off
Signature key ....: [masked]
      created ....: 2026-03-26 15:53:26
Encryption key....: [masked]
      created ....: 2026-03-26 15:53:45
Authentication key: [masked]
      created ....: 2026-03-26 15:54:00
General key info..: sub  ed25519/1915EA0F3C320F72 2026-03-26 Leslie Leung <lesily9@gmail.com>
ssb>  ed25519/[masked] created: 2026-03-26  expires: 2027-03-26
                                card-no: [masked]
ssb>  cv25519/[masked]  created: 2026-03-26  expires: 2027-03-26
                                card-no: [masked]
ssb>  ed25519/[masked]  created: 2026-03-26  expires: 2027-03-26
                                card-no: [masked]

导出 SSH 密钥

在上面的 key 中，找到 A 字样的 key，这个代表授权，导出对应的 SSH key。

sub   ed25519/8472C3F353CD9B06 2026-03-26 [A] [expires: 2027-03-26]
      C1B5CC41426C03A0CC0DAFF78472C3F353CD9B06

$ gpg --export-ssh-key C1B5CC41426C03A0CC0DAFF78472C3F353CD9B06!
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINGvVhlehNBnCQMuNp5llACDgGYgtztvM9P66j9ReXkN openpgp:0x53CD9B06

这个公钥就是后续用来进行 SSH 登录的。

配置 SSH

编辑 ~/.gnupg/gpg-agent.conf。

enable-ssh-support
default-cache-ttl-ssh 300
max-cache-ttl-ssh 7200

重启 agent。

$ gpgconf --reload gpg-agent

修改 .zshrc

export GPG_TTY=$(tty)
unset SSH_AGENT_PID
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then
  export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"
fi
gpg-connect-agent /bye >/dev/null 2>&1

加载配置

$ source ~/.zshrc

GitHub 配置

点击右上角头像 - Settings - SSH and GPG keys，New SSH key，填入刚才生成的公钥，保存。

然后测试一下：

$ ssh -T git@github.com
(弹窗输入 pin)
Hi LeslieLeung! You've successfully authenticated, but GitHub does not provide shell access.

服务器配置

把对应的公钥添加到 ~/.ssh/authorized_keys，然后尝试用 ssh 登录即可。

子钥续期

一般情况下，如果密钥没有被泄露，不需要专门做什么维护。在子钥到期前，给子钥续期，然后导出更新后的公钥，在对应的机器或者网站上更新即可。这一步不需要使用 Yubikey 进行操作。

$ gpg --quick-set-expire <PRIMARY_FPR> 1y '*'
$ gpg -a --export <PRIMARY_FPR>

FAQ

忘记了 PIN

如果忘记了 pin 或者 admin pin，可以对 Yubikey 的 GPG 区进行重置，注意这会丢失里面存储的密钥。

$ ykman openpgp reset

多个 Yubikey 切换时，提示插入卡号 xx 的卡

执行以下操作：

$ gpg-connect-agent "scd serialno" "learn --force" /bye

最后

总的来说，把 SSH 密钥放进 YubiKey，并不是为了追求“更复杂”的配置，而是为了把最关键的私钥从日常使用环境中尽量隔离出来。在面对本机入侵、供应链投毒、误操作和密钥泄露这类现实风险时，这种做法虽然不能解决所有问题，但确实能把攻击者获取私钥的门槛提高很多。

更重要的是，YubiKey 的价值并不只体现在 SSH 上，它还可以承载 OpenPGP 密钥，用来做 GPG 签名，例如给 Git commit、tag、文件甚至邮件签名。签名的意义不只是证明内容是谁发出的，也能证明内容在签名之后没有被篡改；放在 Git 的场景里，它可以帮助团队确认某次提交确实来自你本人，而不是他人伪造了身份信息。

这套方案确实不算轻量，配置起来麻烦，理解成本也不低，但它换来的，是更强的私钥保护、更可信的身份认证，以及在混乱环境里更稳定的安全边界。很多时候，安全并不是让你永远不出事，而是让你在真正出事的时候，仍然能守住最关键的东西。从这个角度看，把 SSH 和签名能力都收敛到 YubiKey 里，或许正是一种值得长期坚持的做法。

References

GitHub - drduh/YubiKey-Guide: Community guide to using YubiKey for GnuPG and SSH - protect secrets with hardware crypto. · GitHub

阿猫的博客