idnits 2.17.1 draft-ietf-netconf-zerotouch-25.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 == Line 405 has weird spacing: '...gorithm ide...' == Line 1313 has weird spacing: '...gorithm ide...' == Line 1698 has weird spacing: '...rmation cms...' == Line 2269 has weird spacing: '... string cer...' == Line 3044 has weird spacing: '...address ine...' -- The document date (September 13, 2018) is 2052 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFCXXXX' is mentioned on line 2864, but not defined == Outdated reference: A later version (-05) exists of draft-ietf-netmod-yang-data-ext-01 -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU.X690.2015' ** Obsolete normative reference: RFC 3315 (Obsoleted by RFC 8415) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) == Outdated reference: A later version (-34) exists of draft-ietf-netconf-crypto-types-00 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-00 Summary: 2 errors (**), 0 flaws (~~), 10 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Juniper Networks 4 Intended status: Standards Track M. Abrahamsson 5 Expires: March 17, 2019 T-Systems 6 I. Farrer 7 Deutsche Telekom AG 8 September 13, 2018 10 Zero Touch Provisioning for Networking Devices 11 draft-ietf-netconf-zerotouch-25 13 Abstract 15 This draft presents a technique to securely provision a networking 16 device when it is booting in a factory-default state. Variations in 17 the solution enables it to be used on both public and private 18 networks. The provisioning steps are able to update the boot image, 19 commit an initial configuration, and execute arbitrary scripts to 20 address auxiliary needs. The updated device is subsequently able to 21 establish secure connections with other systems. For instance, a 22 device may establish NETCONF (RFC 6241) and/or RESTCONF (RFC 8040) 23 connections with deployment-specific network management systems. 25 Editorial Note (To be removed by RFC Editor) 27 This draft contains many placeholder values that need to be replaced 28 with finalized values at the time of publication. This note 29 summarizes all of the substitutions that are needed. No other RFC 30 Editor instructions are specified elsewhere in this document. 32 Artwork in the IANA Considerations section contains placeholder 33 values for DHCP options pending IANA assignment. Please apply the 34 following replacements: 36 o "TBD1" --> the assigned value for id-ct-zerotouchInformationXML 38 o "TBD2" --> the assigned value for id-ct-zerotouchInformationJSON 40 Artwork in this document contains shorthand references to drafts in 41 progress. Please apply the following replacements: 43 o "XXXX" --> the assigned numerical RFC value for this draft 45 Artwork in this document contains placeholder values for the date of 46 publication of this draft. Please apply the following replacement: 48 o "2018-09-13" --> the publication date of this draft 49 The following one Appendix section is to be removed prior to 50 publication: 52 o Appendix A. Change Log 54 Status of This Memo 56 This Internet-Draft is submitted in full conformance with the 57 provisions of BCP 78 and BCP 79. 59 Internet-Drafts are working documents of the Internet Engineering 60 Task Force (IETF). Note that other groups may also distribute 61 working documents as Internet-Drafts. The list of current Internet- 62 Drafts is at https://datatracker.ietf.org/drafts/current/. 64 Internet-Drafts are draft documents valid for a maximum of six months 65 and may be updated, replaced, or obsoleted by other documents at any 66 time. It is inappropriate to use Internet-Drafts as reference 67 material or to cite them other than as "work in progress." 69 This Internet-Draft will expire on March 17, 2019. 71 Copyright Notice 73 Copyright (c) 2018 IETF Trust and the persons identified as the 74 document authors. All rights reserved. 76 This document is subject to BCP 78 and the IETF Trust's Legal 77 Provisions Relating to IETF Documents 78 (https://trustee.ietf.org/license-info) in effect on the date of 79 publication of this document. Please review these documents 80 carefully, as they describe your rights and restrictions with respect 81 to this document. Code Components extracted from this document must 82 include Simplified BSD License text as described in Section 4.e of 83 the Trust Legal Provisions and are provided without warranty as 84 described in the Simplified BSD License. 86 Table of Contents 88 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 89 1.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 5 90 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 91 1.3. Requirements Language . . . . . . . . . . . . . . . . . . 7 92 1.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 8 93 2. Types of Bootstrapping Information . . . . . . . . . . . . . 8 94 2.1. Redirect Information . . . . . . . . . . . . . . . . . . 8 95 2.2. Onboarding Information . . . . . . . . . . . . . . . . . 9 96 3. Artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . 9 97 3.1. Zero Touch Information . . . . . . . . . . . . . . . . . 10 98 3.2. Owner Certificate . . . . . . . . . . . . . . . . . . . . 11 99 3.3. Ownership Voucher . . . . . . . . . . . . . . . . . . . . 12 100 3.4. Artifact Encryption . . . . . . . . . . . . . . . . . . . 12 101 3.5. Artifact Groupings . . . . . . . . . . . . . . . . . . . 13 102 4. Sources of Bootstrapping Data . . . . . . . . . . . . . . . . 14 103 4.1. Removable Storage . . . . . . . . . . . . . . . . . . . . 14 104 4.2. DNS Server . . . . . . . . . . . . . . . . . . . . . . . 15 105 4.3. DHCP Server . . . . . . . . . . . . . . . . . . . . . . . 16 106 4.4. Bootstrap Server . . . . . . . . . . . . . . . . . . . . 17 107 5. Device Details . . . . . . . . . . . . . . . . . . . . . . . 18 108 5.1. Initial State . . . . . . . . . . . . . . . . . . . . . . 18 109 5.2. Boot Sequence . . . . . . . . . . . . . . . . . . . . . . 20 110 5.3. Processing a Source of Bootstrapping Data . . . . . . . . 21 111 5.4. Validating Signed Data . . . . . . . . . . . . . . . . . 23 112 5.5. Processing Redirect Information . . . . . . . . . . . . . 24 113 5.6. Processing Onboarding Information . . . . . . . . . . . . 25 114 6. The Zero Touch Information Data Model . . . . . . . . . . . . 28 115 6.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 28 116 6.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 29 117 6.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 31 118 7. The Zero Touch Bootstrap Server API . . . . . . . . . . . . . 37 119 7.1. API Overview . . . . . . . . . . . . . . . . . . . . . . 37 120 7.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 38 121 7.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 40 122 8. DHCP Zero Touch Options . . . . . . . . . . . . . . . . . . . 51 123 8.1. DHCPv4 Zero Touch Option . . . . . . . . . . . . . . . . 51 124 8.2. DHCPv6 Zero Touch Option . . . . . . . . . . . . . . . . 52 125 8.3. Common Field Encoding . . . . . . . . . . . . . . . . . . 53 126 9. Security Considerations . . . . . . . . . . . . . . . . . . . 54 127 9.1. Clock Sensitivity . . . . . . . . . . . . . . . . . . . . 54 128 9.2. Use of IDevID Certificates . . . . . . . . . . . . . . . 54 129 9.3. Immutable Storage for Trust Anchors . . . . . . . . . . . 54 130 9.4. Secure Storage for Long-lived Private Keys . . . . . . . 54 131 9.5. Blindly Authenticating a Bootstrap Server . . . . . . . . 55 132 9.6. Disclosing Information to Untrusted Servers . . . . . . . 55 133 9.7. Sequencing Sources of Bootstrapping Data . . . . . . . . 56 134 9.8. Safety of Private Keys used for Trust . . . . . . . . . . 56 135 9.9. Infinite Redirection Loops and Sequences . . . . . . . . 57 136 9.10. Increased Reliance on Manufacturers . . . . . . . . . . . 57 137 9.11. Concerns with Trusted Bootstrap Servers . . . . . . . . . 58 138 9.12. Validity Period for Zero Touch Information . . . . . . . 58 139 9.13. The "ietf-zerotouch-information" YANG Module . . . . . . 59 140 9.14. The "ietf-zerotouch-bootstrap-server" YANG Module . . . . 60 141 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 60 142 10.1. The IETF XML Registry . . . . . . . . . . . . . . . . . 61 143 10.2. The YANG Module Names Registry . . . . . . . . . . . . . 61 144 10.3. The SMI Security for S/MIME CMS Content Type Registry . 61 145 10.4. The BOOTP Manufacturer Extensions and DHCP Options 146 Registry . . . . . . . . . . . . . . . . . . . . . . . . 62 147 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 62 148 11.1. Normative References . . . . . . . . . . . . . . . . . . 62 149 11.2. Informative References . . . . . . . . . . . . . . . . . 64 150 Appendix A. The Zero Touch Device Data Model . . . . . . . . . . 66 151 A.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 66 152 A.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 66 153 A.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 67 154 Appendix B. Promoting a Connection from Untrusted to Trusted . . 70 155 Appendix C. Workflow Overview . . . . . . . . . . . . . . . . . 72 156 C.1. Enrollment and Ordering Devices . . . . . . . . . . . . . 72 157 C.2. Owner Stages the Network for Bootstrap . . . . . . . . . 74 158 C.3. Device Powers On . . . . . . . . . . . . . . . . . . . . 76 159 Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 79 160 D.1. ID to 00 . . . . . . . . . . . . . . . . . . . . . . . . 79 161 D.2. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 79 162 D.3. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 79 163 D.4. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 80 164 D.5. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 80 165 D.6. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 80 166 D.7. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 81 167 D.8. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 81 168 D.9. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 81 169 D.10. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 81 170 D.11. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 81 171 D.12. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 82 172 D.13. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 82 173 D.14. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 82 174 D.15. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 83 175 D.16. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 83 176 D.17. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 83 177 D.18. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 84 178 D.19. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 84 179 D.20. 18 to 19 . . . . . . . . . . . . . . . . . . . . . . . . 85 180 D.21. 19 to 20 . . . . . . . . . . . . . . . . . . . . . . . . 85 181 D.22. 20 to 21 . . . . . . . . . . . . . . . . . . . . . . . . 86 182 D.23. 21 to 22 . . . . . . . . . . . . . . . . . . . . . . . . 86 183 D.24. 22 to 23 . . . . . . . . . . . . . . . . . . . . . . . . 86 184 D.25. 23 to 24 . . . . . . . . . . . . . . . . . . . . . . . . 87 185 D.26. 24 to 25 . . . . . . . . . . . . . . . . . . . . . . . . 87 186 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 88 187 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 88 189 1. Introduction 191 A fundamental business requirement for any network operator is to 192 reduce costs where possible. For network operators, deploying 193 devices to many locations can be a significant cost, as sending 194 trained specialists to each site for installations is both cost 195 prohibitive and does not scale. 197 This document defines Secure Zero Touch Provisioning (SZTP), a 198 bootstrapping strategy enabling devices to securely obtain 199 bootstrapping data with no installer action beyond physical placement 200 and connecting network and power cables. As such, SZTP enables non- 201 technical personnel to bring up devices in remote locations without 202 the need for any operator input. 204 The SZTP solution includes updating the boot image, committing an 205 initial configuration, and executing arbitrary scripts to address 206 auxiliary needs. The updated device is subsequently able to 207 establish secure connections with other systems. For instance, a 208 devices may establish NETCONF [RFC8040] and/or RESTCONF [RFC6241] 209 connections with deployment-specific network management systems. 211 This document primarily regards physical devices, where the setting 212 of the device's initial state, described in Section 5.1, occurs 213 during the device's manufacturing process. The SZTP solution may be 214 extended to support virtual machines or other such logical 215 constructs, but details for how this can be accomplished is left for 216 future work. 218 1.1. Use Cases 220 o Device connecting to a remotely administered network 222 This use-case involves scenarios, such as a remote branch 223 office or convenience store, whereby a device connects as an 224 access gateway to an ISP's network. Assuming it is not 225 possible to customize the ISP's network to provide any 226 bootstrapping support, and with no other nearby device to 227 leverage, the device has no recourse but to reach out to an 228 Internet-based bootstrap server to bootstrap from. 230 o Device connecting to a locally administered network 232 This use-case covers all other scenarios and differs only in 233 that the device may additionally leverage nearby devices, which 234 may direct it to use a local service to bootstrap from. If no 235 such information is available, or the device is unable to use 236 the information provided, it can then reach out to the network 237 just as it would for the remotely administered network use- 238 case. 240 Conceptual workflows for how SZTP might be deployed are provided in 241 Appendix C. 243 1.2. Terminology 245 This document uses the following terms (sorted by name): 247 Artifact: The term "artifact" is used throughout to represent any of 248 the three artifacts defined in Section 3 (zero touch information, 249 ownership voucher, and owner certificate). These artifacts 250 collectively provide all the bootstrapping data a device may use. 252 Bootstrapping Data: The term "bootstrapping data" is used throughout 253 this document to refer to the collection of data that a device 254 may obtain during the bootstrapping process. Specifically, it 255 refers to the three artifacts zero touch information, owner 256 certificate, and ownership voucher, as described in Section 3. 258 Bootstrap Server: The term "bootstrap server" is used within this 259 document to mean any RESTCONF server implementing the YANG module 260 defined in Section 7.3. 262 Device: The term "device" is used throughout this document to refer 263 to a network element that needs to be bootstrapped. See 264 Section 5 for more information about devices. 266 Manufacturer: The term "manufacturer" is used herein to refer to the 267 manufacturer of a device or a delegate of the manufacturer. 269 Network Management System (NMS): The acronym "NMS" is used 270 throughout this document to refer to the deployment specific 271 management system that the bootstrapping process is responsible 272 for introducing devices to. From a device's perspective, when 273 the bootstrapping process has completed, the NMS is a NETCONF or 274 RESTCONF client. 276 Onboarding Information: The term "onboarding information" is used 277 herein to refer to one of the two types of "zero touch 278 information" defined in this document, the other being "redirect 279 information". Onboarding information is formally defined by the 280 "onboarding-information" YANG-data structure in Section 6.3. 282 Onboarding Server: The term "onboarding server" is used herein to 283 refer to a bootstrap server that only returns onboarding 284 information. 286 Owner: The term "owner" is used throughout this document to refer to 287 the person or organization that purchased or otherwise owns a 288 device. 290 Owner Certificate: The term "owner certificate" is used in this 291 document to represent an X.509 certificate that binds an owner 292 identity to a public key, which a device can use to validate a 293 signature over the zero touch information artifact. The owner 294 certificate may be communicated along with its chain of 295 intermediate certificates leading up to a known trust anchor. 296 The owner certificate is one of the three bootstrapping artifacts 297 described in Section 3. 299 Ownership Voucher: The term "ownership voucher" is used in this 300 document to represent the voucher artifact defined in [RFC8366]. 301 The ownership voucher is used to assign a device to an owner. 302 The ownership voucher is one of the three bootstrapping artifacts 303 described in Section 3. 305 Redirect Information: The term "redirect information" is used herein 306 to refer to one of the two types of "zero touch information" 307 defined in this document, the other being "onboarding 308 information". Redirect information is formally defined by the 309 "redirect-information" YANG-data structure in Section 6.3. 311 Redirect Server: The term "redirect server" is used to refer to a 312 bootstrap server that only returns redirect information. A 313 redirect server is particularly useful when hosted by a 314 manufacturer, as a well-known (e.g., Internet-based) resource to 315 redirect devices to deployment-specific bootstrap servers. 317 Signed Data: The term "signed data" is used throughout to mean zero 318 touch information that has been signed, specifically by a private 319 key possessed by a device's owner. 321 Unsigned Data: The term "unsigned data" is used throughout to mean 322 zero touch information that has not been signed. 324 Zero Touch Information: The term "zero touch information" is used 325 herein to refer either redirect information or onboarding 326 information. Zero touch information is one of the three 327 bootstrapping artifacts described in Section 3. 329 1.3. Requirements Language 331 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 332 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 333 "OPTIONAL" in this document are to be interpreted as described in BCP 334 14 [RFC2119] [RFC8174] when, and only when, they appear in all 335 capitals, as shown here. 337 1.4. Tree Diagrams 339 Tree diagrams used in this document follow the notation defined in 340 [RFC8340]. 342 2. Types of Bootstrapping Information 344 This document defines two types of information that devices can 345 access during the bootstrapping process. These information types are 346 described in this section. Examples are provided in Section 6.2 348 2.1. Redirect Information 350 Redirect information redirects a device to another bootstrap server. 351 Redirect information encodes a list of bootstrap servers, each 352 specifying the bootstrap server's hostname (or IP address), an 353 optional port, and an optional trust anchor certificate that the 354 device can use to authenticate the bootstrap server with. 356 Redirect information is YANG modeled data formally defined by the 357 "redirect-information" container in the YANG module presented in 358 Section 6.3. This container has the tree diagram shown below. 360 +--:(redirect-information) 361 +-- redirect-information 362 +-- bootstrap-server* [address] 363 +-- address inet:host 364 +-- port? inet:port-number 365 +-- trust-anchor? cms 367 Redirect information may be trusted or untrusted. The redirect 368 information is trusted whenever it is obtained via a secure 369 connection to a trusted bootstrap server, or whenever it is signed by 370 the device's owner. In all other cases, the redirect information is 371 untrusted. 373 Trusted redirect information is useful for enabling a device to 374 establish a secure connection to a specified bootstrap server, which 375 is possible when the redirect information includes the bootstrap 376 server's trust anchor certificate. 378 Untrusted redirect information is useful for directing a device to a 379 bootstrap server where signed data has been staged for it to obtain. 380 Note that, when the redirect information is untrusted, devices 381 discard any potentially included trust anchor certificates. 383 How devices process redirect information is described in Section 5.5. 385 2.2. Onboarding Information 387 Onboarding information provides data necessary for a device to 388 bootstrap itself and establish secure connections with other systems. 389 As defined in this document, onboarding information can specify 390 details about the boot image a device must be running, specify an 391 initial configuration the device must commit, and specify scripts 392 that the device must successfully execute. 394 Onboarding information is YANG modeled data formally defined by the 395 "onboarding-information" container in the YANG module presented in 396 Section 6.3. This container has the tree diagram shown below. 398 +--:(onboarding-information) 399 +-- onboarding-information 400 +-- boot-image 401 | +-- os-name? string 402 | +-- os-version? string 403 | +-- download-uri* inet:uri 404 | +-- image-verification* [hash-algorithm] 405 | +-- hash-algorithm identityref 406 | +-- hash-value yang:hex-string 407 +-- configuration-handling? enumeration 408 +-- pre-configuration-script? script 409 +-- configuration? binary 410 +-- post-configuration-script? script 412 Onboarding information must be trusted for it to be of any use to a 413 device. There is no option for a device to process untrusted 414 onboarding information. 416 Onboarding information is trusted whenever it is obtained via a 417 secure connection to a trusted bootstrap server, or whenever it is 418 signed by the device's owner. In all other cases, the onboarding 419 information is untrusted. 421 How devices process onboarding information is described in 422 Section 5.6. 424 3. Artifacts 426 This document defines three artifacts that can be made available to 427 devices while they are bootstrapping. Each source of bootstrapping 428 data specifies how it provides the artifacts defined in this section 429 (see Section 4). 431 3.1. Zero Touch Information 433 The zero touch information artifact encodes the essential 434 bootstrapping data for the device. This artifact is used to encode 435 the redirect information and onboarding information types discussed 436 in Section 2. 438 The zero touch information artifact is a CMS structure, as described 439 in [RFC5652], encoded using ASN.1 distinguished encoding rules (DER), 440 as specified in ITU-T X.690 [ITU.X690.2015]. The CMS structure MUST 441 contain content conforming to the YANG module specified in 442 Section 6.3. 444 The zero touch information CMS structure may encode signed or 445 unsigned bootstrapping data. When the bootstrapping data is signed, 446 it may also be encrypted but, from a terminology perspective, it is 447 still "signed data" Section 1.2. 449 When the zero touch information artifact is unsigned, as it might be 450 when communicated over trusted channels, the CMS structure's top-most 451 content type MUST be one of the OIDs described in Section 10.3, or 452 the OID id-data (1.2.840.113549.1.7.1), in which case the encoding 453 (JSON, XML, etc.) SHOULD be communicated externally. In either 454 case, the associated content is an octet string containing 455 "zerotouch-information" data in the expected encoding. 457 When the zero touch information artifact is signed, as it might be 458 when communicated over untrusted channels, the CMS structure's top- 459 most content type MUST be the OID id-signedData 460 (1.2.840.113549.1.7.2), and its inner eContentType MUST be one of the 461 OIDs described in Section 10.3, or the OID id-data 462 (1.2.840.113549.1.7.1), in which case the encoding (JSON, XML, etc.) 463 SHOULD be communicated externally. In either case, the associated 464 content or eContent is an octet string containing "zerotouch- 465 information" data in the expected encoding. 467 When the zero touch information artifact is signed and encrypted, as 468 it might be when communicated over untrusted channels and privacy is 469 important, the CMS structure's top-most content type MUST be the OID 470 id-envelopedData (1.2.840.113549.1.7.3), and the 471 encryptedContentInfo's content type MUST be the OID id-signedData 472 (1.2.840.113549.1.7.2), whose eContentType MUST be one of the OIDs 473 described in Section 10.3, or the OID id-data (1.2.840.113549.1.7.1), 474 in which case the encoding (JSON, XML, etc.) SHOULD be communicated 475 externally. In either case, the associated content or eContent is an 476 octet string containing "zerotouch-information" data in the expected 477 encoding. 479 3.2. Owner Certificate 481 The owner certificate artifact is an X.509 certificate [RFC5280] that 482 is used to identify an "owner" (e.g., an organization). The owner 483 certificate can be signed by any certificate authority (CA). The 484 owner certificate either MUST have no Key Usage specified or the Key 485 Usage MUST at least set the "digitalSignature" bit. The values for 486 the owner certificate's "subject" and/or "subjectAltName" are not 487 constrained by this document. 489 The owner certificate is used by a device to verify the signature 490 over the zero touch information artifact (Section 3.1) that the 491 device should have also received, as described in Section 3.5. In 492 particular, the device verifies the signature using the public key in 493 the owner certificate over the content contained within the zero 494 touch information artifact. 496 The owner certificate artifact is formally a CMS structure, as 497 specified by [RFC5652], encoded using ASN.1 distinguished encoding 498 rules (DER), as specified in ITU-T X.690 [ITU.X690.2015]. 500 The owner certificate CMS structure MUST contain the owner 501 certificate itself, as well as all intermediate certificates leading 502 to the "pinned-domain-cert" certificate specified in the ownership 503 voucher. The owner certificate artifact MAY optionally include the 504 "pinned-domain-cert" as well. 506 In order to support devices deployed on private networks, the owner 507 certificate CMS structure MAY also contain suitably fresh, as 508 determined by local policy, revocation objects (e.g., CRLs). Having 509 these revocation objects stapled to the owner certificate may obviate 510 the need for the device to have to download them dynamically using 511 the CRL distribution point or an OCSP responder specified in the 512 associated certificates. 514 When unencrypted, the owner certificate artifact's CMS structure's 515 top-most content type MUST be the OID id-signedData 516 (1.2.840.113549.1.7.2). The inner SignedData structure is the 517 degenerate form, whereby there are no signers, that is commonly used 518 to disseminate certificates and revocation objects. 520 When encrypted, the owner certificate artifact's CMS structure's top- 521 most content type MUST be the OID id-envelopedData 522 (1.2.840.113549.1.7.3), and the encryptedContentInfo's content type 523 MUST be the OID id-signedData (1.2.840.113549.1.7.2), whereby the 524 inner SignedData structure is the degenerate form that has no signers 525 commonly used to disseminate certificates and revocation objects. 527 3.3. Ownership Voucher 529 The ownership voucher artifact is used to securely identify a 530 device's owner, as it is known to the manufacturer. The ownership 531 voucher is signed by the device's manufacturer. 533 The ownership voucher is used to verify the owner certificate 534 (Section 3.2) that the device should have also received, as described 535 in Section 3.5. In particular, the device verifies that the owner 536 certificate has a chain of trust leading to the trusted certificate 537 included in the ownership voucher ("pinned-domain-cert"). Note that 538 this relationship holds even when the owner certificate is a self- 539 signed certificate, and hence also the pinned-domain-cert. 541 When unencrypted, the ownership voucher artifact is as defined in 542 [RFC8366]. As described, it is a CMS structure whose top-most 543 content type MUST be the OID id-signedData (1.2.840.113549.1.7.2), 544 whose eContentType MUST be OID id-ct-animaJSONVoucher 545 (1.2.840.113549.1.9.16.1), or the OID id-data (1.2.840.113549.1.7.1), 546 in which case the encoding (JSON, XML, etc.) SHOULD be communicated 547 externally. In either case, the associated content is an octet 548 string containing ietf-voucher data in the expected encoding. 550 When encrypted, the ownership voucher artifact's CMS structure's top- 551 most content type MUST be the OID id-envelopedData 552 (1.2.840.113549.1.7.3), and the encryptedContentInfo's content type 553 MUST be the OID id-signedData (1.2.840.113549.1.7.2), whose 554 eContentType MUST be OID id-ct-animaJSONVoucher 555 (1.2.840.113549.1.9.16.1), or the OID id-data (1.2.840.113549.1.7.1), 556 in which case the encoding (JSON, XML, etc.) SHOULD be communicated 557 externally. In either case, the associated content is an octet 558 string containing ietf-voucher data in the expected encoding. 560 3.4. Artifact Encryption 562 Each of the three artifacts MAY be individually encrypted. 563 Encryption may be important in some environments where the content is 564 considered sensitive. 566 Each of the three artifacts are encrypted in the same way, by the 567 unencrypted form being encapsulated inside a CMS EnvelopedData type. 569 As a consequence, both the zero touch information and ownership 570 voucher artifacts are signed and then encrypted, never encrypted and 571 then signed. 573 This sequencing has the advantage of shrouding the signer's 574 certificate, and ensuring that the owner knows the content being 575 signed. This sequencing further enables the owner to inspect an 576 unencrypted voucher obtained from a manufacturer and then encrypt the 577 voucher later themselves, perhaps while also stapling in current 578 revocation objects, when ready to place the artifact in an unsafe 579 location. 581 When encrypted, the CMS MUST be encrypted using a secure device 582 identity certificate for the device. This certificate MAY be the 583 same as the TLS-level client certificate the device uses when 584 connecting to bootstrap servers. The owner must possess the device's 585 identity certificate at the time of encrypting the data. How the 586 owner comes to posses the device's identity certificate for this 587 purpose is outside the scope of this document. 589 3.5. Artifact Groupings 591 The previous sections discussed the bootstrapping artifacts, but only 592 certain groupings of these artifacts make sense to return in the 593 various bootstrapping situations described in this document. These 594 groupings are: 596 Unsigned Data: This artifact grouping is useful for cases when 597 transport level security can be used to convey trust (e.g., 598 HTTPS), or when the zero touch information can be processed in 599 a provisional manner (i.e. unsigned redirect information). 601 Signed Data, without revocations: This artifact grouping is 602 useful when signed data is needed (i.e., because the data is 603 obtained from an untrusted source and it cannot be processed 604 provisionally) and either revocations are not needed or the 605 revocations can be obtained dynamically. 607 Signed Data, with revocations: This artifact grouping is useful 608 when signed data is needed (i.e., because the data is obtained 609 from an untrusted source and it cannot be processed 610 provisionally), and revocations are needed, and the revocations 611 cannot be obtained dynamically. 613 The presence of each artifact, and any distinguishing 614 characteristics, are identified for each artifact grouping in the 615 table below ("yes/no" regards if the artifact is present in the 616 artifact grouping): 618 +---------------------+---------------+--------------+--------------+ 619 | Artifact | Zero Touch | Ownership | Owner | 620 | Grouping | Information | Voucher | Certificate | 621 +=====================+===============+==============+==============+ 622 | Unsigned Data | Yes, no sig | No | No | 623 +---------------------+---------------+--------------+--------------+ 624 | Signed Data, | Yes, with sig | Yes, without | Yes, without | 625 | without revocations | | revocations | revocations | 626 +---------------------+---------------+--------------+--------------+ 627 | Signed Data, | Yes, with sig | Yes, with | Yes, with | 628 | with revocations | | revocations | revocations | 629 +---------------------+---------------+--------------+--------------+ 631 4. Sources of Bootstrapping Data 633 This section defines some sources for bootstrapping data that a 634 device can access. The list of sources defined here is not meant to 635 be exhaustive. It is left to future documents to define additional 636 sources for obtaining bootstrapping data. 638 For each source of bootstrapping data defined in this section, 639 details are given for how the three artifacts listed in Section 3 are 640 provided. 642 4.1. Removable Storage 644 A directly attached removable storage device (e.g., a USB flash 645 drive) MAY be used as a source of zero touch bootstrapping data. 647 Use of a removable storage device is compelling, as it does not 648 require any external infrastructure to work. It is notable that the 649 raw boot image file can also be located on the removable storage 650 device, enabling a removable storage device to be a fully self- 651 standing bootstrapping solution. 653 To use a removable storage device as a source of bootstrapping data, 654 a device need only detect if the removable storage device is plugged 655 in and mount its filesystem. 657 A removable storage device is an untrusted source of bootstrapping 658 data. This means that the information stored on the removable 659 storage device either MUST be signed or MUST be information that can 660 be processed provisionally (e.g., unsigned redirect information). 662 From an artifact perspective, since a removable storage device 663 presents itself as a filesystem, the bootstrapping artifacts need to 664 be presented as files. The three artifacts defined in Section 3 are 665 mapped to files below. 667 Artifact to File Mapping: 669 Zero Touch Information: Mapped to a file containing the binary 670 artifact described in Section 3.1 (e.g., zerotouch- 671 information.cms). 673 Owner Certificate: Mapped to a file containing the binary 674 artifact described in Section 3.2 (e.g., owner- 675 certificate.cms). 677 Ownership Voucher: Mapped to a file containing the binary 678 artifact described in Section 3.3 (e.g., ownership-voucher.cms 679 or ownership-voucher.vcj). 681 The format of the removable storage device's filesystem and the 682 naming of the files are outside the scope of this document. However, 683 in order to facilitate interoperability, it is RECOMMENDED devices 684 support open and/or standards based filesystems. It is also 685 RECOMMENDED that devices assume a file naming convention that enables 686 more than one instance of bootstrapping data (i.e., for different 687 devices) to exist on a removable storage device. The file naming 688 convention SHOULD additionally be unique to the manufacturer, in 689 order to enable bootstrapping data from multiple manufacturers to 690 exist on a removable storage device. 692 4.2. DNS Server 694 A DNS server MAY be used as a source of zero touch bootstrapping 695 data. 697 Using a DNS server may be a compelling option for deployments having 698 existing DNS infrastructure, as it enables a touchless bootstrapping 699 option that does not entail utilizing an Internet based resource 700 hosted by a 3rd-party. 702 To use a DNS server as a source of bootstrapping data, a device MAY 703 perform a multicast DNS [RFC6762] query searching for the service 704 "_zerotouch._tcp.local.". Alternatively the device MAY perform DNS- 705 SD [RFC6763] via normal DNS operation, using the domain returned to 706 it from the DHCP server; for example, searching for the service 707 "_zerotouch._tcp.example.com". 709 Unsigned DNS records (e.g., not using DNSSEC as described in 710 [RFC6698]) are an untrusted source of bootstrapping data. This means 711 that the information stored in the DNS records either MUST be signed, 712 or MUST be information that can be processed provisionally (e.g., 713 unsigned redirect information). 715 From an artifact perspective, since a DNS server presents resource 716 records (Section 3.2.1 of [RFC1035]), the bootstrapping artifacts 717 need to be presented as resource records. The three artifacts 718 defined in Section 3 are mapped to resource records below. 720 Artifact to Resource Record Mapping: 722 Zero Touch Information: Mapped to a TXT record called "zt-info" 723 containing the base64-encoding of the binary artifact described 724 in Section 3.1. 726 Owner Certificate: Mapped to a TXT record called "zt-cert" 727 containing the base64-encoding of the binary artifact described 728 in Section 3.2. 730 Ownership Voucher: Mapped to a TXT record called "zt-voucher" 731 containing the base64-encoding of the binary artifact described 732 in Section 3.3. 734 TXT records have an upper size limit of 65535 bytes (Section 3.2.1 in 735 RFC1035), since "RDLENGTH" is a 16-bit field. Please see 736 Section 3.1.3 in RFC4408 for how a TXT record can achieve this size. 737 Due to this size limitation, some zero touch information artifacts 738 may not fit. In particular, onboarding information could hit this 739 upper bound, depending on the size of the included configuration and 740 scripts. 742 4.3. DHCP Server 744 A DHCP server MAY be used as a source of zero touch bootstrapping 745 data. 747 Using a DHCP server may be a compelling option for deployments having 748 existing DHCP infrastructure, as it enables a touchless bootstrapping 749 option that does not entail utilizing an Internet based resource 750 hosted by a 3rd-party. 752 A DHCP server is an untrusted source of bootstrapping data. Thus the 753 information stored on the DHCP server either MUST be signed, or it 754 MUST be information that can be processed provisionally (e.g., 755 unsigned redirect information). 757 However, unlike other sources of bootstrapping data described in this 758 document, the DHCP protocol (especially DHCP for IPv4) is very 759 limited in the amount of data that can be conveyed, to the extent 760 that signed data cannot be communicated. This means that only 761 unsigned redirect information can be conveyed via DHCP. 763 Since the redirect information is unsigned, it SHOULD NOT include the 764 optional trust anchor certificate, as it takes up space in the DHCP 765 message, and the device would have to discard it anyway. For this 766 reason, the DHCP options defined in Section 8 do not enable the trust 767 anchor certificate to be encoded. 769 From an artifact perspective, the three artifacts defined in 770 Section 3 are mapped to the DHCP fields specified in Section 8 as 771 follows: 773 Zero Touch Information: This artifact is not supported directly. 774 Instead, the essence of unsigned redirect information is mapped 775 to the DHCP options described in Section 8. 777 Owner Certificate: Not supported. There is not enough space in 778 the DHCP packet to hold an owner certificate artifact. 780 Ownership Voucher: Not supported. There is not enough space in 781 the DHCP packet to hold an ownership voucher artifact. 783 4.4. Bootstrap Server 785 A bootstrap server MAY be used as a source of zero touch 786 bootstrapping data. A bootstrap server is defined as a RESTCONF 787 [RFC8040] server implementing the YANG module provided in Section 7. 789 Using a bootstrap server as a source of bootstrapping data is a 790 compelling option as it MAY use transport-level security, obviating 791 the need for signed data, which may be easier to deploy in some 792 situations. 794 Unlike any other source of bootstrapping data described in this 795 document, a bootstrap server is not only a source of data, but it can 796 also receive data from devices using the YANG-defined "report- 797 progress" RPC defined in the YANG module (Section 7.3). The "report- 798 progress" RPC enables visibility into the bootstrapping process 799 (e.g., warnings and errors), and provides potentially useful 800 information upon completion (e.g., the device's SSH host-keys). 802 A bootstrap server may be a trusted or an untrusted source of 803 bootstrapping data, depending on if the device learned about the 804 bootstrap server's trust anchor from a trusted source. When a 805 bootstrap server is trusted, the zero touch information returned from 806 it MAY be signed. When the bootstrap server is untrusted, the zero 807 touch information either MUST be signed or MUST be information that 808 can be processed provisionally (e.g., unsigned redirect information). 810 From an artifact perspective, since a bootstrap server presents data 811 conforming to a YANG data model, the bootstrapping artifacts need to 812 be mapped to YANG nodes. The three artifacts defined in Section 3 813 are mapped to "output" nodes of the "get-bootstrapping-data" RPC 814 defined in Section 7.3 below. 816 Artifact to Bootstrap Server Mapping: 818 Zero Touch Information: Mapped to the "zerotouch-information" 819 leaf in the output of the "get-bootstrapping-data" RPC. 821 Owner Certificate: Mapped to the "owner-certificate" leaf in the 822 output of the "get-bootstrapping-data" RPC. 824 Ownership Voucher: Mapped to the "ownership-voucher" leaf in the 825 output of the "get-bootstrapping-data" RPC. 827 Zero touch bootstrap servers have only two endpoints, one for the 828 "get-bootstrapping-data" RPC and one for the "report-progress" RPC. 829 These RPCs use the authenticated RESTCONF username to isolate the 830 execution of the RPC from other devices. 832 5. Device Details 834 Devices supporting the bootstrapping strategy described in this 835 document MUST have the preconfigured state and bootstrapping logic 836 described in the following sections. 838 5.1. Initial State 839 +-------------------------------------------------------------+ 840 | | 841 | | 842 | +---------------------------------------------------------+ | 843 | | | | 844 | | | | 845 | | 1. flag to enable zerotouch bootstrapping set to "true" | | 846 | +---------------------------------------------------------+ | 847 | | 848 | +---------------------------------------------------------+ | 849 | | | | 850 | | | | 851 | | 2. TLS client cert & related intermediate certificates | | 852 | | 3. list of trusted well-known bootstrap servers | | 853 | | 4. list of trust anchor certs for bootstrap servers | | 854 | | 5. list of trust anchor certs for ownership vouchers | | 855 | +---------------------------------------------------------+ | 856 | | 857 | +-----------------------------------------------------+ | 858 | | | | 859 | | | | 860 | | 6. private key for TLS client certificate | | 861 | | 7. private key for decrypting zerotouch artifacts | | 862 | +-----------------------------------------------------+ | 863 | | 864 +-------------------------------------------------------------+ 866 Each numbered item below corresponds to a numbered item in the 867 diagram above. 869 1. Devices MUST have a configurable variable that is used to enable/ 870 disable zerotouch bootstrapping. This variable MUST be enabled 871 by default in order for zerotouch bootstrapping to run when the 872 device first powers on. Because it is a goal that the 873 configuration installed by the bootstrapping process disables 874 zerotouch bootstrapping, and because the configuration may be 875 merged into the existing configuration, using a configuration 876 node that relies on presence is NOT RECOMMENDED, as it cannot be 877 removed by the merging process. 879 2. Devices that support loading bootstrapping data from bootstrap 880 servers (see Section 4.4) SHOULD possess a TLS-level client 881 certificate and any intermediate certificates leading to the 882 certificate's well-known trust-anchor. The well-known trust 883 anchor certificate may be an intermediate certificate or a self- 884 signed root certificate. To support devices not having a client 885 certificate, devices MAY, alternatively or in addition to, 886 identify and authenticate themselves to the bootstrap server 887 using an HTTP authentication scheme, as allowed by Section 2.5 in 888 [RFC8040]; however, this document does not define a mechanism for 889 operator input enabling, for example, the entering of a password. 891 3. Devices that support loading bootstrapping data from well-known 892 bootstrap servers MUST possess a list of the well-known bootstrap 893 servers. Consistent with redirect information (Section 2.1, each 894 bootstrap server can be identified by its hostname or IP address, 895 and an optional port. 897 4. Devices that support loading bootstrapping data from well-known 898 bootstrap servers MUST also possess a list of trust anchor 899 certificates that can be used to authenticate the well-known 900 bootstrap servers. For each trust anchor certificate, if it is 901 not itself a self-signed root certificate, the device SHOULD also 902 possess the chain of intermediate certificates leading up to and 903 including the self-signed root certificate. 905 5. Devices that support loading signed data (see Section 1.2) MUST 906 possess the trust anchor certificates for validating ownership 907 vouchers. For each trust anchor certificate, if it is not itself 908 a self-signed root certificate, the device SHOULD also possess 909 the chain of intermediate certificates leading up to and 910 including the self-signed root certificate. 912 6. Devices that support using a TLS-level client certificate to 913 identify and authenticate themselves to a bootstrap server MUST 914 possess the private key that corresponds to the public key 915 encoded in the TLS-level client certificate. This private key 916 SHOULD be securely stored, ideally in a cryptographic processor 917 (e.g., a TPM). 919 7. Devices that support decrypting zerotouch artifacts MUST posses 920 the private key that corresponds to the public key encoded in the 921 secure device identity certificate used when encrypting the 922 artifacts. This private key SHOULD be securely stored, ideally 923 in a cryptographic processor (e.g., a TPM). This private key MAY 924 be the same as the one associated to the TLS-level client 925 certificate used when connecting to bootstrap servers. 927 A YANG module representing this data is provided in Appendix A. 929 5.2. Boot Sequence 931 A device claiming to support the bootstrapping strategy defined in 932 this document MUST support the boot sequence described in this 933 section. 935 Power On 936 | 937 v No 938 1. Zerotouch bootstrapping configured ------> Boot normally 939 | 940 | Yes 941 v 942 2. For each supported source of bootstrapping data, 943 try to load bootstrapping data from the source 944 | 945 | 946 v Yes 947 3. Able to bootstrap from any source? -----> Run with new config 948 | 949 | No 950 v 951 4. Loop and/or wait for manual provisioning. 953 Each numbered item below corresponds to a numbered item in the 954 diagram above. 956 1. When the device powers on, it first checks to see if zerotouch 957 bootstrapping is configured, as is expected to be the case for 958 the device's preconfigured initial state. If zerotouch 959 bootstrapping is not configured, then the device boots normally. 961 2. The device iterates over its list of sources for bootstrapping 962 data (Section 4). Details for how to processes a source of 963 bootstrapping data are provided in Section 5.3. 965 3. If the device is able to bootstrap itself from any of the sources 966 of bootstrapping data, it runs with the new bootstrapped 967 configuration. 969 4. Otherwise the device MAY loop back through the list of 970 bootstrapping sources again and/or wait for manual provisioning. 972 5.3. Processing a Source of Bootstrapping Data 974 This section describes a recursive algorithm that devices can use to, 975 ultimately, obtain onboarding information. The algorithm is 976 recursive because sources of bootstrapping data may return redirect 977 information, which causes the algorithm to run again, for the newly 978 discovered sources of bootstrapping data. An expression that 979 captures all possible successful sequences of bootstrapping data is 980 zero or more redirect information responses, followed by one 981 onboarding information response. 983 An important aspect of the algorithm is knowing when data needs to be 984 signed or not. The following figure provides a summary of options: 986 Untrusted Source Trusted Source 987 Kind of Bootstrapping Data Can Provide? Can Provide? 989 Unsigned Redirect Info : Yes+ Yes 990 Signed Redirect Info : Yes Yes* 991 Unsigned Onboarding Info : No Yes 992 Signed Onboarding Info : Yes Yes* 994 The '+' above denotes that the source redirected to MUST 995 return signed data, or more unsigned redirect information. 997 The '*' above denotes that, while possible, it is generally 998 unnecessary for a trusted source to return signed data. 1000 The recursive algorithm uses a conceptual global-scoped variable 1001 called "trust-state". The trust-state variable is initialized to 1002 FALSE. The ultimate goal of this algorithm is for the device to 1003 process onboarding information (Section 2.2) while the trust-state 1004 variable is TRUE. 1006 If the source of bootstrapping data (Section 4) is a bootstrap server 1007 (Section 4.4), and the device is able to authenticate the bootstrap 1008 server using X.509 certificate path validation ([RFC6125], Section 6) 1009 to one of the device's preconfigured trust anchors, or to a trust 1010 anchor that it learned from a previous step, then the device MUST set 1011 trust-state to TRUE. 1013 When establishing a connection to a bootstrap server, whether trusted 1014 or untrusted, the device MUST identify and authenticate itself to the 1015 bootstrap server using a TLS-level client certificate and/or an HTTP 1016 authentication scheme, per Section 2.5 in [RFC8040]. If both 1017 authentication mechanisms are used, they MUST both identify the same 1018 serial number. 1020 When sending a client certificate, the device MUST also send all of 1021 the intermediate certificates leading up to, and optionally 1022 including, the client certificate's well-known trust anchor 1023 certificate. 1025 For any source of bootstrapping data (e.g., Section 4), if any 1026 artifact obtained is encrypted, the device MUST first decrypt it 1027 using the private key associated with the device certificate used to 1028 encrypt the artifact. 1030 If the zero touch information artifact is signed, and the device is 1031 able to validate the signed data using the algorithm described in 1032 Section 5.4, then the device MUST set trust-state to TRUE; otherwise, 1033 if the device is unable to validate the signed data, the device MUST 1034 set trust-state to FALSE. Note, this is worded to cover the special 1035 case when signed data is returned even from a trusted bootstrap 1036 server. 1038 If the zero touch information artifact contains onboarding 1039 information, and trust-state is FALSE, the device MUST exit the 1040 recursive algorithm (as this is not allowed, see the figure above), 1041 returning to the bootstrapping sequence described in Section 5.2. 1042 Otherwise, the device MUST attempt to process the onboarding 1043 information as described in Section 5.6. In either case, success or 1044 failure, the device MUST exit the recursive algorithm, returning to 1045 the bootstrapping sequence described in Section 5.2, the only 1046 difference being in how it responds to the "Able to bootstrap from 1047 any source?" conditional described in the figure in the section. 1049 If the zero touch information artifact contains redirect information, 1050 the device MUST, within limits of how many recursive loops the device 1051 allows, process the redirect information as described in Section 5.5. 1052 This is the recursion step, it will cause the device to reenter this 1053 algorithm, but this time the data source will definitely be a 1054 bootstrap server, as that is all redirect information is able to 1055 redirect a device to. 1057 5.4. Validating Signed Data 1059 Whenever a device is presented signed data, it MUST validate the 1060 signed data as described in this section. This includes the case 1061 where the signed data is provided by a trusted source. 1063 Whenever there is signed data, the device MUST also be provided an 1064 ownership voucher and an owner certificate. How all the needed 1065 artifacts are provided for each source of bootstrapping data is 1066 described in Section 4. 1068 In order to validate signed data, the device MUST first authenticate 1069 the ownership voucher by validating its signature to one of its 1070 preconfigured trust anchors (see Section 5.1), which may entail using 1071 additional intermediate certificates attached to the ownership 1072 voucher. If the device has an accurate clock, it MUST verify that 1073 the ownership voucher was created in the past (i.e., "created-on" < 1074 now) and, if the "expires-on" leaf is present, the device MUST verify 1075 that the ownership voucher has not yet expired (i.e., now < "expires- 1076 on"). The device MUST verify that the ownership voucher's 1077 "assertion" value is acceptable (e.g., some devices may only accept 1078 the assertion value "verified"). The device MUST verify that the 1079 ownership voucher specifies the device's serial number in the 1080 "serial-number" leaf. If the "idevid-issuer" leaf is present, the 1081 device MUST verify that the value is set correctly. If the 1082 authentication of the ownership voucher is successful, the device 1083 extracts the "pinned-domain-cert" node, an X.509 certificate, that is 1084 needed to verify the owner certificate in the next step. 1086 The device MUST next authenticate the owner certificate by performing 1087 X.509 certificate path verification to the trusted certificate 1088 extracted from the ownership voucher's "pinned-domain-cert" node. 1089 This verification may entail using additional intermediate 1090 certificates attached to the owner certificate artifact. If the 1091 ownership voucher's "domain-cert-revocation-checks" node's value is 1092 set to "true", the device MUST verify the revocation status of the 1093 certificate chain used to sign the owner certificate and, if 1094 suitably-fresh revocation status is unattainable or if it is 1095 determined that a certificate has been revoked, the device MUST NOT 1096 validate the owner certificate. 1098 Finally the device MUST verify the zero touch information artifact 1099 was signed by the validated owner certificate. 1101 If any of these steps fail, the device MUST invalidate the signed 1102 data and not perform any subsequent steps. 1104 5.5. Processing Redirect Information 1106 In order to process redirect information (Section 2.1), the device 1107 MUST follow the steps presented in this section. 1109 Processing redirect information is straightforward, the device 1110 sequentially steps through the list of provided bootstrap servers 1111 until it can find one it can bootstrap from. 1113 If a hostname is provided, and the hostname's DNS resolution is to 1114 more than one IP address, the device MUST attempt to connect to all 1115 of the DNS resolved addresses at least once, before moving on to the 1116 next bootstrap server. If the device is able to obtain bootstrapping 1117 data from any of the DNS resolved addresses, it MUST immediately 1118 process that data, without attempting to connect to any of the other 1119 DNS resolved addresses. 1121 If the redirect information is trusted (e.g., trust-state is TRUE), 1122 and the bootstrap server entry contains a trust anchor certificate, 1123 then the device MUST authenticate the specified bootstrap server's 1124 TLS server certificate using X.509 certificate path validation 1125 ([RFC6125], Section 6) to the specified trust anchor. If the 1126 bootstrap server entry does not contain a trust anchor certificate 1127 device, the device MUST establish a provisional connection to the 1128 bootstrap server (i.e., by blindly accepting its server certificate), 1129 and set trust-state to FALSE. 1131 If the redirect information is untrusted (e.g., trust-state is 1132 FALSE), the device MUST discard any trust anchors provided by the 1133 redirect information and establish a provisional connection to the 1134 bootstrap server (i.e., by blindly accepting its TLS server 1135 certificate). 1137 5.6. Processing Onboarding Information 1139 In order to process onboarding information (Section 2.2), the device 1140 MUST follow the steps presented in this section. 1142 When processing onboarding information, the device MUST first process 1143 the boot image information (if any), then execute the pre- 1144 configuration script (if any), then commit the initial configuration 1145 (if any), and then execute the post-configuration script (if any), in 1146 that order. 1148 When the onboarding information is obtained from a trusted bootstrap 1149 server, the device MUST send the "bootstrap-initiated" progress 1150 report, and send either a terminating "boot-image-installed- 1151 rebooting", "bootstrap-complete", or error specific progress report. 1152 If the bootstrap server's "get-bootstrapping-data" RPC-reply's 1153 "reporting-level" node is set to "verbose", the device MUST 1154 additionally send all appropriate non-terminating progress reports 1155 (e.g., initiated, warning, complete, etc.). Regardless the 1156 reporting-level indicated by the bootstrap server, the device MAY 1157 send progress reports beyond the mandatory ones specified for the 1158 given reporting level. 1160 When the onboarding information is obtained from an untrusted 1161 bootstrap server, the device MUST NOT send any progress reports to 1162 the bootstrap server. 1164 If the device encounters an error at any step, it MUST stop 1165 processing the onboarding information and return to the bootstrapping 1166 sequence described in Section 5.2. In the context of a recursive 1167 algorithm, the device MUST return to the enclosing loop, not back to 1168 the very beginning. Some state MAY be retained from the 1169 bootstrapping process (e.g., updated boot image, logs, remnants from 1170 a script, etc.). However, the retained state MUST NOT be active in 1171 any way (e.g., no new configuration or running of software), and MUST 1172 NOT hinder the ability for the device to continue the bootstrapping 1173 sequence (i.e., process onboarding information from another bootstrap 1174 server). 1176 At this point, the specific ordered sequence of actions the device 1177 MUST perform is described. 1179 If the onboarding information is obtained from a trusted bootstrap 1180 server, the device MUST send a "bootstrap-initiated" progress report. 1181 It is an error if the device does not receive back the "204 No 1182 Content" HTTP status line. If an error occurs, the device MUST try 1183 to send a "bootstrap-error" progress report before exiting. 1185 The device MUST parse the provided onboarding information document, 1186 to extract values used in subsequent steps. Whether using a stream- 1187 based parser or not, if there is an error when parsing the onboarding 1188 information, and the device is connected to a trusted bootstrap 1189 server, the device MUST try to send a "parsing-error" progress report 1190 before exiting. 1192 If boot image criteria are specified, the device MUST first determine 1193 if the boot image it is running satisfies the specified boot image 1194 criteria. If the device is already running the specified boot image, 1195 then it skips the remainder of this step. If the device is not 1196 running the specified boot image, then it MUST download, verify, and 1197 install, in that order, the specified boot image, and then reboot. 1198 If connected to a trusted bootstrap server, the device MAY try to 1199 send a "boot-image-mismatch" progress report. To download the boot 1200 image, the device MUST only use the URIs supplied by the onboarding 1201 information. To verify the boot image, the device MUST either use 1202 one of the verification fingerprints supplied by the onboarding 1203 information, or use a cryptographic signature embedded into the boot 1204 image itself using a mechanism not described by this document. 1205 Before rebooting, if connected to a trusted bootstrap server, the 1206 device MUST try to send a "boot-image-installed-rebooting" progress 1207 report. Upon rebooting, the bootstrapping process runs again, which 1208 will eventually come to this step again, but then the device will be 1209 running the specified boot image, and thus will move to processing 1210 the next step. If an error occurs at any step while the device is 1211 connected to a trusted bootstrap server (i.e., before the reboot), 1212 the device MUST try to send a "boot-image-error" progress report 1213 before exiting. 1215 If a pre-configuration script has been specified, the device MUST 1216 execute the script, capture any output emitted from the script, and 1217 check if the script had any warnings or errors. If an error occurs 1218 while the device is connected to a trusted bootstrap server, the 1219 device MUST try to send a "pre-script-error" progress report before 1220 exiting. 1222 If an initial configuration has been specified, the device MUST 1223 atomically commit the provided initial configuration, using the 1224 approach specified by the "configuration-handling" leaf. If an error 1225 occurs while the device is connected to a trusted bootstrap server, 1226 the device MUST try to send a "config-error" progress report before 1227 exiting. 1229 If a post-configuration script has been specified, the device MUST 1230 execute the script, capture any output emitted from the script, and 1231 check if the script had any warnings or errors. If an error occurs 1232 while the device is connected to a trusted bootstrap server, the 1233 device MUST try to send a "post-script-error" progress report before 1234 exiting. 1236 If the onboarding information was obtained from a trusted bootstrap 1237 server, and the result of the bootstrapping process did not disable 1238 the "flag to enable zerotouch bootstrapping" described in 1239 Section 5.1, the device SHOULD send an "bootstrap-warning" progress 1240 report. 1242 If the onboarding information was obtained from a trusted bootstrap 1243 server, the device MUST send a "bootstrap-complete" progress report. 1244 It is an error if the device does not receive back the "204 No 1245 Content" HTTP status line. If an error occurs, the device MUST try 1246 to send a "bootstrap-error" progress report before exiting. 1248 At this point, the device has completely processed the bootstrapping 1249 data. 1251 The device is now running its initial configuration. Notably, if 1252 NETCONF Call Home or RESTCONF Call Home [RFC8071] is configured, the 1253 device initiates trying to establish the call home connections at 1254 this time. 1256 Implementation Notes: 1258 Implementations may vary in how to ensure no unwanted state is 1259 retained when an error occurs. 1261 Following are some guidelines for if the implementation chooses to 1262 undo previous steps: 1264 * When an error occurs, the device must roll out of the current 1265 step and any previous steps. 1267 * Most steps are atomic. For instance, when a commit fails, it 1268 is expected to have no impact on the configuration. Similarly, 1269 if the error occurs when executing a script, the script will 1270 gracefully exit. 1272 * In case the error occurs after the initial configuration was 1273 committed, the device must restore the configuration to the 1274 configuration that existed prior to the configuration being 1275 committed. 1277 * In case the error occurs after a script had executed 1278 successfully, it may be helpful for the implementation to 1279 define scripts as being able to take a conceptual input 1280 parameter indicating that the script should remove its 1281 previously set state. 1283 6. The Zero Touch Information Data Model 1285 This section defines a YANG 1.1 [RFC7950] module that is used to 1286 define the data model for the zero touch information artifact 1287 described in Section 3.1. This data model uses the "yang-data" 1288 extension statement defined in [I-D.ietf-netmod-yang-data-ext]. 1289 Examples illustrating this data model are provided in Section 6.2. 1291 6.1. Data Model Overview 1293 The following tree diagram provides an overview of the data model for 1294 the zero touch information artifact. 1296 module: ietf-zerotouch-information 1298 yang-data zerotouch-information: 1299 +-- (information-type) 1300 +--:(redirect-information) 1301 | +-- redirect-information 1302 | +-- bootstrap-server* [address] 1303 | +-- address inet:host 1304 | +-- port? inet:port-number 1305 | +-- trust-anchor? cms 1306 +--:(onboarding-information) 1307 +-- onboarding-information 1308 +-- boot-image 1309 | +-- os-name? string 1310 | +-- os-version? string 1311 | +-- download-uri* inet:uri 1312 | +-- image-verification* [hash-algorithm] 1313 | +-- hash-algorithm identityref 1314 | +-- hash-value yang:hex-string 1315 +-- configuration-handling? enumeration 1316 +-- pre-configuration-script? script 1317 +-- configuration? binary 1318 +-- post-configuration-script? script 1320 6.2. Example Usage 1322 The following example illustrates how redirect information 1323 (Section 2.1) can be encoded using JSON. 1325 { 1326 "ietf-zerotouch-information:redirect-information" : { 1327 "bootstrap-server" : [ 1328 { 1329 "address" : "phs1.example.com", 1330 "port" : 8443, 1331 "trust-anchor" : "base64encodedvalue==" 1332 }, 1333 { 1334 "address" : "phs2.example.com", 1335 "port" : 8443, 1336 "trust-anchor" : "base64encodedvalue==" 1337 }, 1338 { 1339 "address" : "phs3.example.com", 1340 "port" : 8443, 1341 "trust-anchor" : "base64encodedvalue==" 1342 } 1343 ] 1344 } 1345 } 1347 The following example illustrates how onboarding information 1348 (Section 2.2) can be encoded using JSON. 1350 [Note: '\' line wrapping for formatting only] 1352 { 1353 "ietf-zerotouch-information:onboarding-information" : { 1354 "boot-image" : { 1355 "os-name" : "VendorOS", 1356 "os-version" : "17.2R1.6", 1357 "download-uri" : [ "http://some/path/to/raw/file" ], 1358 "image-verification" : [ 1359 { 1360 "hash-algorithm" : "ietf-zerotouch-information:sha-256", 1361 "hash-value" : "ba:ec:cf:a5:67:82:b4:10:77:c6:67:a6:22:ab:\ 1362 7d:50:04:a7:8b:8f:0e:db:02:8b:f4:75:55:fb:c1:13:b2:33" 1363 } 1364 ] 1365 }, 1366 "configuration-handling" : "merge", 1367 "pre-configuration-script" : "base64encodedvalue==", 1368 "configuration" : "base64encodedvalue==", 1369 "post-configuration-script" : "base64encodedvalue==" 1370 } 1371 } 1373 6.3. YANG Module 1375 The zero touch information data model is defined by the YANG module 1376 presented in this section. 1378 This module uses data types defined in [RFC5280], [RFC5652], 1379 [RFC6234], and [RFC6991], an extension statement from 1380 [I-D.ietf-netmod-yang-data-ext], and an encoding defined in 1381 [ITU.X690.2015]. 1383 file "ietf-zerotouch-information@2018-09-13.yang" 1384 module ietf-zerotouch-information { 1385 yang-version 1.1; 1386 namespace "urn:ietf:params:xml:ns:yang:ietf-zerotouch-information"; 1387 prefix zti; 1389 import ietf-yang-types { 1390 prefix yang; 1391 reference "RFC 6991: Common YANG Data Types"; 1392 } 1393 import ietf-inet-types { 1394 prefix inet; 1395 reference "RFC 6991: Common YANG Data Types"; 1396 } 1397 import ietf-yang-data-ext { 1398 prefix yd; 1399 reference "I-D.ietf-netmod-yang-data-ext: YANG Data Extensions"; 1400 } 1402 organization 1403 "IETF NETCONF (Network Configuration) Working Group"; 1405 contact 1406 "WG Web: http://tools.ietf.org/wg/netconf 1407 WG List: 1408 Author: Kent Watsen "; 1410 description 1411 "This module defines the data model for the Zero Touch 1412 Information artifact defined in RFC XXXX: Zero Touch 1413 Provisioning for Networking Devices. 1415 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1416 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', 1417 and 'OPTIONAL' in the module text are to be interpreted as 1418 described in RFC 2119. 1420 Copyright (c) 2018 IETF Trust and the persons identified as 1421 authors of the code. All rights reserved. 1423 Redistribution and use in source and binary forms, with or 1424 without modification, is permitted pursuant to, and subject 1425 to the license terms contained in, the Simplified BSD License 1426 set forth in Section 4.c of the IETF Trust's Legal Provisions 1427 Relating to IETF Documents (http://trustee.ietf.org/license-info) 1429 This version of this YANG module is part of RFC XXXX; see the 1430 RFC itself for full legal notices."; 1432 revision 2018-09-13 { 1433 description 1434 "Initial version"; 1435 reference 1436 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 1437 } 1439 // identities 1441 identity hash-algorithm { 1442 description 1443 "A base identity for hash algorithm verification"; 1444 } 1446 identity sha-256 { 1447 base "hash-algorithm"; 1448 description "The SHA-256 algorithm."; 1449 reference "RFC 6234: US Secure Hash Algorithms."; 1450 } 1452 // typedefs 1454 typedef cms { 1455 type binary; 1456 description 1457 "A ContentInfo structure, as specified in RFC 5652, 1458 encoded using ASN.1 distinguished encoding rules (DER), 1459 as specified in ITU-T X.690."; 1460 reference 1461 "RFC 5652: 1462 Cryptographic Message Syntax (CMS) 1463 ITU-T X.690: 1464 Information technology - ASN.1 encoding rules: 1465 Specification of Basic Encoding Rules (BER), 1466 Canonical Encoding Rules (CER) and Distinguished 1467 Encoding Rules (DER)."; 1468 } 1469 // yang-data 1471 yd:yang-data "zerotouch-information" { 1472 choice information-type { 1473 mandatory true; 1474 description 1475 "This choice statement ensures the response contains 1476 redirect-information or onboarding-information."; 1477 container redirect-information { 1478 description 1479 "Redirect information is described in Section 2.1 in 1480 RFC XXXX. Its purpose is to redirect a device to 1481 another bootstrap server."; 1482 reference 1483 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 1484 list bootstrap-server { 1485 key "address"; 1486 min-elements 1; 1487 description 1488 "A bootstrap server entry."; 1489 leaf address { 1490 type inet:host; 1491 mandatory true; 1492 description 1493 "The IP address or hostname of the bootstrap server the 1494 device should redirect to."; 1495 } 1496 leaf port { 1497 type inet:port-number; 1498 default "443"; 1499 description 1500 "The port number the bootstrap server listens on. If no 1501 port is specified, the IANA-assigned port for 'https' 1502 (443) is used."; 1503 } 1504 leaf trust-anchor { 1505 type cms; 1506 description 1507 "A CMS structure that MUST contain the chain of 1508 X.509 certificates needed to authenticate the TLS 1509 certificate presented by this bootstrap server. 1511 The CMS MUST only contain a single chain of 1512 certificates. The bootstrap server MUST only 1513 authenticate to last intermediate CA certificate 1514 listed in the chain. 1516 In all cases, the chain MUST include a self-signed 1517 root certificate. In the case where the root 1518 certificate is itself the issuer of the bootstrap 1519 server's TLS certificate, only one certificate 1520 is present. 1522 If needed by the device, this CMS structure MAY 1523 also contain suitably fresh revocation objects 1524 with which the device can verify the revocation 1525 status of the certificates. 1527 This CMS encodes the degenerate form of the SignedData 1528 structure that is commonly used to disseminate X.509 1529 certificates and revocation objects (RFC 5280)."; 1530 reference 1531 "RFC 5280: 1532 Internet X.509 Public Key Infrastructure Certificate 1533 and Certificate Revocation List (CRL) Profile."; 1534 } 1535 } 1536 } 1537 container onboarding-information { 1538 description 1539 "Onboarding information is described in Section 2.2 in 1540 RFC XXXX. Its purpose is to provide the device everything 1541 it needs to bootstrap itself."; 1542 reference 1543 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 1544 container boot-image { 1545 description 1546 "Specifies criteria for the boot image the device MUST 1547 be running, as well as information enabling the device 1548 to install the required boot image."; 1549 leaf os-name { 1550 type string; 1551 description 1552 "The name of the operating system software the device 1553 MUST be running in order to not require a software 1554 image upgrade (ex. VendorOS)."; 1555 } 1556 leaf os-version { 1557 type string; 1558 description 1559 "The version of the operating system software the 1560 device MUST be running in order to not require a 1561 software image upgrade (ex. 17.3R2.1)."; 1562 } 1563 leaf-list download-uri { 1564 type inet:uri; 1565 ordered-by user; 1566 description 1567 "An ordered list of URIs to where the same boot image 1568 file may be obtained. How the URI schemes (http, ftp, 1569 etc.) a device supports are known is vendor specific. 1570 If a secure scheme (e.g., https) is provided, a device 1571 MAY establish an untrusted connection to the remote 1572 server, by blindly accepting the server's end-entity 1573 certificate, to obtain the boot image."; 1574 } 1575 list image-verification { 1576 must '../download-uri' { 1577 description 1578 "Download URIs must be provided if an image is to 1579 be verified."; 1580 } 1581 key hash-algorithm; 1582 description 1583 "A list of hash values that a device can use to verify 1584 boot image files with."; 1585 leaf hash-algorithm { 1586 type identityref { 1587 base "hash-algorithm"; 1588 } 1589 description 1590 "Identifies the hash algorithm used."; 1591 } 1592 leaf hash-value { 1593 type yang:hex-string; 1594 mandatory true; 1595 description 1596 "The hex-encoded value of the specified hash 1597 algorithm over the contents of the boot image 1598 file."; 1599 } 1600 } 1601 } 1602 leaf configuration-handling { 1603 type enumeration { 1604 enum "merge" { 1605 description 1606 "Merge configuration into the running datastore."; 1607 } 1608 enum "replace" { 1609 description 1610 "Replace the existing running datastore with the 1611 passed configuration."; 1612 } 1614 } 1615 must '../configuration'; 1616 description 1617 "This enumeration indicates how the server should process 1618 the provided configuration."; 1619 } 1620 leaf pre-configuration-script { 1621 type script; 1622 description 1623 "A script that, when present, is executed before the 1624 configuration has been processed."; 1625 } 1626 leaf configuration { 1627 type binary; 1628 must '../configuration-handling'; 1629 description 1630 "Any configuration known to the device. The use of 1631 the 'binary' type enables e.g., XML-content to be 1632 embedded into a JSON document. The exact encoding 1633 of the content, as with the scripts, is vendor 1634 specific."; 1635 } 1636 leaf post-configuration-script { 1637 type script; 1638 description 1639 "A script that, when present, is executed after the 1640 configuration has been processed."; 1641 } 1642 } 1643 } 1644 } 1646 typedef script { 1647 type binary; 1648 description 1649 "A device specific script that enables the execution of 1650 commands to perform actions not possible thru configuration 1651 alone. 1653 No attempt is made to standardize the contents, running 1654 context, or programming language of the script, other than 1655 that it can indicate if any warnings or errors occurred and 1656 can emit output. The contents of the script are considered 1657 specific to the vendor, product line, and/or model of the 1658 device. 1660 If the script execution indicates that an warning occurred, 1661 then the device MUST assume that the script had a soft error 1662 that the script believes will not affect manageability. 1664 If the script execution indicates that an error occurred, 1665 the device MUST assume the script had a hard error that the 1666 script believes will affect manageability. In this case, 1667 the script is required to gracefully exit, removing any 1668 state that might hinder the device's ability to continue 1669 the bootstrapping sequence (e.g., process onboarding 1670 information obtained from another bootstrap server)."; 1671 } 1672 } 1673 1675 7. The Zero Touch Bootstrap Server API 1677 This section defines the API for bootstrap servers. The API is 1678 defined as that produced by a RESTCONF [RFC8040] server that supports 1679 the YANG 1.1 [RFC7950] module defined in this section. 1681 7.1. API Overview 1683 The following tree diagram provides an overview for the bootstrap 1684 server RESTCONF API. 1686 module: ietf-zerotouch-bootstrap-server 1688 rpcs: 1689 +---x get-bootstrapping-data 1690 | +---w input 1691 | | +---w untrusted-connection? empty 1692 | | +---w hw-model? string 1693 | | +---w os-name? string 1694 | | +---w os-version? string 1695 | | +---w nonce? binary 1696 | +--ro output 1697 | +--ro reporting-level? enumeration 1698 | +--ro zerotouch-information cms 1699 | +--ro owner-certificate? cms 1700 | +--ro ownership-voucher? cms 1701 +---x report-progress 1702 +---w input 1703 +---w progress-type enumeration 1704 +---w message? string 1705 +---w ssh-host-keys 1706 | +---w ssh-host-key* binary 1707 +---w trust-anchor-certs 1708 +---w trust-anchor-cert* cms 1710 7.2. Example Usage 1712 This section presents three examples illustrating the bootstrap 1713 server's API. Two examples are provided for the "get-bootstrapping- 1714 data" RPC (once to an untrusted bootstrap server, and again to a 1715 trusted bootstrap server), and one example for the "report-progress" 1716 RPC. 1718 The following example illustrates a device using the API to fetch its 1719 bootstrapping data from a untrusted bootstrap server. In this 1720 example, the device sends the "untrusted-connection" input parameter 1721 and receives signed data in the response. 1723 REQUEST 1724 ------- 1725 ['\' line wrapping added for formatting only] 1727 POST /restconf/operations/ietf-zerotouch-bootstrap-server:get-boot\ 1728 strapping-data HTTP/1.1 1729 HOST: example.com 1730 Content-Type: application/yang.data+xml 1732 1734 1735 1737 RESPONSE 1738 -------- 1740 HTTP/1.1 200 OK 1741 Date: Sat, 31 Oct 2015 17:02:40 GMT 1742 Server: example-server 1743 Content-Type: application/yang.data+xml 1745 1747 base64encodedvalue== 1748 base64encodedvalue== 1749 base64encodedvalue== 1750 1752 The following example illustrates a device using the API to fetch its 1753 bootstrapping data from a trusted bootstrap server. In this example, 1754 the device sends addition input parameters to the bootstrap server, 1755 which it may use when formulating its response to the device. 1757 REQUEST 1758 ------- 1759 ['\' line wrapping added for formatting only] 1761 POST /restconf/operations/ietf-zerotouch-bootstrap-server:get-boot\ 1762 strapping-data HTTP/1.1 1763 HOST: example.com 1764 Content-Type: application/yang.data+xml 1766 1768 model-x 1769 vendor-os 1770 17.3R2.1 1771 base64encodedvalue== 1772 1774 RESPONSE 1775 -------- 1777 HTTP/1.1 200 OK 1778 Date: Sat, 31 Oct 2015 17:02:40 GMT 1779 Server: example-server 1780 Content-Type: application/yang.data+xml 1782 1784 verbose 1785 base64encodedvalue== 1786 1788 The following example illustrates a device using the API to post a 1789 progress report to a bootstrap server. Illustrated below is the 1790 "bootstrap-complete" message, but the device may send other progress 1791 reports to the server while bootstrapping. In this example, the 1792 device is sending both its SSH host keys and a TLS server 1793 certificate, which the bootstrap server may, for example, pass to an 1794 NMS, as discussed in Appendix C.3. 1796 REQUEST 1797 ------- 1798 ['\' line wrapping added for formatting only] 1800 POST /restconf/operations/ietf-zerotouch-bootstrap-server:report-\ 1801 progress HTTP/1.1 1802 HOST: example.com 1803 Content-Type: application/yang.data+xml 1805 1807 bootstrap-complete 1808 example message 1809 1810 base64encodedvalue== 1811 base64encodedvalue2= 1812 1813 1814 base64encodedvalue== 1815 1816 1818 RESPONSE 1819 -------- 1821 HTTP/1.1 204 No Content 1822 Date: Sat, 31 Oct 2015 17:02:40 GMT 1823 Server: example-server 1825 7.3. YANG Module 1827 The bootstrap server's device-facing API is normatively defined by 1828 the YANG module defined in this section. 1830 This module uses data types defined in [RFC4253], [RFC5652], 1831 [RFC5280], [RFC6960], and [RFC8366], uses an encoding defined in 1832 [ITU.X690.2015], and makes a reference to [RFC6187]. 1834 file "ietf-zerotouch-bootstrap-server@2018-09-13.yang" 1835 module ietf-zerotouch-bootstrap-server { 1836 yang-version 1.1; 1837 namespace 1838 "urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server"; 1839 prefix ztbs; 1841 organization 1842 "IETF NETCONF (Network Configuration) Working Group"; 1844 contact 1845 "WG Web: 1846 WG List: 1847 Author: Kent Watsen "; 1849 description 1850 "This module defines an interface for bootstrap servers, as 1851 defined by RFC XXXX: Zero Touch Provisioning for Networking 1852 Devices. 1854 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1855 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', 1856 and 'OPTIONAL' in the module text are to be interpreted as 1857 described in RFC 2119. 1859 Copyright (c) 2018 IETF Trust and the persons identified as 1860 authors of the code. All rights reserved. 1862 Redistribution and use in source and binary forms, with or 1863 without modification, is permitted pursuant to, and subject 1864 to the license terms contained in, the Simplified BSD License 1865 set forth in Section 4.c of the IETF Trust's Legal Provisions 1866 Relating to IETF Documents (http://trustee.ietf.org/license-info) 1868 This version of this YANG module is part of RFC XXXX; see the 1869 RFC itself for full legal notices."; 1871 revision 2018-09-13 { 1872 description 1873 "Initial version"; 1874 reference 1875 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 1876 } 1878 // typedefs 1880 typedef cms { 1881 type binary; 1882 description 1883 "A CMS structure, as specified in RFC 5652, encoded using 1884 ASN.1 distinguished encoding rules (DER), as specified in 1885 ITU-T X.690."; 1886 reference 1887 "RFC 5652: 1888 Cryptographic Message Syntax (CMS) 1889 ITU-T X.690: 1890 Information technology - ASN.1 encoding rules: 1891 Specification of Basic Encoding Rules (BER), 1892 Canonical Encoding Rules (CER) and Distinguished 1893 Encoding Rules (DER)."; 1894 } 1896 // RPCs 1898 rpc get-bootstrapping-data { 1899 description 1900 "This RPC enables a device, as identified by the RESTCONF 1901 username, to obtain bootstrapping data that has been made 1902 available for it."; 1903 input { 1904 leaf untrusted-connection { 1905 type empty; 1906 description 1907 "This optional input parameter enables a device to 1908 communicate to the bootstrap server that it is unable to 1909 authenticate the bootstrap server's TLS certificate. In 1910 such circumstances, the device likely does not send any 1911 of the other input parameters, except for the 'nonce' 1912 parameter. Upon receiving this input parameter, the 1913 bootstrap server should only return unsigned redirect 1914 information or signed data of any type."; 1915 } 1916 leaf hw-model { 1917 type string; 1918 description 1919 "This optional input parameter enables a device to 1920 communicate to the bootstrap server its vendor specific 1921 hardware model number. This parameter may be needed, 1922 for instance, when a device's IDevID certificate does 1923 not include the 'hardwareModelName' value in its 1924 subjectAltName field, as is allowed by 802.1AR-2009."; 1925 reference 1926 "IEEE 802.1AR-2009: IEEE Standard for Local and 1927 metropolitan area networks - Secure Device Identity"; 1928 } 1929 leaf os-name { 1930 type string; 1931 description 1932 "This optional input parameter enables a device to 1933 communicate to the bootstrap server the name of its 1934 operating system. This parameter may be useful if 1935 the device, as identified by its serial number, can 1936 run more than one type of operating system (e.g., 1937 on a white-box system."; 1938 } 1939 leaf os-version { 1940 type string; 1941 description 1942 "This optional input parameter enables a device to 1943 communicate to the bootstrap server the version of its 1944 operating system. This parameter may be used by a 1945 bootstrap server to return an operating system specific 1946 response to the device, thus negating the need for a 1947 potentially expensive boot-image update."; 1948 } 1949 leaf nonce { 1950 type binary { 1951 length "8..32"; 1952 } 1953 description 1954 "This optional input parameter enables a device to 1955 communicate to the bootstrap server a nonce value. 1956 This may be especially useful for devices lacking 1957 an accurate clock, as then the bootstrap server 1958 can dynamically obtain from the manufacturer a 1959 voucher with the nonce value in it, as described 1960 in RFC 8366."; 1961 reference 1962 "RFC 8366: 1963 A Voucher Artifact for Bootstrapping Protocols"; 1964 } 1965 } 1966 output { 1967 leaf reporting-level { 1968 type enumeration { 1969 enum standard { 1970 description 1971 "Send just the progress reports required by RFC XXXX."; 1972 } 1973 enum verbose { 1974 description 1975 "Send additional progress reports that might help 1976 troubleshooting an SZTP bootstrapping issue."; 1977 } 1978 } 1979 default standard; 1980 description 1981 "Specifies the reporting level for progress reports the 1982 bootstrap server would like to receive when processing 1983 onboarding information. Progress reports are not sent 1984 when processing redirect information, or when the 1985 bootstrap server is untrusted (e.g., device sent the 1986 '' input parameter)."; 1987 } 1988 leaf zerotouch-information { 1989 type cms; 1990 mandatory true; 1991 description 1992 "A zero touch information artifact, as described in 1993 Section 3.1 of RFC XXXX."; 1994 reference 1995 "RFC XXXX: 1996 Zero Touch Provisioning for Networking Devices"; 1997 } 1998 leaf owner-certificate { 1999 type cms; 2000 must '../ownership-voucher' { 2001 description 2002 "An ownership voucher must be present whenever an owner 2003 certificate is presented."; 2004 } 2005 description 2006 "An owner certificate artifact, as described in Section 2007 3.2 of RFC XXXX. This leaf is optional because it is 2008 only needed when the zero touch information artifact 2009 is signed."; 2010 reference 2011 "RFC XXXX: 2012 Zero Touch Provisioning for Networking Devices"; 2013 } 2014 leaf ownership-voucher { 2015 type cms; 2016 must '../owner-certificate' { 2017 description 2018 "An owner certificate must be present whenever an 2019 ownership voucher is presented."; 2020 } 2021 description 2022 "An ownership voucher artifact, as described by Section 2023 3.3 of RFC XXXX. This leaf is optional because it is 2024 only needed when the zero touch information artifact 2025 is signed."; 2026 reference 2027 "RFC XXXX: 2028 Zero Touch Provisioning for Networking Devices"; 2029 } 2030 } 2031 } 2033 rpc report-progress { 2034 description 2035 "This RPC enables a device, as identified by the RESTCONF 2036 username, to report its bootstrapping progress to the 2037 bootstrap server. This RPC is expected to be used when 2038 the device obtains onboarding-information from a trusted 2039 bootstap server."; 2040 input { 2041 leaf progress-type { 2042 type enumeration { 2043 enum "bootstrap-initiated" { 2044 description 2045 "Indicates that the device just used the 2046 'get-bootstrapping-data' RPC. The 'message' node 2047 below MAY contain any additional information that 2048 the manufacturer thinks might be useful."; 2049 } 2050 enum "parsing-initiated" { 2051 description 2052 "Indicates that the device is about to start parsing 2053 the onboarding information. This progress type is 2054 only for when parsing is implemented as a distinct 2055 step."; 2056 } 2057 enum "parsing-warning" { 2058 description 2059 "Indicates that the device had a non-fatal error when 2060 parsing the response from the bootstrap server. The 2061 'message' node below SHOULD indicate the specific 2062 warning that occurred."; 2063 } 2064 enum "parsing-error" { 2065 description 2066 "Indicates that the device encountered a fatal error 2067 when parsing the response from the bootstrap server. 2068 For instance, this could be due to malformed encoding, 2069 the device expecting signed data when only unsigned 2070 data is provided, the ownership voucher not listing 2071 the device's serial number, or because the signature 2072 didn't match. The 'message' node below SHOULD 2073 indicate the specific error. This progress type 2074 also indicates that the device has abandoned trying 2075 to bootstrap off this bootstrap server."; 2076 } 2077 enum "parsing-complete" { 2078 description 2079 "Indicates that the device successfully completed 2080 parsing the onboarding information. This progress 2081 type is only for when parsing is implemented as a 2082 distinct step."; 2083 } 2084 enum "boot-image-initiated" { 2085 description 2086 "Indicates that the device is about to start 2087 processing the boot-image information."; 2088 } 2089 enum "boot-image-warning" { 2090 description 2091 "Indicates that the device encountered a non-fatal 2092 error condition when trying to install a boot-image. 2093 A possible reason might include a need to reformat a 2094 partition causing loss of data. The 'message' node 2095 below SHOULD indicate any warning messages that were 2096 generated."; 2097 } 2098 enum "boot-image-error" { 2099 description 2100 "Indicates that the device encountered an error when 2101 trying to install a boot-image, which could be for 2102 reasons such as a file server being unreachable, 2103 file not found, signature mismatch, etc. The 2104 'message' node SHOULD indicate the specific error 2105 that occurred. This progress type also indicates 2106 that the device has abandoned trying to bootstrap 2107 off this bootstrap server."; 2108 } 2109 enum "boot-image-mismatch" { 2110 description 2111 "Indicates that the device that has determined that 2112 it is not running the correct boot image. This 2113 message SHOULD precipitate trying to download 2114 a boot image."; 2115 } 2116 enum "boot-image-installed-rebooting" { 2117 description 2118 "Indicates that the device successfully installed 2119 a new boot image and is about to reboot. After 2120 sending this progress type, the device is not 2121 expected to access the bootstrap server again."; 2122 } 2123 enum "boot-image-complete" { 2124 description 2125 "Indicates that the device believes that it is 2126 running the correct boot-image."; 2127 } 2128 enum "pre-script-initiated" { 2129 description 2130 "Indicates that the device is about to execute the 2131 'pre-configuration-script'."; 2133 } 2134 enum "pre-script-warning" { 2135 description 2136 "Indicates that the device obtained a warning from the 2137 'pre-configuration-script' when it was executed. The 2138 'message' node below SHOULD capture any output the 2139 script produces."; 2140 } 2141 enum "pre-script-error" { 2142 description 2143 "Indicates that the device obtained an error from the 2144 'pre-configuration-script' when it was executed. The 2145 'message' node below SHOULD capture any output the 2146 script produces. This progress type also indicates 2147 that the device has abandoned trying to bootstrap 2148 off this bootstrap server."; 2149 } 2150 enum "pre-script-complete" { 2151 description 2152 "Indicates that the device successfully executed the 2153 'pre-configuration-script'."; 2154 } 2155 enum "config-initiated" { 2156 description 2157 "Indicates that the device is about to commit the 2158 initial configuration."; 2159 } 2160 enum "config-warning" { 2161 description 2162 "Indicates that the device obtained warning messages 2163 when it committed the initial configuration. The 2164 'message' node below SHOULD indicate any warning 2165 messages that were generated."; 2166 } 2167 enum "config-error" { 2168 description 2169 "Indicates that the device obtained error messages 2170 when it committed the initial configuration. The 2171 'message' node below SHOULD indicate the error 2172 messages that were generated. This progress type 2173 also indicates that the device has abandoned trying 2174 to bootstrap off this bootstrap server."; 2175 } 2176 enum "config-complete" { 2177 description 2178 "Indicates that the device successfully committed 2179 the initial configuration."; 2180 } 2181 enum "post-script-initiated" { 2182 description 2183 "Indicates that the device is about to execute the 2184 'post-configuration-script'."; 2185 } 2186 enum "post-script-warning" { 2187 description 2188 "Indicates that the device obtained a warning from the 2189 'post-configuration-script' when it was executed. The 2190 'message' node below SHOULD capture any output the 2191 script produces."; 2192 } 2193 enum "post-script-error" { 2194 description 2195 "Indicates that the device obtained an error from the 2196 'post-configuration-script' when it was executed. The 2197 'message' node below SHOULD capture any output the 2198 script produces. This progress type also indicates 2199 that the device has abandoned trying to bootstrap 2200 off this bootstrap server."; 2201 } 2202 enum "post-script-complete" { 2203 description 2204 "Indicates that the device successfully executed the 2205 'post-configuration-script'."; 2206 } 2207 enum "bootstrap-warning" { 2208 description 2209 "Indicates that a warning condition occurred for which 2210 there no other 'progress-type' enumeration is deemed 2211 suitable. The 'message' node below SHOULD describe 2212 the warning."; 2213 } 2214 enum "bootstrap-error" { 2215 description 2216 "Indicates that an error condition occurred for which 2217 there no other 'progress-type' enumeration is deemed 2218 suitable. The 'message' node below SHOULD describe 2219 the error. This progress type also indicates that 2220 the device has abandoned trying to bootstrap off 2221 this bootstrap server."; 2222 } 2223 enum "bootstrap-complete" { 2224 description 2225 "Indicates that the device successfully processed 2226 all 'onboarding-information' provided, and that it 2227 is ready to be managed. The 'message' node below 2228 MAY contain any additional information that the 2229 manufacturer thinks might be useful. After sending 2230 this progress type, the device is not expected to 2231 access the bootstrap server again."; 2232 } 2233 enum "informational" { 2234 description 2235 "Indicates any additional information not captured 2236 by any of the other progress types. For instance, 2237 a message indicating that the device is about to 2238 reboot after having installed a boot-image could 2239 be provided. The 'message' node below SHOULD 2240 contain information that the manufacturer thinks 2241 might be useful."; 2242 } 2243 } 2244 mandatory true; 2245 description 2246 "The type of progress report provided."; 2247 } 2248 leaf message { 2249 type string; 2250 description 2251 "An optional arbitrary value."; 2252 } 2253 container ssh-host-keys { 2254 when "../progress-type = 'bootstrap-complete'" { 2255 description 2256 "SSH host keys are only sent when the progress type 2257 is 'bootstrap-complete'."; 2258 } 2259 description 2260 "A list of trust anchor certificates an NMS may use to 2261 authenticate subsequent SSH-based connections to this 2262 device (e.g., netconf-ssh, netconf-ch-ssh)."; 2263 leaf-list ssh-host-key { 2264 type binary; 2265 description 2266 "The binary public key data for this SSH key, as 2267 specified by RFC 4253, Section 6.6, i.e.: 2269 string certificate or public key format 2270 identifier 2271 byte[n] key/certificate data."; 2272 reference 2273 "RFC 4253: The Secure Shell (SSH) Transport Layer 2274 Protocol"; 2275 } 2276 } 2277 container trust-anchor-certs { 2278 when "../progress-type = 'bootstrap-complete'" { 2279 description 2280 "Trust anchors are only sent when the progress type 2281 is 'bootstrap-complete'."; 2282 } 2283 description 2284 "A list of trust anchor certificates an NMS may use to 2285 authenticate subsequent certificate-based connections 2286 to this device (e.g., restconf-tls, netconf-tls, or 2287 even netconf-ssh with X.509 support from RFC 6187). 2288 In practice, trust anchors for IDevID certificates do 2289 not need to be conveyed using this mechanism."; 2290 reference 2291 "RFC 6187: 2292 X.509v3 Certificates for Secure Shell Authentication."; 2293 leaf-list trust-anchor-cert { 2294 type cms; 2295 description 2296 "A CMS structure whose top-most content type MUST be the 2297 signed-data content type, as described by Section 5 in 2298 RFC 5652. 2300 The CMS MUST contain the chain of X.509 certificates 2301 needed to authenticate the certificate presented by 2302 the device. 2304 The CMS MUST contain only a single chain of 2305 certificates. The device's end-entity certificate 2306 MUST only authenticate to last intermediate CA 2307 certificate listed in the chain. 2309 In all cases, the chain MUST include a self-signed 2310 root certificate. In the case where the root 2311 certificate is itself the issuer of the device's 2312 end-entity certificate, only one certificate is 2313 present. 2315 This CMS encodes the degenerate form of the SignedData 2316 structure that is commonly used to disseminate X.509 2317 certificates and revocation objects (RFC 5280)."; 2318 reference 2319 "RFC 5280: 2320 Internet X.509 Public Key Infrastructure 2321 Certificate and Certificate Revocation List (CRL) 2322 Profile. 2323 RFC 5652: 2324 Cryptographic Message Syntax (CMS)"; 2326 } 2327 } 2328 } 2329 } 2330 } 2331 2333 8. DHCP Zero Touch Options 2335 This section defines two DHCP options, one for DHCPv4 and one for 2336 DHCPv6. These two options are semantically the same, though 2337 syntactically different. 2339 8.1. DHCPv4 Zero Touch Option 2341 The DHCPv4 Zero Touch Option is used to provision the client with one 2342 or more URIs for bootstrap servers that can be contacted to attempt 2343 further configuration. 2345 DHCPv4 Zero Touch Redirect Option 2347 0 1 2348 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 2349 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2350 | option-code (143) | option-length | 2351 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2352 . . 2353 . bootstrap-server-list (variable length) . 2354 . . 2355 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2357 o option-code: OPTION_V4_ZEROTOUCH_REDIRECT (143) 2358 o option-length: The option length in octets. 2359 o bootstrap-server-list: A list of servers for the 2360 client to attempt contacting, in order to obtain 2361 further bootstrapping data, in the format shown 2362 in [common-field-encoding]. 2364 DHCPv4 Client Behavior 2366 Clients MAY request the OPTION_V4_ZEROTOUCH_REDIRECT by including its 2367 option code in the Parameter Request List (55) in DHCP request 2368 messages. 2370 On receipt of a DHCPv4 Reply message which contains the 2371 OPTION_V4_ZEROTOUCH_REDIRECT, the client processes the response 2372 according to Section 5.5, with the understanding that the "address" 2373 and "port" values are encoded in the URIs. 2375 Any invalid URI entries received in the uri-data field are ignored by 2376 the client. If OPTION_V4_ZEROTOUCH_REDIRECT does not contain at 2377 least one valid URI entry in the uri-data field, then the client MUST 2378 discard the option. 2380 As the list of URIs may exceed the maximum allowed length of a single 2381 DHCPv4 option (255 octets), the client MUST implement [RFC3396], 2382 allowing the URI list to be split across a number of 2383 OPTION_V4_ZEROTOUCH_REDIRECT option instances. 2385 DHCPv4 Server Behavior 2387 The DHCPv4 server MAY include a single instance of Option 2388 OPTION_V4_ZEROTOUCH_REDIRECT in DHCP messages it sends. Servers MUST 2389 NOT send more than one instance of the OPTION_V4_ZEROTOUCH_REDIRECT 2390 option. 2392 As the list of URIs may exceed the maximum allowed length of a single 2393 DHCPv4 option (255 octets), the server MUST implement [RFC3396], 2394 allowing the URI list to be split across a number of 2395 OPTION_V4_ZEROTOUCH_REDIRECT option instances. 2397 8.2. DHCPv6 Zero Touch Option 2399 The DHCPv6 Zero Touch Option is used to provision the client with one 2400 or more URIs for bootstrap servers that can be contacted to attempt 2401 further configuration. 2403 DHCPv6 Zero Touch Redirect Option 2405 0 1 2 3 2406 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2407 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2408 | option-code (136) | option-length | 2409 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2410 . bootstrap-server-list (variable length) . 2411 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2413 o option-code: OPTION_V6_ZEROTOUCH_REDIRECT (136) 2414 o option-length: The option length in octets. 2415 o bootstrap-server-list: A list of servers for the client to 2416 attempt contacting, in order to obtain further bootstrapping 2417 data, in the format shown in [common-field-encoding]. 2419 DHCPv6 Client Behavior 2421 Clients MAY request the OPTION_V6_ZEROTOUCH_REDIRECT option, as 2422 defined in [RFC3315], Sections 17.1.1, 18.1.1, 18.1.3, 18.1.4, 2423 18.1.5, and 22.7. As a convenience to the reader, we mention here 2424 that the client includes requested option codes in the Option Request 2425 Option. 2427 On receipt of a DHCPv6 Reply message which contains the 2428 OPTION_V6_ZEROTOUCH_REDIRECT, the client processes the response 2429 according to Section 5.5, with the understanding that the "address" 2430 and "port" values are encoded in the URIs. 2432 Any invalid URI entries received in the uri-data field are ignored by 2433 the client. If OPTION_V6_ZEROTOUCH_REDIRECT does not contain at 2434 least one valid URI entry in the uri-data field, then the client MUST 2435 discard the option. 2437 DHCPv6 Server Behavior 2439 Sections 17.2.2 and 18.2 of [RFC3315] govern server operation 2440 in regard to option assignment. As a convenience to the reader, 2441 we mention here that the server will send a particular option code 2442 only if configured with specific values for that option code and if 2443 the client requested it. 2445 Option OPTION_V6_ZEROTOUCH_REDIRECT is a singleton. Servers MUST NOT 2446 send more than one instance of the OPTION_V6_ZEROTOUCH_REDIRECT 2447 option. 2449 8.3. Common Field Encoding 2451 Both of the DHCPv4 and DHCPv6 options defined in this section encode 2452 a list of bootstrap server URIs. The "URI" structure is an option 2453 that can contain multiple URIs (see [RFC7227], Section 5.7). 2455 bootstrap-server-list: 2457 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 2458 | uri-length | URI | 2459 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 2461 o uri-length: 2 octets long, specifies the length of the URI data. 2463 o URI: URI of zerotouch bootstrap server, using the HTTPS URI 2464 scheme defined in Section 2.7.2 of RFC7230. URI MUST be in 2465 form "https://[:]". 2467 9. Security Considerations 2469 9.1. Clock Sensitivity 2471 The solution in this document relies on TLS certificates, owner 2472 certificates, and ownership vouchers, all of which require an 2473 accurate clock in order to be processed correctly (e.g., to test 2474 validity dates and revocation status). Implementations SHOULD ensure 2475 devices have an accurate clock when shipped from manufacturing 2476 facilities, and take steps to prevent clock tampering. 2478 If it is not possible to ensure clock accuracy, it is RECOMMENDED 2479 that implementations disable the aspects of the solution having clock 2480 sensitivity. In particular, such implementations should assume that 2481 TLS certificates, ownership vouchers, and owner certificates never 2482 expire and are not revokable. From an ownership voucher perspective, 2483 manufacturers SHOULD issue a single ownership voucher for the 2484 lifetime of such devices. 2486 Implementations SHOULD NOT rely on NTP for time, as NTP is not a 2487 secure protocol. 2489 9.2. Use of IDevID Certificates 2491 IDevID certificates, as defined in [Std-802.1AR-2009], are 2492 RECOMMENDED, both for the TLS-level client certificate used by 2493 devices when connecting to a bootstrap server, as well as for the 2494 device identity certificate used by owners when encrypting the zero 2495 touch artifacts. 2497 9.3. Immutable Storage for Trust Anchors 2499 Devices MUST ensure that all their trust anchor certificates, 2500 including those for connecting to bootstrap servers and verifying 2501 ownership vouchers, are protected from external modification. 2503 It may be necessary to update these certificates over time (e.g., the 2504 manufacturer wants to delegate trust to a new CA). It is therefore 2505 expected that devices MAY update these trust anchors when needed 2506 through a verifiable process, such as a software upgrade using signed 2507 software images. 2509 9.4. Secure Storage for Long-lived Private Keys 2511 Manufacturer-generated device identifiers may have very long 2512 lifetimes. For instance, [Std-802.1AR-2009] recommends using the 2513 "notAfter" value 99991231235959Z in IDevID certificates. Given the 2514 long-lived nature of these private keys, it is paramount that they 2515 are stored so as to resist discovery, such as in a secure 2516 cryptographic processor (e.g., a TPM). 2518 9.5. Blindly Authenticating a Bootstrap Server 2520 This document allows a device to blindly authenticate a bootstrap 2521 server's TLS certificate. It does so to allow for cases where the 2522 redirect information may be obtained in an unsecured manner, which is 2523 desirable to support in some cases. 2525 To compensate for this, this document requires that devices, when 2526 connected to an untrusted bootstrap server, assert that data 2527 downloaded from the server is signed. 2529 9.6. Disclosing Information to Untrusted Servers 2531 This document allows devices to establish connections to untrusted 2532 bootstrap servers. However, since the bootstrap server is untrusted, 2533 it may be under the control of an adversary, and therefore devices 2534 SHOULD be cautious about the data they send to the bootstrap server 2535 in such cases. 2537 Devices send different data to bootstrap servers at each of the 2538 protocol layers TCP, TLS, HTTP, and RESTCONF. 2540 At the TCP protocol layer, devices may relay their IP address, 2541 subject to network translations. Disclosure of this information is 2542 not considered a security risk. 2544 At the TLS protocol layer, devices may use a client certificate to 2545 identify and authenticate themselves to untrusted bootstrap servers. 2546 At a minimum, the client certificate must disclose the device's 2547 serial number, and may disclose additional information such as the 2548 device's manufacturer, hardware model, public key, etc. Knowledge of 2549 this information may provide an adversary with details needed to 2550 launch an attack. It is RECOMMENDED that secrecy of the network 2551 constituency is not relied on for security. 2553 At the HTTP protocol layer, devices may use an HTTP authentication 2554 scheme to identify and authenticate themselves to untrusted bootstrap 2555 servers. At a minimum, the authentication scheme must disclose the 2556 device's serial number and, concerningly, may, depending on the 2557 authentication mechanism used, reveal a secret that is only supposed 2558 to be known to the device (e.g., a password). Devices SHOULD NOT use 2559 an HTTP authentication scheme (e.g., HTTP Basic) with an untrusted 2560 bootstrap server that reveals a secret that is only supposed to be 2561 known to the device. 2563 At the RESTCONF protocol layer, devices use the "get-bootstrapping- 2564 data" RPC, but not the "report-progress" RPC, when connected to an 2565 untrusted bootstrap server. The "get-bootstrapping-data" RPC allows 2566 additional input parameters to be passed to the bootstrap server 2567 (e.g., "os-name", "os-version", "hw-model"). It is RECOMMENDED that 2568 devices only pass the "untrusted-connection" input parameter to an 2569 untrusted bootstrap server. While it is okay for a bootstrap server 2570 to immediately return signed onboarding information, it is 2571 RECOMMENDED that bootstrap servers instead promote the untrusted 2572 connection to a trusted connection, as described in Appendix B, thus 2573 enabling the device to use the "report-progress" RPC while processing 2574 the onboarding information. 2576 9.7. Sequencing Sources of Bootstrapping Data 2578 For devices supporting more than one source for bootstrapping data, 2579 no particular sequencing order has to be observed for security 2580 reasons, as the solution for each source is considered equally 2581 secure. However, from a privacy perspective, it is RECOMMENDED that 2582 devices access local sources before accessing remote sources. 2584 9.8. Safety of Private Keys used for Trust 2586 The solution presented in this document enables bootstrapping data to 2587 be trusted in two ways, either through transport level security or 2588 through the signing of artifacts. 2590 When transport level security (i.e., a trusted bootstrap server) is 2591 used, the private key for the end-entity certificate must be online 2592 in order to establish the TLS connection. 2594 When artifacts are signed, the signing key is required to be online 2595 only when the bootstrap server is returning a dynamically generated 2596 signed-data response. For instance, a bootstrap server, upon 2597 receiving the "untrusted-connection" input parameter to the "get- 2598 bootstrapping-data" RPC, may dynamically generate a response that is 2599 signed. 2601 Bootstrap server administrators are RECOMMENDED to follow best 2602 practice to protect the private key used for any online operation. 2603 Use of an hardware security module (HSM) is RECOMMENDED. If an HSM 2604 is not used, frequent private key refreshes are RECOMMENDED. 2606 For best security, it is RECOMMENDED that owners only provide 2607 bootstrapping data that has been signed, using a private key that is 2608 not accessible to a network of questionable integrity, and encrypted, 2609 using the device's public key from its secure device identity 2610 certificate. 2612 9.9. Infinite Redirection Loops and Sequences 2614 The recursive algorithm described in this document enables redirect 2615 information to lead to more redirect information, which may cause a 2616 device to redirect forever. 2618 Whilst a trusted bootstrap server may be misconfigured to cause a 2619 device to return to it again ad infitum, the greater concern is that 2620 any untrusted source of bootstrapping data could be used by an 2621 adversary to purposely cause this. 2623 Infinite redirections are most easily constructed via loops, where 2624 some bootstrap server redirects back to a previously visited 2625 bootstrap server. Infinite redirections can also be created without 2626 a loop by an adversary dynamically instantiated bootstrap servers on 2627 the fly. 2629 Implementations SHOULD limit the maximum number of recursive 2630 redirects allowed; no more than a half dozen seems reasonable. 2632 9.10. Increased Reliance on Manufacturers 2634 The zero touch bootstrapping protocol presented in this document 2635 shifts some control of initial configuration away from the rightful 2636 owner of the device and towards the manufacturer and its delegates. 2638 The manufacturer maintains the list of well-known bootstrap servers 2639 its devices will trust. By design, if no bootstrapping data is found 2640 via other methods first, the device will try to reach out to the 2641 well-known bootstrap servers. There is no mechanism to prevent this 2642 from occurring other than by using an external firewall to block such 2643 connections. Concerns related to trusted bootstrap servers are 2644 discussed in Section 9.11. 2646 Similarly, the manufacturer maintains the list of voucher signing 2647 authorities its devices will trust. The voucher signing authorities 2648 issue the vouchers that enable a device to trust an owner's domain 2649 certificate. It is vital that manufacturers ensure the integrity of 2650 these voucher signing authorities, so as to avoid incorrect 2651 assignments. 2653 Operators should be aware that this system assumes that they trust 2654 all the pre-configured bootstrap servers and voucher signing 2655 authorities designated by the manufacturers. 2657 9.11. Concerns with Trusted Bootstrap Servers 2659 Trusted bootstrap servers, whether well-known or discovered, have the 2660 potential to cause problems, such as the following. 2662 o A trusted bootstrap server that has been compromised may be 2663 modified to return unsigned data of any sort. For instance, a 2664 bootstrap server that is only suppose to return redirect 2665 information might be modified to return onboarding information. 2666 Similarly, a bootstrap server that is only supposed to return 2667 signed data, may be modified to return unsigned data. In both 2668 cases, the device will accept the response, unaware that it wasn't 2669 supposed to be any different. It is RECOMMENDED that maintainers 2670 of trusted bootstrap servers ensure that their systems are not 2671 easily compromised and, in case of compromise, have mechanisms in 2672 place to detect and remediate the compromise as expediently as 2673 possible. 2675 o A trusted bootstrap server hosting either unsigned or signed but 2676 not encrypted data may disclose information to unwanted parties 2677 (e.g., an administrator of the bootstrap server). This is a 2678 privacy issue only, but could reveal information that might be 2679 used in a subsequent attack. Disclosure of redirect information 2680 has limited exposure (it is just a list of bootstrap servers), 2681 whereas disclosure of onboarding information could be highly 2682 revealing (e.g., network topology, firewall policies, etc.). It 2683 is RECOMMENDED that operators encrypt the bootstrapping data when 2684 its contents are considered sensitive, even to the administrators 2685 of a bootstrap server. 2687 9.12. Validity Period for Zero Touch Information 2689 Zero touch information does not specify a validity period. For 2690 instance, neither redirect information nor onboarding information 2691 enable "not-before" or "not-after" values to be specified, and 2692 neither artifact alone can be revoked. 2694 For unsigned data provided by an untrusted source of bootstrapping 2695 data, it is not meaningful to discuss its validity period when the 2696 information itself has no authenticity and may have come from 2697 anywhere. 2699 For unsigned data provided by a trusted source of bootstrapping data 2700 (i.e., a bootstrap server), the availability of the data is the only 2701 measure of it being current. Since the untrusted data comes from a 2702 trusted source, its current availability is meaningful and, since 2703 bootstrap servers use TLS, the contents of the exchange cannot be 2704 modified or replayed. 2706 For signed data, whether provided by an untrusted or trusted source 2707 of bootstrapping data, the validity is constrained by the validity of 2708 the both the ownership voucher and owner certificate used to 2709 authenticate it. 2711 The ownership voucher's validity is primarily constrained by the 2712 ownership voucher's "created-on" and "expires-on" nodes. While 2713 [RFC8366] recommends short-lived vouchers (see Section 6.1), the 2714 "expires-on" node may be set to any point in the future, or omitted 2715 altogether to indicate that the voucher never expires. The ownership 2716 voucher's validity is secondarily constrained by the manufacturer's 2717 PKI used to sign the voucher; whilst an ownership voucher cannot be 2718 revoked directly, the PKI used to sign it may be. 2720 The owner certificate's validity is primarily constrained by the 2721 X.509's validity field, the "notBefore" and "notAfter" values, as 2722 specified by the certificate authority that signed it. The owner 2723 certificate's validity is secondarily constrained by the validity of 2724 the PKI used to sign the voucher. Owner certificates may be revoked 2725 directly. 2727 For owners that wish to have maximum flexibility in their ability to 2728 specify and constrain the validity of signed data, it is RECOMMENDED 2729 that a unique owner certificate is created for each signed artifact. 2730 Not only does this enable a validity period to be specified, for each 2731 artifact, but it also enables to the validity of each artifact to be 2732 revoke. 2734 9.13. The "ietf-zerotouch-information" YANG Module 2736 The ietf-zerotouch-information module defined in this document 2737 defines a data structure that is always wrapped by a CMS structure. 2738 When accessed by a secure mechanism (e.g., protected by TLS), then 2739 the CMS structure may be unsigned. However, when accessed by an 2740 insecure mechanism (e.g., removable storage device), then the CMS 2741 structure must be signed, in order for the device to trust it. 2743 Implementations should be aware that signed bootstrapping data only 2744 protects the data from modification, the contents are still visible 2745 to others. This doesn't affect security so much as privacy. That 2746 the contents may be read by unintended parties when accessed by 2747 insecure mechanisms is considered next. 2749 The ietf-zerotouch-information module defines a top-level "choice" 2750 statement that declares the contents are either "redirect- 2751 information" or "onboarding-information". Each of these two cases 2752 are now considered. 2754 When the content of the CMS structure is redirect-information, an 2755 observer can learn about the bootstrap servers the device is being 2756 directed to, their IP addresses or hostnames, ports, and trust anchor 2757 certificates. Knowledge of this information could provide an 2758 observer some insight into a network's inner structure. 2760 When the content of the CMS structure is onboarding-information, an 2761 observer could learn considerable information about how the device is 2762 to be provisioned. This information includes the operating system 2763 version, initial configuration, and script contents. This 2764 information should be considered sensitive and precautions should be 2765 taken to protect it (e.g., encrypt artifact with device public key). 2767 9.14. The "ietf-zerotouch-bootstrap-server" YANG Module 2769 The ietf-zerotouch-bootstrap-server module defined in this document 2770 specifies an API for a RESTCONF [RFC8040]. The lowest RESTCONF layer 2771 is HTTPS, and the mandatory-to-implement secure transport is TLS 2772 [RFC8446]. 2774 The NETCONF Access Control Model (NACM) [RFC8341] provides the means 2775 to restrict access for particular users to a preconfigured subset of 2776 all available protocol operations and content. 2778 This module presents no data nodes (only RPCs). There is no need to 2779 discuss the sensitivity of data nodes. 2781 This module defines two RPC operations that may be considered 2782 sensitive in some network environments. These are the operations and 2783 their sensitivity/vulnerability: 2785 get-bootstrapping-data: This RPC is used by devices to obtain their 2786 bootstrapping data. By design, each device, as identified by its 2787 authentication credentials (e.g. client certificate), can only 2788 obtain its own data. NACM is not needed to further constrain 2789 access to this RPC. 2791 report-progress: This RPC is used by devices to report their 2792 bootstrapping progress. By design, each device, as identified by 2793 its authentication credentials (e.g. client certificate), can 2794 only report data for itself. NACM is not needed to further 2795 constrain access to this RPC. 2797 10. IANA Considerations 2798 10.1. The IETF XML Registry 2800 This document registers two URIs in the IETF XML registry [RFC3688]. 2801 Following the format in [RFC3688], the following registrations are 2802 requested: 2804 URI: urn:ietf:params:xml:ns:yang:ietf-zerotouch-information 2805 Registrant Contact: The NETCONF WG of the IETF. 2806 XML: N/A, the requested URI is an XML namespace. 2808 URI: urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server 2809 Registrant Contact: The NETCONF WG of the IETF. 2810 XML: N/A, the requested URI is an XML namespace. 2812 10.2. The YANG Module Names Registry 2814 This document registers two YANG modules in the YANG Module Names 2815 registry [RFC6020]. Following the format defined in [RFC6020], the 2816 the following registrations are requested: 2818 name: ietf-zerotouch-information 2819 namespace: urn:ietf:params:xml:ns:yang:ietf-zerotouch-information 2820 prefix: zti 2821 reference: RFC XXXX 2823 name: ietf-zerotouch-bootstrap-server 2824 namespace: urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-\ 2825 server (note: '\' used for formatting reasons only) 2826 prefix: ztbs 2827 reference: RFC XXXX 2829 10.3. The SMI Security for S/MIME CMS Content Type Registry 2831 IANA is kindly requested to add two entries in the "SMI Security for 2832 S/MIME CMS Content Type" registry (1.2.840.113549.1.9.16.1), with 2833 values as follows: 2835 Decimal Description References 2836 ------- -------------------------------------- ---------- 2837 TBD1 id-ct-zerotouchInformationXML [RFCXXXX] 2838 TBD2 id-ct-zerotouchInformationJSON [RFCXXXX] 2840 id-ct-zerotouchInformationXML indicates that the "zerotouch- 2841 information" is encoded using XML. id-ct-zerotouchInformationJSON 2842 indicates that the "zerotouch-information" is encoded using JSON. 2844 10.4. The BOOTP Manufacturer Extensions and DHCP Options Registry 2846 IANA is kindly requested to make permanent the following early code 2847 point allocation in the "BOOTP Manufacturer Extensions and DHCP 2848 Options" registry maintained at http://www.iana.org/assignments/ 2849 bootp-dhcp-parameters: 2851 Tag: 143 2852 Name: OPTION_V4_ZEROTOUCH_REDIRECT 2853 Data Length: N 2854 Meaning: This option provides a list of URIs 2855 for zerotouch bootstrap servers 2856 Reference: [RFCXXXX] 2858 And the following early code point allocation in the "Dynamic Host 2859 Configuration Protocol for IPv6 (DHCPv6)" registry maintained at 2860 http://www.iana.org/assignments/dhcpv6-parameters: 2862 Value: 136 2863 Description: OPTION_V6_ZEROTOUCH_REDIRECT 2864 Reference: [RFCXXXX] 2866 11. References 2868 11.1. Normative References 2870 [I-D.ietf-netmod-yang-data-ext] 2871 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data 2872 Extensions", draft-ietf-netmod-yang-data-ext-01 (work in 2873 progress), March 2018. 2875 [ITU.X690.2015] 2876 International Telecommunication Union, "Information 2877 Technology - ASN.1 encoding rules: Specification of Basic 2878 Encoding Rules (BER), Canonical Encoding Rules (CER) and 2879 Distinguished Encoding Rules (DER)", ITU-T Recommendation 2880 X.690, ISO/IEC 8825-1, August 2015, 2881 . 2883 [RFC1035] Mockapetris, P., "Domain names - implementation and 2884 specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, 2885 November 1987, . 2887 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2888 Requirement Levels", BCP 14, RFC 2119, 2889 DOI 10.17487/RFC2119, March 1997, 2890 . 2892 [RFC3315] Droms, R., Ed., Bound, J., Volz, B., Lemon, T., Perkins, 2893 C., and M. Carney, "Dynamic Host Configuration Protocol 2894 for IPv6 (DHCPv6)", RFC 3315, DOI 10.17487/RFC3315, July 2895 2003, . 2897 [RFC3396] Lemon, T. and S. Cheshire, "Encoding Long Options in the 2898 Dynamic Host Configuration Protocol (DHCPv4)", RFC 3396, 2899 DOI 10.17487/RFC3396, November 2002, 2900 . 2902 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 2903 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, 2904 January 2006, . 2906 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2907 Housley, R., and W. Polk, "Internet X.509 Public Key 2908 Infrastructure Certificate and Certificate Revocation List 2909 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 2910 . 2912 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 2913 RFC 5652, DOI 10.17487/RFC5652, September 2009, 2914 . 2916 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2917 the Network Configuration Protocol (NETCONF)", RFC 6020, 2918 DOI 10.17487/RFC6020, October 2010, 2919 . 2921 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2922 Verification of Domain-Based Application Service Identity 2923 within Internet Public Key Infrastructure Using X.509 2924 (PKIX) Certificates in the Context of Transport Layer 2925 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2926 2011, . 2928 [RFC6762] Cheshire, S. and M. Krochmal, "Multicast DNS", RFC 6762, 2929 DOI 10.17487/RFC6762, February 2013, 2930 . 2932 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 2933 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, 2934 . 2936 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2937 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2938 . 2940 [RFC7227] Hankins, D., Mrugalski, T., Siodelski, M., Jiang, S., and 2941 S. Krishnan, "Guidelines for Creating New DHCPv6 Options", 2942 BCP 187, RFC 7227, DOI 10.17487/RFC7227, May 2014, 2943 . 2945 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2946 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2947 . 2949 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2950 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2951 . 2953 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2954 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2955 May 2017, . 2957 [RFC8366] Watsen, K., Richardson, M., Pritikin, M., and T. Eckert, 2958 "A Voucher Artifact for Bootstrapping Protocols", 2959 RFC 8366, DOI 10.17487/RFC8366, May 2018, 2960 . 2962 [Std-802.1AR-2009] 2963 IEEE SA-Standards Board, "IEEE Standard for Local and 2964 metropolitan area networks - Secure Device Identity", 2965 December 2009, . 2968 11.2. Informative References 2970 [I-D.ietf-netconf-crypto-types] 2971 Watsen, K., "Common YANG Data Types for Cryptography", 2972 draft-ietf-netconf-crypto-types-00 (work in progress), 2973 June 2018. 2975 [I-D.ietf-netconf-trust-anchors] 2976 Watsen, K., "YANG Data Model for Global Trust Anchors", 2977 draft-ietf-netconf-trust-anchors-00 (work in progress), 2978 June 2018. 2980 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2981 DOI 10.17487/RFC3688, January 2004, 2982 . 2984 [RFC6187] Igoe, K. and D. Stebila, "X.509v3 Certificates for Secure 2985 Shell Authentication", RFC 6187, DOI 10.17487/RFC6187, 2986 March 2011, . 2988 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 2989 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 2990 DOI 10.17487/RFC6234, May 2011, 2991 . 2993 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2994 and A. Bierman, Ed., "Network Configuration Protocol 2995 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2996 . 2998 [RFC6698] Hoffman, P. and J. Schlyter, "The DNS-Based Authentication 2999 of Named Entities (DANE) Transport Layer Security (TLS) 3000 Protocol: TLSA", RFC 6698, DOI 10.17487/RFC6698, August 3001 2012, . 3003 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 3004 Galperin, S., and C. Adams, "X.509 Internet Public Key 3005 Infrastructure Online Certificate Status Protocol - OCSP", 3006 RFC 6960, DOI 10.17487/RFC6960, June 2013, 3007 . 3009 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 3010 RFC 8071, DOI 10.17487/RFC8071, February 2017, 3011 . 3013 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 3014 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 3015 . 3017 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 3018 Access Control Model", STD 91, RFC 8341, 3019 DOI 10.17487/RFC8341, March 2018, 3020 . 3022 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3023 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3024 . 3026 Appendix A. The Zero Touch Device Data Model 3028 This section defines a non-normative data model that enables the 3029 configuration of zerotouch bootstrapping and discovery of what 3030 parameters are used by a device's bootstrapping logic. 3032 A.1. Data Model Overview 3034 The following tree diagram provides an overview for the zerotouch 3035 device data model. 3037 module: example-zerotouch-device 3038 +--rw zerotouch 3039 +--rw enabled? boolean 3040 +--ro idevid-certificate? 3041 | ct:end-entity-cert-cms {bootstrap-servers}? 3042 +--ro bootstrap-servers {bootstrap-servers}? 3043 | +--ro bootstrap-server* [address] 3044 | +--ro address inet:host 3045 | +--ro port? inet:port-number 3046 +--ro bootstrap-server-pinned-certificates? 3047 | ta:pinned-certificates-ref {bootstrap-servers}? 3048 +--ro voucher-pinned-certificates? 3049 ta:pinned-certificates-ref {signed-data}? 3051 In the above diagram, notice that there is only one configurable node 3052 "enabled". The expectation is that this node would be set to "true" 3053 in device's factory default configuration and that it would either be 3054 set to "false" or deleted when the zerotouch bootstrapping is longer 3055 needed. 3057 A.2. Example Usage 3059 Following is an instance example for this data model. 3061 [Note: '\' line wrapping for formatting only] 3063 3065 true 3066 base64encodedvalue== 3067 3068 3069
phs1.example.com
3070 8443 3071 3072 3073
phs2.example.com
3074 8443 3075 3076 3077
phs3.example.com
3078 8443 3079 3080 3081 manufacturers-root-ca-certs<\ 3082 /bootstrap-server-pinned-certificates> 3083 manufacturers-root-ca-certs 3085 3087 A.3. YANG Module 3089 The device model is defined by the YANG module defined in this 3090 section. 3092 This module uses data types defined in [RFC6991], 3093 [I-D.ietf-netconf-crypto-types], and 3094 [I-D.ietf-netconf-trust-anchors]. 3096 module example-zerotouch-device { 3097 yang-version 1.1; 3098 namespace "https://example.com/zerotouch-device"; 3099 prefix ztd; 3101 import ietf-inet-types { 3102 prefix inet; 3103 reference "RFC 6991: Common YANG Data Types"; 3104 } 3106 import ietf-crypto-types { 3107 prefix ct; 3108 revision-date 2018-06-04; 3109 description 3110 "This revision is defined in the -00 version of 3111 draft-ietf-netconf-crypto-types"; 3112 reference 3113 "draft-ietf-netconf-crypto-types: 3114 Common YANG Data Types for Cryptography"; 3115 } 3117 import ietf-trust-anchors { 3118 prefix ta; 3119 revision-date 2018-06-04; 3120 description 3121 "This revision is defined in -00 version of 3122 draft-ietf-netconf-trust-anchors."; 3123 reference 3124 "draft-ietf-netconf-trust-anchors: 3125 YANG Data Model for Global Trust Anchors"; 3126 } 3128 organization 3129 "Example Corporation"; 3131 contact 3132 "Author: Bootstrap Admin "; 3134 description 3135 "This module defines a data model to enable zerotouch 3136 bootstrapping and discover what parameters are used. 3137 This module assumes the use of an IDevID certificate, 3138 as opposed to any other client certificate, or the 3139 use of an HTTP-based client authentication scheme."; 3141 revision 2018-09-13 { 3142 description 3143 "Initial version"; 3144 reference 3145 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 3146 } 3148 // features 3150 feature bootstrap-servers { 3151 description 3152 "The device supports bootstrapping off bootstrap servers."; 3153 } 3155 feature signed-data { 3156 description 3157 "The device supports bootstrapping off signed data."; 3158 } 3160 // protocol accessible nodes 3162 container zerotouch { 3163 description 3164 "Top-level container for zerotouch data model."; 3165 leaf enabled { 3166 type boolean; 3167 default false; 3168 description 3169 "The 'enabled' leaf controls if zerotouch bootstrapping is 3170 enabled or disabled. The default is 'false' so that, when 3171 not enabled, which is most of the time, no configuration 3172 is needed."; 3173 } 3174 leaf idevid-certificate { 3175 if-feature bootstrap-servers; 3176 type ct:end-entity-cert-cms; 3177 config false; 3178 description 3179 "This CMS structure contains the IEEE 802.1AR-2009 3180 IDevID certificate itself, and all intermediate 3181 certificates leading up to, and optionally including, 3182 the manufacturer's well-known trust anchor certificate 3183 for IDevID certificates. The well-known trust anchor 3184 does not have to be a self-signed certificate."; 3185 reference 3186 "IEEE 802.1AR-2009: 3187 IEEE Standard for Local and metropolitan area 3188 networks - Secure Device Identity."; 3189 } 3190 container bootstrap-servers { 3191 if-feature bootstrap-servers; 3192 config false; 3193 description 3194 "List of bootstrap servers this device will attempt 3195 to reach out to when bootstrapping."; 3196 list bootstrap-server { 3197 key "address"; 3198 description 3199 "A bootstrap server entry."; 3200 leaf address { 3201 type inet:host; 3202 mandatory true; 3203 description 3204 "The IP address or hostname of the bootstrap server the 3205 device should redirect to."; 3206 } 3207 leaf port { 3208 type inet:port-number; 3209 default "443"; 3210 description 3211 "The port number the bootstrap server listens on. If no 3212 port is specified, the IANA-assigned port for 'https' 3213 (443) is used."; 3214 } 3215 } 3216 } 3217 leaf bootstrap-server-pinned-certificates { 3218 if-feature bootstrap-servers; 3219 type ta:pinned-certificates-ref; 3220 config false; 3221 description 3222 "A reference to a list of pinned certificate authority (CA) 3223 certificates that the device uses to validate bootstrap 3224 servers with."; 3225 } 3226 leaf voucher-pinned-certificates { 3227 if-feature signed-data; 3228 type ta:pinned-certificates-ref; 3229 config false; 3230 description 3231 "A reference to a list of pinned certificate authority (CA) 3232 certificates that the device uses to validate ownership 3233 vouchers with."; 3234 } 3235 } 3236 } 3238 Appendix B. Promoting a Connection from Untrusted to Trusted 3240 The following diagram illustrates a sequence of bootstrapping 3241 activities that promote an untrusted connection to a bootstrap server 3242 to a trusted connection to the same bootstrap server. This enables a 3243 device to limit the amount of information it might disclose to an 3244 adversary hosting an untrusted bootstrap server. 3246 +----------+ 3247 |Deployment| 3248 | Specific | 3249 +------+ |Bootstrap | 3250 |Device| | Server | 3251 +------+ +----------+ 3252 | | 3253 | 1. "HTTPS" Request ("untrusted-connection", nonce) | 3254 |------------------------------------------------------->| 3255 | 2. "HTTPS" Response (signed redirect information) | 3256 |<-------------------------------------------------------| 3257 | | 3258 | | 3259 | 3. HTTPS Request (os-name=xyz, os-version=123, etc.) | 3260 |------------------------------------------------------->| 3261 | 4. HTTPS Response (unsigned onboarding information | 3262 |<-------------------------------------------------------| 3263 | | 3265 The interactions in the above diagram are described below. 3267 1. The device initiates an untrusted connection to a bootstrap 3268 server, as is indicated by putting "HTTPS" in double quotes 3269 above. It is still an HTTPS connection, but the device is unable 3270 to authenticate the bootstrap server's TLS certificate. Because 3271 the device is unable to trust the bootstrap server, it sends the 3272 "untrusted-connection" input parameter, and optionally also the 3273 "nonce" input parameter, in the "get-bootstrapping-data" RPC. 3274 The "untrusted-connection" parameter informs the bootstrap server 3275 that the device does not trust it and may be holding back some 3276 additional input parameters from the server (e.g., other input 3277 parameters, progress reports, etc.). The "nonce" input parameter 3278 enables the bootstrap server to dynamically obtain an ownership 3279 voucher from a MASA, which may be important for devices that do 3280 not have a reliable clock. 3282 2. The bootstrap server, seeing the "untrusted-connection" input 3283 parameter, knows that it can either send unsigned redirect 3284 information or signed data of any type. But, in this case, the 3285 bootstrap server has the ability to sign data and chooses to 3286 respond with signed redirect information, not signed onboarding 3287 information as might be expected, securely redirecting the device 3288 back to it again. Not displayed but, if the "nonce" input 3289 parameter was passed, the bootstrap server could dynamically 3290 connect to a download a voucher from the MASA having the nonce 3291 value in it. Details regarding a protocol enabling this 3292 integration is outside the scope of this document. 3294 3. Upon validating the signed redirect information, the device 3295 establishes a secure connection to the bootstrap server. 3296 Unbeknownst to the device, it is the same bootstrap server it was 3297 connected to previously but, because the device is able to 3298 authenticate the bootstrap server this time, it sends its normal 3299 "get-bootstrapping-data" request (i.e., with additional input 3300 parameters) as well as its progress reports (not depicted). 3302 4. This time, because the "untrusted-connection" parameter was not 3303 passed, having access to all of the device's input parameters, 3304 the bootstrap server returns, in this example, unsigned 3305 onboarding information to the device. 3307 Appendix C. Workflow Overview 3309 The zero touch solution presented in this document is conceptualized 3310 to be composed of the non-normative workflows described in this 3311 section. Implementation details are expected to vary. Each diagram 3312 is followed by a detailed description of the steps presented in the 3313 diagram, with further explanation on how implementations may vary. 3315 C.1. Enrollment and Ordering Devices 3317 The following diagram illustrates key interactions that may occur 3318 from when a prospective owner enrolls in a manufacturer's zero touch 3319 program to when the manufacturer ships devices for an order placed by 3320 the prospective owner. 3322 +-----------+ 3323 +------------+ |Prospective| +---+ 3324 |Manufacturer| | Owner | |NMS| 3325 +------------+ +-----------+ +---+ 3326 | | | 3327 | | | 3328 | 1. initiate enrollment | | 3329 #<-----------------------------| | 3330 # | | 3331 # | | 3332 # IDevID trust anchor | | 3333 #-----------------------------># set IDevID trust anchor | 3334 # #--------------------------->| 3335 # | | 3336 # bootstrap server | | 3337 # account credentials | | 3338 #-----------------------------># set credentials | 3339 | #--------------------------->| 3340 | | | 3341 | | | 3342 | 2. set owner certificate trust anchor | 3343 |<----------------------------------------------------------| 3344 | | | 3345 | | | 3346 | 3. place device order | | 3347 |<-----------------------------# model devices | 3348 | #--------------------------->| 3349 | | | 3350 | 4. ship devices and send | | 3351 | device identifiers and | | 3352 | ownership vouchers | | 3353 |-----------------------------># set device identifiers | 3354 | # and ownership vouchers | 3355 | #--------------------------->| 3356 | | | 3358 Each numbered item below corresponds to a numbered item in the 3359 diagram above. 3361 1. A prospective owner of a manufacturer's devices initiates an 3362 enrollment process with the manufacturer. This process includes 3363 the following: 3365 * Regardless how the prospective owner intends to bootstrap 3366 their devices, they will always obtain from the manufacturer 3367 the trust anchor certificate for the IDevID certificates. 3368 This certificate will is installed on the prospective owner's 3369 NMS so that the NMS can authenticate the IDevID certificates 3370 when they are presented to subsequent steps. 3372 * If the manufacturer hosts an Internet based bootstrap server 3373 (e.g., a redirect server) such as described in Section 4.4, 3374 then credentials necessary to configure the bootstrap server 3375 would be provided to the prospective owner. If the bootstrap 3376 server is configurable through an API (outside the scope of 3377 this document), then the credentials might be installed on the 3378 prospective owner's NMS so that the NMS can subsequently 3379 configure the manufacturer-hosted bootstrap server directly. 3381 2. If the manufacturer's devices are able to validate signed data 3382 (Section 5.4), and assuming that the prospective owner's NMS is 3383 able to prepare and sign the bootstrapping data itself, the 3384 prospective owner's NMS might set a trust anchor certificate onto 3385 the manufacturer's bootstrap server, using the credentials 3386 provided in the previous step. This certificate is the trust 3387 anchor certificate that the prospective owner would like the 3388 manufacturer to place into the ownership vouchers it generates, 3389 thereby enabling devices to trust the owner's owner certificate. 3390 How this trust anchor certificate is used to enable devices to 3391 validate signed bootstrapping data is described in Section 5.4. 3393 3. Some time later, the prospective owner places an order with the 3394 manufacturer, perhaps with a special flag checked for zero touch 3395 handling. At this time, or perhaps before placing the order, the 3396 owner may model the devices in their NMS, creating virtual 3397 objects for the devices with no real-world device associations. 3398 For instance the model can be used to simulate the device's 3399 location in the network and the configuration it should have when 3400 fully operational. 3402 4. When the manufacturer fulfills the order, shipping the devices to 3403 their intended locations, they may notify the owner of the 3404 devices' serial numbers and shipping destinations, which the 3405 owner may use to stage the network for when the devices power on. 3406 Additionally, the manufacturer may send one or more ownership 3407 vouchers, cryptographically assigning ownership of those devices 3408 to the owner. The owner may set this information on their NMS, 3409 perhaps binding specific modeled devices to the serial numbers 3410 and ownership vouchers. 3412 C.2. Owner Stages the Network for Bootstrap 3414 The following diagram illustrates how an owner might stage the 3415 network for bootstrapping devices. 3417 +----------+ +------------+ 3418 |Deployment| |Manufacturer| +------+ +------+ 3419 | Specific | | Hosted | | Local| | Local| +---------+ 3420 +---+ |Bootstrap | | Bootstrap | | DNS | | DHCP | |Removable| 3421 |NMS| | Server | | Server | |Server| |Server| | Storage | 3422 +---+ +----------+ +------------+ +------+ +------+ +---------+ 3423 | | | | | | 3424 1. | | | | | | 3425 activate| | | | | | 3426 modeled | | | | | | 3427 device | | | | | | 3428 ------->| | | | | | 3429 | 2. (optional) | | | | 3430 | configure | | | | 3431 | bootstrap | | | | 3432 | server | | | | 3433 |------->| | | | | 3434 | | | | | | 3435 | 3. (optional) configure | | | 3436 | bootstrap server | | | | 3437 |--------------------->| | | | 3438 | | | | | | 3439 | | | | | | 3440 | 4. (optional) configure DNS server| | | 3441 |---------------------------------->| | | 3442 | | | | | | 3443 | | | | | | 3444 | 5. (optional) configure DHCP server | | 3445 |------------------------------------------->| | 3446 | | | | | | 3447 | | | | | | 3448 | 6. (optional) store bootstrapping artifacts on media | 3449 |----------------------------------------------------->| 3450 | | | | | | 3451 | | | | | | 3453 Each numbered item below corresponds to a numbered item in the 3454 diagram above. 3456 1. Having previously modeled the devices, including setting their 3457 fully operational configurations and associating device serial 3458 numbers and (optionally) ownership vouchers, the owner might 3459 "activate" one or more modeled devices. That is, the owner tells 3460 the NMS to perform the steps necessary to prepare for when the 3461 real-world devices power up and initiate the bootstrapping 3462 process. Note that, in some deployments, this step might be 3463 combined with the last step from the previous workflow. Here it 3464 is depicted that an NMS performs the steps, but they may be 3465 performed manually or through some other mechanism. 3467 2. If it is desired to use a deployment specific bootstrap server, 3468 it must be configured to provide the bootstrapping data for the 3469 specific devices. Configuring the bootstrap server may occur via 3470 a programmatic API not defined by this document. Illustrated 3471 here as an external component, the bootstrap server may be 3472 implemented as an internal component of the NMS itself. 3474 3. If it is desired to use a manufacturer hosted bootstrap server, 3475 it must be configured to provide the bootstrapping data for the 3476 specific devices. The configuration must be either redirect or 3477 onboarding information. That is, either the manufacturer hosted 3478 bootstrap server will redirect the device to another bootstrap 3479 server, or provide the device with the onboarding information 3480 itself. The types of bootstrapping data the manufacturer hosted 3481 bootstrap server supports may vary by implementation; some 3482 implementations may only support redirect information, or only 3483 support onboarding information, or support both redirect and 3484 onboarding information. Configuring the bootstrap server may 3485 occur via a programmatic API not defined by this document. 3487 4. If it is desired to use a DNS server to supply bootstrapping 3488 data, a DNS server needs to be configured. If multicast DNS-SD 3489 is desired, then the server must reside on the local network, 3490 otherwise the DNS server may reside on a remote network. Please 3491 see Section 4.2 for more information about how to configure DNS 3492 servers. Configuring the DNS server may occur via a programmatic 3493 API not defined by this document. 3495 5. If it is desired to use a DHCP server to supply bootstrapping 3496 data, a DHCP server needs to be configured. The DHCP server may 3497 be accessed directly or via a DHCP relay. Please see Section 4.3 3498 for more information about how to configure DHCP servers. 3499 Configuring the DHCP server may occur via a programmatic API not 3500 defined by this document. 3502 6. If it is desired to use a removable storage device (e.g., USB 3503 flash drive) to supply bootstrapping data, the data would need to 3504 be placed onto it. Please see Section 4.1 for more information 3505 about how to configure a removable storage device. 3507 C.3. Device Powers On 3509 The following diagram illustrates the sequence of activities that 3510 occur when a device powers on. 3512 +----------+ 3513 +-----------+ |Deployment| 3514 | Source of | | Specific | 3515 +------+ | Bootstrap | |Bootstrap | +---+ 3516 |Device| | Data | | Server | |NMS| 3517 +------+ +-----------+ +----------+ +---+ 3518 | | | | 3519 | | | | 3520 | 1. if zerotouch bootstrap service | | | 3521 | is not enabled, then exit. | | | 3522 | | | | 3523 | 2. for each source supported, check | | | 3524 | for bootstrapping data. | | | 3525 |------------------------------------>| | | 3526 | | | | 3527 | 3. if onboarding information found, | | | 3528 | initialize self and, only if | | | 3529 | source is a trusted bootstrap | | | 3530 | server, send progress reports. | | | 3531 |------------------------------------># | | 3532 | # webhook | | 3533 | #----------------------->| 3534 | | | 3535 | 4. else if redirect-information found, for each | | 3536 | bootstrap server specified, check for data. | | 3537 |-+------------------------------------------------->| | 3538 | | | | 3539 | | if more redirect-information is found, recurse | | 3540 | | (not depicted), else if onboarding-information | | 3541 | | found, initialize self and post progress reports | | 3542 | +-------------------------------------------------># | 3543 | # webhook | 3544 | #-------->| 3545 | 3546 | 5. retry sources and/or wait for manual provisioning. 3547 | 3549 The interactions in the above diagram are described below. 3551 1. Upon power being applied, the device checks to see if zerotouch 3552 bootstrapping is configured, such as must be the case when 3553 running its "factory default" configuration. If zerotouch 3554 bootstrapping is not configured, then the bootstrapping logic 3555 exits and none of the following interactions occur. 3557 2. For each source of bootstrapping data the device supports, 3558 preferably in order of closeness to the device (e.g., removable 3559 storage before Internet based servers), the device checks to see 3560 if there is any bootstrapping data for it there. 3562 3. If onboarding information is found, the device initializes itself 3563 accordingly (e.g., installing a boot-image and committing an 3564 initial configuration). If the source is a bootstrap server, and 3565 the bootstrap server can be trusted (i.e., TLS-level 3566 authentication), the device also sends progress reports to the 3567 bootstrap server. 3569 * The contents of the initial configuration should configure an 3570 administrator account on the device (e.g., username, ssh-rsa 3571 key, etc.), and should configure the device either to listen 3572 for NETCONF or RESTCONF connections or to initiate call home 3573 connections [RFC8071], and should disable the zerotouch 3574 bootstrapping service (e.g., the "enabled" leaf in data model 3575 presented in Appendix A). 3577 * If the bootstrap server supports forwarding device progress 3578 reports to external systems (e.g., via a webhook), a 3579 "bootstrap-complete" progress report (Section 7.3) informs the 3580 external system to know when it can, for instance, initiate a 3581 connection to the device. To support this scenario further, 3582 the "bootstrap-complete" progress report may also relay the 3583 device's SSH host keys and/or TLS certificates, with which the 3584 external system can use to authenticate subsequent connections 3585 to the device. 3587 If the device successfully completes the bootstrapping process, 3588 it exits the bootstrapping logic without considering any 3589 additional sources of bootstrapping data. 3591 4. Otherwise, if redirect information is found, the device iterates 3592 through the list of specified bootstrap servers, checking to see 3593 if it has bootstrapping data for the device. If the bootstrap 3594 server returns more redirect information, then the device 3595 processes it recursively. Otherwise, if the bootstrap server 3596 returns onboarding information, the device processes it following 3597 the description provided in (3) above. 3599 5. After having tried all supported sources of bootstrapping data, 3600 the device may retry again all the sources and/or provide 3601 manageability interfaces for manual configuration (e.g., CLI, 3602 HTTP, NETCONF, etc.). If manual configuration is allowed, and 3603 such configuration is provided, the configuration should also 3604 disable the zerotouch bootstrapping service, as the need for 3605 bootstrapping would no longer be present. 3607 Appendix D. Change Log 3609 D.1. ID to 00 3611 o Major structural update; the essence is the same. Most every 3612 section was rewritten to some degree. 3614 o Added a Use Cases section 3616 o Added diagrams for "Actors and Roles" and "NMS Precondition" 3617 sections, and greatly improved the "Device Boot Sequence" diagram 3619 o Removed support for physical presence or any ability for 3620 configlets to not be signed. 3622 o Defined the Zero Touch Information DHCP option 3624 o Added an ability for devices to also download images from 3625 configuration servers 3627 o Added an ability for configlets to be encrypted 3629 o Now configuration servers only have to support HTTP/S - no other 3630 schemes possible 3632 D.2. 00 to 01 3634 o Added boot-image and validate-owner annotations to the "Actors and 3635 Roles" diagram. 3637 o Fixed 2nd paragraph in section 7.1 to reflect current use of 3638 anyxml. 3640 o Added encrypted and signed-encrypted examples 3642 o Replaced YANG module with XSD schema 3644 o Added IANA request for the Zero Touch Information DHCP Option 3646 o Added IANA request for media types for boot-image and 3647 configuration 3649 D.3. 01 to 02 3651 o Replaced the need for a configuration signer with the ability for 3652 each NMS to be able to sign its own configurations, using 3653 manufacturer signed ownership vouchers and owner certificates. 3655 o Renamed configuration server to bootstrap server, a more 3656 representative name given the information devices download from 3657 it. 3659 o Replaced the concept of a configlet by defining a southbound 3660 interface for the bootstrap server using YANG. 3662 o Removed the IANA request for the boot-image and configuration 3663 media types 3665 D.4. 02 to 03 3667 o Minor update, mostly just to add an Editor's Note to show how this 3668 draft might integrate with the draft-pritikin-anima-bootstrapping- 3669 keyinfra. 3671 D.5. 03 to 04 3673 o Major update formally introducing unsigned data and support for 3674 Internet-based redirect servers. 3676 o Added many terms to Terminology section. 3678 o Added all new "Guiding Principles" section. 3680 o Added all new "Sources for Bootstrapping Data" section. 3682 o Rewrote the "Interactions" section and renamed it "Workflow 3683 Overview". 3685 D.6. 04 to 05 3687 o Semi-major update, refactoring the document into more logical 3688 parts 3690 o Created new section for information types 3692 o Added support for DNS servers 3694 o Now allows provisional TLS connections 3696 o Bootstrapping data now supports scripts 3698 o Device Details section overhauled 3700 o Security Considerations expanded 3702 o Filled in enumerations for notification types 3704 D.7. 05 to 06 3706 o Minor update 3708 o Added many Normative and Informative references. 3710 o Added new section Other Considerations. 3712 D.8. 06 to 07 3714 o Minor update 3716 o Added an Editorial Note section for RFC Editor. 3718 o Updated the IANA Considerations section. 3720 D.9. 07 to 08 3722 o Minor update 3724 o Updated to reflect review from Michael Richardson. 3726 D.10. 08 to 09 3728 o Added in missing "Signature" artifact example. 3730 o Added recommendation for manufacturers to use interoperable 3731 formats and file naming conventions for removable storage devices. 3733 o Added configuration-handling leaf to guide if config should be 3734 merged, replaced, or processed like an edit-config/yang-patch 3735 document. 3737 o Added a pre-configuration script, in addition to the post- 3738 configuration script from -05 (issue #15). 3740 D.11. 09 to 10 3742 o Factored ownership voucher and voucher revocation to a separate 3743 document: draft-kwatsen-netconf-voucher. (issue #11) 3745 o Removed options "edit-config" and "yang- 3746 patch". (issue #12) 3748 o Defined how a signature over signed-data returned from a bootstrap 3749 server is processed. (issue #13) 3751 o Added recommendation for removable storage devices to use open/ 3752 standard file systems when possible. (issue #14) 3754 o Replaced notifications "script-[warning/error]" with "[pre/post]- 3755 script-[warning/error]". (goes with issue #15) 3757 o switched owner-certificate to be encoded using the PKCS #7 format. 3758 (issue #16) 3760 o Replaced md5/sha1 with sha256 inside a choice statement, for 3761 future extensibility. (issue #17) 3763 o A ton of editorial changes, as I went thru the entire draft with a 3764 fine-toothed comb. 3766 D.12. 10 to 11 3768 o fixed yang validation issues found by IETFYANGPageCompilation. 3769 note: these issues were NOT found by pyang --ietf or by the 3770 submission-time validator... 3772 o fixed a typo in the yang module, someone the config false 3773 statement was removed. 3775 D.13. 11 to 12 3777 o fixed typo that prevented Appendix B from loading the examples 3778 correctly. 3780 o fixed more yang validation issues found by 3781 IETFYANGPageCompilation. note: again, these issues were NOT found 3782 by pyang --ietf or by the submission-time validator... 3784 o updated a few of the notification enumerations to be more 3785 consistent with the other enumerations (following the warning/ 3786 error pattern). 3788 o updated the information-type artifact to state how it is encoded, 3789 matching the language that was in Appendix B. 3791 D.14. 12 to 13 3793 o defined a standalone artifact to encode the old information-type 3794 into a PKCS #7 structure. 3796 o standalone information artifact hardcodes JSON encoding (to match 3797 the voucher draft). 3799 o combined the information and signature PKCS #7 structures into a 3800 single PKCS #7 structure. 3802 o moved the certificate-revocations into the owner-certificate's 3803 PKCS #7 structure. 3805 o eliminated support for voucher-revocations, to reflect the 3806 voucher-draft's switch from revocations to renewals. 3808 D.15. 13 to 14 3810 o Renamed "bootstrap information" to "onboarding information". 3812 o Rewrote DHCP sections to address the packet-size limitation issue, 3813 as discussed in Chicago. 3815 o Added Ian as an author for his text-contributions to the DHCP 3816 sections. 3818 o Removed the Guiding Principles section. 3820 D.16. 14 to 15 3822 o Renamed action "notification" to "update-progress" and, likewise 3823 "notification-type" to "update-type". 3825 o Updated examples to use "base64encodedvalue==" for binary values. 3827 o Greatly simplified the "Artifact Groupings" section, and moved it 3828 as a subsection to the "Artifacts" section. 3830 o Moved the "Workflow Overview" section to the Appendix. 3832 o Renamed "bootstrap information" to "update information". 3834 o Removed "Other Considerations" section. 3836 o Tons of editorial updates. 3838 D.17. 15 to 16 3840 o tweaked language to refer to "initial state" rather than "factory 3841 default configuration", so as accommodate white-box scenarios. 3843 o added a paragraph to Intro regarding how the solution primarily 3844 regards physical machines, but could be extended to VMs by a 3845 future document. 3847 o added a pointer to the Workflow Overview section (recently moved 3848 to the Appendix) to the Intro. 3850 o added a note that, in order to simplify the verification process, 3851 the "Zerotouch Information" PKCS #7 structure MUST also contain 3852 the signing X.509 certificate. 3854 o noted that the owner certificate's must either have no Key Usage 3855 or the Key Usage must set the "digitalSignature" bit. 3857 o noted that the owner certificate's subject and subjectAltName 3858 values are not constrained. 3860 o moved/consolidated some text from the Artifacts section down to 3861 the Device Details section. 3863 o tightened up some ambiguous language, for instance, by referring 3864 to specific leaf names in the Voucher artifact. 3866 o reverted a previously overzealous s/unique-id/serial-number/ 3867 change. 3869 o modified language for when ZTP runs from when factory-default 3870 config is running to when ZTP is configured, which the factory- 3871 defaults should set . 3873 D.18. 16 to 17 3875 o Added an example for how to promote an untrusted connection to a 3876 trusted connection. 3878 o Added a "query parameters" section defining some parameters 3879 enabling scenarios raised in last call. 3881 o Added a "Disclosing Information to Untrusted Servers" section to 3882 the Security Considerations. 3884 D.19. 17 to 18 3886 o Added Security Considerations for each YANG module. 3888 o Reverted back to the device always sending its DevID cert. 3890 o Moved data tree to "get-bootstrapping-data" RPC. 3892 o Moved the "update-progress" action to a "report-progress" RPC. 3894 o Added an "untrusted-connection" parameter to "get-bootstrapping- 3895 data" RPC. 3897 o Added the "ietf-zerotouch-device" module. 3899 o Lots of small updates. 3901 D.20. 18 to 19 3903 o Fixed "must" expressions, by converting "choice" to a "list" of 3904 "image-verification", each of which now points to a base identity 3905 called "hash-algorithm". There's just one algorithm currently 3906 defined (sha-256). Wish there was a standard crypto module that 3907 could identify such identities. 3909 D.21. 19 to 20 3911 o Now references I-D.ietf-netmod-yang-tree-diagrams. 3913 o Fixed tree-diagrams in Section 2 to always reflect current YANG 3914 (now they are now dynamically generated). 3916 o The "redirect-information" container's "trust-anchor" is now a CMS 3917 structure that can contain a chain of certificates, rather than a 3918 single certificate. 3920 o The "onboarding-information" container's support for image 3921 verification reworked to be extensible. 3923 o Added a reference to the "Device Details" section to the new 3924 example-zerotouch-device module. 3926 o Clarified that the device must always pass its IDevID certificate, 3927 even for untrusted bootstrap servers. 3929 o Fixed the description statement for the "script" typedef to refer 3930 to the [pre/post]-script-[warning/error] enums, rather than the 3931 legacy script-[warning/error] enums. 3933 o For the get-bootstrapping-data RPC's input, removed the "remote- 3934 id" and "circuit-id" fields, and added a "hw-model" field. 3936 o Improved DHCP error handling text. 3938 o Added MUST requirement for DHCPv6 client and server implementing 3939 [RFC3396] to handle URI lists longer than 255 octets. 3941 o Changed the "configuration" value in onboarding-information to be 3942 type "binary" instead of "anydata". 3944 o Moved everything from PKCS#7 to CMS (this shows up as a big 3945 change). 3947 o Added the early code point allocation assignments for the DHCP 3948 Options in the IANA Considerations section, and updated the RFC 3949 Editor note accordingly. 3951 o Added RFC Editor request to replace the assigned values for the 3952 CMS content types. 3954 o Relaxed auth requirements from device needing to always send 3955 IDevID cert to device needing to always send authentication 3956 credentials, as this better matches what RFC 8040 Section 2.5 3957 says. 3959 o Moved normative module "ietf-zerotouch-device" to non-normative 3960 module "example-zerotouch-device". 3962 o Updated Title, Abstract, and Introduction per discussion on list. 3964 D.22. 20 to 21 3966 o Now any of the three artifact can be encrypted. 3968 o Fixed some line-too-long issues. 3970 D.23. 21 to 22 3972 o Removed specifics around how scripts indicate warnings or errors 3973 and how scripts emit output. 3975 o Moved the Zero Touch Device Data Model section to the Appendix. 3977 o Modified the YANG module in the Zero Touch Device Data Model 3978 section to reflect the latest trust-anchors and keystore drafts. 3980 o Modified types in other YANG modules to more closely emulate what 3981 is in draft-ietf-netconf-crypto-types. 3983 D.24. 22 to 23 3985 o Rewrote section 5.6 (processing onboboarding information) to be 3986 clearer about error handling and retained state. Specifically: 3988 * Clarified that a script, upon having an error, must gracefully 3989 exit, cleaning up any state that might hinder subsequent 3990 executions. 3992 * Added ability for scripts to be executed again with a flag 3993 enabling them to clean up state from a previous execution. 3995 * Clarified that the conifguration commit is atomic. 3997 * Clarified that any error encountered after committing the 3998 configuration (e.g., in the "post-configuration-script") must 3999 rollback the configuration to the previous configuration. 4001 * Clarified that failure to successfully deliver the "bootstrap- 4002 initiated" and "bootstrap-complete" progress types must be 4003 treated as an error. 4005 * Clarified that "return to bootstrapping sequence" is to be 4006 interpreted in the recursive context. Meaning that the device 4007 rolls-back one loop, rather than start over from scratch. 4009 o Changed how a device verifies a boot-image from just "MUST match 4010 one of the supplied fingerprints" to also allow for the 4011 verification to use an cryptographic signature embedded into the 4012 image itself. 4014 o Added more "progress-type" enums for visibility reasons, enabling 4015 more strongly-typed debug information to be sent to the bootstrap 4016 server. 4018 o Added Security Considerations based on early SecDir review. 4020 o Added recommendation for device to send warning if the initial 4021 config does not disable the bootstrapping process. 4023 D.25. 23 to 24 4025 o Follow-ups from SecDir and Shepherd. 4027 o Added "boot-image-complete" enumeration. 4029 D.26. 24 to 25 4031 o Removed remaining old "bootstrapping information" term usage. 4033 o Fixed DHCP Option length definition. 4035 o Added reference to RFC 6187. 4037 Acknowledgements 4039 The authors would like to thank for following for lively discussions 4040 on list and in the halls (ordered by last name): Michael Behringer, 4041 Dean Bogdanovic, Martin Bjorklund, Joe Clarke, Toerless Eckert, 4042 Stephen Farrell, Stephen Hanna, Wes Hardaker, David Harrington, Radek 4043 Krejci, David Mandelberg, Russ Mundy, Reinaldo Penno, Randy Presuhn, 4044 Max Pritikin, Michael Richardson, Phil Shafer, Juergen Schoenwaelder. 4046 Special thanks goes to Steve Hanna, Russ Mundy, and Wes Hardaker for 4047 brainstorming the original I-D's solution during the IETF 87 meeting 4048 in Berlin. 4050 Authors' Addresses 4052 Kent Watsen 4053 Juniper Networks 4055 EMail: kwatsen@juniper.net 4057 Mikael Abrahamsson 4058 T-Systems 4060 EMail: mikael.abrahamsson@t-systems.se 4062 Ian Farrer 4063 Deutsche Telekom AG 4065 EMail: ian.farrer@telekom.de