RFC: Support for SUIT in the Firmware Update API

[athoelke]

This is a draft PR that creates an RFC proposal document, considering how to implement full support for SUIT in the Firmware Update API.

Reading the proposal is easiest by viewing the document in its branch: rfc-01-fwu-suit

Please provide feedback on the analysis, the draft proposal, and any of the currently open issues (end of the document right now); either in the PR discussion thread, or as review comments against the 'Files changed'.

[athoelke]

I've updated the proposal following initial discussion, and further, detailed reading of some of the additional SUIT specifications relating to nested/dependency manifests.

• Reworked the state model and API based on detailed understanding of the Multiple Trust Domain extension to the base SUIT specification.
• Added component state information to the detailed sequence graphic to clarify the programming model.
• Aligned the document with the details of the SUIT specifications.
• Provided more detail on how the API design supports the alternative flow scenarios.

Much of the text has been altered or completely rewritten - if you have read v1, it may be worthwhile reading the whole new proposal, instead of reviewing the diffs.

[athoelke]

A second update to the proposal.

• I have added graphics to show flows for fetching payloads during suit-install, and not just the suit-payload-fetch command sequence. And text to explain the rationale for this support.
• I have added some information about Firmware Update API component identifier usage.

A few key open issues remain:

• Component identifier definition (in particular the C type)
• Need for additional component information in response to a status query
• API for processing SUIT fetch commands during suit-payload-fetch and suit-install misaligns with existing per-component transfer, but all-CANDIDATE installation APIs.

[athoelke]

Version 0.4 uploaded. Revision notes:

• Resolved issue: Removed FETCHING state from the envelope.

• Resolved issue: API design for handling fetching during suit-install:

  • Restrict the API: only a single top-level SUIT envelope component can be install at a time. If two MUST be installed together (due to interdependency) they SHOULD be dependencies within a single, separate Dependent manifest.
  • Remove the envelope component id parameter from psa_fwu_process(). As there is only one envelope being installed, the client does not need to indicate what needs to be processed.
• Resolved issue: Make psa_fwu_component_t a 32-bit integral type. In the v1.0 API it only appears as a function parameter, so widen the type does not affect source compatibility for the API.
• Described different strategies for envelope id allocation, and use of additional component ids for querying the firmware status of the system.

Note also: Alternative flow is possible with one-at-a-time restriction. See the appendix in the proposal for details.

[athoelke]

Updated to v0.5 - see commit or revision history for update notes.

[athoelke]

v0.6: I've made an attempt to define the API. This raises a few additional issues to resolve relating to detailed API design.

[athoelke]

Updated the proposal to v0.8:

• Describe a third (now preferred) option for the payload information discovery API, OPTION C. The additional function used in this option is also reflected in updated sequence diagrams.
• Permit an implementation to optionally provide additional payload size and digest information. (Only coded into the payload information structure in Option C).

[athoelke]

The Open Issues remaining:

• Final naming of API elements. The names seemed to have settled - but the new API psa_fwu_payload() to retrieve the payload parameters might not be ideal yet. I have renamed the structure for payload information to psa_fwu_payload_info_t to match the existing psa_fwu_component_info_t.

• We don't think there additional attributes for components that need to be included in the psa_fwu_component_info_t. Specifically, we don't expect Update clients to implement a SUIT processor - the new API design is based around the processor being inside the implementation.

• The psa_fwu_payload() function (in Option C) is unusual in returning a variable length buffer, but without returning the actual length written to the buffer. The length is returned by the preceding call to psa_fwu_process(). If we add the parameter, the API now returns this length twice (which is also slightly odd).

• I have considered merging the action of the call to psa_fwu_start(payload_id, 0, 0) into psa_fwu_payload(payload_id, ...), which must always follow it (maybe calling it psa_fwu_start_payload(payload_id, ...)).

  This would reduce the functions called, and does not affect the size of the API, but would make the image transfer for payloads slightly different to that for other component images, potentially reducing the ability to share code for these activities.

  For now, the API reuses the same psa_fwu_start() call for initiating payload transfer after the call to psa_fwu_payload().