使用 YubiKey 配置 OpenPGP：密钥生成、备份与日常使用

最终要得到什么#

OpenPGP 卡提供三个相互独立的私钥槽：

本文复现当前已经使用的结构：

1
主密钥      [SC]  → Signature 槽
2
加密子密钥   [E]  → Encryption 槽
3
认证子密钥   [A]  → Authentication 槽

其中 S、C、E、A 分别表示 Sign、Certify、Encrypt 和 Authenticate。

还有一种隔离更严格的结构：让主密钥只具有 [C] 能力并永久离线，另外创建 [S]、[E]、[A] 三把子密钥放入卡片。这样日常使用的卡片无法直接签发新子密钥或修改身份，适合长期维护的重要身份。本文采用 [SC] + [E] + [A]，优点是结构简单、能够复现当前配置；如果以后准备重建长期身份，可以再评估离线 [C] 方案。

WARNING

keytocard 会在保存后把当前钥匙环里的对应私钥材料替换为智能卡引用。卡内私钥不能再导出，所以必须在迁移之前完成完整私钥备份，并实际验证备份可以恢复。

1. 准备 GnuPG 与卡片#

1
brew install gnupg pinentry-mac

1
gpg --version

1
pinentry-program /opt/homebrew/bin/pinentry-mac

1
gpgconf --kill gpg-agent

1
sudo apt update
2
sudo apt install gnupg scdaemon pcscd

1
sudo systemctl enable --now pcscd

1
gpg --card-status

1
Application type .: OpenPGP
2
Signature key ....: [none]
3
Encryption key....: [none]
4
Authentication key: [none]

2. 先规划算法与有效期#

当前卡片报告的属性是：

1
Key attributes ...: rsa2048 rsa2048 rsa2048

因此本文统一使用 RSA-2048，优先保证导入成功和客户端兼容性。不要在没有确认固件支持的情况下直接修改 key-attr。如果使用的是明确支持 RSA-3072、RSA-4096 或 ECC 的设备，可以在创建身份之前重新评估算法，但三把待迁移密钥必须与对应卡槽兼容。

本文把有效期设为 0，即 OpenPGP 元数据中的“永不过期”。这不表示算法和设备会永远安全，只表示 GnuPG 不会因为日期自动判定密钥失效。长期身份仍应定期评估算法、设备状态和备份介质。

3. 创建主密钥与子密钥#

先创建具有认证和签名能力的主密钥：

1
gpg --quick-generate-key \
2
  "Example User <user@example.com>" \
3
  rsa2048 cert,sign 0

为本地私钥设置一条足够强、且与卡片 PIN 不同的保护密码。

查看完整指纹：

1
gpg --list-secret-keys \
2
  --keyid-format long \
3
  --with-subkey-fingerprint \
4
  "user@example.com"

复制 sec 下一行的 40 位完整主密钥指纹，并设置变量：

1
FPR='<PRIMARY_KEY_FINGERPRINT>'

不要使用只有 8 位或 16 位的短 Key ID。先验证变量确实指向预期身份：

1
gpg --list-secret-keys --keyid-format long "$FPR"

添加加密子密钥和认证子密钥：

1
gpg --quick-add-key "$FPR" rsa2048 encrypt 0
2
gpg --quick-add-key "$FPR" rsa2048 auth 0

再次检查结构：

1
gpg --list-secret-keys \
2
  --keyid-format long \
3
  --with-subkey-fingerprint \
4
  "$FPR"

此时应类似：

1
sec   rsa2048/... [SC]
2
ssb   rsa2048/... [E]
3
ssb   rsa2048/... [A]

4. 在迁移前制作完整备份#

把下面的目录改为加密移动硬盘或其他离线介质上的真实路径：

1
BACKUP_DIR="/Volumes/EncryptedBackup/openpgp-backup"
2
install -d -m 700 "$BACKUP_DIR"

导出公钥、完整私钥、子密钥和 ownertrust：

1
gpg --armor \
2
  --output "$BACKUP_DIR/example-public.asc" \
3
  --export "$FPR"
4

5
gpg --armor \
6
  --output "$BACKUP_DIR/example-secret-full.asc" \
7
  --export-secret-keys "$FPR"
8

9
gpg --armor \
10
  --output "$BACKUP_DIR/example-secret-subkeys.asc" \
11
  --export-secret-subkeys "$FPR"
12

13
gpg --export-ownertrust \
14
  > "$BACKUP_DIR/ownertrust.txt"

--export-ownertrust 应通过 Shell 重定向保存；某些 GnuPG 版本不会把这个命令的输出写入 --output 指定的文件。如果信任记录直接打印在终端里，应检查 ownertrust.txt 是否真的存在。

GnuPG 通常会在生成主密钥时自动创建吊销证书。把它复制到备份介质：

1
cp "$HOME/.gnupg/openpgp-revocs.d/$FPR.rev" \
2
  "$BACKUP_DIR/example-revocation-certificate.rev"
3

4
chmod 600 "$BACKUP_DIR"/*
5
ls -la "$BACKUP_DIR"

备份目录至少应包含：

1
example-public.asc
2
example-secret-full.asc
3
example-secret-subkeys.asc
4
example-revocation-certificate.rev
5
ownertrust.txt

推荐保存两份加密离线备份，并放在不同地点。私钥保护密码、卡片 PIN 和 Reset Code 不要与备份介质放在一起。

1
VERIFY_HOME="$(mktemp -d)"
2
chmod 700 "$VERIFY_HOME"

1
gpg --homedir "$VERIFY_HOME" \
2
  --import "$BACKUP_DIR/example-secret-full.asc"
3

4
gpg --homedir "$VERIFY_HOME" \
5
  --list-secret-keys \
6
  --keyid-format long \
7
  --with-subkey-fingerprint \
8
  "$FPR"

1
export GPG_TTY="$(tty)"
2

3
VERIFY_FILE="$(mktemp /tmp/openpgp-backup-verification.XXXXXX)"
4
VERIFY_SIGNATURE="$BACKUP_DIR/$(basename "$VERIFY_FILE").asc"
5
printf 'OpenPGP backup verification\n' > "$VERIFY_FILE"
6

7
gpg --homedir "$VERIFY_HOME" \
8
  --local-user "$FPR" \
9
  --armor \
10
  --clearsign \
11
  --output "$VERIFY_SIGNATURE" \
12
  "$VERIFY_FILE"
13

14
gpg --homedir "$VERIFY_HOME" \
15
  --verify "$VERIFY_SIGNATURE"

5. 修改卡片 PIN#

进入卡片编辑模式：

1
gpg --card-edit

依次进入管理模式和 PIN 菜单：

1
admin
2
passwd

通常可以看到：

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

至少完成以下三项：

1. 修改用户 PIN；
2. 修改管理员 PIN；
3. 设置独立的 Reset Code。

标准原厂 YubiKey 的默认用户 PIN 通常为 123456，管理员 PIN 通常为 12345678，但兼容设备不一定相同。以厂商文档为准，不要连续猜测，因为每类 PIN 通常只有三次重试机会。

Max. PIN lengths 显示的是最大长度，不是最小长度。标准 OpenPGP 卡通常要求用户 PIN 至少 6 位、管理员 PIN 和 Reset Code 至少 8 位；兼容固件还可能有更严格的字符限制。为了兼容性，本文建议使用 8 位以上的用户 PIN，以及 12～16 位 ASCII 字母和数字组成的管理员 PIN、Reset Code，不要使用 4 位数字 PIN。

修改 PIN 时，pinentry 会先收集当前 PIN、新 PIN 和重复的新 PIN，最后才一次性交给卡片验证。因此，看到“输入新 PIN”的界面不代表当前 PIN 已经通过验证。如果最终提示 Bad PIN 或“损坏的 PIN”，先退出并运行 gpg --card-status：管理员 PIN 对应 PIN retry counter 的最后一位；若计数没有减少，更可能是新 PIN 太短或格式不受支持，若计数减少则说明当前 PIN 错误。

三类凭据的用途不同：

• 用户 PIN：执行签名、解密和认证；
• 管理员 PIN：修改卡片设置、写入或删除密钥；
• Reset Code：用户 PIN 被锁定后的恢复凭据。

6. 把三把私钥迁移到卡片#

进入密钥编辑界面：

1
gpg --edit-key "$FPR"

先输入：

1
list

1
keytocard

1
1

1
Note: the local copy of the secret key will only be deleted with "save".

1
key 1
2
list

1
keytocard

1
2

1
key 1

1
key 2
2
list

1
keytocard

1
3

1
key 2
2
list
3
save

7. 验证卡片状态#

查看 OpenPGP 卡：

1
gpg --card-status

配置成功后应同时出现三把指纹：

1
Signature key ....: <PRIMARY_KEY_FINGERPRINT>
2
Encryption key....: <ENCRYPTION_SUBKEY_FINGERPRINT>
3
Authentication key: <AUTH_SUBKEY_FINGERPRINT>

再查看本地钥匙环：

1
gpg --list-secret-keys \
2
  --keyid-format long \
3
  --with-subkey-fingerprint \
4
  "$FPR"

预期类似：

1
sec>  rsa2048/... [SC]
2
ssb>  rsa2048/... [E]
3
ssb>  rsa2048/... [A]

> 表示私钥操作由智能卡完成，本地只保留卡片引用。它不表示私钥已经被公开或可以从卡中导出。

8. 分别测试三个卡槽#

1
export GPG_TTY="$(tty)"
2

3
SIGN_TEST="$(mktemp /tmp/openpgp-card-signing.XXXXXX)"
4
SIGNATURE="${SIGN_TEST}.sig.asc"
5
printf 'OpenPGP smartcard signing test: %s\n' \
6
  "$(date '+%Y-%m-%dT%H:%M:%S%z')" \
7
  > "$SIGN_TEST"
8

9
gpg --local-user "$FPR" \
10
  --armor \
11
  --detach-sign \
12
  --output "$SIGNATURE" \
13
  "$SIGN_TEST"
14

15
gpg --verify "$SIGNATURE" "$SIGN_TEST"
16

17
printf '测试文件：%s\n签名文件：%s\n' \
18
  "$SIGN_TEST" "$SIGNATURE"

1
Good signature from "Example User <user@example.com>"

1
printf 'OpenPGP smartcard encryption test\n' \
2
  > /tmp/openpgp-plaintext.txt
3

4
gpg --armor \
5
  --recipient "$FPR" \
6
  --output /tmp/openpgp-encrypted.asc \
7
  --encrypt /tmp/openpgp-plaintext.txt
8

9
gpg --decrypt /tmp/openpgp-encrypted.asc

1
gpg --export-ssh-key "$FPR"

1
ssh-rsa AAAA... openpgp:0x...

9. 配置 Git commit 签名#

让 Git 使用这把 OpenPGP 密钥：

1
git config --global user.signingkey "$FPR"
2
git config --global commit.gpgsign true
3
git config --global tag.gpgSign true
4
git config --global gpg.program "$(command -v gpg)"

进行一次本地测试：

1
mkdir /tmp/gpg-git-sign-test
2
cd /tmp/gpg-git-sign-test
3
git init
4
git commit --allow-empty -m "test OpenPGP signing"
5
git log --show-signature -1

要让 GitHub 显示 Verified，还需要：

1. 把 user@example.com 添加到 GitHub 账号并完成验证；
2. 在 GitHub 的 SSH and GPG keys 页面添加 ASCII 公钥；
3. commit 的作者邮箱必须属于该账号。

导出可粘贴到 GitHub 的公钥：

1
gpg --armor --export "$FPR"

10. 把认证子密钥用于 SSH#

在 ~/.gnupg/gpg-agent.conf 中加入：

1
enable-ssh-support

重启 gpg-agent：

1
gpgconf --kill gpg-agent
2
gpgconf --launch gpg-agent

当前终端指向 GnuPG 提供的 SSH agent socket：

1
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"

把同一行写入 ~/.zshrc 或 ~/.bashrc，然后重新打开终端。检查 agent 是否识别卡片：

1
ssh-add -L

也可以直接导出公钥保存：

1
gpg --export-ssh-key "$FPR" > ~/.ssh/openpgp-backup.pub

把这行公钥添加到服务器的 ~/.ssh/authorized_keys 或 GitHub 的 SSH keys 页面，再执行实际登录测试：

1
ssh -T git@github.com

拔掉卡后再次连接，应当无法使用这把私钥完成认证。

11. 发布公钥与指纹#

导出公开版本：

1
gpg --armor \
2
  --output example-public.asc \
3
  --export "$FPR"

可以把它发布到个人网站，例如：

1
https://example.com/pgp.asc

这个地址必须直接返回 example-public.asc 的 ASCII 公钥内容。OpenPGP 卡的公钥 URL 是单个字符串字段，只支持一个 URL；如果需要多个镜像，应使用一个长期稳定的地址，再由服务器通过 HTTP 重定向到当前镜像。

设置卡片上的公钥 URL：

1
gpg --card-edit

1
admin
2
url
3
https://example.com/pgp.asc
4
quit

上传后检查服务器返回的指纹：

1
curl -fsSL https://example.com/pgp.asc |
2
  gpg --show-keys --fingerprint

只能公开 example-public.asc。不要上传整个备份目录，也不要公开 example-secret-full.asc、example-secret-subkeys.asc、吊销证书或 ownertrust.txt；备份签名测试文件也不是公钥。

完整指纹应通过另一个独立渠道公开，供别人核对：

1
<PRIMARY_KEY_FINGERPRINT>

还可以把公钥上传到支持的密钥服务器：

1
gpg --keyserver hkps://keys.openpgp.org \
2
  --send-keys "$FPR"

密钥服务器上的记录通常无法像普通文件一样彻底删除，只能通过吊销来声明失效。上传前应确认 UID 中的邮箱适合长期公开；使用 keys.openpgp.org 时，还需要按邮件完成 UID 验证，其他人才可按邮箱搜索到它。

12. 可选的卡片安全设置#

1
Signature PIN ....: 非强制

1
gpg --card-edit

1
admin
2
forcesig
3
quit

1
gpg --card-edit

1
admin
2
uif 1 on
3
quit

1
uif 2 on
2
uif 3 on

1
UIF 1 = Sign
2
UIF 2 = Decrypt
3
UIF 3 = Auth

1
KDF setting ......: off

1
gpg --card-edit
2
admin
3
name
4
lang
5
login
6
url
7
quit

13. 在新电脑上恢复使用#

新电脑不需要导入完整私钥，只需导入公钥并让 GnuPG 学习卡片：

1
gpg --import example-public.asc
2
gpg --card-status

如果本地没有正确建立卡片引用，可以执行：

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

然后重新检查：

1
gpg --list-secret-keys \
2
  --keyid-format long \
3
  --with-subkey-fingerprint \
4
  "$FPR"

需要 SSH 时，再配置 enable-ssh-support 和 SSH_AUTH_SOCK。不要为了日常使用而把完整私钥备份导入联网电脑；那会抵消智能卡隔离私钥的主要价值。

14. 卡片丢失、损坏或 PIN 锁定#

15. 日常检查清单#

• 定期执行 gpg --card-status，确认三个卡槽指纹和 PIN 重试次数正常；
• 每次修改 UID、有效期或子密钥后，重新导出并发布公钥；
• 至少每年检查两份离线备份是否仍可读取；
• 保持 GnuPG、scdaemon、pinentry 和设备固件更新；
• 不把私钥备份、保护密码、PIN 与 Reset Code 放在同一位置；
• 保留一枚备用兼容卡，或至少记录经过验证的换卡流程；
• “永不过期”不等于永远安全，定期重新评估算法和设备寿命。

验收结果#

完成配置后，应得到类似以下结构：

1
主密钥 [SC]
2
<PRIMARY_KEY_FINGERPRINT>
3

4
加密子密钥 [E]
5
<ENCRYPTION_SUBKEY_FINGERPRINT>
6

7
认证子密钥 [A]
8
<AUTH_SUBKEY_FINGERPRINT>

仅看到三把指纹还不算完成。最终验收应同时满足：离线备份已在隔离钥匙环中成功导入并签名，签名与解密均需要卡片，SSH 已完成一次真实登录，sec> / ssb> 显示本地只保留卡片引用，公钥和完整指纹也已发布到稳定位置。可选安全开关应在这些基础流程通过后再逐项启用。

参考资料#

• GnuPG Manual：Smart Card Tool
• GnuPG Manual：OpenPGP Card
• GnuPG Manual：GPG Configuration Options
• Yubico OpenPGP 文档
• GitHub：管理 commit 签名验证
• keys.openpgp.org 使用说明