Signing your own image - Edge Computing Gateway

Signing your own image - Edge Computing Gateway

At a glance

Sign on your PC, let the device trust your package key, install, log in. Keep your keys: without them, no more upgrades.

1
Create your keys
Four files on your PC. Keep offline copies.
2
Sign the image
One command, a few minutes.
3
Import your package key
So the device checks your signature.
4
Install and restart
The device locks to your key on this start.
5
Log in at once
With the factory login, then restore your settings.

From RobustOS Pro 2.5.0, you can sign the system image with your own keys and lock the device to them. The first time the device starts an image that carries your key, it records that key permanently. From then on it starts only system images signed with your key, and refuses Robustel's factory image.

Three things to know before you start: it is permanent, you must keep your keys (without them the device can never be upgraded again), and the first installation resets the device to its factory configuration.

The one rule
Sign on your own PC, keep offline copies of your four key files, and keep the device's factory login at hand before you install.

What your key controls

Your key decides which system image the device starts. The rest of the chain is unchanged.

System image
Starts only if signed with your key. Robustel's factory image is refused.
Your key
Bootloader and kernel
Signed by Robustel, as on every RobustOS Pro device.
Robustel
Robustel-signed update packages
Still accepted, as before enrolment.
Accepted
Developer mode
Skips the signature check on every package while it is on.
Keep it off
The Dashboard shows the state: System Information → Customer Image Signing, Not Enrolled before, Key Enrolled after.
Part of the deviceAfter enrolment
System image (the operating system and Robustel software)Your key. The device starts only system images signed with it. Robustel's factory image, and images signed with any other key, are refused.
Bootloader and kernelSigned by Robustel, as on every RobustOS Pro device.
Update packages signed by RobustelStill accepted, as before enrolment.
Developer modeWhen it is on, the device skips the signature check on every package it installs. Keep it off.

The device shows the state on the Dashboard, under System Information → Customer Image Signing: Not Enrolled before, Key Enrolled after.

Before you start

Three things cannot be undone or skipped. Read them before the first installation.

Enrolment is permanent
The restart after the installation writes your key into the device. Install is the last point to stop.
One way
Keep your keys
Without your private keys the device can never be upgraded again. Two offline copies.
No recovery
The install resets the device
Factory configuration and login; the sudo user is removed. Export your configuration first.
Plan for it

The factory loginYour exported configuration fileA sudo user on the deviceThe signing tool, from Robustel supportThe factory firmware file, 2.5.0 or laterA PC with Ubuntu 22.04 (or WSL)

  • Enrolment is permanent. Installing the signed image is the last moment you can stop. On the restart that follows, the device writes your key into its one-time-programmable memory. No reset, factory restore or Robustel tool removes it.
  • Without your keys, no more upgrades. After enrolment the device accepts only images signed with your private keys. Keep all four key files in at least two offline places before the first installation.
  • The first installation resets the device. The device warns "All user data will be destroyed after the upgrade". Settings return to factory defaults, the login returns to the factory password, and the sudo user is removed. After the restart, the device restarts again about every two minutes until someone logs in to the Web UI.

What to have ready:

ItemWhy
The device's factory loginTo log in after the reset and stop the restarts
Your configuration file (System → Profile → Export Configuration File)The installation erases the configuration
A sudo user on the device (System → User Management)The commands in this guide run over SSH
The signing tool rbt-repack-firmware.shFrom Robustel support, on request
The factory firmware file for your model, 2.5.0 or laterThis is the image you sign
A PC with Ubuntu 22.04, natively or under WSL on WindowsSigning runs on your PC, never on the device

Prepare your PC

Ubuntu 22.04, natively or under WSL. Signing never runs on the device.

wsl --install -d Ubuntu-22.04
sudo apt-get install -y squashfs-tools xz-utils binutils gnupg openssl fakeroot pv coreutils dpkg-dev file libconfig-file-perl libdpkg-perl liblocale-gettext-perl
Give WSL 4 GB of memory. Signing rebuilds a system image of several hundred megabytes. dpkg-sig comes from the Debian 11 archive: see How-to.

Signing runs on Ubuntu 22.04: natively, or under WSL on Windows (wsl --install -d Ubuntu-22.04 in PowerShell as administrator). Give WSL at least 4 GB of memory: signing unpacks and rebuilds a system image of several hundred megabytes, and a busy PC can stop it partway.

Install the tools once: sudo apt-get install -y squashfs-tools xz-utils binutils gnupg openssl fakeroot pv coreutils dpkg-dev file libconfig-file-perl libdpkg-perl liblocale-gettext-perl. The signing tool also needs dpkg-sig, which Ubuntu no longer ships: install it from the Debian 11 archive (the How-to page has the three commands).

Work in your Linux home folder, for example ~/repack-work, not under /mnt/c/. Put the signing tool and the factory firmware file there, with a keys/ folder next to them.

Create your keys

Four files: one key pair for the package, one for the system image. Both pairs are always required.

Package key (GnuPG)
RSA 3072 or 4096, does not expire. gpg.pub and gpg.key.
System-image key (ECDSA P-256)
RSA is refused. sqfs-pub.key is the key the device locks to.
The one in the device
Copy the whole keys/ folder now to two offline places. Step by step: How-to.

You create four files: a key pair that signs the package, and a key pair that signs the system image. Both pairs are always required; there is no way to sign only the package.

FileWhat it isWhere it goes
keys/gpg.keyPackage-signing private keyYour PC and your offline backups only
keys/gpg.pubIts public keyInto the image, and onto the device before you install
keys/sqfs-priv.keySystem-image private keyYour PC and your offline backups only
keys/sqfs-pub.keyIts public keyInto the image; this is the key the device locks to
  • Package key: a GnuPG key, RSA 3072 or 4096 bits, that does not expire (gpg --full-generate-key), exported to keys/gpg.pub and keys/gpg.key. If you give it a passphrase, GnuPG asks for it in its own box while you sign.
  • System-image key: ECDSA P-256 only; the device refuses RSA. Two openssl commands create it; the public file must be named sqfs-pub.key.

Copy the whole keys/ folder now to at least two offline places.

Sign the image

One command signs the system image and the package. It takes a few minutes.

sudo ./rbt-repack-firmware.sh --package <model>-firmware-<version>.bin --gpg-pub keys/gpg.pub --gpg-priv keys/gpg.key --sqfs-pub keys/sqfs-pub.key --sqfs-priv keys/sqfs-priv.key --version <your-version> --name <your-name>
Output: <model>-image-<your-name>_<base-version>_<your-version>_<date>.bin. Recording of a real run: How-to.

One command signs the image with both keys. It takes a few minutes and writes a new file next to the original:

<model>-image-<your-name>_<base-version>_<your-version>_<date>.bin

Your name and version label are your own (for example acme and v1.1); the device shows them in /etc/version-image. The tool adds your public keys, writes the version label, signs the system image with your system-image key and the package with your package key. Nothing else changes, unless you add your own files (--overlay) or Debian packages (--extra-debs).

Install it and enrol the device

Import your package key, install, restart, log in at once.

Import your key
The device trusts only Robustel's key until you do.
→
Install
Web UI: System → Update. Or sudo sysupgrade.
→
Restart
Your key is written on this start.
→
Log in at once
Factory login. Otherwise it restarts every two minutes.
sudo /usr/scripts/rbt_gpg_usr.sh action=import key_file=$HOME/gpg.pub
Do not switch developer mode on instead. It turns the check off rather than teaching the device your key. Do not use dpkg -i: it skips the check.

Let the device trust your package key first. A device trusts only Robustel's package key until you import yours. Copy gpg.pub to the device and import it; the key then appears as a file in /etc/upgrade-keys/customer.d/. Without it, the device refuses your image with "Signature Verification Failed! Origin of the package cannot be trusted." and deletes the uploaded file. Do not switch developer mode on instead: it turns the check off rather than teaching the device your key.

Then install. In the Web UI: System → Update, choose the signed file, click Install. After the upload the device asks "All user data will be destroyed after the upgrade. Continue?". That is the last point to stop; OK installs, and the device then offers to restart. Over SSH, sudo sysupgrade <file> checks and installs the same way in under a minute, without restarting: restart with sudo reboot when it reports success. Do not use dpkg -i: it does not run the signature check.

After the restart, log in at once. The device is back after about two minutes, with its factory configuration and factory login. Log in to the Web UI with the factory credentials as soon as the login page appears: until someone logs in, the device restarts again about every two minutes. Then re-create the sudo user (System → User Management, then the tick at the top right to save and apply) and import your configuration file (System → Profile).

Check the result

The Dashboard says Key Enrolled, and the device reports your version label.

cat /etc/version-image
  • Dashboard → System Information → Customer Image Signing reads Key Enrolled.
  • cat /etc/version-image shows your label, for example acme_2.5.0_v1.1_20261001.

Upgrading an enrolled device

Same four key files, same steps. Import your package key again first: each installation removes it.

Import before every upgrade
The reset after each installation removes the imported key.
Every time
Never the factory file
Robustel's factory image carries no key: the device cannot start it.
Refused
USB recovery
Not covered here. Contact Robustel support before using the USB tool on an enrolled device.
Ask support
ls /etc/upgrade-keys/customer.d

Sign each new firmware release with the same four key files and install it the same way. Import your package key again before every upgrade: each installation resets the device, and the reset removes the imported key. ls /etc/upgrade-keys/customer.d shows whether it is there.

Never install Robustel's factory firmware file on an enrolled device: it does not carry your key, and the device cannot start it. Recovering an enrolled device from USB is not covered here: contact Robustel support before you use the USB flashing tool on one.

Developer mode

It switches off the signature check for every package, and stays on until you switch it off.

sudo rbt-system-mgmt developer-mode state
sudo rbt-system-mgmt developer-mode disable

Developer mode switches off the signature check for every package the device installs. It stays on across restarts and upgrades until you switch it off. Check it with sudo rbt-system-mgmt developer-mode state and switch it off with sudo rbt-system-mgmt developer-mode disable.

What you wantWhere
The hardening checklist for productionSecuring Your Device
What each kind of update changesWhat an Update Changes
How to perform an updateUpdating Your Device
Backups and the configuration fileHow-To: Step by Step
Next · step 7 of 13What an update changes →What survives every operation, part by part.