Package: rpi-derive-key
RPi Derive Key 🔑A utility for deriving secure device-specific keys on Raspberry Pi.⚠️Caution:This tool is based on storing a randomly generateddevice secretin theOne-Time Programmable(OTP) memoryof the Raspberry Pi SoC. The initialization of this secret isirreversible. Pleasemake sure you understand the provided security guaranteesbefore using it for anything serious.Cryptographically strongkey derivation usingSHA3-512andHKDF.Statically-linkedstandalone binarywith zero dependencies.Rust crateandPython packagefor easy integration into your project.How does it work?Upon initialization, a randomly generated 256-bitdevice secretis stored in the OTP memory of the Raspberry Pi SoC. Note that the OTP memory on any board can be programmedonly once. This secret is then used as input key material for the HKDF key derivation algorithm using SHA3-512 as the hash function. This enables the derivation of multiple keys from the device secret. Each key is derived from the device secret and additionalinfomaterial (see HKDF). The device secret should be kept secret andrpi-derive-keydoes not provide any means of reading it directly. Using it and the info material, any key can be reconstructed. Note that the Raspberry Pi SoC doesnotprovide a hardware-protected store for the secret. Any user in thevideogroup and anyone with physical access to the board can obtain the secret (unless secure boot is used). Viasecure bootit is indeed possible to prevent any unauthorized access when deploying Raspberry Pi's in untrusted environments.If you are interested in commercial support,please contact us.🧑‍💻 UsageThe easiest way to properly install RPi Derive Key on a Raspberry Pi is via the official Debian packages.On a 32-bit Raspberry Pi OS (armhf) run:wget https://github.com/silitics/rpi-derive-key/releases/latest/download/rpi-derive-key_armhf.deb
sudo dpkg --install rpi-derive-key_armhf.debOn a 64-bit Raspberry Pi OS (arm64) run:wget https://github.com/silitics/rpi-derive-key/releases/latest/download/rpi-derive-key_arm64.deb
sudo dpkg --install rpi-derive-key_arm64.debNote that the Debian packages do not include the Python package. They merely contain the command line tool and a Systemd service for initializing the device secret during the boot process. The Python package can be installed as usual viapipor added as a dependency to a Python project.For testing and debugging, the Python package is also available for MacOS, Windows, and x86_64 Linux. On these platforms, however, the device secret must be faked by setting theFAKE_RPI_DERIVE_KEY_SECRETenvironment variable (see below). The Python package is documented by itstype stub.Standalone binaries are available on theReleases page.The documentation of the Rust crate isavailable on docs.rs.Initialization of the Device SecretTo derive keys, the device secret needs to be initialized first.Using the command line tool, the device secret is irreversibly initialized with:rpi-derive-key initNote that the initialization may fail if the firmware does not support storing a private key in OTP memory. In this case, you can either update the firmware or use the generic customer-programmable OTP registers instead:rpi-derive-key --customer-otp initThe switch--customer-otpmust subsequently be provided to all commands.The Debian package comes with a Systemd service for initializing the device secret during the boot process. This is useful to initialize devices with an image or SD card. To enable this service, run:sudo systemctl enable rpi-derive-keyStatus Information and ChecksTo print status information, run:rpi-derive-key statusTo check that the secret has been properly initialized, run:rpi-derive-key checkThis is useful when using RPi Derive Key in a script.Deriving a KeyTo derive a key and print it in hex representation userpi-derive-key hex <BYTES> <INFO>where<BYTES>is the key size in bytes and<INFO>is some arbitrary string.For instance, to generate a 512-bit filesystem encryption key run:rpi-derive-key hex 64 fs.root.encryptionMultiple independent keys can be generated by using different values for<INFO>.To derive aUUIDv4userpi-derive-key uuid <INFO>where<INFO>is again some arbitrary string.For instance, to generate a unique device id run:rpi-derive-key uuid device.idTesting and DebuggingFor testing and debugging purposes, you can fake a device secret by setting theFAKE_RPI_DERIVE_KEY_SECRETenvironment variable to any secret you like. Pleasenever use this variable in production.Setting this variable also bypasses initialization viarpi-derive-key init.Example Use CaseImagine you would like to derive a unique public id and a secret identification token for each device.To derive a unique public device id usingdevice.idas<INFO>run:rpi-derive-key uuid device.idYou can now safely use the resulting UUID as a public device identifier. You do not have to keep it secret because it is impossible to reconstruct other keys or the device secret from it.In addition to the public id, you can derive a 256-bit (32 bytes) secret token with:rpi-derive-key hex 32 device.secret.tokenThis secret token is supposed to be shared only with trustworthy entities, e.g., it may be sent in HTTP headers to prove the device's identity to a webserver providing device configurations:wget --header "X-Secret-Token: <SECRET-TOKEN>" https://example.com/<DEVICE-ID>/config.tar.gz📌Tip:You should use different keys (with different info material) for different purposes (e.g., fetching updates or configurations). That way, if a key for a given purpose is compromised, all other keys remain secure.⚖️ LicensingRPi Derive Keyis licensed under eitherMITorApache 2.0at your opinion. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache 2.0 license, shall be dual licensed as above, without any additional terms or conditions.Made with ❤️ for OSS bySilitics.