{"id":15020472,"url":"https://github.com/raspberrypi/rpi-sb-provisioner","last_synced_at":"2025-10-19T16:32:55.569Z","repository":{"id":250913035,"uuid":"835826368","full_name":"raspberrypi/rpi-sb-provisioner","owner":"raspberrypi","description":"A minimal-input automatic secure boot provisioning system for Raspberry Pi devices.","archived":false,"fork":false,"pushed_at":"2025-01-24T16:02:03.000Z","size":243022,"stargazers_count":29,"open_issues_count":15,"forks_count":7,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-01-29T22:08:16.914Z","etag":null,"topics":["cm4","cm5","compute-module-4","compute-module-5","raspberry-pi-4","raspberry-pi-5","raspberrypi"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raspberrypi.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-30T15:51:36.000Z","updated_at":"2025-01-27T13:16:52.000Z","dependencies_parsed_at":"2024-11-20T13:41:54.550Z","dependency_job_id":"7ed050fb-c9a0-4240-8d7a-f9141e7abe69","html_url":"https://github.com/raspberrypi/rpi-sb-provisioner","commit_stats":{"total_commits":55,"total_committers":6,"mean_commits":9.166666666666666,"dds":"0.38181818181818183","last_synced_commit":"61150fadeb4e21cf4b32f9c2050f3e4d22e94c97"},"previous_names":["tdewey-rpi/rpi-sb-provisioner","raspberrypi/rpi-sb-provisioner"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raspberrypi%2Frpi-sb-provisioner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raspberrypi%2Frpi-sb-provisioner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raspberrypi%2Frpi-sb-provisioner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raspberrypi%2Frpi-sb-provisioner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raspberrypi","download_url":"https://codeload.github.com/raspberrypi/rpi-sb-provisioner/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237172211,"owners_count":19266632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cm4","cm5","compute-module-4","compute-module-5","raspberry-pi-4","raspberry-pi-5","raspberrypi"],"created_at":"2024-09-24T19:55:07.263Z","updated_at":"2025-10-19T16:32:50.511Z","avatar_url":"https://github.com/raspberrypi.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"= rpi-sb-provisioner\nProvisioning devices is the act of programming SD cards, NVMe or eMMC devices at manufacture time to put the device into a known and configured state.  For our embedded and industrial customers it is important that they can be sure that their signing keys are programmed correctly, boot security is enabled and the firmware stored in the EEPROM is set to a specific known value.\n\nSecure Boot typically refers to an authenticated boot chain, where from the moment the main processor starts every components authenticates the next component before allowing it to execute.\n\nIn order to simplify the mass deployment of secure boot for Raspberry Pi Devices, we have introduced a new tool, the Raspberry Pi Secure Boot Provisioner.\n\nThis tool, referred to later in the document as `rpi-sb-provisioner`, is designed to fully automate:\n\n* enforcing secure boot on Raspberry Pi devices\n* the programming of firmware\n* the programming of signing and device encryption keys\n* tying the device encryption key to the storage device\n* inserting a customer-supplied (created with `pi-gen`) operating system into an encrypted container on the storage device\n\nFor more information on creating an OS based on Raspberry Pi OS in `pi-gen`, consult the `pi-gen` repository at https://github.com/RPi-Distro/pi-gen\n\n**NOTE**: This tool is under active development. Please report issues at https://github.com/raspberrypi/rpi-sb-provisioner\n\n== Requirements for rpi-sb-provisioner\n\n=== Required hardware for the provisioning system\n\n* A Raspberry Pi 5 (or other 64-bit Raspberry Pi device)\n* An official Raspberry Pi 5 Power Supply\n* An installation of Raspberry Pi OS Bookworm, or later\n* At least 32GB of storage, for temporary working files\n* For provisoning Raspberry Pi Compute Module 4:\n** A USB-A to microUSB-B cable\n** A Raspberry Pi Compute Module 4 IO Board\n** A single Jumper Wire\n* For provisioning Raspberry Pi 5:\n** A USB-A to USB-C cable\n\n=== Hardware configuration\n\nConnect your Raspberry Pi 5 to your Raspberry Pi Compute Module 4 IO Board as illustrated. Grey cables supply power, Red supplies data.\n\n[pdfwidth=90%]\n.A correctly connected provisioning set-up\nimage::docs/images/rpi-connection-cm4io.png[]\n\n=== Software configuration\n\n`rpi-sb-provisioner` is provided from the Raspberry Pi OS APT repositories, and can be installed in the usual manner.\n\nFirst, ensure you are running an up-to-date version of Raspberry Pi OS on your provisioning server:\n\n----\n$ sudo apt update \u0026\u0026 sudo apt full-upgrade -y\n----\n\nNow, install the `rpi-sb-provisioner` package from the releases area:\n\n----\n$ sudo dpkg -i rpi-sb-provisioner_foo.deb\n$ sudo apt --fix-broken install\n$ sudo reboot now\n----\n\nNext, you will have to configure `rpi-sb-provisioner` by using the TUI. In a terminal, run: \n\n----\n$ config.sh\n----\n\nWARNING: This will not work if you have not reboot after installing the package! \n\nWARNING: `rpi-sb-provisioner' must be installed with `--install-suggests' for `config.sh' to work. This will require installation of `python3-textual' and `python3-rich' from Debian's Trixie release.\n\nRunning this command will open up a full screen text UI. The TUI supports mouse input or keyboard navigation! \nEach of the boxes contains a name, text entry and help button. The steps for editing each parameter are as follows:\n\n[pdfwidth=90%]\n.A parameter entry area\nimage::docs/images/rpi-config-textfield.png[]\n\n\n*1 -* Click or use `tab` to click the help button to view the information about the parameter\n\n*2 -* Navigate to the text field and enter the value you wish\n\n*3 -* To stage this value for writing, you must click `return` on your keyboard. If the value is successfully verified, then the field will change color to green and a tick should appear. If validation fails, a warning popup should appear with some help text. A cross will also appear next to the parameter name.\n\n[pdfwidth=90%]\n.A successfully verified parameter\nimage::docs/images/rpi-config-successfully-verified.png[]\n\n\n*4 -* Repeat the above steps to complete your required parameters (some are optional).\n\n*5 -* Write to the configuration file by pressing the `Write verified params to config file` button at the bottom of the screen\n\nOnce you have followed all those steps, `rpi-sb-provisioner` should be correctly configured and ready to run.\n\n== Configuration fields\n\nConfigure `rpi-sb-provisioner` by using the following fields in `/etc/rpi-sb-provisioner/config`\n\n=== CUSTOMER_KEY_FILE_PEM\n*Optional, mandatory if CUSTOMER_KEY_PKCS11_NAME is not set*\n\nThe fully qualified path to your signing key, encoded in PEM format. This file is expected to contain an RSA 2048-bit Private Key.\n\nWARNING: This file should be considered key material, and should be protected while at rest and in use according to your threat model.\n\n=== CUSTOMER_KEY_PKCS11_NAME\n*Optional, mandatory if CUSTOMER_KEY_FILE_PEM is not set*\n\nThe keypair alias for a PKCS11 keypair, typically stored on a Hardware Security Module (HSM) and provided through a helper tool. This is expected to act in place of the RSA 2048-bit Private key specified with CUSTOMER_KEY_FILE_PEM, and will be used as the signing device for all future pre-boot authentication images.\n\nThe value should take the format:\n\n----\n\"pkcs11:object=\u003ckeypair-alias\u003e;type=private\"\n----\n\nWARNING: You must use double quotes to enclose the value.\n\nWARNING: The PKCS11 provider, and it's associated HSM, should be considered key material and should be protected while at rest and in use according to your threat model.\n\n=== GOLD_MASTER_OS_FILE\n*Mandatory*\n\nThis should be your 'gold master' OS image. No customisation should be present in this image that you would not expect to be deployed to your entire fleet. `rpi-sb-provisioner` assumes this image has been created using `pi-gen`, and using a non-`pi-gen` image may produce undefined behaviour.\n\n=== RPI_DEVICE_STORAGE_TYPE\n*Mandatory*\n\nSpecify the kind of storage your target will use. Supported values are `sd`, `emmc`, `nvme`.\n\n=== RPI_DEVICE_FAMILY\n*Mandatory*\n\nSpecify the family of Raspberry Pi device you are provisioning. Supported values are `4, 5`. For example,\n\nA Raspberry Pi Compute Module 4 would be family `4`\nA Raspberry Pi 5 would be family `5`\n\n=== RPI_DEVICE_BOOTLOADER_CONFIG_FILE\n*Mandatory, with a default*\n\nWARNING: `rpi-sb-provisioner` will ignore the Raspberry Pi Bootloader configuration built by `pi-gen`, and use the one provided in this variable.\n\nSpecify the Raspberry Pi Bootloader configuration you want your provisioned devices to use. A default is provided.\n\nFurther information on the format of this configuration file can be found in the Raspberry Pi Documentation, at https://www.raspberrypi.com/documentation/computers/config_txt.html\n\n=== RPI_DEVICE_LOCK_JTAG\n*Optional*\n\nRaspberry Pi devices have a mechanism to restrict JTAG access to the device.\n\nNote that using this function will prevent Raspberry Pi engineers from being able to assist in debugging your device, should you request assitance.\n\nSet to any value to enable the JTAG restrictions.\n\n=== RPI_DEVICE_EEPROM_WP_SET\n*Optional*\n\nRaspberry Pi devices that use an EEPROM as part of their boot flow can configure that EEPROM to enable write protection - preventing modification.\n\nSet to any value to enable EEPROM write protection.\n\n=== RPI_DEVICE_FETCH_METADATA\n*Optional*\n\nCollect manufacturing data from each device that is provisioned. This will include the board type, board revision number, the processor name, the memory configuration, and the factory where the board was made.\n\nThe metadata is inserted into the log for the device, and also as a serial-number named JSON file under the `metadata` subdirectory of the device provisioning logs.\n\nSet to any value to enable metadata collection.\n\n=== RPI_SB_WORKDIR\n*Optional*\n\nWARNING: If you do not set this variable, your modified OS intermediates will not be stored, and will be unavailable for inspection.\n\nSet to a location to cache OS assets between provisioning sessions. Recommended for use in production. For example:\n\n----\nRPI_SB_WORKDIR=/srv/rpi-sb-provisioner/\n----\n\n=== DEMO_MODE_ONLY\n*Optional*\n\nSet to `1` to allow the service to run without actually writing keys or OS images. You may, for example, use `DEMO_MODE_ONLY` in combination with `RPI_SB_WORKDIR` to inspect the modifications `rpi-sb-provisioner` would make to your OS ahead of deployment.\n\n== Using rpi-sb-provisioner\n`rpi-sb-provisioner` is composed of three `systemd` services that are triggered by the connection of a device in RPIBoot mode to a USB port. With `rpi-sb-provisioner` configured to your requirements, all that is therefore required is to connect your target Raspberry Pi device in RPIBoot mode.\n\nFor Raspberry Pi Compute Module 4 on Raspberry Pi Compute Module 4 IO Board, you can do this by using the single jumper wire to connect the `disable eMMC Boot` pins on the 12-pin header at the top of the board\n\n[pdfwidth=90%]\n.Force your Compute Module into RPIBoot mode by connecting the 'disable eMMC Boot' pins\nimage::docs/images/rpi-cm4io-detail.png[]\n\nAfter connecting your device in RPIBoot mode, `rpi-sb-provisioner` will perform the following steps:\n\n* A new device connection is recognised over USB, and enters the *triage* phase:\n** If your device has not been recorded as having been provisioned, start the *provisioner*\n** If the device has been recorded as having been provisioned, cease further actions\n* In the *provisioner* phase:\n** Your device will boot a specialised Raspberry Pi firmware, designed to write a hash of your public signing key (generated from the file pointed to by `CUSTOMER_KEY_FILE_PEM`) into device One Time Programmable (OTP) memory\n** Your device will be updated to Raspberry Pi EEPROM software released on 2024-05-17\n** Your device will perform a silent reboot\n** `rpi-sb-provisioner` will boot your device with a specialised Linux distribution designed to:\n*** create a device unique key\n*** partition and format your device's storage\n*** create a LUKSv2 container\n*** place your OS into the LUKSv2 container\n*** place a customised pre-boot authentication firmware (derived from your gold master OS image) into the 'boot' partition of your device's storage\n\nAfter these steps have been completed, your device should display both the `activity` and `power` LEDs as `off`. If you have ethernet connected, you may still see activity from this port. In this state, your device is safe to power off and package into your product.\n\nNo further intervention is required in the success case.\n\nWARNING: `rpi-sb-provisioner` will not, by default, block JTAG access. If you wish to make use of this facility, you _must_ specify this in the Raspberry Pi Bootloader configuration pointed to by `RPI_DEVICE_BOOTLOADER_CONFIG_FILE`\n\n=== Monitoring via the monitoring application\n\nWARNING: `rpi-sb-provisioner' must be installed with `--install-suggests' for `monitor.sh' to work. This will require installation of `python3-textual' and `python3-rich' from Debian's Trixie release.\n\n`rpi-sb-provisioner` also contains a monitoring application. This can be used to observe the progress of a device as it is being provisioned. It also allows for easy introspection of the log files and lists all completed and failed devices.\nThe monitoring application supports both mouse or keyboard input. Navigation between boxes can be acheived by using the `tab` key or by clicking on the desired area.\n\nTo run, type into a terminal window:\n\n----\n$ monitor.sh\n----\n\nThe TUI will intialise with 2 rows, the top one showing the progress of a device throughout the process, with each of the columns being for devices in the following stages: triaging and provisoning.\nWhen a device is connected, you will be able to watch it progress through each of the sections.\nThe second row of the TUI also has two boxes at the bottom, the left being successfully completed provisions and the right for failed provisions.\nClicking on the device name will open up a second window, with buttons to view the log files for each step of the provisioning service.\nTo return to the main monitoring screen, just press the key `m`.\nTo quit the app use the key combination `CTRL-C` or `q`.\n\n== Debugging and audit\n\n=== Observing active provisioning operations\n\nAs `rpi-sb-provisioner` is implemented using `systemd` services, you can use the typical `systemctl` commands to observe the services as they provision your device.\n\nTo see active provisioning operations, and the serial numbers of the devices involved, type into a Terminal window:\n\n----\n$ systemctl list-units rpi-sb-provisioner*\n----\n\n=== Observing logs\n\nLogs are stored on a per-device, per-phase basis, where logs for a given device are stored at `/var/log/rpi-sb-provisioner/\u003cserial\u003e/\u003cphase\u003e.log`.\n\nFor example, to observe the progress of an individual device through a phase, you could use `tail`:\n\n----\n$ tail -f -n 100 /var/log/rpi-sb-provisioner/\u003cserial\u003e/provisioner.log\n$ tail -f -n 100 /var/log/rpi-sb-provisioner/\u003cserial\u003e/triage.log\n----\n\n=== Identifying secured devices\n\nA 'secured device' is one where your customer signing key has been written - regardless of the state of your OS or other software. Such devices can only load Linux images signed by your customer signing key.\n\nObtain this by inspecting the rpi-sb-provisioner logs:\n\n----\ngrep -R /var/log/rpi-sb-provisioner/ --include=\"progress\" -e \"PROVISIONER-FINISHED\" | tail -n 1 | cut -d '/' -f 5\n----\n\n=== Inspecting the image to be flashed\n\nWhen run with `DEMO_MODE_ONLY=1`, `rpi-sb-provisioner` will only prepare images to be provisioned - allowing you to inspect the OS images prior to mass deployment.\n\nWARNING: You must set `RPI_SB_WORKDIR` in the configuration file to observe the modified image. If you do not set `RPI_SB_WORKDIR`, the intermediates will be deleted at the completion of the run.\n\nWith both variables set, connect a device to be demo-provisioned per the provisoning instructions above.\n\nThe images will be located in the directory pointed to by `RPI_SB_WORKDIR`.\n\nWARNING: Remember to unset `DEMO_MODE_ONLY` before moving to mass deployment.\n\n=== Debugging unexpected results\n\nThe first stage of debugging unexpected results is to delete the contents of the directory pointed to by `RPI_SB_WORKDIR`, which will force any intermediate OS images to be deleted.\n\n----\n$ sudo rm ${RPI_SB_WORKDIR}/*\n----\n\nThe second stage is to remove the progress file matching the serial number of the device you are debugging:\n\n----\n$ sudo rm /var/log/rpi-sb-provisioner/\u003cserial\u003e/progress\n----\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraspberrypi%2Frpi-sb-provisioner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraspberrypi%2Frpi-sb-provisioner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraspberrypi%2Frpi-sb-provisioner/lists"}