idnits 2.17.1 draft-moran-suit-report-00.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 copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (October 23, 2020) is 1271 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 200 -- Looks like a reference, but probably isn't: '0' on line 199 -- Looks like a reference, but probably isn't: '2' on line 200 == Outdated reference: A later version (-25) exists of draft-ietf-suit-manifest-09 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 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 October 23, 2020 5 Expires: April 26, 2021 7 Secure Reporting of Update Status 8 draft-moran-suit-report-00 10 Abstract 12 The Software Update for the Internet of Things (SUIT) manifest 13 provides a way for many different update and boot workflows to be 14 described by a common format. However, this does not provide a 15 feedback mechanism for developers in the event that an update or boot 16 fails. 18 This specification describes a lightweight feedback mechanism that 19 allows a developer in possession of a manifest to reconstruct the 20 decisions made and actions performed by a manifest processor. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on April 26, 2021. 39 Copyright Notice 41 Copyright (c) 2020 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified 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 . . . . . . . . . . . . . . . . . . . . . . . 5 60 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 61 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6 62 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6 63 8. Normative References . . . . . . . . . . . . . . . . . . . . 6 64 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 66 1. Introduction 68 A SUIT manifest processor can fail to install or boot an update for 69 many reasons. Frequently, the error codes generated by such systems 70 fail to provide developers with enough information to find root 71 causes and produce corrective actions, resulting in extra effort to 72 reproduce failures. Logging the results of each SUIT command can 73 simplify this process. 75 While it is possible to report the results of SUIT commands through 76 existing logging or attestation mechanisms, this comes with several 77 drawbacks: 79 - data inflation, particularly when designed for text-based logging 81 - missing information elements 83 - missing support for multiple components 85 The CBOR objects defined in this document allow devices to: 87 - report a trace of how an update was performed 89 - report expected vs. actual values for critical checks 91 - describe the installation of complex multi-component architectures 93 This document provides a definition of a SUIT-specific logging 94 container that may be used in a variety of scenarios. 96 2. Conventions and Terminology 98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 99 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 100 "OPTIONAL" in this document are to be interpreted as described in 101 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 102 capitals, as shown here. 104 Terms used in this specification include: 106 - Boot: initialization of an executable image. Although this 107 specification refers to boot, any boot-specific operations 108 described are equally applicable to starting an executable in an 109 OS context. 111 3. The SUIT Record 113 If the developer can be assumed to have a copy of the manifest, then 114 they need little information to reconstruct what the manifest 115 processor has done. They simply need any data that influences the 116 control flow of the manifest. The manifest only supports the 117 following control flow primitives: 119 - Set Component/Dependency Index 121 - Set/Override Parameters 123 - Try-Each 125 - Run Sequence 127 - Conditions. 129 Of these, only conditions change the behavior of the processor from 130 the default, and then only when the condition fails. 132 Then, to reconstruct the flow of a manifest, all a developer needs is 133 a list of metadata about failed conditions: 135 - the current manifest 137 - the current section 139 - the offset into the current section 141 - the current component index 143 - the "reason" for failure 144 Most conditions compare a parameter to an actual value, so the 145 "reason" is typically simply the actual value. 147 Since it is possible that a non-condition command may fail in an 148 exceptional circumstance, this must be included as well. To 149 accommodate for a failed command, the list of failed conditions is 150 expanded to be a list of failed commands instead. In the case of a 151 command failure, the failure reason is typically a numeric error 152 code. 154 Reconstructing what a device has done in this way is compact, however 155 it requires some reconstruction effort. This is an issue that can be 156 solved by tooling. 158 suit-record = { 159 suit-record-manifest-id => [* uint ], 160 suit-record-manifest-section => int, 161 suit-record-section-offset => uint, 162 ( 163 suit-record-component-index => uint // 164 suit-record-dependency-index => uint 165 ), 166 suit-record-failure-reason => SUIT_Parameters, 167 } 169 suit-record-manifest-id is used to identify which manifest contains 170 the command that caused the record to be generated. The manifest id 171 is a list of integers that form a walk of the manifest tree, starting 172 at the root. An empty list indicates that the command was contained 173 in the root manifest. If the list is not empty, the command was 174 contained in one of the root manifest's dependencies, or nested even 175 further below that. 177 For example, suppose that the root manifest has 3 dependencies and 178 each of those dependencies has 2 dependencies of its own: 180 - Root 182 o Dependency A 184 * Dependency A0 186 * Dependency A1 188 o Dependency B 190 * Dependency B0 191 * Dependency B1 193 o Dependency C 195 * Dependency C0 197 * Dependency C1 199 A manifest-id of [1,0] would indicate that the current command was 200 contained within Dependency B0. Similarly, a manifest-id of [2,1] 201 would indicate Dependency C1 203 suit-record-manifest-section indicates which section of the manifest 204 was active. This is used in addition to an offset so that the 205 developer can index into severable sections in a predictable way. 206 The value of this element is the value of the key that identified the 207 section in the manifest. 209 suit-record-section-offset is the number of bytes into the current 210 section at which the current command is located. 212 suit-record-component-index is the index of the component that was 213 specified at the time that the report was generated. This field is 214 necessary due to the availability of set-current-component values of 215 True and a list of components. Both of these values cause the 216 manifest processor to loop over commands using a series of component- 217 ids , so the developer needs to know which was selected when the 218 command executed. 220 suit-record-dependency-index is similar to suit-record-component- 221 index but is used to identify the dependency that was active. 223 suit-record-failure-reason contains the reason for the command 224 failure. For example, this could be the actual value of a 225 SUIT_Digest or class identifier. This is encoded in a 226 SUIT_Parameters block as defined in [I-D.ietf-suit-manifest]. If it 227 is not a condition that has failed, but a directive, then the value 228 of this element is an integer that represents an implementation- 229 defined failure code. 231 4. The SUIT Report 233 Some metadata is common to all records, such as the root manifest: 234 the manifest that is the entry-point for the manifest processor. 235 This metadata is aggregated with a list of suit-records. 237 suit-report = { 238 suit-report-manifest-digest => SUIT_Digest, 239 ? suit-report-manifest-uri => tstr, 240 suit-report-records => [ *suit-record ] 241 } 243 suit-report-manifest-digest provides a SUIT_Digest (as defined in 244 [I-D.ietf-suit-manifest]) that is the characteristic digest of the 245 Root manifest. 247 suit-report-manifest-uri provides the reference URI that was provided 248 in the root manifest. 250 suit-report-records is a list of 0 or more SUIT Records. Because 251 SUIT Records are only generated on failure, in simple cases this can 252 be an empty list. 254 5. IANA Considerations 256 IANA is requested to allocate a CBOR tag for the SUIT Report. 258 6. Security Considerations 260 The SUIT Report should either be carried over a secure transport, or 261 signed, or both. Ideally, attestation should be used to prove that 262 the report was generated by legitimate hardware. 264 7. Acknowledgements 266 8. Normative References 268 [I-D.ietf-suit-manifest] 269 Moran, B., Tschofenig, H., Birkholz, H., and K. Zandberg, 270 "A Concise Binary Object Representation (CBOR)-based 271 Serialization Format for the Software Updates for Internet 272 of Things (SUIT) Manifest", draft-ietf-suit-manifest-09 273 (work in progress), July 2020. 275 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 276 Requirement Levels", BCP 14, RFC 2119, 277 DOI 10.17487/RFC2119, March 1997, 278 . 280 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 281 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 282 May 2017, . 284 Author's Address 286 Brendan Moran 287 Arm Limited 289 EMail: Brendan.Moran@arm.com