Manufacturing Process for Device Registration

Device registration is important in ensuring that only trusted and authorized devices can connect to the Foundries.io™ infrastructure. lmp-device-auto-register works well manually, and can be configured to auto register devices in CI builds. However, a different process is required for provisioning production devices. The key to production provisioning lies in owning the device gateway PKI.

The device gateway PKI serves as the trust anchor for all device communications. A device presents a TLS certificate when it tries to connect to the Foundries.io gateway. With control of your PKI, you can create client TLS certificates that will be trusted by the Foundries.io device gateway.

Everyone will have unique requirements, so Foundries.io created a reference implementation that you can fork and modify to your liking. Using this example, you can authenticate and register devices, granting them the necessary certificates to be trusted by the Foundries.io gateway. This page covers some common ways to use this reference.

Fully Detached

In this scenario, devices connect to a reference server instance on a private network. This network is isolated from the internet (api.foundries.io). Devices get a valid signed client certificate from the reference server. Each device will be created on-the-fly via api.foundries.io the first time they connect.

This is handy for certain security constrained setups. However, it does have a couple caveats:

Devices do not show up on Foundries.io until they connect the first time.

Devices will not have Foundries.io managed configuration data available until this first connection.

Note

Because devices are created on-the-fly, the backend maintains a deny-list for device UUIDs that get deleted. This can lead to confusion when trying to re-use a denied UUID in a Factory using HSMs. The standard lmp-device-register flow with the Foundries.io backend will remove the denied device. However, in the “fully detached” scenario, you will need to manage the deny list yourself. The deny list can be managed with:

fioctl devices list-denied

fioctl devices delete-denied

Registering Production Device by Default

After the development cycle, when every device to be registered is a production device, it may be good to enable this by default in LmP.

Create or modify the lmp-device-register_%.bbappend file in the Factory’s meta-subscriber-overrides:

mkdir -p meta-subscriber-overrides/recipes-sota/lmp-device-register/
echo 'PACKAGECONFIG += "production"' >> meta-subscriber-overrides/recipes-sota/lmp-device-register/lmp-device-register_%.bbappend

Images created with this configuration include PRODUCTION=on for the command lmp-device-register.

This is useful when the update plan is to use Production Targets.

`lmp-device-auto-register` Configuration

Devices can also have Auto Register enabled. This is needed in order for a device to automatically run lmp-device-register on boot.

Copy lmp-device-auto-register into your Factory’s meta-subscriber-overrides.git production branch as: recipes-support/lmp-device-auto-register/lmp-device-auto-register/lmp-device-auto-register. Add the following two environment variables at the top of the file:

#!/bin/sh -e

TOKEN_FILE=${TOKEN_FILE-/etc/lmp-device-register-token}

DEVICE_API=http://<IP of reference server>/sign
PRODUCTION=1

...

It will now use the reference server to register, instead of https://api.foundries.io.

Registration Reference Configuration

The registration reference should work out-of-the box for this scenario. You only need to copy you PKI keys as described in the reference server’s README.md.

Partially Detached

In this scenario, devices connect to a reference server instance on a private network. However, this time the reference server has access to api.foundries.io. The reference server can create device entries via api.foundries.io as devices are registered.

Additionally, if devices have access to ota-lite.foundries.io:8443, they can download their initial fioconfig data.

Partially Detached `lmp-device-auto-register` Configuration

A factory can also customize lmp-device-auto-register as is explained in Auto Register.

For example:

#!/bin/sh -e

if [ -f /var/sota/sql.db ] ; then
       echo "$0: ERROR: Device appears to already be registered"
       exit 1
fi

# Done in 2 parts. This first part will remove trailing \n's and make
# the output all space separated. The 2nd part makes it comma separated.
[ -d /var/sota/compose-apps ] && APPS=$(ls /var/sota/compose-apps)
APPS=$(echo ${APPS} | tr ' ' ',')
if [ -n "${APPS}" ] ; then
       echo "$0: Registering with default apps = ${APPS}"
       APPS="-a ${APPS}"
else
       echo "$0: Registering with all available apps"
fi

# Register the device but don't start the daemon:
DEVICE_API="http://example.com/sign" \
PRODUCTION=1 \
       /usr/bin/lmp-device-register --start-daemon=0 -T na ${APPS}

# Pull down the device's initial configuration
fioconfig check-in

# Optionally start services, or maybe just power off the device
#systemctl start aktualizr-lite
#systemctl start fioconfig

Partially Detached Registration Reference Configuration

The registration reference should work out-of-the box for this scenario. The operator will need to create a Foundries.io API token with scope devices:create. They can take this token and configure the reference server as per the README.md.