diff --git a/docs/tech/Picokeys.md b/docs/tech/Picokeys.md index 36217c2..b6c4348 100644 --- a/docs/tech/Picokeys.md +++ b/docs/tech/Picokeys.md @@ -2,99 +2,155 @@ !!! 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 和 Webauthn 密钥的唯一途径，并且妥善保管网站提供的恢复代码。** + 近期，原作者[对固件代码增加了防回滚等功能](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 和 Webauthn 密钥的唯一途径，并且妥善保管网站和应用程序提供的恢复代码。** -[Pico Keys](https://www.picokeys.com/) - -## 材料 +## 准备 - [微雪 RP2350-One](https://www.waveshare.net/wiki/RP2350-One) + - 建议使用官方附赠贴纸粘贴在背面Logo处以紧固USB接口 +- [Pico Keys](https://www.picokeys.com/) -建议使用官方附赠贴纸粘贴在背面Logo处以紧固USB接口 +## 刷写固件 -## 安装 +### 下载固件 -[Getting Started - Pico Keys](https://www.picokeys.com/getting-started/) +- 转至 [Getting Started - Pico Keys](https://www.picokeys.com/getting-started/) +- Firmware: `Pico Fido` +- Vendor: `Raspberry` +- Model: `Pico 2` -Pico Fido +### 进入 DFU 模式并刷写固件 -Raspberry +- 拔下 RP2350-One +- 按住 `BOOT` 键，并将 RP2350-One 插入 USB 接口 +- 文件资源管理器 / 访达中将出现一个名为 **RP2350** 的可移动驱动器 +- 复制先前下载的 .uf2 文件，并将其粘贴到可移动驱动器中 +- RP2350-One 将自动卸载可移动驱动器，并重新挂载为 Pico Key -Pico 2 +## 初始化 PicoKeys -For Raspberry Pico, put the Pico device into recovery mode: +- ++windows+i++ - 账户 - 登录选项 - 安全密钥 - 管理 +- 插入 Picokey +- 点击 添加安全密钥 PIN -- Unplug the device -- While pressing the BOOTSEL button, plug the device to the USB port -- A mounted flash unit will appear in the File Explorer / Finder named RP2350 (for RP2350 boards) -- Copy the .uf2 file download previously and copy to the mounted unit -- The device will unmount the flash unit and will be remounted as a Pico Key. The led light will blink periodically +## 配置 PicoKeys -## 初始化 - -++windows+i++ 账户 登录选项 安全密钥 管理 - -插入 Picokey - -添加安全密钥 PIN - -## 配置 - -[picoforge](https://github.com/librekeys/picoforge) - -以管理员身份运行 - -Configuration +下载 [PicoForge](https://github.com/librekeys/picoforge/releases/latest)，安装后以管理员身份运行。 +- 转至 Configuration - Identify - - Vendor Preset `Yubikey 5` - - Product Name `Yubico YubiKey` + - Vendor Preset: `Yubikey 5` + - Product Name: `Yubico YubiKey` - LED Setting - - LED GPIO Pin `16` - - LED Driver `WS2812` - - Brightness `5` - - LED Dimmable `Switch ON` + - LED GPIO Pin: `16` + - LED Driver: `WS2812` + - Brightness: `5` + - LED Dimmable: `Switch ON` - Touch Timing - - Touch Timeouts `15` + - Touch Timeouts: `15` - Device Options - - Power Cycle on Reset `Switch ON` + - Power Cycle on Reset: `Switch ON` +- 点击 Apply Changes +- 按下开发板上的 `Reset` 键 -Apply Changes +## 使用 PicoKeys -按下开发板上的"Reset" +### 添加通行密钥 -## 使用 +- 任意可使用通行密钥的网页 +- 保存通行密钥 +- 选择保存此通行密钥的位置: 安全密钥 +- 输入 PIN +- 单击 `BOOT` 键以授权 -[Yubico Authenticator App for Desktop and Mobile | Yubico](https://www.yubico.com/products/yubico-authenticator/) +### 添加/管理 TOTP 与通行密钥 -添加 TOTP +下载 [Yubico Authenticator App for Desktop and Mobile | Yubico](https://www.yubico.com/products/yubico-authenticator/) -管理 通行密钥 +### 使用 PicoKeys 强化 SSH 身份验证 -- 蓝灯: 设备待机 -- 红灯: 设备处理中 -- 绿灯: 需要用户按 `BOOT` 键以授权 +检查 OpenSSH 版本，建议为 OpenSSH 8.3 或以上。 ``` bash -ssh-keygen -t ed25519-sk -O resident -O verify-required -O application=ssh:custom_name -O user=my_username +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: -O user= -C "comment" +``` + +密钥生成选项详解: + +- `-t ed25519-sk`: 密钥类型。 +- `-O resident`: 创建驻留密钥，存储在 YubiKey 设备本身。支持跨设备便携使用。需要输入 PIN 码。 +- `-O verify-required`: 每次使用均需输入 PIN 码并进行物理按键验证。(适用于 OpenSSH 8.3 及以上版本) +- `-O application=ssh:`: 存储多个 SSH 凭证时的可选标签。 +- `-O user=`: 存储多个 SSH 凭证时的可选用户名标签。 +- `-C "comment"` ：用于分辨密钥的可选信息。 + +若省略 `-O resident`，系统将创建非驻留密钥。其私钥句柄将存储于磁盘，但仍需用户按下物理按键验证。使用 `-O verify-required` 可强制启用 PIN 码验证。 + +密钥生成过程: + +- 请按下您的 PicoKeys `BOOT` 键。 + - 若创建常驻密钥，系统将提示输入 PIN 码。 +- 选择密钥句柄文件的保存位置。 + - 该文件不包含私钥，电脑磁盘仅存储引用句柄。 +- (可选)设置本地密码短语以保护句柄文件。 +- `.pub` 文件是您用于服务器或 GitHub 的公钥文件。 + +**将公钥添加至服务器**: + +方法一: 使用 `ssh-copy-id` + +``` bash +ssh-copy-id -i /path/to/public-key.pub [username]@[server_ip] +``` + +方法二: 将公钥内容插入服务器 `~/.ssh/authorized_keys` 文件的末尾 + +**在新设备上使用常驻密钥**: + +常驻密钥具有便携性，可以轻松取回私钥句柄和公钥文件。 + +新设备需确保已安装 OpenSSH 8.2 或更高版本。 + +插入您的 YubiKey 并运行: + +``` bash +ssh-keygen -K +``` + +这将检索常驻密钥并创建句柄和公钥文件。 + +### 使用 PicoKeys 与 SSH/FIDO2 进行 Git 提交签名 + https://zhuanlan.zhihu.com/p/691575345 -## 其他 +## PicoKeys 指示灯 -如何正确地擦除并刷写新固件？ -在进行任何操作前，你需要先让 ESP32-S3 进入下载模式（Download Mode / DFU）： -按住板子上的 BOOT（或 0）按钮不放。 -单击一下 RESET（或 EN / RST）按钮。 -松开 BOOT 按钮。 -(此时电脑会重新识别到一个串口设备) -接下来，根据你使用的刷写工具，选择对应的擦除方式： -方法一：使用命令行工具 esptool.py（最推荐、最彻底） -如果你熟悉命令行，使用乐鑫官方的 esptool 是最稳妥的。在终端中执行以下命令彻底清空闪存： - -``` powershell -esptool.py --chip esp32s3 --port COM3 erase_flash -``` - -显示 Flash memory erased successfully 后，你就可以像对待一块全新的 ESP32-S3 一样，用常规方法刷写任何其他固件了。 \ No newline at end of file +- 蓝灯: PicoKeys 待机 +- 红灯: PicoKeys 处理中 +- 绿灯: 需要用户按下 `BOOT` 键以授权操作 \ No newline at end of file diff --git a/docs/tech/Snippets.md b/docs/tech/Snippets.md index f6c6b1c..4f14032 100644 --- a/docs/tech/Snippets.md +++ b/docs/tech/Snippets.md @@ -81,4 +81,25 @@ git reset --hard origin/main `git fetch` 从远程下载最新版本，不会尝试合并或重新设置任何内容。 -然后 `git reset` 将 main 分支重置为你刚获取的分支。--hard 选项更改工作树中的所有文件，以匹配 origin/main 中的文件。 \ No newline at end of file +然后 `git reset` 将 main 分支重置为你刚获取的分支。--hard 选项更改工作树中的所有文件，以匹配 origin/main 中的文件。 + +## 擦除 ESP32-S3 固件 + +下载并安装 [esptool](https://github.com/espressif/esptool/releases/latest) + +令 ESP32-S3 进入 DFU 模式: + +- 按住板子上的 `BOOT` 按钮不放，将设备接入电脑 +- 再单击一下 `RESET` 按钮 +- 松开 BOOT 按钮 +- 此时电脑会重新识别到一个串口设备 +- 转至 设备管理器 +- 确定 ESP32-S3 设备所对应的串口 + +用命令行工具 esptool 擦除 ESP32-S3 固件，在终端中执行以下命令: + +``` powershell +D:\esptool-v5.2.0-windows-amd64\esptool.exe --chip esp32s3 --port [ESP32-S3 设备所对应的串口 e.g.:COM3] erase_flash +``` + +显示 `Flash memory erased successfully` 后，你就可以像对待一块全新的 ESP32-S3 一样，用常规方法刷写任何其他固件了。 \ No newline at end of file