PSA Certified
Firmware Update API 1.0

Document number:	IHI 0093
Release Quality:	Final
Issue Number:	0
Confidentiality:	Non-confidential
Date of Issue:	1/8/2023

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 Beta and 1.0.0
  • E.2. Changes between version 0.7 and 1.0 Beta
  • E.3. Changes between version 0.6 and 0.7