3. Architecture

3.1. Concepts and terminology

This section describes important concepts and terminology used in the Firmware Update API specification.

Figure 3 identifies the main actors and agents involved in a typical firmware update scenario.


Figure 3 The Firmware Update API in context

3.1.1. Firmware image

A firmware image, or simply the “image”, is a binary that can contain the complete software of a device or a subset of it. A firmware image can consist of multiple images if the device contains more than one microcontroller. It can also be a compressed archive that contains code, configuration data, and even the entire file system. An image may consist of a differential update for performance reasons.

The terms “firmware image”, “firmware”, and “image” are used in this document and are interchangeable.

3.1.2. Manifest

A manifest contains metadata about the firmware image. The manifest is typically protected against modification using a signed hash of its contents, see Manifest verification.

Metadata that can be in a manifest includes the following:

  • The intended device, which might be a specific instance or class.

  • The intended device component.

  • The version or serial-number of the firmware image.

  • A digest of the image.

  • Information relating to rollback prevention, or other security policies.

  • Dependencies on other firmware images.

  • Hints or explicit instructions on how to decrypt, decompress or install an image.

  • Information on additional steps required to apply the update.

A manifest can be bundled within the firmware image, or detached from it.

3.1.3. Component

A component is a logical part of the device which needs a firmware image. Each firmware image is designed for exactly one component.

A component can have a one to one correspondence with a physical processor in the system, other mappings are possible:

  • A single physical processor might have multiple components. For example:

    • If the SPE and NSPE have separate firmware images, these are separate components.

    • If configuration data for the system can be updated independently, this is a separate component.

  • Multiple processors, or even the whole system, can have the firmware packaged together in a single firmware image. As a whole, this forms a single component in the context of the Firmware Update API.

3.1.4. Component identifier

The component identifier is a small numerical value, that precisely identifies the component within this device.

The identifier values are typically allocated by the device developer or integrator. A component identifier can be used within the manifest during the update process, or can be translated from another identification scheme via a mapping configured in the update client.

3.1.5. Firmware creator

A developer or integrator of the firmware for the device being updated.

The firmware creator is responsible for constructing firmware images and manifests for the device. For devices that implement a secure boot protocol, the firmware creator signs the manifest using a signing key associated with a trust anchor on the device. See Trust anchor.

In systems with multiple components, each component can have a different firmware creator.

3.1.6. Update server

A system within the operational network of the device that hosts firmware images and manages the rollout of updates to devices within that network.

3.1.7. Update client

The update client is a software component that obtains firmware images. For example, this can be downloaded from an update server, or accessed from an attached storages device. When it obtains an image, it transfers it to the update service using the interface described in this document.

The update client runs as part of the application firmware.

It can report device identity and installation state to a remote party, such as the update server. For example, the reported installation state can include the versions of installed images and error information of images that did not install successfully.

3.1.8. Update service

The update service is a software component that stores a firmware image in device memory, ready for installation. The update service implements the interface described in this document.

Depending on the system design, the installation process can be implemented within the update service, or it can be implemented within a bootloader or other system component.

3.1.9. Firmware store

The firmware store is the location where firmware images are stored. Conceptually the firmware store is shared between the update service and the bootloader. Both components share access to the firmware store to manage the firmware update process.

The Firmware Update API presents a separate firmware store for each component. Each component’s firmware store can have one or more images present. The state of the firmware store determines how those images are used, and what is required to proceed with a firmware update.

The staging area is a region within a firmware store used for a firmware image that is being transferred to the device. Once transfer is complete, the image in the staging area can be verified during installation.

3.1.10. Bootloader

A bootloader selects a firmware image to execute when a device boots. The bootloader can also implement the verification and installation process for a firmware update.

In a system that implements secure boot, the bootloader will always verify the authenticity of the firmware image prior to execution.

3.1.11. Trust anchor

A device contains one or more trust anchors. A trust anchor is used to check if an image, or its manifest, are signed by a signing authority that the device trusts.

Each trust anchor is pre-provisioned on the device. A trust anchor can be implemented in many ways, but typically takes the form of a public key or a certificate chain, depending on the complexity of the trust model.

The management and provisioning of trust anchors is not within the scope of this document.

3.2. Firmware image format

The Firmware Update API does not define the format for the firmware image and manifest. This is defined and documented by the implementation, so that a firmware creator can construct valid firmware images and manifests for the device.

The Firmware Update API assumes that manifests and firmware images passed to the update service conform to the format expected by the implementation. The implementation is responsible for verifying that data provided by the client represents a valid manifest or firmware image.

Examples of the firmware image and manifest design details that need to be provided by the implementation, include the following:

  • Whether the manifest is detached from, or bundled with, the firmware image.

  • The format and encoding of the manifest and firmware image.

  • The attributes provided by the manifest, and their impact on processing of the firmware image.

  • Support for encrypted, compressed, or delta firmware image.

  • Firmware image integrity and authentication data.

If firmware images must be signed — for example, for devices implementing secure boot — the device creator must enable the firmware creator to sign new firmware images in accordance with the device policy.

For some deployments, the firmware and manifest formats used by a device can be affected by the protocols used by the update server and update client to notify and transfer firmware updates. In other deployments, the update server and update client can have independent formats for describing firmware updates, to those used by the firmware creator and update service.

3.3. Deployment scenarios

There are different ways in which the Firmware Update API can be implemented, that apply to different system designs. The primary differences relate to the presence and location of trust boundaries within the system, in particular trust boundaries that protect a device Root of Trust.

The implementation architecture can affect the behavior of the Firmware Update API, particularly in regard to if, and when, a firmware update is verified.

These implementation architectures provide use cases for the design of the Firmware Update API.

3.3.1. Untrusted client

Figure 4 shows an implementation architecture for a system where the firmware store is fully protected by the Platform Root of Trust (PRoT).


Figure 4 Implementation architecture with an untrusted update client

In this architecture, part of the update service must run as a service within the PRoT, to query and update the firmware store. The update client accesses this service via an update service proxy library, which implements the Firmware Update API.

The Firmware Update API is designed for implementation across a security boundary, as used in this architecture. The interface between the update service proxy and the update service itself is implementation defined.

This architecture enables all of the firmware verification requirements to be fulfilled by the update service within the PRoT.

As the PRoT trusts the update service, but not the update client, this architecture is referred to as an untrusted client implementation.

3.3.2. Untrusted staging

Figure 5 shows an implementation architecture for a system where the active image is protected by the Platform Root of Trust (PRoT), but the staging area for a new firmware image is not protected from access by the update client.


Figure 5 Implementation architecture with an untrusted update service and staging

The staging area is accessible to untrusted components, so the bootloader cannot trust any verification done by the update service prior to system restart. The bootloader must do all firmware verification prior to completing installation of the firmware.

In this type of implementation, it is still beneficial for the update service to perform some verification of firmware updates: this can reduce the system impact of a malicious or accidental invalid update.

As the PRoT does not trust the staging, or the update service which writes to it, this architecture is referred to as an untrusted staging implementation.

3.3.3. Trusted client

Figure 6 shows an implementation architecture for a system where the update client application is within the system’s Root of Trust.


Figure 6 Implementation architecture with a trusted update client

In this architecture, it is permitted for verification of an update to happen in any component, including the update client itself. This approach can be suitable for highly constrained devices, and relies on the security provided by the protocol used between the update server and update client.


If the implementation assumes that manifests and firmware images provided by the client are valid, and carries out the preparation and installation without further verification, then the Firmware Update API is being used purely as a hardware abstraction layer (HAL) for the firmware store.

An implementation like this must clearly document this assumption to ensure update clients carry out sufficient verification of firmware manifests, firmware images, and firmware dependencies before calling the Firmware Update API.

This implementation architecture can also be used in a device that does not enforce a secure boot policy. For example, this can enable code reuse by using a single API for firmware update across devices that have different security requirements and policies. Although permitted by the Firmware Update API, this usage is not a focus for this specification.