idnits 2.17.1 draft-pagel-suit-manifest-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 date (September 12, 2018) is 2053 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '20' on line 280 -- Looks like a reference, but probably isn't: '64' on line 285 -- Looks like a reference, but probably isn't: '16' on line 297 -- Looks like a reference, but probably isn't: '2' on line 322 -- Looks like a reference, but probably isn't: '1' on line 429 ** Downref: Normative reference to an Informational draft: draft-ietf-suit-architecture (ref. 'I-D.ietf-suit-architecture') == Outdated reference: A later version (-13) exists of draft-ietf-suit-information-model-01 ** Downref: Normative reference to an Informational draft: draft-ietf-suit-information-model (ref. 'I-D.ietf-suit-information-model') Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 SUIT M. Pagel 2 Internet Draft Microsoft Corp 3 Intended status: Standards Track September 12, 2018 4 Expires: March 2018 6 A Binary Manifest Serialization Format 7 draft-pagel-suit-manifest-00 9 Abstract 11 This specification describes the serialization format of a software 12 update manifest that is suitable for low-end devices as it 13 eliminates the need to execute a parser. 15 A manifest is a metadata structure describing the firmware, the 16 devices to which it applies, and cryptographic information 17 protecting the manifest. 19 Status of this Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF), its areas, and its working groups. Note that 26 other groups may also distribute working documents as Internet- 27 Drafts. 29 Internet-Drafts are draft documents valid for a maximum of six 30 months and may be updated, replaced, or obsoleted by other documents 31 at any time. It is inappropriate to use Internet-Drafts as 32 reference material or to cite them other than as "work in progress." 34 The list of current Internet-Drafts can be accessed at 35 http://www.ietf.org/ietf/1id-abstracts.txt 37 The list of Internet-Draft Shadow Directories can be accessed at 38 http://www.ietf.org/shadow.html 40 This Internet-Draft will expire on March 12, 2019. 42 Copyright Notice 44 Copyright (c) 2018 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with 52 respect to this document. Code Components extracted from this 53 document must include Simplified BSD License text as described in 54 Section 4.e of the Trust Legal Provisions and are provided without 55 warranty as described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction...................................................2 60 2. Pros and Cons vs CBOR based Format.............................5 61 3. Manifest Format in Detail......................................5 62 4. Security Considerations........................................8 63 4.1. MFSR1: Monotonic Sequence Numbers.........................8 64 4.2. MFSR2: Vendor, Device-type Identifiers....................8 65 4.3. MFSR3: Best-Before Timestamps.............................8 66 4.4. MFSR5: Cryptographic Authenticity.........................9 67 4.5. MFSR4a/b: Authenticated Payload Type and Storage Location.9 68 4.6. MFSR4c: Authenticated Remote Resource Location............9 69 4.7. MFSR4d: Secure Boot.......................................9 70 4.8. MFSR4e: Authenticated precursor images....................9 71 4.9. MFSR4f: Authenticated Vendor and Class IDs................9 72 4.10. MFSR6: Rights Require Authenticity.......................9 73 4.11. MFSR7: Firmware encryption..............................10 74 5. IANA Considerations...........................................10 75 6. Security Considerations.......................................10 76 7. Mailing List Information......................................10 77 8. References....................................................10 78 8.1. Normative References.....................................10 79 Author's Addresses...............................................11 81 1. Introduction 83 This document describes a binary format for secured, signed software 84 update "manifests" that is suitable for low-end devices as it 85 eliminates the need to execute a parser. 87 The SUIT architecture and information model are designed to maximize 88 flexibility. However, in the field we expect each platform provider 89 to pick a single option to implement within their software stack to 90 keep code as small as possible. For example, basic devices typically 91 support only a single compression or crypto algorithm and associated 92 signature format. Therefore, the manifest used in the field does not 93 need to specify such algorithms as such decision have already been 94 made by the platform provider. SUIT compliant development tools or 95 Update Servers may need to support different options if they want to 96 target multiple device platforms. 98 We expect each device platform to maintain a set of policies 99 separate from the manifest, which may mandate certain software 100 layers and/or components to be present. The manifest format allows 101 for updating any number of software layers such as drivers, 102 operating systems, and application software. Each layer may consist 103 of multiple software components represented by an image of a 104 particular version of such component. Each such layer may be 105 provided and signed by a different vendor and combined into a 106 manifest set and (in footer) signed by the Network Operator as shown 107 below: 109 +------------------------------------------------+ 110 | ManifestSet Header | 111 | +--------------------------------------------+ | 112 | | Manifest 1 Header | | 113 | | +----------------------------------------+ | | 114 | | | Component - Image 1 | | | 115 | | +----------------------------------------+ | | 116 | | ... | | 117 | | +----------------------------------------+ | | 118 | | | Component - Image n | | | 119 | | +----------------------------------------+ | | 120 | | Signature | | 121 | +--------------------------------------------+ | 122 | ... | 123 | +--------------------------------------------+ | 124 | | Manifest m | | 125 | +--------------------------------------------+ | 126 | Signature | 127 +------------------------------------------------+ 129 Manifest Structure 131 Each platform may use a Type id number to identify the type of 132 component and pass such id in the Type parameter to the installer. 133 Each type may also imply a different payload format. The platform 134 may also mandate the order and location each component type gets are 135 installed. A location may be a specific memory partition or separate 136 device such as an SD Card or might even mandate a certain base 137 memory address. A Flags parameter is provided for a vendor to pass 138 any options, such as location or preprocessing requirements, to the 139 device installer. The platform vendor would need to provide platform 140 specific specifications for the Type and Flags parameters. 142 To allow platform vendors to support multiple platforms and identify 143 such, it may use the ClassId parameter of the first manifest in a 144 set to identify the platform. Even more importantly, product 145 manufacturers use the ClassId of the last manifest in the set to 146 identify the specific model of product so that the installer can 147 ensure it uses the proper manifest file intended for the product and 148 such model also implies what platform it uses. 150 To meet privacy requirements, we recommend using transport layer 151 security / channel encryption. 153 At a bare minimum, a manifest describes a single software image to 154 run. However, manifests might expose richer information, like 155 versioning for application binary interfaces (ABI) or even 156 dependencies between components. These dependencies can be verified 157 before downloading or installing software. For example, an 158 application might depend on a particular version of an operating 159 system. Each component may expose ABIs and consume the ABIs of other 160 components. Each ABI would have a specific ABIType id associated 161 with it. To update components selectively, the manifest specifies a 162 full dependency graph for all components. 164 The Operator may deliver the latest manifests via broadcast or via 165 an Update Server. The device may call the Update Server with its 166 ClassId and current software configuration. The Update Server may 167 enforce update policies based on such configuration and deliver 168 different manifests accordingly. Policies may include enforcing a 169 certain update sequence, or throttling of installs, or selective 170 test installs, or location specific installs etc. 172 Rather than including the image URIs in the manifest, the manifest 173 includes only UUID based image descriptors called ImageUid. The 174 device installer receives the manifest and then compares the 175 ImageUids which are currently installed on the device with the ones 176 specified in the manifest and if any have changed, it may request 177 the URIs for those images for download and installation over the 178 network from the Update Server. The Update Server may use a one- 179 time or short-lived URL to limit the availability/distribution of 180 the image. The device may also send its location so that a content 181 distribution network could provide a copy from a nearby file or 182 content cache server, peer device, or in the field via USB 183 thumbdrive. The images may also be received through a broadcast from 184 other devices. The signature of the manifest guarantees the 185 manifest's authenticity. 187 2. Pros and Cons vs CBOR based Format 189 CBOR makes it easier to handle and/or skip optional or new fields 190 whereas a binary structure requires a versioned structure to 191 introduce new fields, which adds complexity to the implementation. 192 However, the binary structure has the advantage that it can be 193 loaded into memory directly without the use of a parser and 194 therefore the installer code is much simpler or smaller. As 195 installers are a common source of bugs and vulnerabilities, simple 196 code is usually considered more secure. It addresses Section 3.6/7 197 of the architecture document (Small bootloader and parser) quite 198 well. Also, the separation of image URIs allows for a much smaller 199 manifest and therefore reduces memory requirements. 201 A basic device may not be able to support many options anyways and 202 such devices are more space constrained; the binary format may be a 203 better fit. 205 A more sophisticated device may offer more options and may use CBOR 206 for other purposes anyways, then the currently proposed format may 207 be more suitable. 209 3. Manifest Format in Detail 211 The following tables show the various fields of the manifest set 212 header and signature footer and each manifest with header, image 213 array, and signature footer and the image array with the embedded 214 dependency array. To allow for simple loading, the byte order of 215 numeric fields is considered specific to the platform. 217 ManifestSetHeader 219 Type Field Description 221 UInt32 MagicValue 0x7086760e acting as a 222 static file format signature 224 UInt16 Version 1 - Version of the manifest 225 set data structure 227 UInt16 Flags Hints for device specific 228 policy engine, it can either 229 be interpreted as 16 flags, 230 integer value, or a 231 combination depending on the 232 device 234 UInt16 ManifestSetDataSize Size of the total set in 235 bytes 237 ManifestSetFooter 239 Type Field Description 241 UInt8[20] SignCertThumbprint Thumbprint of the cert 242 used to sign this 243 manifest. All zeros if the 244 manifest is unsigned. 246 UInt8[64] Signature Digital signature of all 247 the data prior to this 248 field using the signature 249 method specific to the 250 device/platform. 252 Manifest 254 Type Field Description 256 UInt16 Version Version of the manifest 257 data structure 259 UInt16 ImageCount Number of images in the 260 manifest 262 UInt16 ManifestEntrySize Size of each entry in 263 bytes, allows safe 264 interpretation even if 265 size changes due to data 266 structure version changes 268 UInt8[16] VendorId UUID5(DNS, "example.com") 270 UInt8[16] ClassId UUID5(VendorId, "Product 271 X") 273 UInt64 BuildDate Manifest creation time in 274 unix epoch time 276 ImageManifes ImageEntries Entries for the images 277 tEntry[Image 278 Count] 280 UInt8[20] SignCertThumbprint Thumbprint of the cert 281 used to sign this 282 manifest. All zeros if the 283 manifest is unsigned. 285 UInt8[64] Signature Digital signature of all 286 the data prior to this 287 field using the signature 288 method specific to the 289 device/platform. 291 ImageManifestEntry 293 Type Field Description 295 UInt8[16] ImageUid Image UID 297 UInt8[16] ComponentUid UID of the 298 Component the 299 image 300 represents. 302 UInt16 Type Component Type 303 (values specific 304 to the device 305 architecture) 307 UInt32 CompressedImageFileSize Size of the 308 image file in 309 bytes as 310 compressed 312 UInt32 UncompressedImageFileSize Size of the 313 image file in 314 bytes after it 315 is uncompressed 317 ABIDependency[2] Provides Lists any ABI 318 type and version 319 this component 320 provides 322 ABIDependency[2] DependsOn Lists any ABI 323 type and version 324 this component 325 it consumes 326 meaning depends 327 on 329 ABIDependency 331 Type Field Description 333 UInt32 Version Image UID 335 UInt32 ABIType Type of ABI interface 337 4. Security Considerations 339 This document is about a manifest format describing and protecting 340 firmware images and as such it is part of a larger solution for 341 offering a standardized way of delivering firmware updates to IoT 342 devices. A more detailed discussion about security can be found in 343 the architecture document [I-D.ietf-suit-architecture] and in the 344 information model document [I-D.ietf-suit-information-model]. The 345 next few sections address the specific security requirements as 346 defined in the information model: 348 4.1. MFSR1: Monotonic Sequence Numbers 350 The BuildDate may be used to enforce sequential updates. However, 351 there are often other methods (e.g., using a hardware root of trust 352 and e-fuses) to block the installation of compromised images. 354 4.2. MFSR2: Vendor, Device-type Identifiers 356 The array of ImageUIDs provides the specific set of images which 357 need to be installed on the device. 359 4.3. MFSR3: Best-Before Timestamps 361 This requirement appears to be optional. In case you are concerned 362 about this case, an installer could enforce that a manifest is only 363 valid for a particular timeframe from the BuildDate. The Update 364 Server would re-sign (with a new BuildDate) close to the expiry 365 time. 367 4.4. MFSR5: Cryptographic Authenticity 369 Each manifest (and each image file) is signed. 371 4.5. MFSR4a/b: Authenticated Payload Type and Storage Location 373 Each image has a Type identifier. The device software uses its own 374 policy to determine which image types are supported and which 375 location they are installed. If a component can be installed in 376 various locations, the Flags parameter can be used to specify 377 preferred location. 379 4.6. MFSR4c: Authenticated Remote Resource Location 381 Once the manifest is processed and the images to update are 382 identified, the device may request a download location from an 383 Update Server. 385 4.7. MFSR4d: Secure Boot 387 We certainly encourage that both the installer and bootloader verify 388 the authenticity of the manifest. 390 4.8. MFSR4e: Authenticated precursor images 392 As IoT devices may not be able to connect to the Internet to receive 393 updates for a long period of time, we do not believe that sequential 394 installation is practical and therefore the current proposal does 395 not allow for this option. However, we do believe the proposal 396 contains enough flexibility that support could be added later 398 4.9. MFSR4f: Authenticated Vendor and Class IDs 400 Both the Vendor and Class Id are part of the signed manifest body. 402 4.10. MFSR6: Rights Require Authenticity 404 Rights management is outside of the scope of the manifest format, 405 but a device or Update Server may enforce them. 407 4.11. MFSR7: Firmware encryption 409 A platform may mandate image encryption for any or all components. 410 If encryption is optional, the vendor may need to specify such fact 411 in the Flags parameter. 413 5. IANA Considerations 415 TBD 417 6. Security Considerations 419 This document is about a manifest format describing and protecting 420 firmware images and as such it is part of a larger solution for 421 offering a standardized way of delivering firmware updates to IoT 422 devices. A more detailed discussion about security can be found in 423 the architecture document [I-D.ietf-suit-architecture] and in the 424 information model document [I-D.ietf-suit-information-model]. 426 7. Mailing List Information 428 The discussion list for this document is located at the e-mail 429 address suit@ietf.org [1]. Information on the group and information 430 on how to subscribe to the list is at 431 https://www1.ietf.org/mailman/listinfo/suit 433 Archives of the list can be found at: https://www.ietf.org/mail- 434 archive/web/suit/current/index.html 436 8. References 438 8.1. Normative References 440 [I-D.ietf-suit-architecture] 442 Moran, B., Meriac, M., Tschofenig, H., and D. Brown, "A 443 Firmware Update Architecture for Internet of Things Devices", 444 draft-ietf-suit-architecture-01 (work in progress), July 2018. 446 [I-D.ietf-suit-information-model] 447 Moran, B., Tschofenig, H., Birkholz, H., and J. Jimenez, 448 "Firmware Updates for Internet of Things Devices - An 449 Information Model for Manifests", draft-ietf-suit-information- 450 model-01 (work in progress), June 2018. 452 Author's Addresses 454 Martin Pagel 456 Microsoft Corp 458 Email: martin.pagel@microsoft.com