]> Arm Limited

Brendan.Moran.ietf@gmail.com

SECOM CO., LTD.

ken.takayama.ietf@gmail.com

Security SUIT Internet-Draft This document specifies extensions to the SUIT manifest format. These extensions allow a Manifest Author, update distributor, or device operator to more precisely control the distribution and installation of updates to devices. These extensions also provide a mechanism to inform a management system of Software Identifier and Software Bill Of Materials information about an updated device.

Introduction Full management of software updates for unattended, connected devices requires cooperation between Manifest Authors and management, distribution, policy enforcement, and auditing systems. This specification provides extensions to the SUIT manifest that enable Manifest Authors to coordinate with these other systems. These extensions enable Manifest Authors to instruct devices to examine update priority, local update authorisation, update lifetime, and system properties. They also enable devices to report and distributors to collect Software Bill of Materials (SBOM) information. Extensions in this specification are OPTIONAL to implement and OPTIONAL to include in manifests. Knowledge of Recipient support for update-management extensions is deployment-specific and may be established out of band.

Conventions and Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. This document uses SUIT terminology, including Manifest Author and Recipient, as defined in . This document uses semantic versioning terminology from , including major, minor, patch, pre-release, and build metadata. The constrained integer encoding in uses three non-negative release-number integers, a mandatory release-stage integer, and a pre-release end marker when applicable. It supports only the pre-release classes defined there and excludes build metadata from machine-readable comparisons. The integer-array comparison in also supports other version-numbering schemes and prefix selectors. Deployment profile: A specification or agreement for a particular SUIT deployment that selects options left open by this document and defines their local mappings. A deployment profile can be a published specification or configuration agreed among Manifest Authors, Recipients, and the management system; it is not a new wire-format object defined by this document.

Extension Metadata Some additional metadata makes management of SUIT updates easier: A semantic version number for the update represented by the manifest Concise Software Identifiers (CoSWID) Text descriptions of requirements Text description of the current versions of components

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. Manifest Authors SHOULD encode suit-set-version whenever the release can be represented by the constrained version encoding defined in so that Recipients can compare manifests deterministically. Deployments that cannot supply such a version without loss of fidelity MUST omit suit-set-version and convey any human-facing numbering via suit-text-current-version (). Because suit-set-version is a machine-readable parameter for determining compatibility and build metadata is ignored for semantic-version precedence, build metadata MUST NOT be included. suit-set-version encodes a version using SUIT_Condition_Version_Comparison_Value, the version-value array defined for suit-parameter-version in . It does not include a SUIT_Condition_Version_Comparison_Types comparison operator. When using the constrained Semantic Versioning mapping, suit-set-version MUST contain a complete version encoding as defined in , rather than a prefix selector. If build metadata is desired, the Manifest Author MAY include it via suit-text-current-version ().

suit-coswid A CoSWID can enable Software Bill of Materials (SBOM) 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 . This element SHOULD be made severable so that it can be discarded by the Recipient or an intermediary if it is not used by the Recipient while preserving the manifest signature. An implementation that cannot generate severable elements MAY include suit-coswid using the non-severable CDDL alternative. suit-coswid is RECOMMENDED to implement and RECOMMENDED to include in manifests because management systems commonly need a durable software identity after update installation. CoSWID and related Software Bill of Materials metadata can support inventory, vulnerability management, compliance checks, and reconciliation between the installed update state and management-system records. This recommendation is scoped to the operational and security value of identifying installed software; it does not imply that the presence of SBOM metadata proves that the software is free of vulnerabilities or policy issues. Other extension metadata is not generally RECOMMENDED unless required by deployment policy or by a SUIT profile. A Recipient that claims support for suit-coswid MUST accept the non-severable form when it is well-formed and permitted by local policy. A Recipient that does not consume CoSWID metadata need not interpret the CoSWID fields beyond any validation needed to establish well-formedness. When suit-coswid is severable, such Recipients or intermediaries can discard it without invalidating the manifest signature. When suit-coswid is not severable, a Recipient MUST NOT fail solely because a well-formed, policy-permitted suit-coswid field is present. Recipients that use or validate suit-coswid MAY still fail or reject the manifest when the suit-coswid field or its digest is malformed, when local policy rejects the metadata, when processing would exhaust available resources, when validation of processed CoSWID metadata fails, or when a manifest relies on unsupported critical behaviour. These requirements do not imply that every Recipient implements CoSWID processing.

suit-text-version-required suit-text-version-required is used to represent a version-based dependency on suit-parameter-version as described in and . When a Manifest Author communicates such a dependency to operators through the manifest, the Manifest Author MUST populate the suit-text map with a SUIT_Component_Identifier key for the dependency component and place a suit-text-version-required key with a free-text expression in the corresponding map. Deployments that provide operator guidance exclusively through other channels MAY omit this field. The expression is intended to provide enough context for a device operator to understand and validate the dependency; predefined tokens can be used when supporting documentation provides equivalent clarity. Expressions in this field MUST be encoded as UTF-8 text containing only characters in Unicode general categories L, M, N, P, S, or Zs. The following ASCII strings are defined to represent the five comparison operators defined by suit-parameter-version: > (Greater), >= (Greater or Equal), = (Equal), <= (Lesser or Equal), and < (Lesser). No other comparison-operator syntax is defined by this document. When a Manifest Author uses comparison-operator syntax in this field, the Manifest Author MUST use these strings. All other content is free text, and there are no additional formatting rules. A Manifest Processor MUST NOT interpret or otherwise process the content of this field. An implementation that renders this text MUST do so in a manner that prevents markup, control-code, log, or user-interface injection. By way of example only, to express a dependency on a component "['x', 'y']", where the intended version is v1.2.5 or later, but not v2.0 or above, the Manifest Author would add the following structure to the suit-text element. Note that this text is in cbor-diag notation.

=1.2.5,<2" } ]]>

suit-text-current-version suit-text-current-version is used to provide human-readable version information equivalent to suit-set-version (). 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. When a Manifest Author describes a version through the manifest, the Manifest Author MUST populate the suit-text map with a SUIT_Component_Identifier key for the component and place a suit-text-current-version key with a free-text version in the corresponding map. Deployments that provide human-facing version information exclusively through other channels MAY omit this field. The text is intended to provide enough context for a device operator to understand the version and reconcile machine-readable and human-readable records; environments that rely on catalog identifiers can use those identifiers when supporting documentation provides the necessary context. Values in this field MUST be encoded as UTF-8 text containing only characters in Unicode general categories L, M, N, P, S, or Zs. Implementations MUST treat suit-set-version and suit-parameter-version as authoritative when a discrepancy exists. A Manifest Processor MUST NOT interpret or otherwise process the content of this field and MUST treat it as display-only information. An implementation that renders this text MUST do so in a manner that prevents markup, control-code, log, or user-interface injection. This is a free-text field, and there are no additional formatting rules beyond the character restrictions above. When the component uses Semantic Versioning, the Manifest Author SHOULD use the component's full Semantic Version in this field so that human-readable and machine-readable records remain aligned. A deployment that uses another versioning scheme MAY instead use its customary human-readable form. Unlike suit-set-version (), the full Semantic Versioning specification can be used in this field.

Extension Parameters Several parameters are needed to define the behaviour of the commands specified in Extension Commands (). These parameters follow the same considerations as defined in Section 8.4.8 of . Name CDDL Structure Reference Use Before suit-parameter-use-before Minimum Battery suit-parameter-minimum-battery Update Priority suit-parameter-update-priority Version suit-parameter-version Wait Info suit-parameter-wait-info Component Metadata suit-parameter-component-metadata

suit-parameter-use-before An expiry date for the use of the manifest encoded as the non-negative 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 .

suit-parameter-minimum-battery This parameter sets the minimum battery level in mWh. This parameter is encoded as a non-negative integer. Used with suit-condition-minimum-battery ().

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 () 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. Numerically smaller values indicate higher update priority. Recipients and applications that compare suit-parameter-update-priority values MUST use this ordering. Local policy MAY assign deployment-specific meanings to particular values or ranges. 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.

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 the version asserted by the current component when suit-condition-version () is invoked. The current component can 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:

The comparison type can be: Greater. Greater or Equal. Equal. Lesser or Equal. Lesser. The version comparison value is encoded as a CBOR array of integers. Comparisons are done on each integer in sequence. Comparison stops after all integers in the array defined by the manifest have been consumed OR after a 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 all compared integers are equal, the comparison result is Equal. 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. If the component's version array is exhausted before comparison stops, the Manifest Processor MUST use zero for each subsequent component integer required by the comparison.

suit-parameter-version Semantic Versioning encoding guidelines Manifest Authors MUST use the constrained Semantic Versioning encoding summarized in unless the component uses another numbering scheme that cannot be represented faithfully. When another numbering scheme is used, the sequence of integers encoded here MUST preserve release ordering (for example, [2025,12,6] for a calendar-based release). The following rules define a complete version encoding for this mapping. They apply both to the version asserted by a component for comparison and to complete versions encoded in a manifest: The first three integers MUST encode the major, minor, and patch numbers, in that order. All three integers MUST be present and non-negative, including when their values are zero. If a deployment accepts abbreviated human-readable versions, omitted minor or patch numbers MUST be filled with zero before encoding. For example, 1.2 and 1.2.0 both encode the release-number portion as [1,2,0]. The fourth integer MUST encode the release stage, using the values below. It MUST be present for both final releases and pre-releases. A final release MUST end immediately after its release-stage integer, which is zero. A pre-release MUST encode zero or more non-negative numeric suffix integers after its release-stage integer, followed by the end marker -24. Numeric suffix integers MUST be preserved in order, including trailing zero values. The end marker MUST be the final integer in the complete encoding and MUST NOT be used as a release-stage integer or a suffix integer. Semantic Versioning permits arbitrary pre-release identifiers and build metadata. This specification only defines encodings for alpha, beta, and release-candidate pre-release classes. Because suit-parameter-version exists solely to enable the Manifest Processor to make a decision about version compatibility, and because build metadata is ignored for semantic-version precedence, build metadata MUST NOT be included. In semantic versioning terminology: The first integer represents the major number. This indicates breaking changes to the component. The second integer represents the minor number. This is typically reserved for new features or large, non-breaking changes. The third integer is the patch version. This is typically reserved for bug fixes. The release-stage integer is encoded as: 0: Final Release -1: Release Candidate (RC) -2: Beta -3: Alpha The mandatory release-stage integer allows pre-releases to compare correctly with final releases without changing the integer-array comparison. For example, Version 2.0, RC1 is lower than Version 2.0.0 and higher than any Version 1.x: [2,0,0,-1,1,-24] compares as lower than [2,0,0,0]. Similarly, beta (-2) is lower than RC, and alpha (-3) is lower than beta for the same release-number portion. The end marker -24 sorts before every permitted numeric suffix integer. Consequently, a pre-release with no numeric suffix sorts before the same pre-release with a numeric suffix, including zero. For example, [1,2,0,-2,-24] (1.2.0-beta) compares as lower than [1,2,0,-2,0,-24] (1.2.0-beta.0). The end marker has a one-byte CBOR encoding and leaves the values -4 through -23 available for future release-stage assignments; this document does not define those assignments. Pre-release identifiers other than alpha, beta, and release candidate cannot be represented directly in this encoding. Deployments that need other identifiers MUST either map them to one of the defined classes while preserving the intended ordering or omit the machine-readable version field and convey the identifier as suit-text-current-version (). For example: 1.2 and 1.2.0 = [1,2,0,0]. 1.2.3 = [1,2,3,0]. 1.2-rc.3 and 1.2.0-rc.3 = [1,2,0,-1,3,-24]. 1.2-beta and 1.2.0-beta = [1,2,0,-2,-24]. 1.2.0-beta.0 = [1,2,0,-2,0,-24]. 1.2-alpha and 1.2.0-alpha = [1,2,0,-3,-24]. 1.2.3-alpha.4 = [1,2,3,-3,4,-24]. A manifest comparison value using this mapping MUST be either a complete version encoding or a non-empty prefix of a complete version encoding. A prefix selector intentionally omits subsequent integers; it does not omit zero values from within the selected prefix. The comparison rule in is unchanged: an Equal comparison against a complete encoding selects that exact version, while an Equal comparison against a shorter prefix selects all complete encodings with that prefix. For example: Equal [1] selects all versions with major number 1, including pre-releases. Equal [1,2] selects all versions with major number 1 and minor number 2, including pre-releases. Equal [1,2,0] selects the 1.2.0 release and all its pre-releases. Equal [1,2,0,-2] selects the 1.2.0 beta family, with or without numeric suffixes. Equal [1,2,0,-2,-24] selects only 1.2.0-beta. Equal [1,2,3,0] selects only the final release 1.2.3. A Greater or Equal comparison against this encoding excludes 1.2.3-alpha.4 because its release-stage integer is lower.

suit-parameter-wait-info suit-directive-wait () 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. Name Encoding Description suit-wait-event-authorization int Same as suit-parameter-update-priority suit-wait-event-power int Wait until power state suit-wait-event-network int Wait until network state suit-wait-event-other-device-version See below Wait for other device to match version suit-wait-event-time uint Wait until time (seconds since 1970-01-01) suit-wait-event-time-of-day uint Wait until seconds since 00:00:00 Local Time suit-wait-event-time-of-day-utc uint Wait until seconds since 00:00:00 UTC suit-wait-event-day-of-week uint Wait until days since Sunday Local Time suit-wait-event-day-of-week-utc uint Wait until days since Sunday UTC Local Time means the Recipient's configured local civil time zone at the time the wait event is evaluated, including any daylight-saving-time rules available to the Recipient. If the local time zone changes while a Recipient is waiting, the Recipient reevaluates the wait event using the updated time-zone configuration. During daylight-saving-time transitions, a skipped local time is treated as satisfied at the first representable local time after the skipped interval, and a repeated local time is satisfied at its first occurrence. Recipients that do not have configured local-time and daylight-saving-time information MUST treat local-time wait events as unsupported. Manifest Authors SHOULD use the UTC wait events when a deployment does not have a common local-time policy. suit-wait-event-other-device-version reuses the encoding of SUIT_Parameter_Version_Match. It is encoded as a sequence that contains an opaque bstr identifier for the other device and a list of one or more SUIT_Parameter_Version_Match. This document does not assign a namespace for the identifier. For interoperable use, the deployment profile MUST define the identifier namespace and byte-string encoding, the scope within which identifiers are unique, the mechanism by which the Recipient obtains the referenced device's version, and that device's version encoding. For example, a profile might use a fixed-width binary device identifier or the binary encoding of a management-inventory key. Manifests using this event are not portable between deployments that use different definitions. A Recipient MUST treat suit-wait-event-other-device-version as unsupported when these definitions are unavailable.

suit-parameter-component-metadata In some instances, a system needs 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 text-string values in this structure MUST be encoded as UTF-8 text containing only characters in Unicode general categories L, M, N, P, S, or Zs. Text-string values are intended for 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 , Sections 8.4.10.4, 8.4.10.5, and 8.4.10.6. Therefore, the component metadata parameter MUST be set in advance of the component being fetched, copied into, or written.

Creator Sometimes, management of file systems requires that the creator of each file is correctly recorded. Because the default creator of files will be the update agent, this can obscure the actual creator of each file. The Creator metadata element allows overriding the default behaviour and setting the correct creator. The creator is defined as follows:

The actor ID can be whatever is most appropriate for any given system. For example, the actor ID might be a string (e.g., username), integer (e.g., POSIX userid), or UUID (e.g., TEEP TA UUID).

Creation & Modification Time The creation and modification times are defined by CBOR time types. These are defined in , Section 3.4.2. The CBOR tag is REQUIRED when either creation or modification time are provided. The following map entries are excerpted from SUIT_Component_Metadata:

#6.1(uint), ? suit-meta-creation-time => #6.1(uint), ]]>

Component Default Permissions Typical permissions management systems require read, write, and execute permissions that are applied to all users who do not have their own explicit permissions. These are the default permissions for the current component. Default permissions are described by the following CDDL:

User, Role, Group permissions Many filesystems have users and groups. Additionally some have roles. Actors that have these associations can have specific permissions associated with them for each component. Each of these sets of permissions is defined the same way: with a map of actor identifiers to permissions.

SUIT_meta_permissions } ]]>

The SUIT_meta_actor_id is the same as defined for Creator, .

File Type File Type typically identifies whether a file is a directory, regular file, or symbolic link. If not specified, File Type defaults to regular file. This enables specific management operations for SUIT command sequences: To create a directory Set the Component Index to the Component Identifier of the directory to be created Set the Component metadata, including the file type for directory Set suit-parameter-content to an empty bstr Invoke suit-directive-write To create a symbolic link Set the Component Index to the Component Identifier of the link to be created Set the Component metadata, including the file type for symbolic link Set suit-parameter-content to the link target Invoke suit-directive-write Both the Component Identifier naming the symbolic link and the link target carried in suit-parameter-content are untrusted inputs subject to local authorization. Authorization to create the link does not by itself authorize access to every object that the link could reference. For example, the following Payload Fetch & Install sequences will create a new /usr/local/bin directory, download https://cdn.example/example3.bin into a new file: /usr/local/bin/example3, then create a symlink at /usr/bin/example that points to /usr/local/bin/example3. Common has components for: /usr/bin/example /usr/local/bin /usr/local/bin/example3 Payload fetch: set component index = 1 set parameters: content = h'' metadata = {file-type: directory} write set component index = 2 set URI = "https://cdn.example/example3.bin" fetch condition image digest Install: set component index = 0 set parameters: content = "/usr/local/bin/example3" metadata = {file-type: symlink} write

Extension Commands The following table defines the semantics of the commands defined in this specification in the same way as in the Abstract Machine Description, Section 6.4, of . All commands defined in this specification are OPTIONAL to implement. Command Name CDDL Identifier Semantic of the Operation Use Before suit-condition-use-before assert(now() < current.params[use-before]) Check Image Not Match suit-condition-image-not-match assert(not binary-match(digest(current), current.params[digest])) Check Minimum Battery suit-condition-minimum-battery assert(battery >= current.params[minimum-battery]) Check Update Authorized suit-condition-update-authorized assert( isAuthorized( current.params[priority])) Check Version suit-condition-version assert(version_check(current, current.params[version])) Wait For Event suit-directive-wait until event(arg), wait Override Multiple suit-directive-override-multiple components[i].params[k] := v for-each k,v in d for-each i,d in arg Copy Params suit-directive-copy-params current.params[k] = components[i].params[k] for k in l for i,l in arg

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 is to be installed. The recipient evaluates the current time against the suit-parameter-use-before parameter (), 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.

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

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 a primary cell is a single-use, non-rechargeable battery and energy budgeting is therefore a one-way operation. 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 ().

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 () provides an integer priority level that the application can use to determine whether or not to authorize the update. Smaller integer values indicate higher priority; deployment policy defines the action taken for a given priority. suit-condition-update-authorized is OPTIONAL to implement.

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

suit-directive-wait suit-directive-wait directs the manifest processor to pause until a specified event occurs. Some possible events include: Authorization External power Network availability Other device firmware version Time Time of day Day of week

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. Implementations can structure code so 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:

{+ $$SUIT_Parameters} } ]]>

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:

[+ int] } ]]>

Operational and Deployment Considerations This document defines how update-management information is encoded in a SUIT manifest. Some of that information depends on local device configuration and therefore cannot be fully defined by the manifest itself. For each extension used by a deployment, the deployment profile MUST define the applicable local interpretation and the source of any information needed to evaluate it. For example, a deployment profile may indicate: how actor identifiers and permission values are mapped to the Recipient's local access-control mechanisms; where battery-level information is obtained, the required accuracy and freshness of that information, and the behaviour when it is unavailable; the meanings assigned to update-priority values and the authorization policy associated with those values; which local events indicate that time, network, power, authorization, and other wait conditions have been satisfied; and the identifier namespace, version-information source, and version encoding used for other-device version conditions, as described in . A management interface SHOULD report which update-management extensions a Recipient supports. It SHOULD also report whether an update was rejected, has failed, or is waiting, together with the command, parameter, or event responsible for that state. Without such information, an operator might be unable to distinguish an unsupported manifest from a failed or indefinitely waiting update. For updates that can enter a waiting state, the deployment specification MUST define whether that state persists across a Recipient restart and how an operator can cancel the wait. It MUST also define whether a deployment-specific timeout applies. A deployment MAY permit an indefinite wait, but that choice needs to be explicit so that management systems and operators can distinguish intended behaviour from a stalled update. These deployment requirements do not introduce additional fields or change the SUIT wire format. They define the local configuration and management behaviour needed to use the extensions in this document interoperably.

IANA Considerations IANA is requested to allocate the commands, parameters, and metadata values shown in the following tables in the registries of the Software Update for the Internet of Things (SUIT) registry group .

SUIT Envelope Elements Label Name Reference 14 CoSWID

SUIT Manifest Elements Label Name Reference 6 Set Version 14 CoSWID

SUIT Commands Label Name Reference 4 Use Before 25 Image Not Match 26 Minimum Battery 27 Update Authorized 28 Version 29 Wait For Event 34 Override Multiple 35 Copy Params

SUIT Parameters Label Name Reference 4 Use Before 26 Minimum Battery 27 Update Priority 28 Version 29 Wait Info 30 Component Metadata

SUIT Component Text Values Label Name Reference 7 Component Version Required 8 Current Version

Security Considerations This document extends the SUIT manifest specification. The extensions defined here are optional and do not make support for update-management extensions mandatory for implementations of the base SUIT manifest specification. A detailed security treatment can be found in the architecture and in the information model documents. The free-text fields introduced by and are intended solely for human consumption. Recipients MUST treat those values as untrusted input: they MUST NOT evaluate the text, execute embedded markup, or override machine-readable decisions derived from suit-set-version or suit-parameter-version. Implementations SHOULD bound the length of displayed text to mitigate interface flooding and log injection. The suit-coswid element can expose detailed software identity and SBOM information. Such information can help authorized operators assess inventory, vulnerability exposure, and compliance, but the same information can also help an attacker or unauthorized observer quickly identify software components and versions on a device. Deployments SHOULD treat manifests containing suit-coswid as sensitive metadata, limit access to authorized parties, and consider using severable suit-coswid content so that intermediaries and Recipients that do not need this metadata can discard it without invalidating the manifest signature. Component metadata () can expose operator identifiers, file paths, or other locally meaningful strings. Deployments SHOULD validate these values against local policy before applying them, and MUST handle missing or malformed metadata defensively so that the update agent does not escalate privileges or disclose sensitive information inadvertently. Recipients that map Component Identifiers to file-system paths MUST defend against path traversal and symbolic-link races. Before a fetch, copy, or write, the Recipient MUST ensure that the resolved destination remains within storage authorized for the current component and manifest authority. This requirement applies both to pre-existing links and to links created by an earlier command or dependency manifest. Path validation and the file-system operation MUST be performed atomically with respect to namespace changes, or using descriptor-relative or non-link-following operations that provide an equivalent guarantee. A Recipient MUST NOT follow a symbolic link across component or authority boundaries unless local policy explicitly authorizes both the resolved target and that use of the link.

Contributors Hannes Tschofenig contributed the operational and deployment considerations in this document.

Acknowledgements The authors would like to thank Roman Danyliw, Mohamed Boucadair, Mahesh Jethanandani, Andy Newton, and Éric Vyncke for their detailed IESG reviews and constructive suggestions. The authors also thank Hannes Tschofenig for the IoT Directorate review, Roni Even for the GEN-ART review, Niclas Comstedt for the Operations Directorate review, and Russ Housley for the ARTART review. Their comments substantially improved the clarity, interoperability, operational guidance, and security considerations of this document.

ISO/IEC 19770-2:2015 Software Identification (SWID) tags provide an extensible XML-based structure to identify and describe individual software components, patches, and installation bundles. SWID tag representations can be too large for devices with network and storage constraints. This document defines a concise representation of SWID tags: Concise SWID (CoSWID) tags. CoSWID supports a set of semantics and features that are similar to those for SWID tags, as well as new semantics that allow CoSWIDs to describe additional types of information, all in a more memory-efficient format. Arm Limited University of Applied Sciences Bonn-Rhein-Sieg Fraunhofer SIT Inria Nordic Semiconductor This specification describes the format of a manifest. A manifest is a bundle of metadata about code/data obtained by a recipient (chiefly the firmware for an Internet of Things (IoT) device), where to find the code/data, the devices to which it applies, and cryptographic information protecting the manifest. Software updates and Trusted Invocation both tend to use sequences of common operations, so the manifest encodes those sequences of operations, rather than declaring the metadata. The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack. This document obsoletes RFC 7049, providing editorial improvements, new details, and errata fixes while keeping full compatibility with the interchange format of RFC 7049. It does not create a new version of the format. This document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Vulnerabilities with Internet of Things (IoT) devices have raised the need for a reliable and secure firmware update mechanism that is also suitable for constrained devices. Ensuring that devices function and remain secure over their service lifetime requires such an update mechanism to fix vulnerabilities, update configuration settings, and add new functionality. One component of such a firmware update is a concise and machine-processable metadata document, or manifest, that describes the firmware image(s) and offers appropriate protection. This document describes the information that must be present in the manifest. Vulnerabilities in Internet of Things (IoT) devices have raised the need for a reliable and secure firmware update mechanism suitable for devices with resource constraints. Incorporating such an update mechanism is a fundamental requirement for fixing vulnerabilities, but it also enables other important capabilities such as updating configuration settings and adding new functionality. In addition to the definition of terminology and an architecture, this document provides the motivation for the standardization of a manifest format as a transport-agnostic means for describing and protecting firmware updates.

Full CDDL The following definitions use the CDDL notation specified in and MUST be appended to the SUIT Manifest CDDL. The SUIT CDDL is defined in Appendix A of . The combined schema also requires the COSE CDDL definitions used by the SUIT Manifest and the CoSWID CDDL definitions in Section 2.10 of , which define concise-swid-tag. When assembling these definitions into a single CDDL schema, rename the CoSWID-local rule named label and all references to that rule within the CoSWID definitions to coswid-label, to avoid a rule-name collision with COSE. This local rule-name change does not change the encoded data.

bstr .cbor SUIT_Condition_Version_Comparison_Value ) $$SUIT_severable-members-extensions //= ( suit-coswid => bstr .cbor concise-swid-tag) $$severable-manifest-members-choice-extensions //= ( suit-coswid => bstr .cbor concise-swid-tag / SUIT_Digest ) SUIT_Condition //= ( suit-condition-image-not-match, SUIT_Rep_Policy) SUIT_Condition //= ( suit-condition-use-before, SUIT_Rep_Policy) SUIT_Condition //= ( suit-condition-minimum-battery, SUIT_Rep_Policy) SUIT_Condition //= ( suit-condition-update-authorized, SUIT_Rep_Policy) SUIT_Condition //= ( suit-condition-version, SUIT_Rep_Policy) SUIT_Directive //= ( suit-directive-wait, SUIT_Rep_Policy) SUIT_Directive //= ( suit-directive-override-multiple, SUIT_Override_Mult_Arg) SUIT_Directive //=( suit-directive-copy-params, SUIT_Directive_Copy_Params) SUIT_Override_Mult_Arg = { + uint => {+ $$SUIT_Parameters} } SUIT_Directive_Copy_Params = { + uint => [+ int] } SUIT_Wait_Event = { + SUIT_Wait_Events } SUIT_Wait_Events //= (suit-wait-event-authorization => int) SUIT_Wait_Events //= (suit-wait-event-power => int) SUIT_Wait_Events //= (suit-wait-event-network => int) SUIT_Wait_Events //= (suit-wait-event-other-device-version => SUIT_Wait_Event_Argument_Other_Device_Version) SUIT_Wait_Events //= (suit-wait-event-time => uint); Timestamp SUIT_Wait_Events //= (suit-wait-event-time-of-day => uint); Time of Day (seconds since 00:00:00) SUIT_Wait_Events //= (suit-wait-event-day-of-week => uint); Days since Sunday SUIT_Wait_Events //= (suit-wait-event-time-of-day-utc => uint); Time of Day UTC (seconds since 00:00:00) SUIT_Wait_Events //= (suit-wait-event-day-of-week-utc => uint); Days since Sunday UTC SUIT_Wait_Event_Argument_Other_Device_Version = [ other-device: bstr, other-device-version: [ + SUIT_Parameter_Version_Match ] ] $$SUIT_Parameters //= (suit-parameter-use-before => uint) $$SUIT_Parameters //= (suit-parameter-minimum-battery => uint) $$SUIT_Parameters //= (suit-parameter-update-priority => int) $$SUIT_Parameters //= (suit-parameter-version => bstr .cbor SUIT_Parameter_Version_Match) $$SUIT_Parameters //= (suit-parameter-wait-info => bstr .cbor SUIT_Wait_Event) $$SUIT_Parameters //= (suit-parameter-component-metadata => bstr .cbor SUIT_Component_Metadata) SUIT_Parameter_Version_Match = [ suit-condition-version-comparison-type: SUIT_Condition_Version_Comparison_Types, suit-condition-version-comparison-value: SUIT_Condition_Version_Comparison_Value ] SUIT_Condition_Version_Comparison_Types /= suit-condition-version-comparison-greater SUIT_Condition_Version_Comparison_Types /= suit-condition-version-comparison-greater-equal SUIT_Condition_Version_Comparison_Types /= suit-condition-version-comparison-equal SUIT_Condition_Version_Comparison_Types /= suit-condition-version-comparison-lesser-equal SUIT_Condition_Version_Comparison_Types /= suit-condition-version-comparison-lesser suit-condition-version-comparison-greater = 1 suit-condition-version-comparison-greater-equal = 2 suit-condition-version-comparison-equal = 3 suit-condition-version-comparison-lesser-equal = 4 suit-condition-version-comparison-lesser = 5 SUIT_Condition_Version_Comparison_Value = [+int] SUIT_Component_Metadata = { ? suit-meta-default-permissions => SUIT_meta_permissions, ? suit-meta-user-permissions => SUIT_meta_permission_map, ? suit-meta-group-permissions => SUIT_meta_permission_map, ? suit-meta-role-permissions => SUIT_meta_permission_map, ? suit-meta-file-type => SUIT_Filetype, ? suit-meta-modification-time => #6.1(uint), ? suit-meta-creation-time => #6.1(uint), ? suit-meta-creator => SUIT_meta_actor_id, * $$SUIT_Component_Metadata_Extensions } suit-meta-default-permissions = 1 suit-meta-user-permissions = 2 suit-meta-group-permissions = 3 suit-meta-role-permissions = 4 suit-meta-file-type = 5 suit-meta-modification-time = 6 suit-meta-creation-time = 7 suit-meta-creator = 8 SUIT_meta_permissions = uint .bits SUIT_meta_permission_bits SUIT_meta_permission_bits = &( write_attr_ex: 13, read_attr_ex: 12, sync: 11, delete: 10, recurse_delete: 9, write_attr: 8, change_owner: 7, change_perm: 6, read_perm: 5, read_attr: 4, createdir_append: 3, list_read: 2, create_write: 1, traverse_exec: 0, * $$SUIT_meta_permission_bits_extensions ) SUIT_meta_permission_map = { + SUIT_meta_actor_id => SUIT_meta_permissions } SUIT_meta_actor_id = UUID_Tagged / bstr / tstr / int UUID_Tagged = #6.37(bstr) SUIT_Filetype /= suit-filetype-regular SUIT_Filetype /= suit-filetype-directory SUIT_Filetype /= suit-filetype-symlink suit-filetype-regular = 1 suit-filetype-directory = 2 suit-filetype-symlink = 3 $$suit-text-component-key-extensions //= ( suit-text-version-required => tstr) $$suit-text-component-key-extensions //= ( suit-text-current-version => tstr) suit-set-version = 6 suit-coswid = 14 suit-condition-use-before = 4 suit-condition-image-not-match = 25 suit-condition-minimum-battery = 26 suit-condition-update-authorized = 27 suit-condition-version = 28 suit-directive-wait = 29 suit-directive-override-multiple = 34 suit-directive-copy-params = 35 suit-wait-event-authorization = 1 suit-wait-event-power = 2 suit-wait-event-network = 3 suit-wait-event-other-device-version = 4 suit-wait-event-time = 5 suit-wait-event-time-of-day = 6 suit-wait-event-day-of-week = 7 suit-wait-event-time-of-day-utc = 8 suit-wait-event-day-of-week-utc = 9 suit-parameter-use-before = 4 suit-parameter-minimum-battery = 26 suit-parameter-update-priority = 27 suit-parameter-version = 28 suit-parameter-wait-info = 29 suit-parameter-component-metadata = 30 suit-text-version-required = 7 suit-text-current-version = 8 ]]>