Canokey 指南：OTP，FIDO2，PGP 与 PIV

居然在 2021 年收到了 Canokey Pigeon，这很不鸽子。折腾了几个小时，把几个主要的用法都试了一遍，包括 OTP， FIDO2，OpenPGP Smartcard 和 PIV。除了 Windows 下 PIV 无法使用 NIST P-256/P-384 算法，以及某些 OpenPGP 最新的特性还未支持，整体算是物美价廉。

本指南基于 Windows 10 Powershell，其它操作系统基本也可参考使用。虽然本文基于 Canokey Pigeon，但大部分内容均可适用于其他硬件密钥，包括但不限于 Yubikey，Feitian key 等。同时本文的 OpenPGP 部分也可单独作为比较完善的 PGP 使用指南来参考，PIV 部分基本可以说是目前最完整的中文使用指南。

拿到后插入电脑会自动弹出 Canokey Web Console 提示，也可通过自行访问，注意目前只支持 Chromium 内核浏览器，点击右上角连接，如果失败请尝试重新插拔后等待一会重试。

连接成功后会显示 Canokey 的信息，首先进入 Settings 设置全局的 Admin PIN（默认 123456） 并牢记，同时可以配置部分选项，个人建议把 WebUSB prompt enabled 关闭，有些烦人。

注意这里的 Admin PIN 只用于 Canokey Web Console 的 Settings，与下方所有 PIN 均无关，请勿混淆，如觉得麻烦也可跳过这一步。

One-time Password (OTP) 是最常见的二步验证方法，主要分为 HMAC-based One-time Password algorithm (HOTP) 和 Time-based One-time Password (TOTP)，由于绝大部分平台支持的都是后者，本文仅介绍 TOTP。当然国内平台爱用的短信验证码也算一种 OTP，但是这种方法有其缺陷，并不自主可控。

如果那你使用过 Google Authenticator 之类的软件，那你一定对 TOTP 不陌生，其最常见的形式是一个有着 30 秒倒计时的六位数字，本质上是基于一个预共享的密钥和当前时间计算出的验证码。

通常网站会给出一个二维码让我们扫描，其内容一般如下

在 Canokey Web Console 的 TOTP/HTOP 部分添加，重要的是 secret 参数，也就是密钥。部分网站可能会直接给出一个密钥，同样添加即可。Canokey 最多支持存储 128 个密钥，反正我是用不完。还可以通过 Yubico Authenticator 来管理和读取 OTP，可能需要到设置中指定 custom reader 为 canokey。

首先引用谈谈 WebAuthn 的一段的介绍：

FIDO2 标准主要包括四个部分，其一是用于网站和访客设备交互的 WebAuthn，而 Client to Authenticator Protocol 2（CTAP2，客户端-认证器协议）作为 WebAuthn 的补充，则是用于访客的设备和认证器交互的协议。标准的其他两个部分则是 U2F 和 UAF 规范。

实际上这部分的使用是最简单的，只需要在支持的网站或应用中添加硬件密钥即可，目前大部分是用作 2FA，我自己常用的包括 GitHub, Cloudflare, Microsoft, Google, Twitter, Facebook 等，更多支持 FIDO2/U2F/TOTP 的网站可以参考 2FA Directory。

注意部分网站添加时会首先弹出含有 Windows Hello 的选项，需要点击取消跳过，再添加硬件密钥。首次添加时需要自定义 PIN，牢记即可。

目前 Microsoft 账户支持使用硬件密钥实现单因素登录，即无需密码直接登录，可以进入账户的其他安全选项部分进行添加。

这部分可以算是 Canokey 最主要的应用场景，关于 OpenPGP 的具体介绍就不在这里展开了，可以参考 2021年，用更现代的方法使用 PGP 系列文章。下面完整记录一下配置流程。

注意以下操作全部基于 Windows 10 Powershell，其它系统可能存在细微差异。为保护私钥安全，建议全程在离线、一次性环境中完成。

Windows 用户可下载 Gpg4Win，Linux/macOS 用户使用对应包管理软件安装即可。

首先生成主密钥，注意以下全部密钥均为一次性示例，并非本人 PGP 密钥。

查看目前的私钥，可以发现只有一个用作 Certify 的主密钥。

下面生成不同功能的子密钥，其中 为上面输出的密钥指纹，本示例中即为 68697537A54B1F0BFC05E1D9787E848E1A98D086。最后的 2y 为密钥过期时间，可自行设置，如不填写默认永不过期。

再次查看目前的私钥，可以看到已经包含了这三个子密钥。

上面生成了三种功能的子密钥（ssb），分别为加密（E）、认证（A）、签名（S），对应 OpenPGP Applet 中的三个插槽。由于 ECC 实现的原因，加密密钥的算法区别于其他密钥的算法。

加密密钥用于加密文件和信息。签名密钥主要用于给自己的信息签名，保证这真的是来自我的信息。认证密钥主要用于 SSH 登录。

额外提醒，如果你想把这个密钥用于 Git Commit 的签名，同时提交到 GitHub，GitLab等服务，请确保 UID 信息 Editst 与你的本地 Git 邮箱以及 GitHub 已验证邮箱一致。

也可以单独添加 Git 使用的 UID。

gpg 会把你最近添加的 UID 作为主 UID，你也可以手动指定。

首先导出公钥。

然后分别导出各个私钥，请务必备份好，特别是主密钥和吊销证书，建议多介质异地备份。同时记得备份之前自动生成的吊销证书：%APPDATA%\gnupg\openpgp-revocs.d\68697537A54B1F0BFC05E1D9787E848E1A98D086.rev。

注意 key id 后面的 !，表示只导出这一个私钥，若没有的话默认导出全部私钥。

具体备份策略可以参照 2021年，用更现代的方法使用 PGP（中）

下面介绍配合智能卡使用子密钥

首先修改 OpenPGP Applet 的密码

分别设置 PIN（默认 123456） 和 Admin PIN（默认 12345678），注意牢记，忘记后只能重置 OpenPGP Applet。

之后把各个子密钥导入对应插槽，请注意，这步是不可逆的，一但私钥导入智能卡并保存，本地私钥会被删除，无法再次恢复，因此务必确认已经正确完善备份。

如果你使用了多个 Canokey，想同时向其中导入子密钥，请注意最后一步不要保存，直接强行退出，然后更换另一枚 Canokey 或其他智能卡，重复操作即可。

这时再次查看 Canokey 状态，确认导入成功。

可以看到此时子密钥标识符为 ssb>，表示本地只有一个指向 card-no: F1D0 xxxxxxxx 智能卡的指针，已不存在私钥。现在可以删除掉主密钥了，请再次确认你已安全备份好主密钥。

为确保安全，也可直接删除 gpg 的工作目录：%APPDATA%\gnupg，Linux/macOS: ~/.gunpg。

此时切换回日常使用的环境，首先导入公钥

然后设置子密钥指向 Canokey

此时查看本地的私钥，可以看到已经指向了 Canokey

之后可以使用 gpg 进一步配置 Canokey，可以设置 name，forcesig 等内容，同时可前往 Canokey Web Console Touch Policy 配置每次使用时是否需要触摸以及缓存时间等。

如果你使用了多个智能卡，切换后可能会因为私钥仍指向其他卡而出现问题，可以使用下面命令刷新 Card serial no

首先确保 Git 本地配置以及 GitHub 中的邮箱信息包含在 UID 中，然后设置 Git 来指定使用子密钥中的签名（S）密钥。

之后在 git commit 时增加 -S 参数即可使用 gpg 进行签名。也可在配置中设置自动 gpg 签名，此处不建议全局开启该选项，因为有的脚本可能会使用 git am 之类的涉及到 commit 的命令，如果全局开启的话会导致问题。

如果提交到 GitHub，前往 GitHub SSH and GPG keys 添加公钥。此处添加后，可以直接通过对应 GitHub ID 来获取公钥：https://github.com/.gpg

下面步骤针对 Windows 10，其他系统可参考这里。

下载 win-gpg-agent，解压后启动 agent-gui.exe，此时查看 ssh-agent 读取到的公钥信息，把输出的公钥信息添加到服务器的 ~/.ssh/authorized_keys。

此时连接 ssh user@host，会弹出提示输入 PIN 的页面，如果 Touch Policy 开启的话还需要触摸一下 Canokey，之后就可以连接到服务器了。

最后可以把该程序快捷方式添加到启动目录 %AppData%\Microsoft\Windows\Start Menu\Programs\Startup，方便直接使用。

如果需要在 WSL/WSL2 或转发认证，可以进一步参考该应用的 GitHub 页面。

PIV Applet 包含多个插槽，具体信息可以参考 PIV certificate slots，前往 Canokey Web Console，进入 PIV 设置 PIN（默认 123456）和 Management Key（需要 24 Bytes，默认 010203040506070801020304050607080102030405060708）并牢记。

下面介绍两种不同的方法，可以根据自身需求选择。

注意，受限于内存大小，Canokey PIV 证书最大支持 1335 Bytes，过大会导致无法导入 2022年6月发售的 Canokey 据信已改进了这一问题，因本人目前不再持有 Canokey，无法测试。同时由于 Windows 系统的问题，Canokey PIV 目前只支持 RSA2048 算法，NIST P-256/P-384 算法生成的证书无法正常识别（没有 Canokey minidriver）。下面以 RSA2048 作为示例。

首先安装生成 RSA2048 私钥，然后使用 OpenSSL 生成证书

之后安装 yubikey-manager 导入私钥和证书，目前 ckman = ykman，这里使用 9a 插槽

还可以直接使用 ykman 调用 Canokey 来生成私钥和证书，注意这样生成的私钥是无法导出的。也可以在导入私钥的情况下直接调用第二个命令，只生成证书。

下面 -d 参数为有效期，默认为 365 天，-s 参数为 Subject for the certificate，必须传入，具体内容包括 CN: CommonName, OU: OrganizationalUnit, O: Organization, L: Locality, S: StateOrProvinceName, C: CountryName

完成后重新插拔 Canokey，Windows 前往 certmgr.msc，在个人-证书中可以看到已经有了刚才生成的证书。

在 Windows 环境下虽然没有自带的 OpenSSL 组件，但是提供了强大的 certreq 组件来生成证书。下面直接给出参考的配置，可以自行修改，也可以前往 certreq docs 查看更详细地参数说明。

其中 Subject 具体内容包括 CN: CommonName, OU: OrganizationalUnit, O: Organization, L: Locality, S: StateOrProvinceName, C: CountryName，可以自行配置。

保存上面的配置文件到 cert.ini，之后使用 certreq 生成证书，注意这一步生成的 cert_req.req 没啥用，直接删除即可

此时生成的证书已经自动安装在系统中，前往 certmgr.msc，在个人-证书中可以看到已经有了刚才生成的证书。右键选择所有任务-导出，在导出向导中选择导出私钥即可获得完整的证书和私钥文件 cert.pfx。

之后导入需要使用 yubikey-piv-tool，下载安装后手动添加程序路径到环境变量中：C:\Program Files\Yubico\Yubico PIV Tool\bin，之后把证书和私钥导入到 Canokrey

需要首先输入导出证书时的密码，之后再输入 Management Key

前往 WinCrypt SSH Agent 下载并运行，此时查看 ssh-agent 读取到的公钥信息，把输出的公钥信息添加到服务器的 ~/.ssh/authorized_keys

此时连接 ssh user@host，会弹出提示输入 PIN 的页面，注意此时输入的是 PIV Applet PIN，输入后即可成功连接服务器。

注意这种使用方法与 SSH with gpg-agent 并不兼容，选择其中一种使用即可。

如果已经按照上一步生成了证书，需要修改注册表来允许自签名证书，在注册表 HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\FVE 下新建一个 DWORD 的值，名称为 SelfSignedCertificates，数值数据为 1。

或者直接保存下面的注册表配置文件为 selfsig.reg，然后导入。

注意，需要验证智能卡中存有证书对应的私钥，否则会导致可以添加智能卡，但在解锁时失败。运行下面命令，确保输出信息中包含私钥验证测试通过信息。

BitLocker 不要求证书具备 EKU 属性，但是如果已为证书配置了该属性，则必须将前往组策略计算机配置-管理模板-Windows 组件-BitLocker 驱动器加密，设置验证智能卡证书使用合规性为已启用，同时为 BitLocker 配置的对象标识符 (OID) 匹配的 OID。

如果遇到其他问题请尝试执行下面命令，初始化 Card Holder Unique Identifier 和 CCC。

之后启用 BitLocker 时选择使用智能卡解锁驱动器即可，对于已启用 BitLocker 的驱动器，也可以通过管理 BitLocker 来添加智能卡。

感谢你看到这里，如有任何问题欢迎留言或邮件联系 i#editst.com，或者尝试从下面链接中寻找答案。