Configuring Update client on the device

Update client requires some configuration on a device. This falls into two categories:

• Unique identifiers for the device type.
• The certificate used to authenticate updates.

These identifiers are publicly accessible and do not constitute an identity in themselves.

Tip: Follow our device identifiers tutorial to set up your device.

There are also advanced configuration options depending on your device requirements.

Getting started: using the Mbed development tools

The fastest way to get started with Update is to use the Mbed development tools. They integrate with the manifest tool and the update APIs and rely on Mbed OS and its bootloader, as well as Device Management Update client. Please see:

• A quick connect guide for the Online Compiler.
• A review of the Mbed CLI commands.

The first step to using Device Management Update is to prepare your devices to receive updates.

If your device is a supported reference device, you can use the client software and bootloader from the Git repositories together with the example application code to create suitable images for the device.

If your device is not one of the supported reference devices, you must first port the Device Management Client to the device.

In addition to the appropriate firmware image and bootloader, you need an authentication certificate. For development purposes, you can use the manifest tool to generate developer certificates using a private key that you provide. These development certificates are not suitable for commercial deployments. You should only use them during development and prototyping.

You also need to assign some metadata for the devices to identify themselves. This is in the form of a manufacturer ID and a device class ID. You use these unique identifiers to identify the manufacturer of the device and whether a firmware image is suitable for the device.

Development tools

To use Device Management Update client, you need:

• Required tools and accounts.
• The manifest tool installed on the developer's computer.

Unique identifiers

You can use the following identifiers for compatibility checking:

• The unique identifiers: Vendor ID.
• Device class ID.

We recommend RFC-4122 Type 5 UUIDs for these values.

Authenticity certificate

Update client requires the verification certificate and its fingerprint for authorizing updates. The verification certificate and its fingerprint are stored as a certificate with the fingerprint as the key.

The authenticity certificate is a container for a public key that the device trusts. This public key's use is restricted to Device Management Update to compartmentalize and protect Device Management Update in case information about any other key is leaked.

The update authenticity certificate allows the device to verify the authenticity of update manifests. You can also use it to delegate the trust tthe device has in the authenticity certificate from this ultimate source of trust to another trusted party.

Generating authenticity certificates

The manifest tool can generate certificates for use in development, but you should not use these generated certificates in a production environment. You should generate certificates for production in accordance with good security practices and use secure processes and HSM hardware when possible.

Advanced Update client configuration

Check the documentation on advanced Update client configuration options if the default values are not suitable for your device(s).

Verifying update manifests

Before accepting an update, the device's Update client uses public key cryptography to decide whether it trusts the update's author: It verifies the update's manifest using its public key signature (ECDSA with the secp256r1 curve). To trust manifests, the device must therefore trust the public key that it uses to verify the signature. This requires installing the public key on the device at the time of manufacture, or in the initially flashed firmware. The device can then make a judgement about whether or not to trust a given manifest based on its trust of the key used to verify the manifest.

Update client expects the public keys to be packaged in a certificate; Update client and the manifest tool use DER certificates.

Ultimate source of trust

For enhanced security, public keys should be changed from time to time. To do this, the device needs an ultimate source of trust, typically another public key. This public key corresponds to a high security system used to delegate trust to an intermediary.

For example:

1. A company uses a hardware security module (HSM) to sign developer certificates. The HSM is far more secure than a developer's computer, so there is less concern that it will be compromised.
2. The developers in possession of the HSM-signed certificate can then sign manifests using their private key.
3. The device receives the developer certificate without security concerns because the devices trust the authority of the HSM.

This scheme allows a signer to be someone other than the holder of the public key that the device trusts.

Production devices should use this scheme to ensure updates are protected from the exposure of developers' private keys.

Update client does not contain an example of trust delegation. You can implement it by replacing the default arm_uc_registered_certificate_api. To create a certificate for testing purposes, a self-signed certificate is adequate.

Installing device identifiers and the authenticity certificate

You can install the device identifiers and the authenticity certificate in one of two ways:

• Encoded in update_default_resources.c in developer mode. Please see the Update tutorials for more information.
• Installed during the factory process. Please see the Provisioning documentation for more details.

Update storage in the Update client

To store the update image, the Update client uses block device storage (external SD card) with a root of trust generated using a Software One Time Programmed (SOTP) number. Alternatively, you can use your own root of trust by generating it from hardware root of trust functions.

You must make sure the bootloader has been compiled to use block device storage.

There are reference Update clients and compatible bootloaders for a number of platforms available from the Update client and bootloader repositories.

Note: If you are using an Update client version 1.2 or earlier, note that the Update storage option has been changed from a FAT file system to block device. Although Update client 1.3 (or later) continues to work with an old bootloader, the FAT file system is no longer supported in later versions of bootloader (3.0 onward). We recommend you migrate to block device storage, so you can use an optimized and more secure bootloader.

Developing for a non-reference device

When integrating Device Management Client onto a new device or variant of a supported device, you must meet additional requirements before you use the Device Management Update feature.

Device requirements

To receive firmware updates, a device must have an implementation of the Platform Abstraction Layer (PAL) that contains:

• Device Management Client running on the device.
• Storage region definitions:
  • Bootloader to run instead of the regular Mbed OS application.
  • User application.
  • One or more locations for storing new firmware images before you apply them. These can be on external storage.
  • For details on porting Device Management Client, please see the Porting section.

For bootloader porting, please see the reference bootloader.