YubiKey

YubiKey 是一个小的 USB 安全令牌。根据型号，它可以

充当智能卡（使用 CCID 协议） - 允许存储 PGP 和 PIV 密钥。
处理通用第二因素 (U2F) 请求。
存储和查询大约 30 个开放认证倡议 (OATH) 凭据。
处理挑战-响应请求，在 Yubico OTP 模式或 HMAC-SHA1 模式下。
生成一次性密码 (OTP) - Yubico 基于 AES 的标准。
“键入”最多 63 个字符的静态密码。

虽然 YubiKey 的新版本提供了许多功能，但它们并非以开源形式发布。替代品有 Solo、TKey 或 Nitrokey。

安装

管理工具

YubiKey 管理器 — 用于通过 USB 配置和查询 YubiKey 的 Python 库和命令行工具 (ykman)。具有可选的 GUI。

https://developers.yubico.com/yubikey-manager/ || yubikey-manager, yubikey-manager-qt

注意： 安装后，启用 pcscd.service，或者启用 pcscd.socket 可能也很有用。

警告： yubikey-manager-qt 在最新的 Arch/python/yubikey-manager 版本上完全损坏，并且 Yubico 已弃用此工具。

YubiKey 个性化 — 用于通过 OTP USB 连接配置和查询 YubiKey 的库和工具。比 ykman 更强大，但更难使用。具有可选的 GUI。

https://developers.yubico.com/yubikey-personalization/ || yubikey-personalization, yubikey-personalization-gui

身份验证工具

Yubico PAM — 使用 Yubico OTP 或挑战-响应的 PAM 用户身份验证。

https://developers.yubico.com/yubico-pam/ || yubico-pam

Yubico PAM-U2F — 使用 U2F 的 PAM 用户身份验证。

https://developers.yubico.com/pam-u2f/ || pam-u2f

Yubico Authenticator 桌面版 — 用于通过 USB 从 YubiKey 读取 OATH 代码的 GUI。支持较新的 OATH 实现（YubiKey NEO 和 4）以及较旧的基于插槽的实现（YubiKey Standard 和 Edge）。注意 archlinux/packaging/packages/yubioath-desktop#2。

https://developers.yubico.com/OATH/YubiKey_OATH_software.html || yubioath-desktop

Yubico Authenticator 6.0+ 桌面版 — Yubico Authenticator 6.0+（6.0 及更高版本）是用于管理 YubiKey 第二因素凭据的应用程序。从 6.0 版本开始，代码库已使用 Flutter 框架完全重写。

https://developers.yubico.com/yubioath-flutter/ || yubico-authenticator-bin^AUR

libfido2 — 客户端 U2F 支持。使 Web 浏览器能够使用 U2F 协议通过您的 YubiKey 进行身份验证。

https://developers.yubico.com/libfido2/ || libfido2

YubiKey 全盘加密 — 使用挑战-响应模式创建强大的 LUKS 密码。支持全盘加密。

https://github.com/agherzan/yubikey-full-disk-encryption || yubikey-full-disk-encryption

输入

YubiKey 接受 API 调用和按钮按键形式的输入。

按钮非常灵敏。根据上下文，触摸它可以执行以下操作之一

触发静态密码或一次性密码 (OTP)（短按插槽 1，长按插槽 2）。这是默认行为，很容易意外触发。
确认/允许功能或访问。LED 将亮起以提示用户。
插入/弹出智能卡

输出

YubiKey 将这些输入转换为输出

击键（模拟 USB 键盘），用于键入静态密码和 OTP。（请注意，静态密码容易受到键盘记录器的攻击。）
内置 LED
- 插入时闪烁一次，有助于故障排除。
- 当需要按下按钮以允许 API 响应时，稳定闪烁。
通过 USB 的 API 响应。这用于
- 挑战-响应请求（使用 Yubico OTP 模式或 HMAC-SHA1 模式计算）
- U2F 挑战-响应请求
- CCID 智能卡相关请求

USB 连接模式

根据 YubiKey 型号，该设备提供最多三个不同的 USB 接口。其中两个接口实现了 USB HID（人机接口设备）设备类；第三个是智能卡接口 (CCID)。所有三个都可以独立启用或禁用，从而可以控制其关联的协议。

下表显示了哪些协议使用哪些接口

协议	接口
OTP	键盘 HID
FIDO	其他 HID
PIV	CCID
OpenPGP	CCID
OATH	CCID

ykman 使用术语“模式”，命名为 OTP、FIDO 和 CCID。

注意： ykman 在 0.6.1 版本 (2018-04-16) 中将“U2F”重命名为“FIDO”。 https://developers.yubico.com/yubikey-manager/Release_Notes.html

获取已启用模式

对于 5 版本之前的 YubiKey

$ ykman config mode

Current connection mode is: OTP+FIDO+CCID

注意： 命令 ykman mode 已被弃用，可能会在以后版本中删除。

对于 5 版本的 YubiKey

$ ykman info

Device type: YubiKey 5 NFC
Serial number: XXXXXXXXX
Firmware version: 5.4.3
Form factor: Keychain (USB-A)
Enabled USB interfaces: OTP, FIDO, CCID
NFC transport is enabled.

Applications    USB     NFC
FIDO2           Enabled Enabled
OTP             Enabled Enabled
FIDO U2F        Enabled Enabled
OATH            Enabled Enabled
YubiHSM Auth    Enabled Enabled
OpenPGP         Enabled Enabled
PIV             Enabled Enabled

设置模式

所有模式在出厂时均已启用。要更改它们

$ ykman mode [OPTIONS] MODE

MODE 可以是字符串，例如 OTP+FIDO+CCID，或缩写形式 o+f+c。
MODE 可以是模式编号，它编码了多个已启用模式。

如果您想使用模式编号，这里有一个模式编号表

0	仅 OTP 设备。
1	仅 CCID 设备。
2	OTP/CCID 复合设备。
3	仅 U2F 设备。
4	OTP/U2F 复合设备。
5	U2F/CCID 复合设备。
6	OTP/U2F/CCID 复合设备。
81	仅 CCID 设备，带触摸弹出。

注意： 某些示例使用模式编号 86，这是无效的。80 将被忽略，其行为将类似于 6。

选项

--touch-eject - 按钮将插入和弹出智能卡。这仅在模式为仅 CCID 时有效；FIDO 和 OTP 必须禁用。
--autoeject-timeout SECONDS - 在一段时间后自动弹出智能卡。限制与 --touch-eject 相同。
--chalresp-timeout SECONDS - 设置挑战-响应超时。

有关更多信息，请参阅 ykman mode --help。

一次性密码

此功能有一个有点误导性的名称，因为它也包含静态密码和挑战-响应功能。

为此功能提供了 2 个插槽，分别通过短按和长按按钮访问。每个插槽可以配置以下之一

Yubico OTP
OATH-HOTP
OATH-TOTP
挑战-响应
静态密码

每个功能在创建时都提供了多个配置选项，但一旦设置，就无法读回。可以使用 ykman otp swap 交换插槽 1 和 2。

出厂配置

在新的 YubiKey 上，Yubico OTP 在插槽 1 上预配置。此初始 AES 对称密钥存储在 YubiKey 和 Yubico 身份验证服务器上。这允许针对 YubiCloud 进行验证，从而允许将 Yubico OTP 与 Yubico 论坛网站结合使用，例如在 https://demo.yubico.com 上使用。

警告： 如果您曾经覆盖了插槽 1 中的出厂密钥，则无法创建相同信任级别的新密钥。出厂生成的 Yubico OTP 凭据以 CC 前缀开头，而用户生成的凭据以 VV 开头。在安全或功能上没有根本区别，尽管某些服务仅信任 CC 凭据。更多信息可以在这个论坛帖子中找到。

Yubico OTP

Yubico OTP 基于对称密码学。更具体地说，每个 YubiKey 都包含一个 128 位 AES 密钥，该密钥对于该设备是唯一的，并且也存储在验证服务器上。当被要求输入密码时，YubiKey 将通过连接不同的字段（例如密钥的 ID、计数器和随机数）并加密结果来创建令牌。

此 OTP 发送到目标系统，目标系统将其传递给验证服务器。验证服务器（也拥有密钥）对其进行解密并验证内部信息。结果返回给目标系统，然后目标系统可以决定是否授予访问权限。

YubiCloud 和验证服务器

Yubico 提供了一个验证服务器，可以免费无限访问，称为 YubiCloud。YubiCloud 知道所有 YubiKey 的出厂配置，并且是 yubico-pam 使用的（例如）“默认”验证服务。Yubico 还提供服务器的开源实现。

注意： 要验证 Yubico 验证服务器，您可以使用

HMAC：使用 https://upgrade.yubico.com/getapikey/ 获取 HMAC 密钥和 ID
HTTPS：验证服务器的证书由 GoDaddy 签名，因此在 Arch 安装中默认受信任（至少如果您安装了 ca-certificates）

配置和使用

在插槽 2 中生成新密钥，并将其上传到 YubiCloud（在浏览器中打开）

$ ykman otp yubiotp --generate-key --upload 2

有关更多信息，请参阅 ykman otp yubiotp --help。

安全风险

AES 密钥泄露

您可以想象，AES 密钥应该保密。它无法从 YubiKey 本身检索（或者至少不应该使用软件检索）。它也存在于验证服务器中，因此此服务器的安全性非常重要。

验证请求/响应篡改

由于目标系统依赖于验证服务器，因此可能的攻击是冒充它。为防止这种情况，目标系统需要使用 HMAC 或 HTTPS 验证验证服务器。

挑战-响应

挑战被发送到 YubiKey，YubiKey 根据某些密钥计算响应。相同的挑战总是会产生相同的响应。即使有许多挑战-响应对，在没有密钥的情况下，这种计算也是不可行的。

这可以用于

真正的双因素身份验证：向用户提供挑战，他们必须提供正确的响应以及密码。双方都必须拥有密钥。
“半”双因素身份验证：挑战充当密码，服务器存储正确的响应。这不是 OTP，如果任何人可以获得响应，他们将获得访问权限，但这更简单，因为服务器不需要密钥。

有两种挑战-响应算法

HMAC-SHA1
Yubico OTP

您可以使用 GUI 使用 yubikey-personalization-gui 或使用以下说明进行设置

HMAC-SHA1 算法

在挑战响应模式下使用生成的密钥设置插槽 2

$ ykman otp chalresp --generate 2

您可以省略 --generate 标志以提供密钥，请参阅 ykman otp chalresp --help。提供密钥的主要优点是它可以用于将第二个设备设置为备份。例如，命令 openssl rand -hex 20 生成一个合适的密钥。

Yubico OTP 算法

ykman 似乎不支持设置 chal-yubico 算法，但您可以使用 ykpersonalize。在插槽 2 中生成一个随机密钥

$ ykpersonalize -2 -ochal-resp -ochal-yubico

有关更多信息，请参阅 ykpersonalize(1)。

发送挑战

要发送挑战并获得响应，可以使用 ykchalresp -slot challenge 命令。例如，

$ ykchalresp -2 archie

12a19763be77d75af46fb76f0b737c117fa47205

返回特定于编程的插槽 2 的 40 字节 SHA1 哈希值。不同的挑战会产生另一个唯一的响应。

静态密码

您可以生成静态密码

$ ykman otp static --generate slot

或提供一个

$ ykman otp static slot password

您有几个选项；您可以设置生成密码的长度和字符集，以及是否发送 Enter 键击。有关更多信息，请参阅 ykman otp static --help。

提示： 大多数 YubiKey 仅提供有限的 (2) 个插槽来保存静态密码。设置挑战-响应插槽为无限挑战提供静态哈希响应。虽然这些仅是数字和小写字母，但响应长度提供了可观的熵。

模拟 USB 键盘限制，或“为什么我的密码看起来如此脆弱？”

为了使 YubiKey 能够与大多数键盘布局一起使用，默认情况下，密码仅限于 ModHex 字母表 (cbdefghijklnrtuv)、数字 0-9 和 !。这些字符在大量键盘布局中使用相同的扫描码，从而确保与大多数计算机的兼容性。

Yubico 提供了关于此主题的白皮书。

OATH

YubiKey 提供 2 种 OATH 实现

OATH API: 较新的方法，根据型号可以存储大约 30 个凭据。（YubiKey 4、NEO 和更新型号）
OTP 插槽: 较旧的方法，两个 OTP 插槽都可以存储单个凭据。（所有支持挑战-响应的型号）

OATH API

如果您喜欢 GUI，可以使用 yubioath-desktop。

ykman 可以使用 ykman oath uri 以 URI 格式添加代码。这是一个单行命令，它将从 QR 码图像中添加凭据

$ zbarimg qr_code.png --quiet --raw | xargs ykman oath accounts uri

您也可以手动执行操作。编程 TOTP 密钥，需要触摸按钮才能生成代码

$ ykman oath accounts add --touch name secret

编程 HOTP 密钥

$ ykman oath accounts add --oath-type HOTP name secret

列出凭据

$ ykman oath accounts list

生成代码

$ ykman oath accounts code query

要查看所有可用的子命令，请参阅 ykman oath --help。要查看有关每个子命令的信息，请使用 ykman oath subcommand --help。

OTP 插槽实现

在插槽 2 中编程 HOTP

$ ykman otp hotp 2 key

编程 TOTP

$ ykman otp chalresp --totp slot key

生成 HOTP

$ ykman otp calculate slot

生成 TOTP

$ ykman otp calculate --totp slot

另请参阅：ykman otp --help 和 https://developers.yubico.com/OATH/

U2F

使用 YubiKey 的通用第二因素 (U2F) 非常简单，无需对密钥本身进行任何配置。请注意，在某些文档和实用程序中，此模式也称为“FIDO”。您可以通过 ykman 实用程序获得一些有限的管理选项

设置 PIN 码：ykman fido access change-pin
删除单个凭据：ykman fido credentials delete QUERY
重置所有凭据和 PIN 码：ykman fido reset

要使用 U2F 进行身份验证，请参阅 U2F 中的说明。

另请参阅 WebAuthn。

CCID 智能卡

CCID（芯片卡接口设备）是一种 USB 标准设备类，供充当智能卡读卡器的 USB 设备或通过 USB 直接连接的安全令牌（如 YubiKey）使用。HID（人机接口设备）和 CCID 都是 USB 设备类，即它们属于 USB 规范的同一类别。HID 是计算机外围设备的规范，例如键盘。YubiKey 在 OTP 和 FIDO 模式下用作 USB (HID) 键盘，但在使用 PIV 应用程序或作为 OpenPGP 设备时切换到 CCID 协议。

自 2015 年 11 月以来发货的所有 YubiKey 默认应启用 CCID 模式 [1]。至少启用 CCID 模式。请参阅 #获取已启用模式。

PIV

从 YubiKey NEO 开始，YubiKey 在芯片上包含 PIV（个人身份验证）应用程序。PIV 是美国政府标准 (FIPS 201)，它规定了如何将使用 RSA 或 ECC（椭圆曲线密码学）的令牌用于个人电子身份识别。YubiKey NEO 仅支持 RSA 加密，后来的型号（YubiKey 4 和 5）同时支持 RSA 和 ECC。支持的确切算法取决于固件。例如，只有固件 5.7 及更高版本的 YubiKey 支持 RSA 3072、RSA 4096、Ed25519 和 X25519 密钥 [2]。PIV 令牌的显着特征是它旨在保护私钥并在芯片上运行。私钥在安装到令牌后永远不会离开令牌。可选地，私钥甚至可以在芯片上借助片上随机数生成器生成。如果在芯片上生成，则私钥永远不会在芯片外部处理，并且无法从令牌中恢复。当使用 PIV 机制时，YubiKey 充当 CCID 设备。

OpenPGP 智能卡

YubiKey 可以充当标准的 OpenPGP 智能卡；有关如何设置和与 GnuPG 一起使用的说明，请参阅 GnuPG#智能卡。Yubico 还在 https://developers.yubico.com/PGP/ 中提供了一些文档。

如果您不想使用其他功能（U2F 和 OTP），则可以将按钮配置为插入和弹出它，并且还可以设置自动弹出超时。有关更多信息，请参阅 #USB 连接模式。

默认用户 PIN 码为 123456，默认管理员 PIN 码为 12345678。默认 PUK 码也为 12345678。请记住更改所有 3 个。

用例

本节详细介绍了如何将 YubiKey 用于各种身份验证目的。绝非详尽列表。

使用 LUKS 的全盘加密

您有几个选项

挑战-响应： 对某些挑战的响应用作 LUKS 密钥。挑战可以充当密码以进行真正的双因素身份验证，也可以以明文形式存储以进行单因素身份验证。
GnuPG： 使用 yubikey 的 PGP 智能卡功能。提供强大的双因素身份验证，而无需冗长的密码。
FIDO HMAC 密钥： 如果您的 YubiKey 支持 U2F，则可以将其配置为返回对称密钥。

注意： 磁盘加密的强度仅与最弱密钥的强度相同。配置其中一个工具后，请考虑删除初始密码，或将其替换为非常长的密码。

常见先决条件

可引导的 LUKS 加密系统，使用 encrypt mkinitcpio 钩子，至少有一个空闲密钥槽。
- 除了 mkinitcpio-ykfde^AUR 之外，这些工具均不支持 sd-encrypt 钩子。
备份 LUKS 标头（可选，但建议这样做）

挑战-响应

有关完整说明，请参阅 yubikey-full-disk-encryption 的官方文档。大致如下

安装 yubikey-full-disk-encryption。
配置 /etc/ykfde.conf。
注册磁盘：# ykfde-enroll -d /dev/DISK -s LUKS_SLOT
在 encrypt 钩子之前添加 ykfde mkinitcpio 钩子。
重新生成 initramfs.

注意： Plymouth 用户：将 plymouth-encrypt 钩子替换为 ykfde 钩子。

有几种变体可用

双因素身份验证：默认行为。您必须在注册设备时以及启动时提供挑战作为密码。
单因素身份验证：在 ykfde.conf 中设置 YKFDE_CHALLENGE。请注意，这是以明文形式存储的。考虑禁用对此文件的非 root 读取权限。
NFC 支持（实验性）
暂停和恢复支持（实验性）在暂停时自动锁定加密卷，在恢复时解锁它们。

您必须重新生成 initramfs 才能使任何配置更改生效。

基于 systemd 的 initramfs

sd-encrypt hook 的用户可以安装 mkinitcpio-ykfde^AUR 或 mkinitcpio-ykfde-git^AUR，并按照项目文档中的说明进行操作。该过程与 yubikey-full-disk-encryption 大致相似。

GnuPG 加密密钥文件

实现此目的的一个工具是 initramfs-scencrypt；请参阅其文档以获取完整说明。请注意，截至 2022 年 10 月，此软件包尚未在 AUR 中，并且未经全面测试，但 GitHub 存储库提供了 PKGBUILD。

dm-crypt 页面提供了一些替代方案，但它们主要是指向旧论坛帖子的链接。

FIDO2 协议的 HMAC 密钥扩展

使用 YubiKey 进行全盘加密的另一种方法是利用 HMAC 密钥扩展从 YubiKey 检索 LUKS 密码。这可以通过密码短语保护。此功能至少需要固件 5.2.3+ 的 YubiKey 5。对于受密码短语保护的解决方案，请安装 khefin^AUR 并按照项目文档中提供的说明进行操作。对于单因素（可选 PIN 码保护）解决方案，并且从 systemd 248 开始，可以使用 FIDO2 密钥作为 LUKS2 密钥槽。说明可在作者的博客文章中找到。

KeePass

KeePass 可以配置为支持 YubiKey；请参阅 YubiKey 部分以获取说明。

SSH 密钥

CCID

如果您的 YubiKey 支持 CCID 智能卡，您可以将其用作硬件支持的 SSH 密钥，基于 GPG 或 PIV 密钥。 Yubico 提供了良好的文档

注意： YubiKey 上 PIV 应用程序的默认 PIN 码为 123456；您可能需要更改它，以及默认管理密钥。有关更多信息，请参阅设备设置说明。

U2F

您也可以使用 YubiKey 的 U2F 功能来创建硬件支持的 SSH 密钥。请参阅 SSH 密钥#FIDO/U2F 以获取说明。

PIV

yubikey-agent^AUR 将 SSH 密钥存储为 PIV 令牌。请参阅 https://github.com/FiloSottile/yubikey-agent#readme 以获取设置指南。

使用 PAM 进行 Linux 用户身份验证

PAM，以及因此任何使用 PAM 进行用户身份验证的内容，都可以配置为使用 YubiKey 作为其用户身份验证过程的一个因素。这包括 sudo、su、ssh、屏幕锁定器、显示管理器以及几乎 Linux 系统需要验证用户的每个其他实例。其灵活的配置允许您为整个系统、特定应用程序或应用程序组设置适合您需求的任何身份验证要求。例如，您可以接受 YubiKey 作为本地会话密码的替代方案，同时要求远程会话同时使用两者。除了 Arch Wiki，还鼓励您阅读 pam(8) 和 pam.conf(5) 以了解其工作原理以及如何配置它。

有几个模块可用于将 YubiKey 支持的协议集成到 PAM 中

pam-u2f - 通过 FIDO2 标准支持 #U2F。如果您不确定使用哪种方法，这是一个不错的选择。
- 通用第二因素#用户会话身份验证
- Yubico 的官方文档，包括支持的模块参数列表。
- 手册页：pam_u2f(8), pamu2fcfg(1)
oath-toolkit - 支持 #OATH 一次性密码（HOTP 或 TOTP）
- pam_oath
yubico-pam - 支持 #Yubico OTP 和质询-响应 OTP。请注意，Yubico OTP 模式需要网络连接到验证服务器，而质询-响应模式则不需要。
- Yubico 的官方文档
- pam_yubico(8) - 请注意 mode 参数，用于设置质询-响应模式。

警告： 修改 PAM 配置文件时请谨慎操作。错误可能会使系统完全不安全，或过于安全以至于无法进行身份验证。

PAM 配置超出了本文的范围，但以下是一个简要概述

在用户的主目录中或集中创建包含授权密钥的文件。
在适当的 PAM 配置文件中的适当位置添加一行，其格式如下

   auth [required|sufficient] [module_name].so [module arguments]

多因素使用 auth required，单因素使用 auth sufficient。
module_name - 示例：pam_u2f.so。查看已安装模块的列表：ls /usr/lib/security
模块配置参数用于密钥文件的位置，或模块应使用哪种身份验证方法等。

SSH 注意事项

Yubico 提供了其他指南。它是为旧版本的 Ubuntu 编写的，但其中大部分仍然适用于更新的 Arch 系统。
如果您正在配置远程服务器以使用 YubiKey，您应该至少打开一个额外的救援 SSH 会话，这样如果配置失败，您就不会被锁定。
检查 /etc/ssh/sshd_config 是否包含以下设置。 openssh 附带的 sshd_config 默认已正确设置这些。

   ChallengeResponseAuthentication no
   UsePAM yes

浏览器/Web 集成

许多 Web 服务开始支持 FIDO 硬件令牌。有关更多信息，请参阅 U2F 和 WebAuthn 页面，但通常您只需要安装 libfido2 并尝试一下。

技巧与窍门

在插入/移除 YubiKey 设备时执行操作

例如，您想在将 YubiKey 从 USB 插槽中拔出时执行操作，创建 /etc/udev/rules.d/80-yubikey-actions.rules 并添加以下内容

ACTION=="remove", ENV{ID_VENDOR}=="Yubico", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0010|0111|0112|0113|0114|0115|0116|0401|0402|0403|0404|0405|0406|0407|0410", RUN+="/usr/local/bin/script args"

请注意，此示例涵盖了大多数密钥，但可能不适用于所有版本的 YubiKey。您必须查看 lsusb 的输出以获取供应商和型号 ID，以及设备的描述，或者您可以使用 udevadm 获取信息。当然，要在插入时执行脚本，您需要将操作更改为“add”而不是“remove”。

在插入时启动 Yubico Authenticator

Authenticator 是一个长时间运行的 GUI 进程。如果在 udev 规则中直接运行，该进程将阻塞 udev 的处理。如果 fork，udev 将在事件处理完成后无条件地终止该进程。因此，您无法从 udev 规则启动 Authenticator。但是，systemd.device 可以用于处理这种情况。

与上面类似，创建 /etc/udev/rules.d/80-yubikey-actions.rules 并添加以下内容

ENV{ID_VENDOR}=="Yubico", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0010|0111|0112|0113|0114|0115|0116|0401|0402|0403|0404|0405|0406|0407|0410", SYMLINK+="yubikey", TAG+="systemd"

然后创建一个新的 systemd 用户单元

~/.config/systemd/user/yubioath-desktop.service

[Unit]
Description=Autostart Yubico Authenticator
# Uncomment if you want to stop the authenticator when unplugged.
#StopPropagatedFrom=dev-yubikey.device

[Install]
WantedBy=dev-yubikey.device

[Service]
Type=oneshot
ExecStart=/usr/bin/yubioath-desktop

并启用它。 systemctl 会警告说它被添加为对不存在的单元 dev-yubikey.device 的依赖项。但这没关系。一旦 YubiKey 插入，这样的单元将开始存在。

维护 / 升级

为 YubiKey NEO 安装 OATH Applet

这些步骤将允许您将 OATH applet 安装到您的 YubiKey NEO 上。这允许在 Google Play 商店中使用 Yubico Authenticator。

注意： 这些步骤仅适用于固件版本 <= 3.1.2 的 NEO。当前一代 NEO（带有 U2F）已预装 OpenPGP applet）

将 NEO 配置为 CCID 设备

安装 yubikey-personalization-gui (yubikey-personalization-gui-git^AUR)。
添加 udev 规则并重启，以便您可以在无需 root 权限的情况下管理 YubiKey
运行 ykpersonalize -m82，输入 y，然后按 Enter 键。

安装 applet

安装 gpshell^AUR, gppcscconnectionplugin^AUR, globalplatform^AUR, 和 pcsclite。
启动 pcscd.service。
从 ykneo-oath 站点下载最新的 CAP 文件。
从 GitHub 下载 gpinstall.txt。
编辑 gpinstall.txt 中以 install -file 开头的行，以反映 CAP 文件所在的路径。
打开终端并运行 gpshell path/to/gpinstall.txt。

理想情况下，会滚动显示大量文本，最后会显示类似以下内容

Command --> 80E88013D7C000C400BE00C700CA00CA00B400BE00CE00D200D500D700B000DB00C700DF00BEFFFF00BE00E400AC00AE00AE00DB00E700A
A00EA00ED00ED00ED00BE00EF00F100F400F100F700FA00FF00BE00F700AA01010103010700CA00C400B400AA00F700B400AA00B600C7010C
010C00AA0140012001B0056810B0013005600000056810E0011006B4B44304B44404B44106B44B4405B443400343B002410636810E06B4B44
407326810B004B43103441003334002B102B404B3B403BB4003B440076820A4100221024405B4341008B44600000231066820A100
Wrapped command --> 84E88013DFC000C400BE00C700CA00CA00B400BE00CE00D200D500D700B000DB00C700DF00BEFFFF00BE00E400AC00AE00AE00DB00E700A
A00EA00ED00ED00ED00BE00EF00F100F400F100F700FA00FF00BE00F700AA01010103010700CA00C400B400AA00F700B400AA00B600C7010C
010C00AA0140012001B0056810B0013005600000056810E0011006B4B44304B44404B44106B44B4405B443400343B002410636810E06B4B44
407326810B004B43103441003334002B102B404B3B403BB4003B440076820A4100221024405B4341008B44600000231066820A15D848CB77
27D0EDA00
Response <-- 009000
Command --> 80E60C002107A000000527210108A00000052721010108A000000527210101010003C901000000
Wrapped command --> 84E60C002907A000000527210108A00000052721010108A000000527210101010003C9010000B4648127914A4C7C00
Response <-- 009000
card_disconnect
release_context

拔下 NEO 并尝试使用 Yubico Authenticator 应用程序。

（可选）安装 Yubico Authenticator 桌面客户端

您可以通过安装 yubioath-desktop 来获取 Yubico Authenticator 的桌面版本。

在 pcscd.service 运行时，运行 yubioath-desktop 并在提示时插入您的 YubiKey。

故障排除

重启，特别是如果您自上次 YubiKey 工作以来完成了更新。即使某些功能似乎正在运行，也要执行此操作。

YubiKey 不作为 HID 设备运行

注意： 在 systemd v244 之后添加对此功能的本机支持后，这些步骤不再必要。

按照本文中所述添加 udev 规则

/etc/udev/rules.d/10-security-key.rules

KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0664", GROUP="users", ATTRS{idVendor}=="2581", ATTRS{idProduct}=="f1d0"

之后运行 udevadm trigger。

ykman 无法连接到 YubiKey

如果管理器无法连接到 YubiKey，请确保您已启动 pcscd.service 或 pcscd.socket。

错误：连接到 YubiKey 5 [OTP+FIDO+CCID] 失败。请确保应用程序具有所需的权限。

当使用 ykman 访问设备上的 oath 凭据时，如果 scdaemon 已经独占控制了设备，则可能会发生这种情况。[3]

要解决此问题，您可以在 ~/.gnupg/scdaemon.conf 中使用设备的正确值设置 reader-port 选项。[4]

注意： 这将导致 gpgagent 在每次您通过 ykman 访问 YubiKey 后重新提示您解锁 YubiKey。

对于 YubiKey NEO 和 YubiKey 4

reader-port Yubico Yubikey

或对于 YubiKey 5

reader-port Yubico Yubi

YubiKey 无法在访客 VM 中绑定

假设 YubiKey 可用于访客，则问题是由主机上的驱动程序绑定到设备引起的。要解除绑定设备，需要从主机上的 dmesg 获取总线和端口信息

# dmesg | grep -B1 Yubico | tail -n 2 | head -n 1 | sed -E 's/^\[[^]]+\] usb ([^:]*):.*/\1/'

生成的 USB ID 应为 X-Y.Z 或 X-Y 形式。然后，在主机上，使用 find 搜索 /sys/bus/usb/drivers 以查找 YubiKey 绑定到的驱动程序（例如 usbhid 或 usbfs）。

$ find /sys/bus/usb/drivers -name "*X-Y.Z*"

要解除绑定设备，请使用上一个命令的结果（即 /sys/bus/usb/drivers/DRIVER/X-Y.Z:1.0）

# echo 'X-Y.Z:1.0' > /sys/bus/usb/drivers/DRIVER/unbind

错误：[key] 无法在本地签名或 gpg：没有默认密钥：没有公钥

当尝试在非标准密钥环上签名密钥时，例如 Pacman 在 pacman-key --populate 中所做的那样，当 YubiKey 插入时会发生这种情况。解决方案是移除有问题的 YubiKey 并重新开始。

YubiKey 在 Yubico Authenticator 中消失并重新出现

当未安装 CCID 驱动程序时，会发生这种情况。您可能需要安装 ccid 软件包。

YubiKey core error: timeout

您可能使用了错误的插槽。尝试另一个。

gpg: no such device

因为 gpg(scdaemon) 尝试获取对 yubikey 的独占访问权。需要将其配置为使用 pscs 并使用共享访问。[5][6]

您的文件 ~/.gnupg/scdaemon.conf 应包含

disable-ccid
pcsc-shared

对于旧版本的 GnuPG，pcsc-shared 选项不可用。仅保留 disable-ccid 并重启 pcscd.service 作为一种解决方法。