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.

[SylwesterKonczyk]

That functionality may cause confusions. In SUIT, a digest value (or expected payload size) in not a fixed property of component but rather an argument to directive-override-parameters ‘, so:

• Expected digest value (or expected payload size) may be unknown at time of execution of ‘directive-fetch‘ – there is nothing what enforces a manifest creator to call ‘directive-override-parameters’ prior to ‘directive-fetch‘
• Manifest may be crafted in a way that it accepts alternative payloads represented by single URI. In such case manifest may evaluate several digest values on fetched payload.
• Methods of digest calculation for regular image and dependency manifest differs.
• Manifest may be crafted in a way that it repeats fetching in case if recently downloaded payload is damaged, so some resiliency mechanisms are already in-place.

[athoelke]

It is not unlikely that the digest parameter will already be set when calling suit-directive-fetch:

• One of the optimisations suggested for a SUIT processor when restarting a command sequence after interruption, is to elide the fetching of a payload that has already been transferred, by matching a stored payload using the digest of the requested payload.

• This optimisation depends on the component's digest parameter being set prior to the suit-directive-fetch command. In the absence of the digest parameter the optimisation is disabled, and the payload will always be fetched.

I can see that for some systems, being able to detect a non-matching image before download, might avoid costly download or store-to-flash overheads. This could improve long-term-reliability, but only if having incorrect payload images on the update server is considered to be probable. It does not significantly mitigate security concerns, as an attacker can present an acceptable digest, but an invalid image, and would still result in the download and transfer of the image before the SUIT digest verification reports an error.

Conclusion

Adding these might be beneficial for some systems/deployments, but the availability of these attributes is not guaranteed. Therefore, if we add them to the payload information, then they must be optional, and we need another field in the payload information to individually indicate if these parameters are present in the information.

[athoelke]

This is now (from v0.8 of the proposal) optionally provided in the payload information, with a flag to indicate its presence.

[SylwesterKonczyk]

There is no dedicated ‘system validation’ sequence defined in SUIT specification. Maybe it is worth to remove it?

[athoelke]

I think when I first wrote this I was thinking about checking that the update matches the system (device type, etc.) - but that would be integrated into one of the other sequences.

Fixed.

[SylwesterKonczyk]

suit-candidate-validation and suit-install?

[athoelke]

Corrected

[SylwesterKonczyk]

"Then the full set of manifests is involved...," Actually - Currently processed command sequence MAY execute 'process-dependency' on any dependencies of currently processed manifests.

[athoelke]

Corrected/clarified.

[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().