在 WSL2 中使用 YubiKey
序言
最近我开始深入使用 WSL2,其中一个需求是在 WSL2 中使用 YubiKey 进行 GPG 签名等操作。
在这个过程中,我遇到了不少挑战和意想不到的问题。为了帮助后来者避免重蹈覆辙,我决定将整个配置过程和解决方案记录下来,整理成这篇教程。
Note本文以 Arch Linux 作为 WSL 发行版进行演示。
Windows 端的解决方案基于 usbipd-win 项目。
前提条件
- 已在 Windows 中安装 Arch Linux。
- 拥有一枚 YubiKey。
一、连接 YubiKey
Windows 侧配置
首先,我们需要在 Windows 上安装 usbipd-win
,它能让我们通过 IP 网络共享 USB 设备。
winget install --interactive --exact dorssel.usbipd-win
安装完成后,将 YubiKey 插入电脑,并以 管理员权限 打开 PowerShell 或终端,运行以下命令列出所有 USB 设备:
usbipd list
输出结果类似下方所示:
Connected:
BUSID VID:PID DEVICE STATE
1-6 1050:0407 USB Input Device, Microsoft Usbccid Smartcard Reader (WUDF) Not shared
1-7 17ef:6019 USB Input Device Not shared
1-8 1a2c:20c0 USB Input Device Not shared
请记下你的 YubiKey 对应的 BUSID
和 VID:PID
,它们在后续步骤中至关重要。
接下来,使用 bind
命令使 YubiKey 可以被共享:
usbipd bind --busid=<busid>
Tip请将
<busid>
替换为你记下的实际 BUSID。
绑定成功后,就可以将 YubiKey 附加到 WSL2 了:
usbipd attach --wsl --busid=<busid>
Linux 侧验证
进入 WSL2 的 Arch Linux 环境,安装 usbip
和 usbutils
软件包。
sudo pacman -S usbip usbutils
然后执行 lsusb
命令,检查 YubiKey 是否已被成功识别:
lsusb
如果输出中包含 Yubico.com
或 YubiKey
等字样,恭喜你,YubiKey 已经成功连接到 WSL2。
二、配置 GPG 和 Udev 规则
仅仅连接是不够的,我们还需要进行一些配置,才能让 GPG 等工具正常使用 YubiKey。
首先,安装 YubiKey 管理器、PC/SC 智能卡服务和相关工具:
sudo pacman -S yubikey-manager pcsclite pcsc-tools
然后,启用并立即启动 pcscd
服务:
sudo systemctl enable --now pcscd.service
此时,如果你尝试运行 ykman info
,很可能会收到 No YubiKey detected
的错误。这是因为 WSL2 默认没有配置正确的设备访问权限。
为了解决这个问题,我们需要创建 udev
规则。
第一步,创建一个名为 scard
的用户组,用于授予访问智能卡设备的权限,并将当前用户添加进去:
sudo groupadd --system scard
sudo usermod -aG scard $USER
Important添加用户组后,你需要完全关闭并重启 WSL2 才能使变更生效。可以在 Windows 终端中执行
wsl --shutdown
,然后重新打开 ArchWSL。
重启后,创建以下 udev
规则文件。这个规则会在 YubiKey (作为 CCID 设备) 连接时,自动将其权限赋予 scard
用户组。
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="0660", GROUP="scard"
注意:这里的 ID_VENDOR_ID
(厂商ID) 和 ID_MODEL_ID
(产品ID) 需要根据你自己的设备进行修改。还记得之前记下的 VID:PID
吗?它们就分别对应 ID_VENDOR_ID
和 ID_MODEL_ID
。例如,如果你的 VID:PID
是 1050:0407
,则应将 ID_MODEL_ID
修改为 "0407"
。
创建文件后,使用 sudo udevadm trigger
命令让 udev
重新加载所有规则:
sudo udevadm trigger
现在,ykman info
应该可以正常工作了。但此时 GPG 可能仍然无法读取到密钥,这是因为 Polkit
(一个用于控制系统级权限的框架) 限制了相关操作。
我们需要添加一条 Polkit
规则,允许 wheel
用户组的成员访问 PC/SC 服务。
polkit.addRule(function(action, subject) {
if ((action.id == "org.debian.pcsc-lite.access_card" ||
action.id == "org.debian.pcsc-lite.access_pcsc") &&
subject.isInGroup("wheel")) {
return polkit.Result.YES;
}
});
Important使用上述规则前,请确保你的用户位于
wheel
用户组中,否则规则将不会生效。你可以使用groups $USER
命令检查,并使用sudo usermod -aG wheel $USER
添加。
最后,重启 polkit
服务以应用新的规则:
sudo systemctl restart polkit.service
至此,GPG 应该可以正常发现并使用你的 YubiKey 了。
后记
配置过程确实有些繁琐,尤其是 udev
和 Polkit
的部分,花了我不少时间才找到根本原因。希望这篇文章能为你节省宝贵的时间,顺利在 WSL2 中用上 YubiKey。