PSA Certified
Firmware Update API 1.0

Document number:	IHI 0093
Release Quality:	Final
Issue Number:	1
Confidentiality:	Non-confidential
Date of Issue:	23/9/2025

Abstract

This document defines a standard firmware interface for installing firmware updates.

Contents

• About this document
  • Release information
  • License
  • References
  • Terms and abbreviations
  • Potential for change
  • Conventions
  • Feedback

• 1 Introduction
  • 1.1 About Platform Security Architecture
  • 1.2 About the Firmware Update API
  • 1.3 Firmware update
• 2 Design goals
  • 2.1 Suitable for constrained devices
  • 2.2 Updating the Platform Root of Trust
  • 2.3 Updating the Application Root of Trust
  • 2.4 Flexibility for different trust models
  • 2.5 Protocol independence
  • 2.6 Transport independence
  • 2.7 Firmware format independence
  • 2.8 Flexibility for different hardware designs
  • 2.9 Suitable for composite devices
  • 2.10 Robust and reliable update
  • 2.11 Flexibility in implementation design
• 3 Architecture
  • 3.1 Concepts and terminology
    • 3.1.1 Firmware image
    • 3.1.2 Manifest
    • 3.1.3 Component
    • 3.1.4 Component identifier
    • 3.1.5 Firmware creator
    • 3.1.6 Update server
    • 3.1.7 Update client
    • 3.1.8 Update service
    • 3.1.9 Firmware store
    • 3.1.10 Bootloader
    • 3.1.11 Trust anchor
  • 3.2 Firmware image format
  • 3.3 Deployment scenarios
    • 3.3.1 Untrusted client
    • 3.3.2 Untrusted staging
    • 3.3.3 Trusted client
• 4 Programming model
  • 4.1 The firmware store
  • 4.2 State model
    • 4.2.1 Component state
    • 4.2.2 Volatile states
    • 4.2.3 State transitions
    • 4.2.4 Behavior on error
    • 4.2.5 Rationale
  • 4.3 Verifying an update
    • 4.3.1 Manifest verification
    • 4.3.2 Firmware image verification
  • 4.4 Dependencies
  • 4.5 Update client operation
    • 4.5.1 Querying installed firmware
    • 4.5.2 Preparing a new firmware image
    • 4.5.3 Installing the candidate firmware image
    • 4.5.4 Testing the new firmware image
    • 4.5.5 Cleaning up the firmware store
  • 4.6 Bootloader operation
    • 4.6.1 Determine firmware state
    • 4.6.2 Install components
    • 4.6.3 Rollback trial components
    • 4.6.4 Authenticate and execute active firmware
  • 4.7 Sample sequence during firmware update
• 5 API reference
  • 5.1 API conventions
    • 5.1.1 Identifier names
    • 5.1.2 Basic types
    • 5.1.3 Data types
    • 5.1.4 Constants
    • 5.1.5 Functions
    • 5.1.6 Return status
    • 5.1.7 Pointer conventions
    • 5.1.8 Implementation-specific types
  • 5.2 Header file
    • 5.2.1 Required functions
  • 5.3 Library management
    • 5.3.1 Library version
  • 5.4 Status codes
    • 5.4.1 Common status codes
    • 5.4.2 Error codes specific to the Firmware Update API
    • 5.4.3 Success status codes specific to the Firmware Update API
  • 5.5 Firmware components
    • 5.5.1 Component identifier
    • 5.5.2 Component version
    • 5.5.3 Component states
    • 5.5.4 Component flags
    • 5.5.5 Component information
  • 5.6 Firmware installation
    • 5.6.1 Candidate image preparation
    • 5.6.2 Image installation
    • 5.6.3 Image trial

• A Example header file
  • A.1 psa/update.h
• B Example usage
  • B.1 Retrieve versions of installed images
  • B.2 Individual component update (single part operation)
  • B.3 Individual component update (multi part operation)
  • B.4 Multiple components with dependent images
  • B.5 Clean up all component updates
• C Variation in system design parameters
  • C.1 Component with non-volatile staging
    • C.1.1 Component that requires a reboot, but no trial
    • C.1.2 Component that requires a trial, but no reboot
    • C.1.3 Component that requires neither a reboot, nor a trial
  • C.2 Component with volatile staging
• D Security Risk Assessment
  • D.1 About this assessment
    • D.1.1 Subject and scope
    • D.1.2 Risk assessment methodology
  • D.2 Feature definition
    • D.2.1 Introduction
    • D.2.2 Lifecycle
    • D.2.3 Operation and trust boundaries
    • D.2.4 Deployment models
    • D.2.5 Assumptions and constraints
    • D.2.6 Stakeholders and assets
    • D.2.7 Security goals
    • D.2.8 Adversarial model
  • D.3 Feature characterization
    • D.3.1 Detailed deployment dataflow
    • D.3.2 Security features of the API
  • D.4 Threats
    • D.4.1 T.TAMPER: Tampering with the firmware image or manifest
    • D.4.2 T.NON_FUNCTIONAL: Install defective firmware
    • D.4.3 T.ROLLBACK: Install old firmware
    • D.4.4 T.SKIP_INTERMEDIATE: Skip intermediate update
    • D.4.5 T.DEGRADE_DEVICE: Repeatedly install invalid firmware
    • D.4.6 T.INTERFACE_ABUSE: Illegal inputs to the API
    • D.4.7 T.TOCTOU: Modify asset between authentication and use
    • D.4.8 T.PARTIAL_UPDATE: Trigger installation of incomplete update
    • D.4.9 T.INCOMPATIBLE: Mismatched firmware
    • D.4.10 T.DISCLOSURE: Disclosure of protected firmware
    • D.4.11 T.DISRUPT_INSTALL: Corrupt image by disrupting installer
    • D.4.12 T.DISRUPT_DOWNLOAD: Corrupt image by disrupting writes
    • D.4.13 T.FAULT_INJECTION: Verification bypass via glitching
    • D.4.14 T.SERVER: Attack from exploited update server
    • D.4.15 T.CREATOR: Attack from spoof firmware creator
    • D.4.16 T.NETWORK: Manipulate network traffic
  • D.5 Mitigation summary
    • D.5.1 Architectural mitigations
    • D.5.2 Implementation-level mitigations
    • D.5.3 User-level mitigations
• E Document change history
  • E.1 Changes between version 1.0.0 and 1.0.1
  • E.2 Changes between version 1.0 Beta and 1.0.0
  • E.3 Changes between version 0.7 and 1.0 Beta
  • E.4 Changes between version 0.6 and 0.7