262 lines
8.2 KiB
Markdown
262 lines
8.2 KiB
Markdown
# PicoKeys: YubiKey 的开源平替
|
||
|
||
!!! danger "重要提醒"
|
||
|
||
近期，原作者[对固件代码增加了防回滚等功能](https://linux.do/t/topic/1469991)，并且[将Pico Commissioner转入闭源](https://github.com/polhenarejos/pico-fido/issues/216)，社区对原作者行为合理性产生[质疑](https://github.com/polhenarejos/pico-fido/issues/245)。有鉴于此，社区已经产生基于原项目的[完全开源分支](https://github.com/librekeys/)，但是该分支仍处于不稳定状态，分支的整体结构、更新方向和兼容性问题尚未有明确定论。
|
||
|
||
**无论选择哪个分支的固件，我强烈建议不要将刷入该固件的硬件密钥作为你保存 TOTP 和 通行密钥的唯一途径，并且妥善保管网站和应用程序提供的恢复代码。**
|
||
|
||
## 准备
|
||
|
||
- [微雪 RP2350-One](https://www.waveshare.net/wiki/RP2350-One)
|
||
- 建议使用官方附赠贴纸粘贴在背面Logo处以紧固USB接口
|
||
- [Pico Keys](https://www.picokeys.com/)
|
||
|
||
## 刷写固件
|
||
|
||
### 下载固件
|
||
|
||
- 转至 [Getting Started - Pico Keys](https://www.picokeys.com/getting-started/)
|
||
- Firmware: `Pico Fido`
|
||
- Vendor: `Raspberry`
|
||
- Model: `Pico 2`
|
||
|
||
### 进入 DFU 模式并刷写固件
|
||
|
||
- 拔下 RP2350-One
|
||
- 按住 `BOOT` 键，并将 RP2350-One 插入 USB 接口
|
||
- 文件资源管理器 / 访达中将出现一个名为 **RP2350** 的可移动驱动器
|
||
- 复制先前下载的 .uf2 文件，并将其粘贴到可移动驱动器中
|
||
- RP2350-One 将自动卸载可移动驱动器，并重新挂载为 Pico Key
|
||
|
||
## 初始化 PicoKeys
|
||
|
||
- ++windows+i++ - 账户 - 登录选项 - 安全密钥 - 管理
|
||
- 插入 Picokey
|
||
- 点击 添加安全密钥 PIN
|
||
|
||
## 配置 PicoKeys
|
||
|
||
下载 [PicoForge](https://github.com/librekeys/picoforge/releases/latest)，安装后以管理员身份运行。
|
||
|
||
- 转至 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](https://www.yubico.com/products/yubico-authenticator/)
|
||
|
||
### 使用 PicoKeys 强化 SSH 身份验证
|
||
|
||
检查 OpenSSH 版本，建议为 OpenSSH 8.3 或以上。
|
||
|
||
``` bash
|
||
ssh -V
|
||
```
|
||
|
||
如有需要，请更新 OpenSSH:
|
||
|
||
Linux:
|
||
|
||
``` bash
|
||
# 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 客户端。可通过以下命令确认：
|
||
|
||
``` powershell
|
||
Get-WindowsCapability -Online | ? Name -like 'OpenSSH.Client*'
|
||
```
|
||
|
||
**生成 ed25519-sk 密钥**:
|
||
|
||
``` bash
|
||
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`
|
||
|
||
``` bash
|
||
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`
|
||
|
||
``` title="~/.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 并运行:
|
||
|
||
``` bash
|
||
ssh-keygen -K
|
||
```
|
||
|
||
这将检索常驻密钥并创建句柄和公钥文件。
|
||
|
||
### 使用 PicoKeys 与 SSH/FIDO2 进行 Git 提交签名
|
||
|
||
检查 OpenSSH 版本，建议为 OpenSSH 8.3 或以上。检查 Git 版本，建议为 Git 2.34 或以上。
|
||
|
||
``` bash
|
||
ssh -V
|
||
|
||
git --version
|
||
```
|
||
|
||
**设置 Git 默认用户名与邮箱**:
|
||
|
||
此处设置的邮箱必须与在 GitHub/GitLab/Gitea 中设置的一致。
|
||
|
||
``` bash
|
||
git config --global user.name "username"
|
||
git config --global user.email "your.email@example.com"
|
||
```
|
||
|
||
**生成 ed25519-sk 密钥**:
|
||
|
||
``` bash
|
||
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:
|
||
|
||
``` bash
|
||
git config --global gpg.format ssh
|
||
```
|
||
|
||
指定签名密钥(公钥)：
|
||
|
||
``` bash
|
||
git config --global user.signingkey /path/to/your/git-signing-key-public.pub
|
||
```
|
||
|
||
启用自动提交签名和自动标签签名:
|
||
|
||
``` bash
|
||
git config --global commit.gpgSign true
|
||
git config --global tag.forceSignAnnotated true
|
||
```
|
||
|
||
**创建并配置 allowed_signers 文件**:
|
||
|
||
`allowed_signers` 文件每行的格式为: `[email] namespaces="git" [git_signing_public_key_string]`
|
||
|
||
例如:
|
||
|
||
``` title="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` 文件的位置:
|
||
|
||
``` bash
|
||
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 密钥”。
|
||
- 粘贴您的签名公钥。
|
||
- 点击“验证”按钮，[按照提示验证公钥](https://blog.cattom.site/tech/Snippets/#gitea)。
|
||
- Gitea 会将此密钥生成的签名与您的账户关联，并在**提交者邮箱与 Gitea 账户已验证邮箱匹配**时，将提交标记为“已验证”。
|
||
|
||
|
||
## PicoKeys 指示灯
|
||
|
||
- 蓝灯: PicoKeys 待机
|
||
- 红灯: PicoKeys 处理中
|
||
- 绿灯: 需要用户按下 `BOOT` 键以授权操作 |