5. Design overview

The document A Firmware Update Architecture for Internet of Things [SUIT-ARCH] describes an example flow and the expected device side actions:

  • Query image information

  • Validate image metadata

  • Store image

  • Verify image

  • Trigger reboot

The design of the interface offers functions for these actions. The interface contains three major classes of error codes: storage errors, security errors, and dependency errors. The caller must be prepared to handle these.

The interface is expected to be provided by an implementation that runs in the NSPE. However, it may be necessary to protect certain functions using the SPE on some platforms.

5.1. Mandatory functions

The interface supports these actions using the following calls.

5.1.1. Querying installed images

The caller calls psa_fwu_query to fetch information about firmware images on the device. This includes state for installed images, rejected images, and candidate images. This information is expected to be passed to a remote operator or status tracker. A local Update client may also use this information to make a local decision. For example, the data may be used to avoid fetching images unnecessarily if they are already on the device.

To satisfy Section 2.1, the query function uses an iterator to minimize memory footprint. The caller may relay this information to a remote status tracker. Eventually, new firmware is downloaded to the device by the caller.

Each image has its own local identifier that represents the type of image. This is known as an image ID. Queries are based on an image ID.

The image ID of each updatable image can be discovered using the provided iterator functions. The query function returns global identification information about the image, such as the associated Vendor ID, Class ID, and the hash of the public signing key.

5.1.2. Image storing

Each image has its own image ID that represents the type of image. Each image has its own staging area. The image ID is used by the implementation to determine the appropriate staging area.

The caller uses psa_fwu_write to write a candidate image to its staging area. To satisfy Section 2.1 the caller can use this operation to write an image incrementally in blocks. On a rich device with plenty of memory, the caller uses this as a single-part function. A number of errors can be detected and returned by this call, and can depend on the qualities of the implementation.

A staging area can be erased using psa_fwu_abort.

5.1.3. Metadata storage

If the image does not embed metadata, then a standalone metadata object can be associated with the same image by calling psa_fwu_set_manifest with the same image ID.

5.1.4. Verify image

The caller finishes the firmware update process with psa_fwu_install.

On success, the implementation checks any necessary preconditions and prepares installation.

On some implementations, this will starts an integrity check on the firmware image based on the metadata. On other implementations, the validation of the metadata is deferred to the bootloader when the platform next resets.

The implementation indicates whether a reboot is required to complete installation by using a return value.

The implementation indicates whether a dependency is missing by using a set of output parameters.

If a dependency is missing, the dependency is specified in two output parameters, the image ID of the missing image and the required version. The caller then fetches the required image and repeats the process.

5.1.5. Triggering a reboot

If a reboot is required to complete the firmware update process then the caller uses psa_fwu_request_reboot to restart the platform. The caller chooses when is an appropriate time to reboot the platform.

5.2. Optional functions

The following image management functions must be implemented if a PENDING_INSTALL state is supported:

  • A function, psa_fwu_request_rollback, is provided for application firmware to request the device to roll back the recently applied updates. This is for scenarios where the newly updated firmware detects a fatal problem with the update. The implementation may deny this request if this is prevented by security policy (e.g. rollback protection). An implementation can also choose not to support this.

  • A function, psa_fwu_accept, is provided for application firmware to indicate whether the recently applied updates are working correctly. This is for scenarios where the newly installed firmware must be tested before it is permanently installed. An example of a test is a built in self-test.

5.3. State transitions for an image

The permitted state transitions are shown in the following diagram:

Permitted state transitions for an image

Figure 1 Permitted state transitions for an image using the API.

Every firmware update image begins in the CANDIDATE state. All successful firmware update images reach the INSTALLED state.

The state of an image can be queried using psa_fwu_query.

5.4. Dependencies

An image can have a dependency on another image. When an image has a dependency it cannot be installed until all of its dependencies are satisfied. This means that all images must be written prior to calling psa_fwu_install. Dependencies are described within image metadata.

If a dependency is not explicit then the implementation is not guaranteed to detect compatibility issues. For instance, if an installation contains two images, A and B, and A depends on B, then the system will not be able to detect incompatibilities if B is upgraded in isolation. If mutual dependency is required, then A should specify a dependency on B and B should specify a dependency on A.

A dependency consists of an image ID and version.