About this document

Release information

The change history table lists the changes that have been made to this document.

Table 1 Document revision history





Feb 2021

0.7 Beta 0


First release at Beta quality.

October 2022

1.0 Beta 0


Major update of programming model and API.

Relicensed as open source under CC BY-SA 4.0.

August 2023



Finalize API for version 1.0.

Include Security Risk Assessment.

For a detailed list of changes, see Document change history.

PSA Certified Firmware Update API

Copyright © 2020-2023 Arm Limited and/or its affiliates. The copyright statement reflects the fact that some draft issues of this document have been released, to a limited circulation.


Text and illustrations

Text and illustrations in this work are licensed under Attribution-ShareAlike 4.0 International (CC BY-SA 4.0). To view a copy of the license, visit creativecommons.org/licenses/by-sa/4.0.

Grant of patent license. Subject to the terms and conditions of this license (both the CC BY-SA 4.0 Public License and this Patent License), each Licensor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Licensed Material, where such license applies only to those patent claims licensable by such Licensor that are necessarily infringed by their contribution(s) alone or by combination of their contribution(s) with the Licensed Material to which such contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Licensed Material or a contribution incorporated within the Licensed Material constitutes direct or contributory patent infringement, then any licenses granted to You under this license for that Licensed Material shall terminate as of the date such litigation is filed.

The Arm trademarks featured here are registered trademarks or trademarks of Arm Limited (or its subsidiaries) in the US and/or elsewhere. All rights reserved. Please visit arm.com/company/policies/trademarks for more information about Arm’s trademarks.

About the license

The language in the additional patent license is largely identical to that in section 3 of the Apache License, Version 2.0 (Apache 2.0), with two exceptions:

  1. Changes are made related to the defined terms, to align those defined terms with the terminology in CC BY-SA 4.0 rather than Apache 2.0 (for example, changing “Work” to “Licensed Material”).

  2. The scope of the defensive termination clause is changed from “any patent licenses granted to You” to “any licenses granted to You”. This change is intended to help maintain a healthy ecosystem by providing additional protection to the community against patent litigation claims.

To view the full text of the Apache 2.0 license, visit apache.org/licenses/LICENSE-2.0.

Source code

Source code samples in this work are licensed under the Apache License, Version 2.0 (the “License”); you may not use such samples except in compliance with the License. You may obtain a copy of the License at apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and limitations under the License.


This document refers to the following documents.

Table 2 Documents referenced by this document


Document Number



ISO/IEC, ISO/IEC 9899:1999 — Programming Languages — C, December 1999. www.iso.org/standard/29237.html


Arm Limited and Contributors, Embedded Base Boot Requirements (EBBR) Specification. arm-software.github.io/ebbr


EN 303 645

ETSI, Cyber Security for Consumer Internet of Things: Baseline Requirements, June 2020. www.etsi.org/standards/get-standards#search=303%20645


IR 8259

NIST, Foundational Cybersecurity Activities for IoT Device Manufacturers, May 2020. doi.org/10.6028/NIST.IR.8259


LwM2M v1.2

OMA, Lightweight M2M, November 2020. openmobilealliance.org/release/LightweightM2M



PSA Certified™ Level 2 Lightweight Protection Profile. psacertified.org/development-resources/certification-resources/#leveltwo


ARM DEN 0063

Arm® Platform Security Architecture Firmware Framework. developer.arm.com/documentation/den0063


ARM IHI 0097

PSA Certified Status code API. arm-software.github.io/psa-api/status-code


ARM DEN 0128

Platform Security Model. developer.arm.com/documentation/den0128


IETF, A Universally Unique IDentifier (UUID) URN Namespace. tools.ietf.org/html/rfc4122


IAB, Report from the Internet of Things Software Update (IoTSU) Workshop 2016, September 2017. tools.ietf.org/html/rfc8240


IETF, A Firmware Update Architecture for Internet of Things, April 2021. tools.ietf.org/html/rfc9019


IETF, A Manifest Information Model for Firmware Updates in Internet of Things (IoT) Devices, January 2022. tools.ietf.org/html/rfc9124


NIST, NIST Special Publication 800-30 Revision 1: Guide for Conducting Risk Assessments, September 2012. doi.org/10.6028/NIST.SP.800-30r1


IETF, (draft), Encrypted Payloads in SUIT Manifests, April 2023. datatracker.ietf.org/doc/draft-ietf-suit-firmware-encryption


IETF, (draft), A Concise Binary Object Representation (CBOR)-based Serialization Format for the Software Updates for Internet of Things (SUIT) Manifest, February 2023. datatracker.ietf.org/doc/draft-ietf-suit-manifest


UEFI v2.10

UEFI Forum, Inc., Unified Extensible Firmware Interface (UEFI) Specification, August 2022. uefi.org/specifications

Terms and abbreviations

This document uses the following terms and abbreviations.

Table 3 Terms and abbreviations



Application firmware

The main application firmware for the platform, typically comprising an Operating System (OS) and application tasks. On a platform with isolation, the application firmware runs in the NSPE.

Application Root of Trust

This is the security domain in which additional security services are implemented. See Platform Security Model [PSM].

Immutable Platform Root of Trust

Part of the Platform Root of Trust, which is inherently trusted. This refers to the hardware and firmware that cannot be updated on a production device. See Platform Security Model [PSM].

Implementation Defined

Behavior that is not defined by the this specification, but is defined and documented by individual implementations.

Firmware developers can choose to depend on IMPLEMENTATION DEFINED behavior, but must be aware that their code might not be portable to another implementation.


Firmware image metadata that is signed with a cryptographic key. The manifest can be bundled within the firmware image, or detached from it.

See Manifest.


Memory protection unit

Non-secure Processing Environment (NSPE)

This is the security domain outside of the Secure Processing Environment. It is the Application domain, typically containing the application firmware and hardware.

NSPE See Non-secure Processing Environment.

Original equipment manufacturer

OTA See Over-the-Air.
Over-the-Air (OTA)

The procedure where a device downloads an update from a remote location (“over the air”).


Public key infrastructure

Platform Root of Trust (PRoT)

The overall trust anchor for the system. This ensures the platform is securely booted and configured, and establishes the secure environments required to protect security services. See Platform Security Model [PSM].

PRoT See Platform Root of Trust.

Platform Security Architecture

Root of Trust (RoT)

This is the minimal set of software, hardware and data that is implicitly trusted in the platform — there is no software or hardware at a deeper level that can verify that the Root of Trust is authentic and unmodified.

RoT See Root of Trust.
Secure boot

Secure boot is technology to provide a chain of trust for all the components during boot.

Secure Processing Environment (SPE)

This is the security domain that includes the Platform Root of Trust and the Application Root of Trust domains.

SPE See Secure Processing Environment.
Staging area

A region within the 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.

See Firmware store.

Updatable Platform Root of Trust

Part of the Platform Root of Trust firmware that can be updated following manufacturing. See Platform Security Model [PSM].

Update client

Software component that is responsible for downloading firmware updates to the device. The Update client is part of the application firmware.

Volatile staging

A component with volatile staging does not preserve a firmware image that is in the staging area after a reboot.

A component without volatile staging preserves a prepared candidate firmware image after a reboot. It is implementation defined whether a partially prepared image in in the staging area is retained after a system reset.


Potential for change

The contents of this specification are stable for version 1.0.

The following may change in updates to the version 1.0 specification:

  • Small optional feature additions.

  • Clarifications.

Significant additions, or any changes that affect the compatibility of the interfaces defined in this specification will only be included in a new major or minor version of the specification.


Typographical conventions

The typographical conventions are:


Introduces special terminology, and denotes citations.


Used for assembler syntax descriptions, pseudocode, and source code examples.

Also used in the main text for instruction mnemonics and for references to other items appearing in assembler syntax descriptions, pseudocode, and source code examples.

small capitals

Used for some common terms such as implementation defined.

Used for a few terms that have specific technical meanings, and are included in the Terms and abbreviations.

Red text

Indicates an open issue.

Blue text

Indicates a link. This can be

  • A cross-reference to another location within the document

  • A URL, for example example.com


Numbers are normally written in decimal. Binary numbers are preceded by 0b, and hexadecimal numbers by 0x.

In both cases, the prefix and the associated value are written in a monospace font, for example 0xFFFF0000. To improve readability, long numbers can be written with an underscore separator between every four characters, for example 0xFFFF_0000_0000_0000. Ignore any underscores when interpreting the value of a number.


We welcome feedback on the PSA Certified API documentation.

If you have comments on the content of this book, visit github.com/arm-software/psa-api/issues to create a new issue at the PSA Certified API GitHub project. Give:

  • The title (Firmware Update API).

  • The number and issue (IHI 0093 1.0.0).

  • The location in the document to which your comments apply.

  • A concise explanation of your comments.

We also welcome general suggestions for additions and improvements.