[Suit] [suit]: draft-moran-suit-manifest-02

[Brendan Moran <[e-mail]>]

This draft is a significant departure from previous drafts, so I think it is important to highlight the changes. The draft requires a lot of text that hasn’t been written yet, so I will try to put some of that here for discussion.

https://datatracker.ietf.org/doc/draft-moran-suit-manifest/


# Summary of changes
There are a large number of changes in this draft. In addition, the text description of the manifest is yet to be completed. The top level manifest element remains a CBOR array. The primary reason for this is that many of the initial elements are mandatory (see the information model for more detail). In addition to this, the ordering is important because the manifest is a signed document. COSE uses the same paradigm: where fields are mandatory, they are encoded as an array. Where there are optional fields (COSE_Headers) they are encoded as a map (if unsigned) or as a map, wrapped in a bstr if signed.

The primary changes are:

1. Severable text
2. Digest Info is moved to a top-level element
3. Sequence number is now called sequence number instead of timestamp
4. Conditions are divided into preconditions and postconditions
5. Dependencies, Aliases, and payload info are now resources
6. Payloadinfo is divided into resources, processors, and targets

# Severable text:
Text is for humans. Devices shouldn’t parse it. Therefore, we have moved text information out of the manifest. However, humans need to know that the text they are reading correctly corresponds to the manifest they are looking at. Therefore, we have made a container for a COSE_Sign / COSE_Mac and a map of text values. In addition to this, the text values are hashed and the hash is included in the manifest to ensure that the text portion is not modified or corrupted in transit.

This means that, while a manifest with text may be delivered to an update server, that server can strip off the text and deliver only the authenticated, machine-readable part to a target device. This results in reduced bandwidth, reduced buffer sizes, more expressive text information, and reduced opportunity to abuse variably sized fields.

# Digest info at the top level
Digests are used in many places in the manifest. The information required to interpret digests, therefore, must be a top-level element. All digests in any given manifest must use the same digest algorithm.

# Sequence Number
The use of timestamp as sequence number has caused confusion regularly, so we have changed timestamp to sequence number in this draft.

# PreConditions and PostConditions
There has been significant debate about the use of preconditions and postconditions, with several important use cases. Because of this, conditions has been divided into preconditions and postconditions.

# Dependencies, Aliases, PayloadInfo
Each of these has very similar information. Because of this, it seems reasonable to group them into a common structure that just identifies the type of reference.

# Resources, Processors, Targets
To satisfy complex requirements, we considered several use-cases:

Differential update of a dual XIP MCU. To accomplish this and still obtain good compression, the installed image must be un-relocated, then a diff must be applied, then the resulting image must be relocated, then written to storage. This is even more complicated if the diff is compressed and encrypted. Furthermore, there are some differential algorithms that will need to be able to read the data they have written, which means that the target image must also be possible to read, un-relocate, and feed into the differential unpacking engine.

Shared compression table. Several components of an update may be delivered with a single common compression table. If this is the case, then each target image must be decompressed using two inputs: the compressed file and the compression table

The result of this is that we concluded that resources and targets cannot considered the same. While they are the same in the “raw binary” case, and they still appear to be the same in linear-processing case (where all processors have only one input and one output), once differential compression, table compression, and relocation are considered, it is clear that, since processors can require multiple inputs, there must be a way to describe each of these inputs. This clarifies that resources are distinct from the final image that is installed to a device.

Because of this distinction and in order to describe complex use-cases, we have included a mechanism of describing the resources as input nodes to a graph, the installation targets as output nodes from the graph, and the intermediate states as internal nodes of the graph, where each processor forms an edge on the graph.

For the installation of any given target, we expect that this graph could be reduced to a tree with an installation target at the root.

In the simple case, a raw binary payload, one resource is required, identifying an output node, and one installation target is required, identifying the same node as an input node.

Describing this structure as a graph, rather than a tree for each target is a design tradeoff. We believe that the graph as several advantages. First, it reduces the nesting depth of the CBOR parser. This is an important consideration for how much memory is consumed. Second, it allows a validator to iterate over the graph and identify whether it supports each specified processor without any comprehension of the tree structures or graph connectedness. Third, it eliminates repetitive description of resources and intermediates that are used in multiple trees, which could be used to eliminate download (resource acquisition) and processing overhead. We don’t think that the reduction in manifest size would be significant.

As always, your input is most welcome!

Thanks,
Brendan
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.