RPi Derive Key 🔑

A utility for deriving secure device-specific keys on Raspberry Pi.

⚠️ 注意：此工具基于在Raspberry Pi SoC的一次性可编程 (OTP) 存储器中存储随机生成的设备密钥。此密钥的初始化是不可逆的。请在将其用于任何严肃的事情之前，请确保您理解提供的安全保证。

• 使用SHA3-512和HKDF进行密码学上强大的密钥派生。
• 静态链接的独立二进制，无依赖。
• Rust crate和Python包，便于集成到您的项目中。

它是如何工作的？

初始化时，一个随机生成的256位设备密钥被存储在Raspberry Pi SoC的OTP存储器中。请注意，任何板上的OTP存储器只能编程一次。然后，此密钥用作HKDF密钥派生算法的输入密钥材料，使用SHA3-512作为哈希函数。这允许从设备密钥派生出多个密钥。每个密钥都是从设备密钥和额外的信息材料（见HKDF）派生的。设备密钥应保密，而rpi-derive-key不提供读取它的直接方式。使用它和信息材料，可以重建任何密钥。请注意，Raspberry Pi SoC不提供用于存储密钥的硬件保护存储。任何在video组的用户和任何有权访问该板的人都可以获得密钥（除非使用安全启动）。通过安全启动，在部署Raspberry Pi到不受信任的环境中时，确实可以防止任何未授权的访问。

如果您对商业支持感兴趣，请联系我们。

🧑‍💻 使用方法

在Raspberry Pi上正确安装RPi Derive Key的最简单方法是使用官方Debian软件包。

在32位Raspberry Pi OS（armhf）上运行

wget https://github.com/silitics/rpi-derive-key/releases/latest/download/rpi-derive-key_armhf.deb
sudo dpkg --install rpi-derive-key_armhf.deb

在64位Raspberry Pi OS（arm64）上运行

wget https://github.com/silitics/rpi-derive-key/releases/latest/download/rpi-derive-key_arm64.deb
sudo dpkg --install rpi-derive-key_arm64.deb

请注意，Debian软件包不包括Python软件包。它们仅包含命令行工具和在启动过程中初始化设备密钥的系统服务。Python软件包可以通过pip按常规方式安装，或作为Python项目的依赖项添加。

对于测试和调试，Python软件包也适用于MacOS、Windows和x86_64 Linux。然而，在这些平台上，必须通过设置环境变量FAKE_RPI_DERIVE_KEY_SECRET（见下文）来伪造设备密钥。Python软件包由其类型存根进行文档说明。

独立的二进制文件可在发布页面上找到。

Rust crate的文档可在docs.rs上找到。

设备密钥的初始化

要派生密钥，首先需要初始化设备密钥。

使用命令行工具，设备密钥通过以下方式不可逆地初始化

rpi-derive-key init

请注意，如果固件不支持在OTP内存中存储私钥，则初始化可能失败。在这种情况下，您可以更新固件或使用通用的客户可编程OTP寄存器

rpi-derive-key --customer-otp init

必须为所有命令提供切换--customer-otp。

Debian软件包包含一个在启动过程中初始化设备密钥的系统服务。这对于使用镜像或SD卡初始化设备非常有用。要启用此服务，运行

sudo systemctl enable rpi-derive-key

状态信息和检查

要打印状态信息，请运行

rpi-derive-key status

要检查密钥是否已正确初始化，请运行

rpi-derive-key check

这在将RPi Derive Key用于脚本时很有用。

派生密钥

要派生密钥并以十六进制表示打印它，请使用

rpi-derive-key hex <BYTES> <INFO>

其中<BYTES>是密钥大小（以字节为单位），<INFO>是任意字符串。

例如，要生成一个512位文件系统加密密钥，请运行

rpi-derive-key hex 64 fs.root.encryption

可以通过为<INFO>使用不同的值来生成多个独立的密钥。

要派生一个UUIDv4，请使用

rpi-derive-key uuid <INFO>

其中<INFO>又是任意字符串。

例如，要生成一个唯一的设备ID，请运行

rpi-derive-key uuid device.id

测试和调试

为了测试和调试的目的，您可以将环境变量FAKE_RPI_DERIVE_KEY_SECRET设置为任何您喜欢的密钥来伪造设备密钥。请绝对不要在生产中使用此变量。

设置此变量还将绕过通过rpi-derive-key init进行的初始化。

示例用例

想象一下，您想要为每个设备派生一个唯一的公共ID和秘密标识令牌。

使用 device.id 作为 <INFO> 运行来导出唯一的公共设备 ID

rpi-derive-key uuid device.id

现在您可以安全地使用生成的 UUID 作为公共设备标识符。您不需要保密，因为它无法从中重建其他密钥或设备密钥。

除了公共 ID，您还可以使用以下方法导出 256 位（32 字节）的秘密令牌

rpi-derive-key hex 32 device.secret.token

此秘密令牌应仅与可信赖的实体共享，例如，它可以发送到 HTTP 标头中，以向提供设备配置的 web 服务器证明设备的身份

wget --header "X-Secret-Token: <SECRET-TOKEN>" https://example.com/<DEVICE-ID>/config.tar.gz

📌 提示：您应使用不同用途（例如获取更新或配置）的不同密钥（具有不同的信息材料）。这样，如果某个目的的密钥遭到破坏，所有其他密钥仍保持安全。

⚖️ 许可

RPi Derive Key 根据您的意见许可为 MIT 或 Apache 2.0。除非您明确声明，否则您有意提交给此项目的任何贡献，根据 Apache 2.0 许可定义，将按上述方式双重许可，不附加任何额外条款或条件。

由 Silitics 热情地为 OSS 制作。