idnits 2.17.00 (12 Aug 2021) /tmp/idnits7317/draft-ietf-suit-report-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document date (12 January 2022) is 122 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 206 -- Looks like a reference, but probably isn't: '0' on line 205 -- Looks like a reference, but probably isn't: '2' on line 206 == Outdated reference: A later version (-17) exists of draft-ietf-suit-manifest-16 Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SUIT B. Moran 3 Internet-Draft Arm Limited 4 Intended status: Informational H. Birkholz 5 Expires: 16 July 2022 Fraunhofer SIT 6 12 January 2022 8 Secure Reporting of Update Status 9 draft-ietf-suit-report-01 11 Abstract 13 The Software Update for the Internet of Things (SUIT) manifest 14 provides a way for many different update and boot workflows to be 15 described by a common format. However, this does not provide a 16 feedback mechanism for developers in the event that an update or boot 17 fails. 19 This specification describes a lightweight feedback mechanism that 20 allows a developer in possession of a manifest to reconstruct the 21 decisions made and actions performed by a manifest processor. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on 16 July 2022. 40 Copyright Notice 42 Copyright (c) 2022 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 47 license-info) in effect on the date of publication of this document. 48 Please review these documents carefully, as they describe your rights 49 and restrictions with respect to this document. Code Components 50 extracted from this document must include Revised BSD License text as 51 described in Section 4.e of the Trust Legal Provisions and are 52 provided without warranty as described in the Revised BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 3 58 3. The SUIT Record . . . . . . . . . . . . . . . . . . . . . . . 3 59 4. The SUIT Report . . . . . . . . . . . . . . . . . . . . . . . 6 60 5. Attestation . . . . . . . . . . . . . . . . . . . . . . . . . 7 61 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 62 7. Security Considerations . . . . . . . . . . . . . . . . . . . 7 63 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 64 9. Normative References . . . . . . . . . . . . . . . . . . . . 7 65 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 67 1. Introduction 69 A SUIT manifest processor can fail to install or boot an update for 70 many reasons. Frequently, the error codes generated by such systems 71 fail to provide developers with enough information to find root 72 causes and produce corrective actions, resulting in extra effort to 73 reproduce failures. Logging the results of each SUIT command can 74 simplify this process. 76 While it is possible to report the results of SUIT commands through 77 existing logging or attestation mechanisms, this comes with several 78 drawbacks: 80 * data inflation, particularly when designed for text-based logging 82 * missing information elements 84 * missing support for multiple components 86 The CBOR objects defined in this document allow devices to: 88 * report a trace of how an update was performed 90 * report expected vs. actual values for critical checks 92 * describe the installation of complex multi-component architectures 94 * describe the measured properties of a system 96 * report the exact reason for a parsing failure 97 This document provides a definition of a SUIT-specific logging 98 container that may be used in a variety of scenarios. 100 2. Conventions and Terminology 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 104 "OPTIONAL" in this document are to be interpreted as described in 105 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 106 capitals, as shown here. 108 Terms used in this specification include: 110 * Boot: initialization of an executable image. Although this 111 specification refers to boot, any boot-specific operations 112 described are equally applicable to starting an executable in an 113 OS context. 115 3. The SUIT Record 117 If the developer can be assumed to have a copy of the manifest, then 118 they need little information to reconstruct what the manifest 119 processor has done. They simply need any data that influences the 120 control flow of the manifest. The manifest only supports the 121 following control flow primitives: 123 * Set Component/Dependency Index 125 * Set/Override Parameters 127 * Try-Each 129 * Run Sequence 131 * Conditions. 133 Of these, only conditions change the behavior of the processor from 134 the default, and then only when the condition fails. 136 Then, to reconstruct the flow of a manifest, all a developer needs is 137 a list of metadata about failed conditions: 139 * the current manifest 141 * the current section 143 * the offset into the current section 144 * the current component index 146 * the "reason" for failure 148 Most conditions compare a parameter to an actual value, so the 149 "reason" is typically simply the actual value. 151 Since it is possible that a non-condition command (directive) may 152 fail in an exceptional circumstance, this must be included as well. 153 However, a failed directive will terminate processing of the 154 manifest. To accommodate for a failed command and for explicit 155 "completion," an additional "result" element is added as well. In 156 the case of a command failure, the failure reason is typically a 157 numeric error code. However, these error codes need to be 158 standardised in order to be useful. 160 Reconstructing what a device has done in this way is compact, however 161 it requires some reconstruction effort. This is an issue that can be 162 solved by tooling. 164 SUIT_Record = { 165 suit-record-manifest-id => [* uint ], 166 suit-record-manifest-section => int, 167 suit-record-section-offset => uint, 168 ( 169 suit-record-component-index => uint // 170 suit-record-dependency-index => uint 171 ), 172 suit-record-properties => SUIT_Parameters, 173 } 175 suit-record-manifest-id is used to identify which manifest contains 176 the command that caused the record to be generated. The manifest id 177 is a list of integers that form a walk of the manifest tree, starting 178 at the root. An empty list indicates that the command was contained 179 in the root manifest. If the list is not empty, the command was 180 contained in one of the root manifest's dependencies, or nested even 181 further below that. 183 For example, suppose that the root manifest has 3 dependencies and 184 each of those dependencies has 2 dependencies of its own: 186 * Root 188 - Dependency A 190 o Dependency A0 191 o Dependency A1 193 - Dependency B 195 o Dependency B0 197 o Dependency B1 199 - Dependency C 201 o Dependency C0 203 o Dependency C1 205 A manifest-id of [1,0] would indicate that the current command was 206 contained within Dependency B0. Similarly, a manifest-id of [2,1] 207 would indicate Dependency C1 209 suit-record-manifest-section indicates which section of the manifest 210 was active. This is used in addition to an offset so that the 211 developer can index into severable sections in a predictable way. 212 The value of this element is the value of the key that identified the 213 section in the manifest. 215 suit-record-section-offset is the number of bytes into the current 216 section at which the current command is located. 218 suit-record-component-index is the index of the component that was 219 specified at the time that the report was generated. This field is 220 necessary due to the availability of set-current-component values of 221 True and a list of components. Both of these values cause the 222 manifest processor to loop over commands using a series of component- 223 ids, so the developer needs to know which was selected when the 224 command executed. 226 suit-record-dependency-index is similar to suit-record-component- 227 index but is used to identify the dependency that was active. 229 suit-record-properties contains any measured properties that led to 230 the command failure. For example, this could be the actual value of 231 a SUIT_Digest or class identifier. This is encoded in a 232 SUIT_Parameters block as defined in [I-D.ietf-suit-manifest]. 234 4. The SUIT Report 236 Some metadata is common to all records, such as the root manifest: 237 the manifest that is the entry-point for the manifest processor. 238 This metadata is aggregated with a list of SUIT_Records. The 239 SUIT_Report may also contain a list of any system properties that 240 were measured and reported, and a reason for a failure if one 241 occured. 243 SUIT_Report = { 244 suit-report-manifest-digest => SUIT_Digest, 245 ? suit-report-manifest-uri => tstr, 246 ? suit-report-nonce => bstr, 247 suit-report-records => [ * SUIT_Record ], 248 ? suit-system-properties => [ + system-property-claims ], 249 suit-report-result => true / { 250 suit-report-result-code => int, ; could condense to enum later 251 suit-report-result-record => SUIT_Record, 252 } 253 } 254 system-property-claims = { 255 system-component-id => SUIT_Component_Identifier, 256 + SUIT_Parameters, 257 } 259 suit-report-manifest-digest provides a SUIT_Digest (as defined in 260 [I-D.ietf-suit-manifest]) that is the characteristic digest of the 261 Root manifest. 263 suit-report-manifest-uri provides the reference URI that was provided 264 in the root manifest. 266 suit-report-nonce provides a container for freshness or replay 267 protection information. This field MAY be omitted where the suit- 268 report is authenticated within a container that provides freshness 269 already. For example, attestation evidence typically contains a 270 proof of freshness. 272 suit-system-properties provides a list of measured or asserted 273 properties of the system that creates the suit report. These 274 properties are scoped by component identifier. Because this list is 275 expected to be constructed on the fly by a constrained node, 276 component identifiers may appear more than once. A recipient may 277 convert the result to a more conventional structure: 279 SUIT_Record_System_Properties = { 280 * component-id => { 281 + SUIT_Parameters, 282 } 283 } 285 suit-report-records is a list of 0 or more SUIT Records. Because 286 SUIT Records are only generated on failure, in simple cases this can 287 be an empty list. 289 suit-report-result provides a mechanism to show that the SUIT 290 procedure completed successfully (value is true) or why it failed 291 (value is a map of an error code and a SUIT_Record). 293 The suit-report-result-code indicates the reason for the failure. 294 Values are expected to be CBOR parsing failures, Schema validation 295 failures, COSE validation failures or SUIT processing failures. 297 The suit-report-result-record indicates the exact point in the 298 manifest or manifest dependency tree where the error occured. 300 5. Attestation 302 This document contains three sections that are expected to be useful 303 in attestation evidence: 305 * suit-report-records 307 * suit-system-properties 309 * suit-report-result 311 6. IANA Considerations 313 IANA is requested to allocate a CBOR tag for the SUIT Report. 315 7. Security Considerations 317 The SUIT Report should either be carried over a secure transport, or 318 signed, or both. Ideally, attestation should be used to prove that 319 the report was generated by legitimate hardware. 321 8. Acknowledgements 323 9. Normative References 325 [I-D.ietf-suit-manifest] 326 Moran, B., Tschofenig, H., Birkholz, H., and K. Zandberg, 327 "A Concise Binary Object Representation (CBOR)-based 328 Serialization Format for the Software Updates for Internet 329 of Things (SUIT) Manifest", Work in Progress, Internet- 330 Draft, draft-ietf-suit-manifest-16, 25 October 2021, 331 . 334 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 335 Requirement Levels", BCP 14, RFC 2119, 336 DOI 10.17487/RFC2119, March 1997, 337 . 339 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 340 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 341 May 2017, . 343 Authors' Addresses 345 Brendan Moran 346 Arm Limited 348 Email: Brendan.Moran@arm.com 350 Henk Birkholz 351 Fraunhofer SIT 353 Email: henk.birkholz@sit.fraunhofer.de