rpi-sb-provisioner

Automated provisioning of secure boot and encryption for Raspberry Pi devices

What is "provisioning"?

Provisioning means preparing a device for use. Think of it like setting up a new mobile phone:

• Installing the operating system

• Configuring security settings

• Making sure everything is ready to work

This tool does all of that automatically for Raspberry Pi devices.

What Problem Does This Solve?

Imagine you need to prepare 100 Raspberry Pi devices for your business.

Each device needs:

• A secure boot system (so only your software can run on it)

• Encrypted storage (so your data is protected)

• Your custom operating system installed

• Security keys programmed correctly

Without this tool, preparing each device manually is time-consuming and error-prone. Each command must be executed precisely. A single mistake requires restarting the entire process.

This tool automates the entire provisioning workflow. Connect a device, and the tool handles all configuration steps automatically. Typical provisioning time is approximately 3 minutes per device (for a 2.6GB OS image).

Who Should Use This Tool?

This tool is designed for:

• Businesses building products with Raspberry Pi devices

• Manufacturers producing devices at scale

• System integrators deploying secure systems

• Anyone who needs to prepare multiple Raspberry Pi devices with security features

This tool does not require security expertise to operate. Knowledge of encryption algorithms or boot chain implementation is not necessary. The tool handles cryptographic operations and security configuration automatically.

What You Get

When you use this tool, each device you prepare will have:

1. Secure Boot Protection

Your device will only execute software that has been cryptographically signed with your private key. This prevents unauthorized software from running on the device. The secure boot chain verifies each component before execution, from bootloader through to operating system.

2. Encrypted Storage

All data on the device storage is encrypted using full-disk encryption. If the storage media is removed or stolen, the data remains protected. Each device uses a unique encryption key tied to the device hardware, preventing storage from being read on other systems.

3. Your Operating System

The tool automatically deploys your custom Raspberry Pi operating system to each device. You create a single master image, and the tool replicates it to all provisioned devices with appropriate security modifications.

Traditional uncompressed .img files and IDP (Image Description Provisioning) artefacts produced by rpi-image-gen are both supported. IDP artefacts carry their partition layout, encryption and storage metadata in the image descriptor, so the WebUI can derive those settings from the selected image.

4. Manufacturing Records

The tool can maintain a manufacturing database recording details about each provisioned device. This includes serial numbers, MAC addresses, provisioning timestamps, and security configuration. This data supports inventory tracking, warranty management, and customer support operations.

5. Consistent Configuration

Every device receives identical configuration, eliminating human error and configuration drift. This ensures consistent behavior across your device fleet and simplifies technical support operations.

Three Levels of Security

This tool offers three modes of operation. Choose the one that fits your needs:

Mode	What It Does	When To Use It
secure-boot	Full security: secure boot + encrypted storage + device-unique keys	Production devices that need maximum security
fde-only	Encrypted storage + device-unique keys (no secure boot)	When you need encryption but not secure boot restrictions
naked	Just installs your operating system (no encryption, no secure boot)	Development devices or when security is not required

NOTE: This tool is under active development. Please report issues at

Supported Devices

This tool can prepare these Raspberry Pi devices:

• Raspberry Pi 5

• Raspberry Pi 4

• Raspberry Pi Compute Module 5

• Raspberry Pi Compute Module 4

• Raspberry Pi Zero 2 W

For specific connection instructions for each device type, see the Device Connection Guide below.

What You Need

The Provisioning Computer

This is the computer that runs the provisioning tool. You need:

• One Raspberry Pi 5 (or another 64-bit Raspberry Pi device)

• Power supply: Official Raspberry Pi 27W USB C power supply

• Operating system: Raspberry Pi OS Bookworm or newer

• Storage: At least 32GB free space (for temporary files)

This computer stays on your desk. You connect devices to it for provisioning.

Cables and Accessories

What cables you need depends on which devices you want to prepare:

Device You Want To Prepare	What You Need
Raspberry Pi 5	USB A to USB C cable
Raspberry Pi 4	USB A to USB C cable
Raspberry Pi Compute Module 4	• USB A to microUSB B cable
• Compute Module 4 IO Board
• One jumper wire
Raspberry Pi Compute Module 5	• USB A to USB C cable
• Compute Module 5 IO Board
• One jumper wire
Raspberry Pi Zero 2 W	• USB A to microUSB B cable

Connecting the Hardware

For Compute Module 4 or 5 devices:

Connect your provisioning Raspberry Pi to the Compute Module IO Board as shown in this image:

A correctly connected provisioning system

Tip

When the provisioning host and the target IO board are on the same Ethernet network (for example, a CM5 host provisioning a CM4 on its IO board), image transfer can use the fastboot TCP data plane and is typically much faster than USB alone. USB is still required for control-plane commands.

Important

Do not connect other USB devices to the Compute Module IO board during provisioning. The provisioning Raspberry Pi can only supply 900mA of power to the connected device.

For other device types, see the Device Connection Guide below.

Getting Started

Step 1: Install the Software

First, update your provisioning Raspberry Pi to the latest software:

sudo apt update && sudo apt full-upgrade -y

Then install this tool:

sudo apt install -y rpi-sb-provisioner

Step 2: Open the Web Interface

This tool has a simple web interface for configuration. Open it in your browser:

xdg-open http://localhost:3142

You will see a web page with several tabs. Click the Options tab to configure your provisioning settings.

Step 3: Configure Options

Click the Options tab.

You need to set these options:

• Security mode: Choose secure-boot, fde-only, or naked (see Three Levels of Security above)

• Device family: Which Raspberry Pi devices are you preparing? (4, 5, 2W)

• Storage type: Are your devices using SD cards, eMMC, or NVMe? Choose one: sd, emmc, or nvme

• Signing key: For secure boot mode, you need a signing key. The Options page maintains a saved-key registry so you can store multiple PEM and PKCS#11 keys, validate each one, and choose which key is active for provisioning.

• OS Image: Upload a "master" operating system image. For traditional provisioning this is an uncompressed .img file, typically created with pi-gen (see ). You can also upload an IDP artefact archive (.tar.xz, .tar.zst, .tar.gz, .tgz or .zip) produced by rpi-image-gen; the WebUI extracts it and uses its metadata to configure the device family, storage type and encryption settings.

• Device firmware: Select the firmware version to use for your devices

The web interface includes help text for each option. Read it carefully.

For complete details about all configuration options, see the Configuration Reference.

Step 4: Start Provisioning

Configuration is now complete.

The system is ready to provision devices. See the next section for connection instructions.

How To Prepare Devices

Overview

Once configured, the provisioning process is:

1. Connect the device to your provisioning computer

2. Monitor progress (all operations are automatic)

3. Disconnect the device when both LEDs turn off

4. The device is ready for deployment

Typical provisioning time is approximately 3 minutes per device (for a 2.6GB OS image). Progress can be monitored through the web interface.

Connecting Your Device

The way you connect devices depends on the device type.

For Compute Module 4 or Compute Module 5

1. Place the Compute Module into the IO Board

2. Use the jumper wire to connect the two disable eMMC Boot pins (see image below)

3. Connect the IO Board to your provisioning computer with the USB cable

4. The provisioning process starts automatically

Use a jumper wire to connect the 'disable eMMC Boot' pins

For Raspberry Pi 5

Raspberry Pi 5 requires a special button-press procedure:

1. Hold down the power button on the Raspberry Pi 5

2. While holding the button, plug in the USB C cable to your provisioning computer

3. Keep holding the button until the device is recognized

4. The provisioning process starts automatically

For detailed instructions, see: Raspberry Pi 5 Connection Guide

For Raspberry Pi 4

See the detailed guide: Raspberry Pi 4 Connection Guide

For Raspberry Pi Zero 2 W

See the detailed guide: Raspberry Pi Zero 2 W Connection Guide

What Happens During Provisioning

The tool works in three automatic phases:

Phase 1: Bootstrap

• Device connection is recognized

• For secure boot mode: Signing key hash is programmed into device OTP memory (permanent operation)

• Device firmware is updated to the specified version

• Temporary Linux environment is loaded onto the device

Phase 2: Triage

• Selected security mode is determined from configuration

• The device unique secret is provisioned and locked if needed. This hardware-held device identity is used by encrypted-root unlock and Raspberry Pi Connect registration.

• Appropriate provisioning service is started

Phase 3: Provisioning

Operations performed depend on the selected security mode:

• IDP artefact selected:

  • Reads the image descriptor and sparse image files produced by rpi-image-gen

  • Uses the device-side IDP fastboot protocol to create partitions, encryption metadata and flash sparse images

  • For secure-boot IDP images, signs the boot slots and prepares the signed boot chain

• secure-boot mode:

  • Creates a unique encryption key for this device

  • Formats the storage device

  • Creates an encrypted container

  • Installs your operating system into the encrypted container

  • Installs signed boot firmware

• fde-only mode:

  • Creates a unique encryption key for this device

  • Formats the storage device

  • Creates an encrypted container

  • Installs your operating system into the encrypted container

  • Installs boot firmware (not signed)

• naked mode:

  • Formats the storage device

  • Installs your operating system directly

When Is The Device Ready?

Provisioning is complete when both the power LED and activity LED are off.

If an Ethernet cable is connected, network activity may still be visible. This is expected behavior.

When both LEDs are off, you may:

• Disconnect the device from power

• Remove the device

• Deploy the device in your product

No