Update Management Extensions for Software Updates for Internet of Things (SUIT) Manifests

3.1. suit-set-version

This metadata encodes a semantic version for the component set that the manifest updates, including any dependencies. This enables version comparisons to be performed on manifests. Non-manifest images encode their versions independently of the manifest.¶

The version MUST be encoded as a semantic version, according to [semver], so that recipients can compare manifests deterministically. Deployments that cannot supply a semantic version without loss of fidelity MUST omit suit-set-version and convey any human-facing numbering via text-current-version (Section 3.4). Because suit-set-version is a machine-readable parameter for determining compatibility and because [semver] mandates that the build-number is ignored, build numbers MUST NOT be included.¶

The composition of suit-set-version is the same as suit-parameter-version (Section 4.4).¶

If a build number is desired, the manifest author MAY include it via text-current-version (Section 3.4).¶

3.2. suit-coswid

A CoSWID can enable Software Bill of Materials use-cases. Tightly coupling update and attestation ensures that verification infrastructure always knows what software to expect on each device.¶

suit-coswid is a member of the suit-manifest. It contains a Concise Software Identifier (CoSWID) as defined in [RFC9393]. This element SHOULD be made severable so that it can be discarded by the Recipient or an intermediary if it is not required by the Recipient while preserving the manifest signature. Implementations that cannot support severable elements MAY include suit-coswid non-severably, but MUST ensure that Recipients can still process the manifest.¶

suit-coswid typically requires no processing by the Recipient. However, Recipients MUST NOT fail if a suit-coswid is present.¶

suit-coswid is RECOMMENDED to implement and RECOMMENDED to include in manifests.¶

3.3. suit-text-version-required

suit-text-version-required is used to represent a version-based dependency on suit-parameter-version as described in Section 4.4 and Section 5.5. When a Manifest Author needs to communicate such a dependency to operators, the author SHOULD populate the suit-text map with a SUIT_Component_Identifier key for the dependency component, and place in the corresponding map a suit-text-version-required key with a free text expression that is representative of the version constraints placed on the dependency so that field personnel can validate compliance. Deployments that provide operator guidance exclusively through other channels MAY omit this field. This text SHOULD be expressive enough that a device operator can be expected to understand the dependency; predefined tokens MAY be used when supporting documentation ensures equivalent clarity. Expressions in this field MUST be encoded as UTF-8 text limited to printable characters (Unicode general categories L, N, P, or Zs) and SHOULD use simple relational operators (for example >, >=, <, <=, =) so that automated tooling can perform lint checks. This is a free text field and there are no specific formatting rules.¶

By way of example only, to express a dependency on a component "['x', 'y']", where the version should be any v1.x later than v1.2.5, but not v2.0 or above, the author would add the following structure to the suit-text element. Note that this text is in cbor-diag notation.¶

['x','y'] : {
    7 : ">=1.2.5,<2"
}

3.4. text-current-version

suit-text-current-version is used to provide human-readable version information equivalent to suit-set-version (Section 3.1). This metadata MAY have a version listed for each or any component. The Manifest Processor MUST NOT consume this version; it is for human readability only.¶

To describe a version, a Manifest Author SHOULD populate the suit-text map with a SUIT_Component_Identifier key for the dependency component, and place in the corresponding map a suit-text-current-version key with a free text version that is representative of the version of the component so that operators can reconcile machine and human-readable records. Deployments that provide human-facing version information through other configuration channels MAY omit this text. This text SHOULD be expressive enough that a device operator can be expected to understand the version; environments that rely on catalog identifiers MAY use those identifiers when supporting documentation provides the necessary context. Values in this field MUST be encoded as UTF-8 text limited to printable characters, and implementations MUST treat suit-set-version and suit-parameter-version as authoritative when a discrepancy exists. Recipients MUST NOT interpret this text as executable code or markup and MUST treat it as display-only information. This is a free text field and there are no specific formatting rules.¶

It is RECOMMENDED that the Manifest Author use a Semantic Version ([semver]) in the free-text field to keep human-readable and machine-readable versions aligned. Unlike suit-set-version (Section 3.1), the full semantic version specification can be used.¶

4.1. suit-parameter-use-before

An expiry date for the use of the manifest encoded as the positive integer number of seconds since 1970-01-01. Implementations that use this parameter MUST use a 64-bit internal representation of the integer. Used with Section 5.1.¶

4.2. suit-parameter-minimum-battery

This parameter sets the minimum battery level in mWh. This parameter is encoded as a positive integer. Used with suit-condition-minimum-battery (Section 5.3).¶

4.3. suit-parameter-update-priority

This parameter sets the priority of the update. This parameter is encoded as an integer. It is used along with suit-condition-update-authorized (Section 5.4) to ask an application for permission to initiate an update. This does not constitute a privilege inversion because an explicit request for authorization has been provided by the Update Authority in the form of the suit-condition-update-authorized command.¶

Applications MAY define their own meanings for the update priority. For example, critical reliability and vulnerability fixes might be given negative numbers, while bug fixes might be given small positive numbers, and feature additions might be given larger positive numbers, which allows an application to make an informed decision about whether and when to allow an update to proceed.¶

4.4. suit-parameter-version

Indicates allowable versions for the specified component. One version comparison can be made with each suit-parameter-version. This parameter is compared with version asserted by the current component when suit-condition-version (Section 5.5) is invoked. The current component may assert the current version in many ways, including storage in a parameter storage database, in a metadata object, or in a known location within the component itself.¶

Each suit-parameter-version contains a comparison operator and a version, according to the following CDDL:¶

SUIT_Parameter_Version_Match = [
    suit-condition-version-comparison-type:
        SUIT_Condition_Version_Comparison_Types,
    suit-condition-version-comparison-value:
        SUIT_Condition_Version_Comparison_Value
]

The comparison type can be:¶

• Greater.¶

• Greater or Equal.¶

• Equal.¶

• Lesser or Equal.¶

• Lesser.¶

The version comparison value is encoded as a CBOR list of integers. Comparisons are done on each integer in sequence. Comparison stops after all integers in the list defined by the manifest have been consumed OR after an non-equal comparison has occurred. For example, if the manifest defines a comparison, "Equal [1]", then this will match all version sequences starting with 1. If a manifest defines both "Greater or Equal [1,0]" and "Lesser [1,10]", then it will match versions 1.0.x up to, but not including 1.10.¶

4.5. suit-parameter-wait-info

suit-directive-wait (Section 5.6) directs the manifest processor to pause until a specified event occurs. The suit-parameter-wait-info encodes the parameters needed for the directive.¶

The exact implementation of the pause is implementation-defined. For example, this could be done by blocking on a semaphore, registering an event handler and suspending the manifest processor, polling for a notification, or aborting the update entirely, then restarting when a notification is received.¶

suit-parameter-wait-info is encoded as a map of wait events. All wait events MUST be satisfied before the Manifest Processor continues. The wait events currently defined are described in the following table.¶

suit-wait-event-other-device-version reuses the encoding of SUIT_Parameter_Version_Match. It is encoded as a sequence that contains an implementation-defined bstr identifier for the other device, and a list of one or more SUIT_Parameter_Version_Match.¶

4.6. suit-parameter-component-metadata

In some instances, a system may need to know the file metadata for a component. This metadata can include:¶

• creator¶

• creation time¶

• modification time¶

• default permissions (rwx)¶

• a map of user/permission pairs¶

• a map of role/permission pairs¶

• a map of group/permission pairs¶

• file type¶

Unless otherwise stated, all string values in this structure MUST be encoded as UTF-8 without control characters (Unicode general categories Cc or Cf) and SHOULD be limited to human-readable identifiers such as names or POSIX-style paths. Binary values conveyed via bstr MUST be well-formed for the consuming platform (for example, a UUID or permissions bitmap) and MUST NOT exceed the minimum length required to represent the value canonically.¶

Component metadata is applied at time of fetch, copy, or write; see [I-D.ietf-suit-manifest], sections 8.4.10.4, 8.4.10.5, 8.4.10.6. Therefore, the component metadata parameter must be set in advance of the component being fetched, copied into, or written.¶

SUIT_meta_actor_id = UUID_Tagged / bstr / str / int
UUID_Tagged = #6.37(bstr)

suit-meta-modification-time => #6.1(uint)
suit-meta-creation-time => #6.1(uint)

SUIT_meta_permissions = uint .bits SUIT_meta_permission_bits
SUIT_meta_permission_bits = &(
    r: 2, w: 1, x: 0,
    * $$SUIT_meta_permission_bits_extensions
)

SUIT_meta_permission_map = {
    + SUIT_meta_actor_id => SUIT_meta_permissions
}

5.1. suit-condition-use-before

Verify that the current time is BEFORE the specified time. suit-condition-use-before is used to specify the last time at which an update should be installed. The recipient evaluates the current time against the suit-parameter-use-before parameter (Section 4.1), which must have already been set as a parameter, encoded as seconds after 1970-01-01 00:00:00 UTC. Timestamp conditions MUST be evaluated in 64 bits, regardless of encoded CBOR size. suit-condition-use-before is OPTIONAL to implement.¶

5.2. suit-condition-image-not-match

Verify that the current component does not match the suit-parameter-image-digest (Section 8.4.8.6 of [I-D.ietf-suit-manifest]). If no digest is specified, the condition fails. suit-condition-image-not-match is OPTIONAL to implement.¶

5.3. suit-condition-minimum-battery

suit-condition-minimum-battery provides a mechanism to test a Recipient's battery level before installing an update. This condition is primarily for use in primary-cell applications, where the battery is only ever discharged. For batteries that are charged, suit-directive-wait is more appropriate, since it defines a "wait" until the battery level is sufficient to install the update. suit-condition-minimum-battery is specified in mWh. suit-condition-minimum-battery is OPTIONAL to implement. suit-condition-minimum-battery consumes suit-parameter-minimum-battery (Section 4.2).¶

5.4. suit-condition-update-authorized

Request authorization from the application and fail if not authorized. This can allow a user to decline an update. suit-parameter-update-priority (Section 4.3) provides an integer priority level that the application can use to determine whether or not to authorize the update. Priorities are application defined. suit-condition-update-authorized is OPTIONAL to implement.¶

5.5. suit-condition-version

suit-condition-version allows comparing versions of firmware. Verifying image digests is preferred to version checks because digests are more precise. suit-condition-version examines a component's version against the version info specified in suit-parameter-version (Section 4.4).¶

5.6. suit-directive-wait

suit-directive-wait directs the manifest processor to pause until a specified event occurs. Some possible events include:¶

1. Authorization¶

2. External power¶

3. Network availability¶

4. Other device firmware version¶

5. Time¶

6. Time of day¶

7. Day of week¶

5.7. suit-directive-override-multiple

This directive enables setting parameters for multiple components at the same time. This allows a small reduction in encoding overhead:¶

• without override-multiple, the encoding for each component consists of:¶

  • set-component-index (2 bytes)¶

  • override-parameters (1 byte + parameter map)¶

• with override-multiple, the encoding for each component consists of:¶

  • the component index key (1 byte)¶

  • the parameter map¶

Override-multiple requires the command (1-2 bytes) and one additional map to hold the parameter sets (1 byte). For one component, there is no savings. For multiple components, there is an encoding savings of 2 bytes per component.¶

Proper structuring of code should ensure that override-multiple follows a code-path nearly identical to set-component-index + override-parameters.¶

This command is purely an encoding alias for set-component-index and override-parameters. The component index is set to the last component listed in the override-multiple argument when override-multiple completes.¶

The following CDDL defines the argument for suit-directive-override-multiple:¶

CDDL SUIT_Override_Mult_Arg = { uint => {+ $$SUIT_Parameters} } ¶

5.8. suit-directive-copy-params

suit-directive-copy-params enables a manifest author to specify one or more components to copy parameters from, and a list of parameters to copy from each specified source component.¶

The behaviour is exactly the same as override parameters, but with parameter values defined in existing components. Parameters are only copied between identical keys (no copying from URI to digest, for example).¶

For each entry in the map, the manifest processor sets the source component to be the component identified by the index contained in the map key. For each parameter identified in the copy list, the manifest processor copies the parameter from the source component to the current component.¶

The following CDDL defines the argument for suit-directive-copy-params:¶

CDDL SUIT_Directive_Copy_Params = { uint => [+ int] } ¶

6.1. SUIT Commands

6.2. SUIT Parameters

8.1. Normative References

[I-D.ietf-suit-manifest]

Moran, B., Tschofenig, H., Birkholz, H., Zandberg, K., and O. Rønningstad, "A Concise Binary Object Representation (CBOR)-based Serialization Format for the Software Updates for Internet of Things (SUIT) Manifest", Work in Progress, Internet-Draft, draft-ietf-suit-manifest-34, 28 May 2025, <https://datatracker.ietf.org/doc/html/draft-ietf-suit-manifest-34>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8949]

Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", STD 94, RFC 8949, DOI 10.17487/RFC8949, December 2020, <https://www.rfc-editor.org/rfc/rfc8949>.

[RFC9393]

Birkholz, H., Fitzgerald-McKay, J., Schmidt, C., and D. Waltermire, "Concise Software Identification Tags", RFC 9393, DOI 10.17487/RFC9393, June 2023, <https://www.rfc-editor.org/rfc/rfc9393>.

[semver]

"Semantic Versioning 2.0.0", 18 June 2013, <https://semver.org>.

8.2. Informative References

[I-D.ietf-suit-information-model]

Moran, B., Tschofenig, H., and H. Birkholz, "A Manifest Information Model for Firmware Updates in Internet of Things (IoT) Devices", Work in Progress, Internet-Draft, draft-ietf-suit-information-model-13, 8 July 2021, <https://datatracker.ietf.org/doc/html/draft-ietf-suit-information-model-13>.

[RFC9019]

Moran, B., Tschofenig, H., Brown, D., and M. Meriac, "A Firmware Update Architecture for Internet of Things", RFC 9019, DOI 10.17487/RFC9019, April 2021, <https://www.rfc-editor.org/rfc/rfc9019>.