PicoKeys: YubiKey 的开源平替

重要提醒

近期，原作者对固件代码增加了防回滚等功能，并且将Pico Commissioner转入闭源，社区对原作者行为合理性产生质疑。有鉴于此，社区已经产生基于原项目的完全开源分支，但是该分支仍处于不稳定状态，分支的整体结构、更新方向和兼容性问题尚未有明确定论。

无论选择哪个分支的固件，我强烈建议不要将刷入该固件的硬件密钥作为你保存 TOTP 和 通行密钥的唯一途径，并且妥善保管网站和应用程序提供的恢复代码。

准备

• 微雪 RP2350-One
  • 建议使用官方附赠贴纸粘贴在背面Logo处以紧固USB接口
• Pico Keys

刷写固件

下载固件

• 转至 Getting Started - Pico Keys
• Firmware: Pico Fido
• Vendor: Raspberry
• Model: Pico 2

进入 DFU 模式并刷写固件

• 拔下 RP2350-One
• 按住 BOOT 键，并将 RP2350-One 插入 USB 接口
• 文件资源管理器 / 访达中将出现一个名为 RP2350 的可移动驱动器
• 复制先前下载的 .uf2 文件，并将其粘贴到可移动驱动器中
• RP2350-One 将自动卸载可移动驱动器，并重新挂载为 Pico Key

初始化 PicoKeys

• Win+I - 账户 - 登录选项 - 安全密钥 - 管理
• 插入 Picokey
• 点击 添加安全密钥 PIN

配置 PicoKeys

下载 PicoForge，安装后以管理员身份运行。

• 转至 Configuration
• Identify
  • Vendor Preset: Yubikey 5
  • Product Name: Yubico YubiKey
• LED Setting
  • LED GPIO Pin: 16
  • LED Driver: WS2812
  • Brightness: 5
  • LED Dimmable: Switch ON
• Touch Timing
  • Touch Timeouts: 15
• Device Options
  • Power Cycle on Reset: Switch ON
• 点击 Apply Changes
• 按下开发板上的 Reset 键

使用 PicoKeys

添加通行密钥

• 任意可使用通行密钥的网页
• 保存通行密钥
• 选择保存此通行密钥的位置: 安全密钥
• 输入 PIN
• 单击 BOOT 键以授权

添加/管理 TOTP 与通行密钥

下载 Yubico Authenticator App for Desktop and Mobile | Yubico

使用 PicoKeys 强化 SSH 身份验证

检查 OpenSSH 版本，建议为 OpenSSH 8.3 或以上。

ssh -V

如有需要，请更新 OpenSSH:

Linux:

# Debian/Ubuntu
sudo apt update && sudo apt install openssh-client

# Fedora/RHEL/CentOS
sudo dnf install openssh-clients

Windows: Windows 10 (1809 版本及以上)和 Windows 11 系统内置了 OpenSSH 客户端。可通过以下命令确认：

Get-WindowsCapability -Online | ? Name -like 'OpenSSH.Client*'

生成 ed25519-sk 密钥:

ssh-keygen -t ed25519-sk -O resident -O verify-required -O application=ssh:<name> -O user=<name> -C "comment"

密钥生成选项详解:

• -t ed25519-sk: 密钥类型。
• -O resident: 创建驻留密钥，存储在 YubiKey 设备本身。支持跨设备便携使用。需要输入 PIN 码。
• -O verify-required: 每次使用均需输入 PIN 码并进行物理按键验证。(适用于 OpenSSH 8.3 及以上版本)
• -O application=ssh:<name>: 存储多个 SSH 凭证时的可选标签。
• -O user=<name>: 存储多个 SSH 凭证时的可选用户名标签。
• -C "comment" ：用于分辨密钥的可选信息。

若省略 -O resident，系统将创建非驻留密钥。其私钥句柄将存储于磁盘，但仍需用户按下物理按键验证。使用 -O verify-required 可强制启用 PIN 码验证。

密钥生成过程:

• 请按下您的 PicoKeys BOOT 键。
  • 若创建常驻密钥，系统将提示输入 PIN 码。
• 选择密钥句柄文件的保存位置。
  • 该文件不包含私钥，电脑磁盘仅存储引用句柄。
• (可选)设置本地密码短语以保护句柄文件。
• .pub 文件是您用于服务器或 GitHub 的公钥文件。

将公钥添加至服务器:

方法一: 使用 ssh-copy-id

ssh-copy-id -i /path/to/key.pub [username]@[server_ip]

方法二: 将公钥内容插入服务器 ~/.ssh/authorized_keys 文件的末尾

将公钥添加至 GitHub:

• 将密钥作为 SSH 密钥上传至 GitHub: SSH 公钥必须添加到 GitHub 账户的 SSH 和 GPG 密钥设置。
• 前往 GitHub > 设置 > SSH 和 GPG 密钥。
• 点击“添加 SSH 密钥”。
• 粘贴您的公钥。

修改 /path/to/.ssh/config

~/.ssh/config

Host github.com
HostName ssh.github.com
User git
Port 443
PreferredAuthentications publickey
IdentityFile "/path/to/.ssh/key"

测试能否正常连接: ssh -T git@github.com

在新设备上使用常驻密钥:

常驻密钥具有便携性，可以轻松取回私钥句柄和公钥文件。

新设备需确保已安装 OpenSSH 8.2 或更高版本。

插入您的 YubiKey 并运行:

ssh-keygen -K

这将检索常驻密钥并创建句柄和公钥文件。

使用 PicoKeys 与 SSH/FIDO2 进行 Git 提交签名

检查 OpenSSH 版本，建议为 OpenSSH 8.3 或以上。检查 Git 版本，建议为 Git 2.34 或以上。

ssh -V

git --version

设置 Git 默认用户名与邮箱:

此处设置的邮箱必须与在 GitHub/GitLab/Gitea 中设置的一致。

git config --global user.name "username"
git config --global user.email "your.email@example.com"

生成 ed25519-sk 密钥:

ssh-keygen -t ed25519-sk -O resident -O verify-required -O application=ssh:git-signing -O user=<name> -C "Git Signing Key"

为 Git 配置 SSH 签名:

将 Git 的 GPG 格式设置为 SSH:

git config --global gpg.format ssh

指定签名密钥(公钥)：

git config --global user.signingkey /path/to/your/git-signing-key-public.pub

启用自动提交签名和自动标签签名:

git config --global commit.gpgSign true
git config --global tag.forceSignAnnotated true

创建并配置 allowed_signers 文件:

allowed_signers 文件每行的格式为: [email] namespaces="git" [git_signing_public_key_string]

例如:

allowed_signers

your.email@example.com namespaces="git" ssh-ed25519 AAAAC3NzaC1lZYourPublicKeyData... Git Signing Key

请确保 your.email@example.com 与在 git config user.email 设置的邮箱完全匹配。namespaces="git" 对于限定密钥权限范围至关重要。

在 Git 中设定 allowed_signers 文件的位置:

git config --global gpg.ssh.allowedSignersFile /path/to/your/.ssh/allowed_signers"

本地验证签名情况:

• 针对提交: git log --show-signature
• 针对标签: git tag -v <tag-name>
• 查看是否有 Good "git" signature for your.email@example.com with ED25519-SK key ...

在 GitHub 与 Gitea 上获取“已验证”标志:

GitHub:

• 将您的签名密钥作为 SSH 密钥上传至 GitHub: 用于签名的 SSH 公钥必须以认证密钥的形式添加到 GitHub 账户的 SSH 和 GPG 密钥设置。
• 前往 GitHub > 设置 > SSH 和 GPG 密钥。
• 点击“添加 SSH 密钥”。
• 粘贴您的签名公钥。
• GitHub 会将此密钥生成的签名与您的账户关联，并在提交者邮箱与 GitHub 账户已验证邮箱匹配时，将提交标记为“已验证”。

Gitea:

• 将您的签名密钥作为 SSH 密钥上传至 Gitea: 用于签名的 SSH 公钥必须以认证密钥的形式添加到 Gitea 账户的 SSH 和 GPG 密钥设置。
• 前往 Gitea > 设置 > SSH 和 GPG 密钥。
• 点击“添加 SSH 密钥”。
• 粘贴您的签名公钥。
• 点击“验证”按钮，按照提示验证公钥。
• Gitea 会将此密钥生成的签名与您的账户关联，并在提交者邮箱与 Gitea 账户已验证邮箱匹配时，将提交标记为“已验证”。

PicoKeys 指示灯

• 蓝灯: PicoKeys 待机
• 红灯: PicoKeys 处理中
• 绿灯: 需要用户按下 BOOT 键以授权操作