idnits 2.17.1 draft-ietf-netconf-zerotouch-24.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 404 has weird spacing: '...gorithm ide...' == Line 1307 has weird spacing: '...gorithm ide...' == Line 1692 has weird spacing: '...rmation cms...' == Line 2263 has weird spacing: '... string cer...' == Line 3034 has weird spacing: '...address ine...' -- The document date (September 5, 2018) is 2031 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 2858, 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 9, 2019 T-Systems 6 I. Farrer 7 Deutsche Telekom AG 8 September 5, 2018 10 Zero Touch Provisioning for Networking Devices 11 draft-ietf-netconf-zerotouch-24 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-05" --> 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 9, 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 . . . . . . . . . . . . . . . . . . . . . . . . 4 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 . . . . . . . . . . . . . . . . . . . . 77 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 . . . . . . . . . . . . . . . . . . . . . . . . 80 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 . . . . . . . . . . . . . . . . . . . . . . . . 83 174 D.15. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 83 175 D.16. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 83 176 D.17. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 84 177 D.18. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 84 178 D.19. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 85 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 . . . . . . . . . . . . . . . . . . . . . . . . 87 184 D.25. 23 to 24 . . . . . . . . . . . . . . . . . . . . . . . . 87 185 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 88 186 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 88 188 1. Introduction 190 A fundamental business requirement for any network operator is to 191 reduce costs where possible. For network operators, deploying 192 devices to many locations can be a significant cost, as sending 193 trained specialists to each site for installations is both cost 194 prohibitive and does not scale. 196 This document defines Secure Zero Touch Provisioning (SZTP), a 197 bootstrapping strategy enabling devices to securely obtain 198 bootstrapping data with no installer action beyond physical placement 199 and connecting network and power cables. As such, SZTP enables non- 200 technical personnel to bring up devices in remote locations without 201 the need for any operator input. 203 The SZTP solution includes updating the boot image, committing an 204 initial configuration, and executing arbitrary scripts to address 205 auxiliary needs. The updated device is subsequently able to 206 establish secure connections with other systems. For instance, a 207 devices may establish NETCONF [RFC8040] and/or RESTCONF [RFC6241] 208 connections with deployment-specific network management systems. 210 This document primarily regards physical devices, where the setting 211 of the device's initial state, described in Section 5.1, occurs 212 during the device's manufacturing process. The SZTP solution may be 213 extended to support virtual machines or other such logical 214 constructs, but details for how this can be accomplished is left for 215 future work. 217 1.1. Use Cases 219 o Device connecting to a remotely administered network 221 This use-case involves scenarios, such as a remote branch 222 office or convenience store, whereby a device connects as an 223 access gateway to an ISP's network. Assuming it is not 224 possible to customize the ISP's network to provide any 225 bootstrapping support, and with no other nearby device to 226 leverage, the device has no recourse but to reach out to an 227 Internet-based bootstrap server to bootstrap from. 229 o Device connecting to a locally administered network 231 This use-case covers all other scenarios and differs only in 232 that the device may additionally leverage nearby devices, which 233 may direct it to use a local service to bootstrap from. If no 234 such information is available, or the device is unable to use 235 the information provided, it can then reach out to the network 236 just as it would for the remotely administered network use- 237 case. 239 Conceptual workflows for how SZTP might be deployed are provided in 240 Appendix C. 242 1.2. Terminology 244 This document uses the following terms (sorted by name): 246 Artifact: The term "artifact" is used throughout to represent any of 247 the three artifacts defined in Section 3 (zero touch information, 248 ownership voucher, and owner certificate). These artifacts 249 collectively provide all the bootstrapping data a device may use. 251 Bootstrapping Data: The term "bootstrapping data" is used throughout 252 this document to refer to the collection of data that a device 253 may obtain during the bootstrapping process. Specifically, it 254 refers to the three artifacts zero touch information, owner 255 certificate, and ownership voucher, as described in Section 3. 257 Bootstrap Server: The term "bootstrap server" is used within this 258 document to mean any RESTCONF server implementing the YANG module 259 defined in Section 7.3. 261 Device: The term "device" is used throughout this document to refer 262 to a network element that needs to be bootstrapped. See 263 Section 5 for more information about devices. 265 Manufacturer: The term "manufacturer" is used herein to refer to the 266 manufacturer of a device or a delegate of the manufacturer. 268 Network Management System (NMS): The acronym "NMS" is used 269 throughout this document to refer to the deployment specific 270 management system that the bootstrapping process is responsible 271 for introducing devices to. From a device's perspective, when 272 the bootstrapping process has completed, the NMS is a NETCONF or 273 RESTCONF client. 275 Onboarding Information: The term "onboarding information" is used 276 herein to refer to one of the two types of "zero touch 277 information" defined in this document, the other being "redirect 278 information". Onboarding information is formally defined by the 279 "onboarding-information" YANG-data structure in Section 6.3. 281 Onboarding Server: The term "onboarding server" is used herein to 282 refer to a bootstrap server that only returns onboarding 283 information. 285 Owner: The term "owner" is used throughout this document to refer to 286 the person or organization that purchased or otherwise owns a 287 device. 289 Owner Certificate: The term "owner certificate" is used in this 290 document to represent an X.509 certificate that binds an owner 291 identity to a public key, which a device can use to validate a 292 signature over the zero touch information artifact. The owner 293 certificate may be communicated along with its chain of 294 intermediate certificates leading up to a known trust anchor. 295 The owner certificate is one of the three bootstrapping artifacts 296 described in Section 3. 298 Ownership Voucher: The term "ownership voucher" is used in this 299 document to represent the voucher artifact defined in [RFC8366]. 300 The ownership voucher is used to assign a device to an owner. 301 The ownership voucher is one of the three bootstrapping artifacts 302 described in Section 3. 304 Redirect Information: The term "redirect information" is used herein 305 to refer to one of the two types of "zero touch information" 306 defined in this document, the other being "onboarding 307 information". Redirect information is formally defined by the 308 "redirect-information" YANG-data structure in Section 6.3. 310 Redirect Server: The term "redirect server" is used to refer to a 311 bootstrap server that only returns redirect information. A 312 redirect server is particularly useful when hosted by a 313 manufacturer, as a well-known (e.g., Internet-based) resource to 314 redirect devices to deployment-specific bootstrap servers. 316 Signed Data: The term "signed data" is used throughout to mean zero 317 touch information that has been signed, specifically by a private 318 key possessed by a device's owner. 320 Unsigned Data: The term "unsigned data" is used throughout to mean 321 zero touch information that has not been signed. 323 Zero Touch Information: The term "zero touch information" is used 324 herein to refer either redirect information or onboarding 325 information. Zero touch information is one of the three 326 bootstrapping artifacts described in Section 3. 328 1.3. Requirements Language 330 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 331 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 332 "OPTIONAL" in this document are to be interpreted as described in BCP 333 14 [RFC2119] [RFC8174] when, and only when, they appear in all 334 capitals, as shown here. 336 1.4. Tree Diagrams 338 Tree diagrams used in this document follow the notation defined in 339 [RFC8340]. 341 2. Types of Bootstrapping Information 343 This document defines two types of information that devices can 344 access during the bootstrapping process. These information types are 345 described in this section. Examples are provided in Section 6.2 347 2.1. Redirect Information 349 Redirect information redirects a device to another bootstrap server. 350 Redirect information encodes a list of bootstrap servers, each 351 specifying the bootstrap server's hostname (or IP address), an 352 optional port, and an optional trust anchor certificate that the 353 device can use to authenticate the bootstrap server with. 355 Redirect information is YANG modeled data formally defined by the 356 "redirect-information" container in the YANG module presented in 357 Section 6.3. This container has the tree diagram shown below. 359 +--:(redirect-information) 360 +-- redirect-information 361 +-- bootstrap-server* [address] 362 +-- address inet:host 363 +-- port? inet:port-number 364 +-- trust-anchor? cms 366 Redirect information may be trusted or untrusted. The redirect 367 information is trusted whenever it is obtained via a secure 368 connection to a trusted bootstrap server, or whenever it is signed by 369 the device's owner. In all other cases, the redirect information is 370 untrusted. 372 Trusted redirect information is useful for enabling a device to 373 establish a secure connection to a specified bootstrap server, which 374 is possible when the redirect information includes the bootstrap 375 server's trust anchor certificate. 377 Untrusted redirect information is useful for directing a device to a 378 bootstrap server where signed data has been staged for it to obtain. 379 Note that, when the redirect information is untrusted, devices 380 discard any potentially included trust anchor certificates. 382 How devices process redirect information is described in Section 5.5. 384 2.2. Onboarding Information 386 Onboarding information provides data necessary for a device to 387 bootstrap itself and establish secure connections with other systems. 388 As defined in this document, onboarding information can specify 389 details about the boot image a device must be running, specify an 390 initial configuration the device must commit, and specify scripts 391 that the device must successfully execute. 393 Onboarding information is YANG modeled data formally defined by the 394 "onboarding-information" container in the YANG module presented in 395 Section 6.3. This container has the tree diagram shown below. 397 +--:(onboarding-information) 398 +-- onboarding-information 399 +-- boot-image 400 | +-- os-name? string 401 | +-- os-version? string 402 | +-- download-uri* inet:uri 403 | +-- image-verification* [hash-algorithm] 404 | +-- hash-algorithm identityref 405 | +-- hash-value yang:hex-string 406 +-- configuration-handling? enumeration 407 +-- pre-configuration-script? script 408 +-- configuration? binary 409 +-- post-configuration-script? script 411 Onboarding information must be trusted for it to be of any use to a 412 device. There is no option for a device to process untrusted 413 onboarding information. 415 Onboarding information is trusted whenever it is obtained via a 416 secure connection to a trusted bootstrap server, or whenever it is 417 signed by the device's owner. In all other cases, the onboarding 418 information is untrusted. 420 How devices process onboarding information is described in 421 Section 5.6. 423 3. Artifacts 425 This document defines three artifacts that can be made available to 426 devices while they are bootstrapping. Each source of bootstrapping 427 information specifies how it provides the artifacts defined in this 428 section (see Section 4). 430 3.1. Zero Touch Information 432 The zero touch information artifact encodes the essential 433 bootstrapping data for the device. This artifact is used to encode 434 the redirect information and onboarding information types discussed 435 in Section 2. 437 The zero touch information artifact is a CMS structure, as described 438 in [RFC5652], encoded using ASN.1 distinguished encoding rules (DER), 439 as specified in ITU-T X.690 [ITU.X690.2015]. The CMS structure MUST 440 contain content conforming to the YANG module specified in 441 Section 6.3. 443 The zero touch information CMS structure may encode signed or 444 unsigned bootstrapping data. When the bootstrapping data is signed, 445 it may also be encrypted but, from a terminology perspective, it is 446 still "signed data" Section 1.2. 448 When the zero touch information artifact is unsigned, as it might be 449 when communicated over trusted channels, the CMS structure's top-most 450 content type MUST be one of the OIDs described in Section 10.3, or 451 the OID id-data (1.2.840.113549.1.7.1), in which case the encoding 452 (JSON, XML, etc.) SHOULD be communicated externally. In either 453 case, the associated content is an octet string containing 454 "zerotouch-information" data in the expected encoding. 456 When the zero touch information artifact is signed, as it might be 457 when communicated over untrusted channels, the CMS structure's top- 458 most content type MUST be the OID id-signedData 459 (1.2.840.113549.1.7.2), and its inner eContentType MUST be one of the 460 OIDs described in Section 10.3, or the OID id-data 461 (1.2.840.113549.1.7.1), in which case the encoding (JSON, XML, etc.) 462 SHOULD be communicated externally. In either case, the associated 463 content or eContent is an octet string containing "zerotouch- 464 information" data in the expected encoding. 466 When the zero touch information artifact is signed and encrypted, as 467 it might be when communicated over untrusted channels and privacy is 468 important, the CMS structure's top-most content type MUST be the OID 469 id-envelopedData (1.2.840.113549.1.7.3), and the 470 encryptedContentInfo's content type MUST be the OID id-signedData 471 (1.2.840.113549.1.7.2), whose eContentType MUST be one of the OIDs 472 described in Section 10.3, or the OID id-data (1.2.840.113549.1.7.1), 473 in which case the encoding (JSON, XML, etc.) SHOULD be communicated 474 externally. In either case, the associated content or eContent is an 475 octet string containing "zerotouch-information" data in the expected 476 encoding. 478 3.2. Owner Certificate 480 The owner certificate artifact is an X.509 certificate [RFC5280] that 481 is used to identify an "owner" (e.g., an organization). The owner 482 certificate can be signed by any certificate authority (CA). The 483 owner certificate either MUST have no Key Usage specified or the Key 484 Usage MUST at least set the "digitalSignature" bit. The values for 485 the owner certificate's "subject" and/or "subjectAltName" are not 486 constrained by this document. 488 The owner certificate is used by a device to verify the signature 489 over the zero touch information artifact (Section 3.1) that the 490 device should have also received, as described in Section 3.5. In 491 particular, the device verifies the signature using the public key in 492 the owner certificate over the content contained within the zero 493 touch information artifact. 495 The owner certificate artifact is formally a CMS structure, as 496 specified by [RFC5652], encoded using ASN.1 distinguished encoding 497 rules (DER), as specified in ITU-T X.690 [ITU.X690.2015]. 499 The owner certificate CMS structure MUST contain the owner 500 certificate itself, as well as all intermediate certificates leading 501 to the "pinned-domain-cert" certificate specified in the ownership 502 voucher. The owner certificate artifact MAY optionally include the 503 "pinned-domain-cert" as well. 505 In order to support devices deployed on private networks, the owner 506 certificate CMS structure MAY also contain suitably fresh, as 507 determined by local policy, revocation objects (e.g., CRLs). Having 508 these revocation objects stapled to the owner certificate may obviate 509 the need for the device to have to download them dynamically using 510 the CRL distribution point or an OCSP responder specified in the 511 associated certificates. 513 When unencrypted, the owner certificate artifact's CMS structure's 514 top-most content type MUST be the OID id-signedData 515 (1.2.840.113549.1.7.2). The inner SignedData structure is the 516 degenerate form, whereby there are no signers, that is commonly used 517 to disseminate certificates and revocation objects. 519 When encrypted, the owner certificate artifact's CMS structure's top- 520 most content type MUST be the OID id-envelopedData 521 (1.2.840.113549.1.7.3), and the encryptedContentInfo's content type 522 MUST be the OID id-signedData (1.2.840.113549.1.7.2), whereby the 523 inner SignedData structure is the degenerate form that has no signers 524 commonly used to disseminate certificates and revocation objects. 526 3.3. Ownership Voucher 528 The ownership voucher artifact is used to securely identify a 529 device's owner, as it is known to the manufacturer. The ownership 530 voucher is signed by the device's manufacturer. 532 The ownership voucher is used to verify the owner certificate 533 (Section 3.2) that the device should have also received, as described 534 in Section 3.5. In particular, the device verifies that the owner 535 certificate has a chain of trust leading to the trusted certificate 536 included in the ownership voucher ("pinned-domain-cert"). Note that 537 this relationship holds even when the owner certificate is a self- 538 signed certificate, and hence also the pinned-domain-cert. 540 When unencrypted, the ownership voucher artifact is as defined in 541 [RFC8366]. As described, it is a CMS structure whose top-most 542 content type MUST be the OID id-signedData (1.2.840.113549.1.7.2), 543 whose eContentType MUST be OID id-ct-animaJSONVoucher 544 (1.2.840.113549.1.9.16.1), or the OID id-data (1.2.840.113549.1.7.1), 545 in which case the encoding (JSON, XML, etc.) SHOULD be communicated 546 externally. In either case, the associated content is an octet 547 string containing ietf-voucher data in the expected encoding. 549 When encrypted, the ownership voucher artifact's CMS structure's top- 550 most content type MUST be the OID id-envelopedData 551 (1.2.840.113549.1.7.3), and the encryptedContentInfo's content type 552 MUST be the OID id-signedData (1.2.840.113549.1.7.2), whose 553 eContentType MUST be OID id-ct-animaJSONVoucher 554 (1.2.840.113549.1.9.16.1), or the OID id-data (1.2.840.113549.1.7.1), 555 in which case the encoding (JSON, XML, etc.) SHOULD be communicated 556 externally. In either case, the associated content is an octet 557 string containing ietf-voucher data in the expected encoding. 559 3.4. Artifact Encryption 561 Each of the three artifacts MAY be individually encrypted. 562 Encryption may be important in some environments where the content is 563 considered sensitive. 565 Each of the three artifacts are encrypted in the same way, by the 566 unencrypted form being encapsulated inside a CMS EnvelopedData type. 568 As a consequence, both the zerotouch information and ownership 569 voucher artifacts are signed and then encrypted, never encrypted and 570 then signed. 572 This sequencing has the advantage of shrouding the signer's 573 certificate, and ensuring that the owner knows the content being 574 signed. This sequencing further enables the owner to inspect an 575 unencrypted voucher obtained from a manufacturer and then encrypt the 576 voucher later themselves, perhaps while also stapling in current 577 revocation objects, when ready to place the artifact in an unsafe 578 location. 580 When encrypted, the CMS MUST be encrypted using a secure device 581 identity certificate for the device. This certificate MAY be the 582 same as the TLS-level client certificate the device uses when 583 connecting to bootstrap servers. The owner must possess the device's 584 identity certificate at the time of encrypting the data. How the 585 owner comes to posses the device's identity certificate for this 586 purpose is outside the scope of this document. 588 3.5. Artifact Groupings 590 The previous sections discussed the bootstrapping artifacts, but only 591 certain groupings of these artifacts make sense to return in the 592 various bootstrapping situations described in this document. These 593 groupings are: 595 Unsigned Information: This grouping is useful for cases when 596 transport level security can be used to convey trust (e.g., 597 HTTPS), or when the information can be processed in a 598 provisional manner (i.e. unsigned redirect information). 600 Signed Information, without revocations: This grouping is useful 601 when signed information is needed, because it is obtained from 602 an untrusted source, and it cannot be processed provisionally, 603 and yet either revocations are not needed or they can be 604 obtained dynamically. 606 Signed Information, with revocations: This grouping is useful 607 when signed information is needed, because it is obtained from 608 an untrusted source, and it cannot be processed provisionally, 609 and revocations are needed and cannot be obtained dynamically. 611 The artifacts associated with these groupings are described below: 613 Zero Touch Ownership Owner 614 Grouping Information Voucher Certificate 615 -------------------- ------------- ------------ ----------- 616 Unsigned Information Yes, no sig No No 618 Signed Information, Yes, with sig Yes, without Yes, without 619 without revocations revocations revocations 621 Signed Information, Yes, with sig Yes, with Yes, with 622 with revocations revocations revocations 624 4. Sources of Bootstrapping Data 626 This section defines some sources for bootstrapping data that a 627 device can access. The list of sources defined here is not meant to 628 be exhaustive. It is left to future documents to define additional 629 sources for obtaining bootstrapping data. 631 For each source of bootstrapping data defined in this section, 632 details are given for how the three artifacts listed in Section 3 are 633 provided. 635 4.1. Removable Storage 637 A directly attached removable storage device (e.g., a USB flash 638 drive) MAY be used as a source of zero touch bootstrapping data. 640 Use of a removable storage device is compelling, as it does not 641 require any external infrastructure to work. It is notable that the 642 raw boot image file can also be located on the removable storage 643 device, enabling a removable storage device to be a fully self- 644 standing bootstrapping solution. 646 To use a removable storage device as a source of bootstrapping data, 647 a device need only detect if the removable storage device is plugged 648 in and mount its filesystem. 650 A removable storage device is an untrusted source of bootstrapping 651 data. This means that the information stored on the removable 652 storage device either MUST be signed or MUST be information that can 653 be processed provisionally (e.g., unsigned redirect information). 655 From an artifact perspective, since a removable storage device 656 presents itself as a filesystem, the bootstrapping artifacts need to 657 be presented as files. The three artifacts defined in Section 3 are 658 mapped to files below. 660 Artifact to File Mapping: 662 Zero Touch Information: Mapped to a file containing the binary 663 artifact described in Section 3.1 (e.g., zerotouch- 664 information.cms). 666 Owner Certificate: Mapped to a file containing the binary 667 artifact described in Section 3.2 (e.g., owner- 668 certificate.cms). 670 Ownership Voucher: Mapped to a file containing the binary 671 artifact described in Section 3.3 (e.g., ownership-voucher.cms 672 or ownership-voucher.vcj). 674 The format of the removable storage device's filesystem and the 675 naming of the files are outside the scope of this document. However, 676 in order to facilitate interoperability, it is RECOMMENDED devices 677 support open and/or standards based filesystems. It is also 678 RECOMMENDED that devices assume a file naming convention that enables 679 more than one instance of bootstrapping data (i.e., for different 680 devices) to exist on a removable storage device. The file naming 681 convention SHOULD additionally be unique to the manufacturer, in 682 order to enable bootstrapping data from multiple manufacturers to 683 exist on a removable storage device. 685 4.2. DNS Server 687 A DNS server MAY be used as a source of zero touch bootstrapping 688 data. 690 Using a DNS server may be a compelling option for deployments having 691 existing DNS infrastructure, as it enables a touchless bootstrapping 692 option that does not entail utilizing an Internet based resource 693 hosted by a 3rd-party. 695 To use a DNS server as a source of bootstrapping data, a device MAY 696 perform a multicast DNS [RFC6762] query searching for the service 697 "_zerotouch._tcp.local.". Alternatively the device MAY perform DNS- 698 SD [RFC6763] via normal DNS operation, using the domain returned to 699 it from the DHCP server; for example, searching for the service 700 "_zerotouch._tcp.example.com". 702 Unsigned DNS records (e.g., not using DNSSEC as described in 703 [RFC6698]) are an untrusted source of bootstrapping data. This means 704 that the information stored in the DNS records either MUST be signed, 705 or MUST be information that can be processed provisionally (e.g., 706 unsigned redirect information). 708 From an artifact perspective, since a DNS server presents resource 709 records (Section 3.2.1 of [RFC1035]), the bootstrapping artifacts 710 need to be presented as resource records. The three artifacts 711 defined in Section 3 are mapped to resource records below. 713 Artifact to Resource Record Mapping: 715 Zero Touch Information: Mapped to a TXT record called "zt-info" 716 containing the base64-encoding of the binary artifact described 717 in Section 3.1. 719 Owner Certificate: Mapped to a TXT record called "zt-cert" 720 containing the base64-encoding of the binary artifact described 721 in Section 3.2. 723 Ownership Voucher: Mapped to a TXT record called "zt-voucher" 724 containing the base64-encoding of the binary artifact described 725 in Section 3.3. 727 TXT records have an upper size limit of 65535 bytes (Section 3.2.1 in 728 RFC1035), since "RDLENGTH" is a 16-bit field. Please see 729 Section 3.1.3 in RFC4408 for how a TXT record can achieve this size. 730 Due to this size limitation, some zero touch information artifacts 731 may not fit. In particular, onboarding information could hit this 732 upper bound, depending on the size of the included configuration and 733 scripts. 735 4.3. DHCP Server 737 A DHCP server MAY be used as a source of zero touch bootstrapping 738 data. 740 Using a DHCP server may be a compelling option for deployments having 741 existing DHCP infrastructure, as it enables a touchless bootstrapping 742 option that does not entail utilizing an Internet based resource 743 hosted by a 3rd-party. 745 A DHCP server is an untrusted source of bootstrapping data. Thus the 746 information stored on the DHCP server either MUST be signed, or it 747 MUST be information that can be processed provisionally (e.g., 748 unsigned redirect information). 750 However, unlike other sources of bootstrapping data described in this 751 document, the DHCP protocol (especially DHCP for IPv4) is very 752 limited in the amount of data that can be conveyed, to the extent 753 that signed data cannot be communicated. This means that only 754 unsigned redirect information can be conveyed via DHCP. 756 Since the redirect information is unsigned, it SHOULD NOT include the 757 optional trust anchor certificate, as it takes up space in the DHCP 758 message, and the device would have to discard it anyway. For this 759 reason, the DHCP options defined in Section 8 do not enable the trust 760 anchor certificate to be encoded. 762 From an artifact perspective, the three artifacts defined in 763 Section 3 are mapped to the DHCP fields specified in Section 8 as 764 follows: 766 Zero Touch Information: This artifact is not supported directly. 767 Instead, the essence of unsigned redirect information is mapped 768 to the DHCP options described in Section 8. 770 Owner Certificate: Not supported. There is not enough space in 771 the DHCP packet to hold an owner certificate artifact. 773 Ownership Voucher: Not supported. There is not enough space in 774 the DHCP packet to hold an ownership voucher artifact. 776 4.4. Bootstrap Server 778 A bootstrap server MAY be used as a source of zero touch 779 bootstrapping data. A bootstrap server is defined as a RESTCONF 780 [RFC8040] server implementing the YANG module provided in Section 7. 782 Using a bootstrap server as a source of bootstrapping data is a 783 compelling option as it MAY use transport-level security, obviating 784 the need for signed data, which may be easier to deploy in some 785 situations. 787 Unlike any other source of bootstrapping data described in this 788 document, a bootstrap server is not only a source of data, but it can 789 also receive data from devices using the YANG-defined "report- 790 progress" RPC defined in the YANG module (Section 7.3). The "report- 791 progress" RPC enables visibility into the bootstrapping process 792 (e.g., warnings and errors), and provides potentially useful 793 information upon completion (e.g., the device's SSH host-keys). 795 A bootstrap server may be a trusted or an untrusted source of 796 bootstrapping data, depending on if the device learned about the 797 bootstrap server's trust anchor from a trusted source. When a 798 bootstrap server is trusted, the information returned from it MAY be 799 signed. However, when the server is untrusted, in order for its 800 information to be of any use to the device, the bootstrap information 801 either MUST be signed or MUST be information that can be processed 802 provisionally (e.g., unsigned redirect information). 804 From an artifact perspective, since a bootstrap server presents data 805 conforming to a YANG data model, the bootstrapping artifacts need to 806 be mapped to YANG nodes. The three artifacts defined in Section 3 807 are mapped to "output" nodes of the "get-bootstrapping-data" RPC 808 defined in Section 7.3 below. 810 Artifact to Bootstrap Server Mapping: 812 Zero Touch Information: Mapped to the "zerotouch-information" 813 leaf in the output of the "get-bootstrapping-data" RPC. 815 Owner Certificate: Mapped to the "owner-certificate" leaf in the 816 output of the "get-bootstrapping-data" RPC. 818 Ownership Voucher: Mapped to the "ownership-voucher" leaf in the 819 output of the "get-bootstrapping-data" RPC. 821 Zero touch bootstrap servers have only two endpoints, one for the 822 "get-bootstrapping-data" RPC and one for the "report-progress" RPC. 823 These RPCs use the authenticated RESTCONF username to isolate the 824 execution of the RPC from other devices. 826 5. Device Details 828 Devices supporting the bootstrapping strategy described in this 829 document MUST have the preconfigured state and bootstrapping logic 830 described in the following sections. 832 5.1. Initial State 833 +-------------------------------------------------------------+ 834 | | 835 | | 836 | +---------------------------------------------------------+ | 837 | | | | 838 | | | | 839 | | 1. flag to enable zerotouch bootstrapping set to "true" | | 840 | +---------------------------------------------------------+ | 841 | | 842 | +---------------------------------------------------------+ | 843 | | | | 844 | | | | 845 | | 2. TLS client cert & related intermediate certificates | | 846 | | 3. list of trusted well-known bootstrap servers | | 847 | | 4. list of trust anchor certs for bootstrap servers | | 848 | | 5. list of trust anchor certs for ownership vouchers | | 849 | +---------------------------------------------------------+ | 850 | | 851 | +-----------------------------------------------------+ | 852 | | | | 853 | | | | 854 | | 6. private key for TLS client certificate | | 855 | | 7. private key for decrypting zerotouch artifacts | | 856 | +-----------------------------------------------------+ | 857 | | 858 +-------------------------------------------------------------+ 860 Each numbered item below corresponds to a numbered item in the 861 diagram above. 863 1. Devices MUST have a configurable variable that is used to enable/ 864 disable zerotouch bootstrapping. This variable MUST be enabled 865 by default in order for zerotouch bootstrapping to run when the 866 device first powers on. Because it is a goal that the 867 configuration installed by the bootstrapping process disables 868 zerotouch bootstrapping, and because the configuration may be 869 merged into the existing configuration, using a configuration 870 node that relies on presence is NOT RECOMMENDED, as it cannot be 871 removed by the merging process. 873 2. Devices that support loading bootstrapping data from bootstrap 874 servers (see Section 4.4) SHOULD possess a TLS-level client 875 certificate and any intermediate certificates leading to the 876 certificate's well-known trust-anchor. The well-known trust 877 anchor certificate may be an intermediate certificate or a self- 878 signed root certificate. To support devices not having a client 879 certificate, devices MAY, alternatively or in addition to, 880 identify and authenticate themselves to the bootstrap server 881 using an HTTP authentication scheme, as allowed by Section 2.5 in 882 [RFC8040]; however, this document does not define a mechanism for 883 operator input enabling, for example, the entering of a password. 885 3. Devices that support loading bootstrapping data from well-known 886 bootstrap servers MUST possess a list of the well-known bootstrap 887 servers. Consistent with redirect information (Section 2.1, each 888 bootstrap server can be identified by its hostname or IP address, 889 and an optional port. 891 4. Devices that support loading bootstrapping data from well-known 892 bootstrap servers MUST also possess a list of trust anchor 893 certificates that can be used to authenticate the well-known 894 bootstrap servers. For each trust anchor certificate, if it is 895 not itself a self-signed root certificate, the device SHOULD also 896 possess the chain of intermediate certificates leading up to and 897 including the self-signed root certificate. 899 5. Devices that support loading signed data (see Section 1.2) MUST 900 possess the trust anchor certificates for validating ownership 901 vouchers. For each trust anchor certificate, if it is not itself 902 a self-signed root certificate, the device SHOULD also possess 903 the chain of intermediate certificates leading up to and 904 including the self-signed root certificate. 906 6. Devices that support using a TLS-level client certificate to 907 identify and authenticate themselves to a bootstrap server MUST 908 possess the private key that corresponds to the public key 909 encoded in the TLS-level client certificate. This private key 910 SHOULD be securely stored, ideally in a cryptographic processor 911 (e.g., a TPM). 913 7. Devices that support decrypting zerotouch artifacts MUST posses 914 the private key that corresponds to the public key encoded in the 915 secure device identity certificate used when encrypting the 916 artifacts. This private key SHOULD be securely stored, ideally 917 in a cryptographic processor (e.g., a TPM). This private key MAY 918 be the same as the one associated to the TLS-level client 919 certificate used when connecting to bootstrap servers. 921 A YANG module representing this data is provided in Appendix A. 923 5.2. Boot Sequence 925 A device claiming to support the bootstrapping strategy defined in 926 this document MUST support the boot sequence described in this 927 section. 929 Power On 930 | 931 v No 932 1. Zerotouch bootstrapping configured ------> Boot normally 933 | 934 | Yes 935 v 936 2. For each supported source of bootstrapping data, 937 try to load bootstrapping data from the source 938 | 939 | 940 v Yes 941 3. Able to bootstrap from any source? -----> Run with new config 942 | 943 | No 944 v 945 4. Loop and/or wait for manual provisioning. 947 Each numbered item below corresponds to a numbered item in the 948 diagram above. 950 1. When the device powers on, it first checks to see if zerotouch 951 bootstrapping is configured, as is expected to be the case for 952 the device's preconfigured initial state. If zerotouch 953 bootstrapping is not configured, then the device boots normally. 955 2. The device iterates over its list of sources for bootstrapping 956 data (Section 4). Details for how to processes a source of 957 bootstrapping data are provided in Section 5.3. 959 3. If the device is able to bootstrap itself from any of the sources 960 of bootstrapping data, it runs with the new bootstrapped 961 configuration. 963 4. Otherwise the device MAY loop back through the list of 964 bootstrapping sources again and/or wait for manual provisioning. 966 5.3. Processing a Source of Bootstrapping Data 968 This section describes a recursive algorithm that devices can use to, 969 ultimately, obtain onboarding information. The algorithm is 970 recursive because sources of bootstrapping data may return redirect 971 information, which causes the algorithm to run again, for the newly 972 discovered sources of bootstrapping information. An expression that 973 captures all possible successful sequences of bootstrapping 974 information is zero or more redirect information responses, followed 975 by one onboarding information response. 977 An important aspect of the algorithm is knowing when data needs to be 978 signed or not. The following figure provides a summary of options: 980 Untrusted Source Trusted Source 981 Kind of Bootstrapping Data Can Provide? Can Provide? 983 Unsigned Redirect Info : Yes+ Yes 984 Signed Redirect Info : Yes Yes* 985 Unsigned Onboarding Info : No Yes 986 Signed Onboarding Info : Yes Yes* 988 The '+' above denotes that the source redirected to MUST 989 return signed data, or more unsigned redirect information. 991 The '*' above denotes that, while possible, it is generally 992 unnecessary for a trusted source to return signed data. 994 The recursive algorithm uses a conceptual global-scoped variable 995 called "trust-state". The trust-state variable is initialized to 996 FALSE. The ultimate goal of this algorithm is for the device to 997 process onboarding information (Section 2.2) while the trust-state 998 variable is TRUE. 1000 If the source of bootstrapping data (Section 4) is a bootstrap server 1001 (Section 4.4), and the device is able to authenticate the bootstrap 1002 server using X.509 certificate path validation ([RFC6125], Section 6) 1003 to one of the device's preconfigured trust anchors, or to a trust 1004 anchor that it learned from a previous step, then the device MUST set 1005 trust-state to TRUE. 1007 When establishing a connection to a bootstrap server, whether trusted 1008 or untrusted, the device MUST identify and authenticate itself to the 1009 bootstrap server using a TLS-level client certificate and/or an HTTP 1010 authentication scheme, per Section 2.5 in [RFC8040]. If both 1011 authentication mechanisms are used, they MUST both identify the same 1012 serial number. 1014 When sending a client certificate, the device MUST also send all of 1015 the intermediate certificates leading up to, and optionally 1016 including, the client certificate's well-known trust anchor 1017 certificate. 1019 For any source of bootstrapping data (e.g., Section 4), if any 1020 artifact obtained is encrypted, the device MUST first decrypt it 1021 using the private key associated with the device certificate used to 1022 encrypt the artifact. 1024 If the zero touch information artifact is signed, and the device is 1025 able to validate the signed data using the algorithm described in 1026 Section 5.4, then the device MUST set trust-state to TRUE; otherwise, 1027 if the device is unable to validate the signed data, the device MUST 1028 set trust-state to FALSE. Note, this is worded to cover the special 1029 case when signed data is returned even from a trusted bootstrap 1030 server. 1032 If the zero touch information artifact contains onboarding 1033 information, and trust-state is FALSE, the device MUST exit the 1034 recursive algorithm (as this is not allowed, see the figure above), 1035 returning to the bootstrapping sequence described in Section 5.2. 1036 Otherwise, the device MUST attempt to process the onboarding 1037 information as described in Section 5.6. In either case, success or 1038 failure, the device MUST exit the recursive algorithm, returning to 1039 the bootstrapping sequence described in Section 5.2, the only 1040 difference being in how it responds to the "Able to bootstrap from 1041 any source?" conditional described in the figure in the section. 1043 If the zero touch information artifact contains redirect information, 1044 the device MUST, within limits of how many recursive loops the device 1045 allows, process the redirect information as described in Section 5.5. 1046 This is the recursion step, it will cause the device to reenter this 1047 algorithm, but this time the data source will definitely be a 1048 bootstrap server, as that is all redirect information is able to 1049 redirect a device to. 1051 5.4. Validating Signed Data 1053 Whenever a device is presented signed data, it MUST validate the 1054 signed data as described in this section. This includes the case 1055 where the signed data is provided by a trusted source. 1057 Whenever there is signed data, the device MUST also be provided an 1058 ownership voucher and an owner certificate. How all the needed 1059 artifacts are provided for each source of bootstrapping data is 1060 described in Section 4. 1062 In order to validate signed data, the device MUST first authenticate 1063 the ownership voucher by validating its signature to one of its 1064 preconfigured trust anchors (see Section 5.1), which may entail using 1065 additional intermediate certificates attached to the ownership 1066 voucher. If the device has an accurate clock, it MUST verify that 1067 the ownership voucher was created in the past (i.e., "created-on" < 1068 now) and, if the "expires-on" leaf is present, the device MUST verify 1069 that the ownership voucher has not yet expired (i.e., now < "expires- 1070 on"). The device MUST verify that the ownership voucher's 1071 "assertion" value is acceptable (e.g., some devices may only accept 1072 the assertion value "verified"). The device MUST verify that the 1073 ownership voucher specifies the device's serial number in the 1074 "serial-number" leaf. If the "idevid-issuer" leaf is present, the 1075 device MUST verify that the value is set correctly. If the 1076 authentication of the ownership voucher is successful, the device 1077 extracts the "pinned-domain-cert" node, an X.509 certificate, that is 1078 needed to verify the owner certificate in the next step. 1080 The device MUST next authenticate the owner certificate by performing 1081 X.509 certificate path verification to the trusted certificate 1082 extracted from the ownership voucher's "pinned-domain-cert" node. 1083 This verification may entail using additional intermediate 1084 certificates attached to the owner certificate artifact. If the 1085 ownership voucher's "domain-cert-revocation-checks" node's value is 1086 set to "true", the device MUST verify the revocation status of the 1087 certificate chain used to sign the owner certificate and, if 1088 suitably-fresh revocation status is unattainable or if it is 1089 determined that a certificate has been revoked, the device MUST NOT 1090 validate the owner certificate. 1092 Finally the device MUST verify the zero touch information artifact 1093 was signed by the validated owner certificate. 1095 If any of these steps fail, the device MUST invalidate the signed 1096 data and not perform any subsequent steps. 1098 5.5. Processing Redirect Information 1100 In order to process redirect information (Section 2.1), the device 1101 MUST follow the steps presented in this section. 1103 Processing redirect information is straightforward, the device 1104 sequentially steps through the list of provided bootstrap servers 1105 until it can find one it can bootstrap from. 1107 If a hostname is provided, and the hostname's DNS resolution is to 1108 more than one IP address, the device MUST attempt to connect to all 1109 of the DNS resolved addresses at least once, before moving on to the 1110 next bootstrap server. If the device is able to obtain bootstrapping 1111 data from any of the DNS resolved addresses, it MUST immediately 1112 process that data, without attempting to connect to any of the other 1113 DNS resolved addresses. 1115 If the redirect information is trusted (e.g., trust-state is TRUE), 1116 and the bootstrap server entry contains a trust anchor certificate, 1117 then the device MUST authenticate the specified bootstrap server's 1118 TLS server certificate using X.509 certificate path validation 1119 ([RFC6125], Section 6) to the specified trust anchor. If the 1120 bootstrap server entry does not contain a trust anchor certificate 1121 device, the device MUST establish a provisional connection to the 1122 bootstrap server (i.e., by blindly accepting its server certificate), 1123 and set trust-state to FALSE. 1125 If the redirect information is untrusted (e.g., trust-state is 1126 FALSE), the device MUST discard any trust anchors provided by the 1127 redirect information and establish a provisional connection to the 1128 bootstrap server (i.e., by blindly accepting its TLS server 1129 certificate). 1131 5.6. Processing Onboarding Information 1133 In order to process onboarding information (Section 2.2), the device 1134 MUST follow the steps presented in this section. 1136 When processing onboarding information, the device MUST first process 1137 the boot image information (if any), then execute the pre- 1138 configuration script (if any), then commit the initial configuration 1139 (if any), and then execute the post-configuration script (if any), in 1140 that order. 1142 When the onboarding information is obtained from a trusted bootstrap 1143 server, the device MUST send the "bootstrap-initiated" progress 1144 report, and send either a terminating "boot-image-installed- 1145 rebooting", "bootstrap-complete", or error specific progress report. 1146 If the bootstrap server's "get-bootstrapping-data" RPC-reply's 1147 "reporting-level" node is set to "verbose", the device MUST 1148 additionally send all appropriate non-terminating progress reports 1149 (e.g., initiated, warning, complete, etc.). Regardless the 1150 reporting-level indicated by the bootstrap server, the device MAY 1151 send progress reports beyond the mandatory ones specified for the 1152 given reporting level. 1154 When the onboarding information is obtained from an untrusted 1155 bootstrap server, the device MUST NOT send any progress reports to 1156 the bootstrap server. 1158 If the device encounters an error at any step, it MUST stop 1159 processing the onboarding information and return to the bootstrapping 1160 sequence described in Section 5.2. In the context of a recursive 1161 algorithm, the device MUST return to the enclosing loop, not back to 1162 the very beginning. Some state MAY be retained from the 1163 bootstrapping process (e.g., updated boot image, logs, remnants from 1164 a script, etc.). However, the retained state MUST NOT be active in 1165 any way (e.g., no new configuration or running of software), and MUST 1166 NOT hinder the ability for the device to continue the bootstrapping 1167 sequence (i.e., process onboarding information from another bootstrap 1168 server). 1170 At this point, the specific ordered sequence of actions the device 1171 MUST perform is described. 1173 If the onboarding information is obtained from a trusted bootstrap 1174 server, the device MUST send a "bootstrap-initiated" progress report. 1175 It is an error if the device does not receive back the "204 No 1176 Content" HTTP status line. If an error occurs, the device MUST try 1177 to send a "bootstrap-error" progress report before exiting. 1179 The device MUST parse the provided onboarding information document, 1180 to extract values used in subsequent steps. Whether using a stream- 1181 based parser or not, if there is an error when parsing the onboarding 1182 information, and the device is connected to a trusted bootstrap 1183 server, the device MUST try to send a "parsing-error" progress report 1184 before exiting. 1186 If boot image criteria are specified, the device MUST first determine 1187 if the boot image it is running satisfies the specified boot image 1188 criteria. If the device is already running the specified boot image, 1189 then it skips the remainder of this step. If the device is not 1190 running the specified boot image, then it MUST download, verify, and 1191 install, in that order, the specified boot image, and then reboot. 1192 If connected to a trusted bootstrap server, the device MAY try to 1193 send a "boot-image-mismatch" progress report. To download the boot 1194 image, the device MUST only use the URIs supplied by the onboarding 1195 information. To verify the boot image, the device MUST either use 1196 one of the verification fingerprints supplied by the onboarding 1197 information, or use a cryptographic signature embedded into the boot 1198 image itself using a mechanism not described by this document. 1199 Before rebooting, if connected to a trusted bootstrap server, the 1200 device MUST try to send a "boot-image-installed-rebooting" progress 1201 report. Upon rebooting, the bootstrapping process runs again, which 1202 will eventually come to this step again, but then the device will be 1203 running the specified boot image, and thus will move to processing 1204 the next step. If an error occurs at any step while the device is 1205 connected to a trusted bootstrap server (i.e., before the reboot), 1206 the device MUST try to send a "boot-image-error" progress report 1207 before exiting. 1209 If a pre-configuration script has been specified, the device MUST 1210 execute the script, capture any output emitted from the script, and 1211 check if the script had any warnings or errors. If an error occurs 1212 while the device is connected to a trusted bootstrap server, the 1213 device MUST try to send a "pre-script-error" progress report before 1214 exiting. 1216 If an initial configuration has been specified, the device MUST 1217 atomically commit the provided initial configuration, using the 1218 approach specified by the "configuration-handling" leaf. If an error 1219 occurs while the device is connected to a trusted bootstrap server, 1220 the device MUST try to send a "config-error" progress report before 1221 exiting. 1223 If a post-configuration script has been specified, the device MUST 1224 execute the script, capture any output emitted from the script, and 1225 check if the script had any warnings or errors. If an error occurs 1226 while the device is connected to a trusted bootstrap server, the 1227 device MUST try to send a "post-script-error" progress report before 1228 exiting. 1230 If the onboarding information was obtained from a trusted bootstrap 1231 server, and the result of the bootstrapping process did not disable 1232 the "flag to enable zerotouch bootstrapping" described in 1233 Section 5.1, the device SHOULD send an "bootstrap-warning" progress 1234 report. 1236 If the onboarding information was obtained from a trusted bootstrap 1237 server, the device MUST send a "bootstrap-complete" progress report. 1238 It is an error if the device does not receive back the "204 No 1239 Content" HTTP status line. If an error occurs, the device MUST try 1240 to send a "bootstrap-error" progress report before exiting. 1242 At this point, the device has completely processed the bootstrapping 1243 data. 1245 The device is now running its initial configuration. Notably, if 1246 NETCONF Call Home or RESTCONF Call Home [RFC8071] is configured, the 1247 device initiates trying to establish the call home connections at 1248 this time. 1250 Implementation Notes: 1252 Implementations may vary in how to ensure no unwanted state is 1253 retained when an error occurs. 1255 Following are some guidelines for if the implementation chooses to 1256 undo previous steps: 1258 * When an error occurs, the device must roll out of the current 1259 step and any previous steps. 1261 * Most steps are atomic. For instance, when a commit fails, it 1262 is expected to have no impact on the configuration. Similarly, 1263 if the error occurs when executing a script, the script will 1264 gracefully exit. 1266 * In case the error occurs after the initial configuration was 1267 committed, the device must restore the configuration to the 1268 configuration that existed prior to the configuration being 1269 committed. 1271 * In case the error occurs after a script had executed 1272 successfully, it may be helpful for the implementation to 1273 define scripts as being able to take a conceptual input 1274 parameter indicating that the script should remove its 1275 previously set state. 1277 6. The Zero Touch Information Data Model 1279 This section defines a YANG 1.1 [RFC7950] module that is used to 1280 define the data model for the zero touch information artifact 1281 described in Section 3.1. This data model uses the "yang-data" 1282 extension statement defined in [I-D.ietf-netmod-yang-data-ext]. 1283 Examples illustrating this data model are provided in Section 6.2. 1285 6.1. Data Model Overview 1287 The following tree diagram provides an overview of the data model for 1288 the zero touch information artifact. 1290 module: ietf-zerotouch-information 1292 yang-data zerotouch-information: 1293 +-- (information-type) 1294 +--:(redirect-information) 1295 | +-- redirect-information 1296 | +-- bootstrap-server* [address] 1297 | +-- address inet:host 1298 | +-- port? inet:port-number 1299 | +-- trust-anchor? cms 1300 +--:(onboarding-information) 1301 +-- onboarding-information 1302 +-- boot-image 1303 | +-- os-name? string 1304 | +-- os-version? string 1305 | +-- download-uri* inet:uri 1306 | +-- image-verification* [hash-algorithm] 1307 | +-- hash-algorithm identityref 1308 | +-- hash-value yang:hex-string 1309 +-- configuration-handling? enumeration 1310 +-- pre-configuration-script? script 1311 +-- configuration? binary 1312 +-- post-configuration-script? script 1314 6.2. Example Usage 1316 The following example illustrates how redirect information 1317 (Section 2.1) can be encoded using JSON. 1319 { 1320 "ietf-zerotouch-information:redirect-information" : { 1321 "bootstrap-server" : [ 1322 { 1323 "address" : "phs1.example.com", 1324 "port" : 8443, 1325 "trust-anchor" : "base64encodedvalue==" 1326 }, 1327 { 1328 "address" : "phs2.example.com", 1329 "port" : 8443, 1330 "trust-anchor" : "base64encodedvalue==" 1331 }, 1332 { 1333 "address" : "phs3.example.com", 1334 "port" : 8443, 1335 "trust-anchor" : "base64encodedvalue==" 1336 } 1337 ] 1338 } 1339 } 1341 The following example illustrates how onboarding information 1342 (Section 2.2) can be encoded using JSON. 1344 [Note: '\' line wrapping for formatting only] 1346 { 1347 "ietf-zerotouch-information:onboarding-information" : { 1348 "boot-image" : { 1349 "os-name" : "VendorOS", 1350 "os-version" : "17.2R1.6", 1351 "download-uri" : [ "http://some/path/to/raw/file" ], 1352 "image-verification" : [ 1353 { 1354 "hash-algorithm" : "ietf-zerotouch-information:sha-256", 1355 "hash-value" : "ba:ec:cf:a5:67:82:b4:10:77:c6:67:a6:22:ab:\ 1356 7d:50:04:a7:8b:8f:0e:db:02:8b:f4:75:55:fb:c1:13:b2:33" 1357 } 1358 ] 1359 }, 1360 "configuration-handling" : "merge", 1361 "pre-configuration-script" : "base64encodedvalue==", 1362 "configuration" : "base64encodedvalue==", 1363 "post-configuration-script" : "base64encodedvalue==" 1364 } 1365 } 1367 6.3. YANG Module 1369 The zero touch information data model is defined by the YANG module 1370 presented in this section. 1372 This module uses data types defined in [RFC5280], [RFC5652], 1373 [RFC6234], and [RFC6991], an extension statement from 1374 [I-D.ietf-netmod-yang-data-ext], and an encoding defined in 1375 [ITU.X690.2015]. 1377 file "ietf-zerotouch-information@2018-09-05.yang" 1378 module ietf-zerotouch-information { 1379 yang-version 1.1; 1380 namespace "urn:ietf:params:xml:ns:yang:ietf-zerotouch-information"; 1381 prefix zti; 1383 import ietf-yang-types { 1384 prefix yang; 1385 reference "RFC 6991: Common YANG Data Types"; 1386 } 1387 import ietf-inet-types { 1388 prefix inet; 1389 reference "RFC 6991: Common YANG Data Types"; 1390 } 1391 import ietf-yang-data-ext { 1392 prefix yd; 1393 reference "I-D.ietf-netmod-yang-data-ext: YANG Data Extensions"; 1394 } 1396 organization 1397 "IETF NETCONF (Network Configuration) Working Group"; 1399 contact 1400 "WG Web: http://tools.ietf.org/wg/netconf 1401 WG List: 1402 Author: Kent Watsen "; 1404 description 1405 "This module defines the data model for the Zero Touch 1406 Information artifact defined in RFC XXXX: Zero Touch 1407 Provisioning for Networking Devices. 1409 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1410 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', 1411 and 'OPTIONAL' in the module text are to be interpreted as 1412 described in RFC 2119. 1414 Copyright (c) 2018 IETF Trust and the persons identified as 1415 authors of the code. All rights reserved. 1417 Redistribution and use in source and binary forms, with or 1418 without modification, is permitted pursuant to, and subject 1419 to the license terms contained in, the Simplified BSD License 1420 set forth in Section 4.c of the IETF Trust's Legal Provisions 1421 Relating to IETF Documents (http://trustee.ietf.org/license-info) 1423 This version of this YANG module is part of RFC XXXX; see the 1424 RFC itself for full legal notices."; 1426 revision 2018-09-05 { 1427 description 1428 "Initial version"; 1429 reference 1430 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 1431 } 1433 // identities 1435 identity hash-algorithm { 1436 description 1437 "A base identity for hash algorithm verification"; 1438 } 1440 identity sha-256 { 1441 base "hash-algorithm"; 1442 description "The SHA-256 algorithm."; 1443 reference "RFC 6234: US Secure Hash Algorithms."; 1444 } 1446 // typedefs 1448 typedef cms { 1449 type binary; 1450 description 1451 "A ContentInfo structure, as specified in RFC 5652, 1452 encoded using ASN.1 distinguished encoding rules (DER), 1453 as specified in ITU-T X.690."; 1454 reference 1455 "RFC 5652: 1456 Cryptographic Message Syntax (CMS) 1457 ITU-T X.690: 1458 Information technology - ASN.1 encoding rules: 1459 Specification of Basic Encoding Rules (BER), 1460 Canonical Encoding Rules (CER) and Distinguished 1461 Encoding Rules (DER)."; 1462 } 1463 // yang-data 1465 yd:yang-data "zerotouch-information" { 1466 choice information-type { 1467 mandatory true; 1468 description 1469 "This choice statement ensures the response contains 1470 redirect-information or onboarding-information."; 1471 container redirect-information { 1472 description 1473 "Redirect information is described in Section 2.1 in 1474 RFC XXXX. Its purpose is to redirect a device to 1475 another bootstrap server."; 1476 reference 1477 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 1478 list bootstrap-server { 1479 key "address"; 1480 min-elements 1; 1481 description 1482 "A bootstrap server entry."; 1483 leaf address { 1484 type inet:host; 1485 mandatory true; 1486 description 1487 "The IP address or hostname of the bootstrap server the 1488 device should redirect to."; 1489 } 1490 leaf port { 1491 type inet:port-number; 1492 default "443"; 1493 description 1494 "The port number the bootstrap server listens on. If no 1495 port is specified, the IANA-assigned port for 'https' 1496 (443) is used."; 1497 } 1498 leaf trust-anchor { 1499 type cms; 1500 description 1501 "A CMS structure that MUST contain the chain of 1502 X.509 certificates needed to authenticate the TLS 1503 certificate presented by this bootstrap server. 1505 The CMS MUST only contain a single chain of 1506 certificates. The bootstrap server MUST only 1507 authenticate to last intermediate CA certificate 1508 listed in the chain. 1510 In all cases, the chain MUST include a self-signed 1511 root certificate. In the case where the root 1512 certificate is itself the issuer of the bootstrap 1513 server's TLS certificate, only one certificate 1514 is present. 1516 If needed by the device, this CMS structure MAY 1517 also contain suitably fresh revocation objects 1518 with which the device can verify the revocation 1519 status of the certificates. 1521 This CMS encodes the degenerate form of the SignedData 1522 structure that is commonly used to disseminate X.509 1523 certificates and revocation objects (RFC 5280)."; 1524 reference 1525 "RFC 5280: 1526 Internet X.509 Public Key Infrastructure Certificate 1527 and Certificate Revocation List (CRL) Profile."; 1528 } 1529 } 1530 } 1531 container onboarding-information { 1532 description 1533 "Onboarding information is described in Section 2.2 in 1534 RFC XXXX. Its purpose is to provide the device everything 1535 it needs to bootstrap itself."; 1536 reference 1537 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 1538 container boot-image { 1539 description 1540 "Specifies criteria for the boot image the device MUST 1541 be running, as well as information enabling the device 1542 to install the required boot image."; 1543 leaf os-name { 1544 type string; 1545 description 1546 "The name of the operating system software the device 1547 MUST be running in order to not require a software 1548 image upgrade (ex. VendorOS)."; 1549 } 1550 leaf os-version { 1551 type string; 1552 description 1553 "The version of the operating system software the 1554 device MUST be running in order to not require a 1555 software image upgrade (ex. 17.3R2.1)."; 1556 } 1557 leaf-list download-uri { 1558 type inet:uri; 1559 ordered-by user; 1560 description 1561 "An ordered list of URIs to where the same boot image 1562 file may be obtained. How the URI schemes (http, ftp, 1563 etc.) a device supports are known is vendor specific. 1564 If a secure scheme (e.g., https) is provided, a device 1565 MAY establish an untrusted connection to the remote 1566 server, by blindly accepting the server's end-entity 1567 certificate, to obtain the boot image."; 1568 } 1569 list image-verification { 1570 must '../download-uri' { 1571 description 1572 "Download URIs must be provided if an image is to 1573 be verified."; 1574 } 1575 key hash-algorithm; 1576 description 1577 "A list of hash values that a device can use to verify 1578 boot image files with."; 1579 leaf hash-algorithm { 1580 type identityref { 1581 base "hash-algorithm"; 1582 } 1583 description 1584 "Identifies the hash algorithm used."; 1585 } 1586 leaf hash-value { 1587 type yang:hex-string; 1588 mandatory true; 1589 description 1590 "The hex-encoded value of the specified hash 1591 algorithm over the contents of the boot image 1592 file."; 1593 } 1594 } 1595 } 1596 leaf configuration-handling { 1597 type enumeration { 1598 enum "merge" { 1599 description 1600 "Merge configuration into the running datastore."; 1601 } 1602 enum "replace" { 1603 description 1604 "Replace the existing running datastore with the 1605 passed configuration."; 1606 } 1608 } 1609 must '../configuration'; 1610 description 1611 "This enumeration indicates how the server should process 1612 the provided configuration."; 1613 } 1614 leaf pre-configuration-script { 1615 type script; 1616 description 1617 "A script that, when present, is executed before the 1618 configuration has been processed."; 1619 } 1620 leaf configuration { 1621 type binary; 1622 must '../configuration-handling'; 1623 description 1624 "Any configuration known to the device. The use of 1625 the 'binary' type enables e.g., XML-content to be 1626 embedded into a JSON document. The exact encoding 1627 of the content, as with the scripts, is vendor 1628 specific."; 1629 } 1630 leaf post-configuration-script { 1631 type script; 1632 description 1633 "A script that, when present, is executed after the 1634 configuration has been processed."; 1635 } 1636 } 1637 } 1638 } 1640 typedef script { 1641 type binary; 1642 description 1643 "A device specific script that enables the execution of 1644 commands to perform actions not possible thru configuration 1645 alone. 1647 No attempt is made to standardize the contents, running 1648 context, or programming language of the script, other than 1649 that it can indicate if any warnings or errors occurred and 1650 can emit output. The contents of the script are considered 1651 specific to the vendor, product line, and/or model of the 1652 device. 1654 If the script execution indicates that an warning occurred, 1655 then the device MUST assume that the script had a soft error 1656 that the script believes will not affect manageability. 1658 If the script execution indicates that an error occurred, 1659 the device MUST assume the script had a hard error that the 1660 script believes will affect manageability. In this case, 1661 the script is required to gracefully exit, removing any 1662 state that might hinder the device's ability to continue 1663 the bootstrapping sequence (e.g., process onboarding 1664 information obtained from another bootstrap server)."; 1665 } 1666 } 1667 1669 7. The Zero Touch Bootstrap Server API 1671 This section defines the API for bootstrap servers. The API is 1672 defined as that produced by a RESTCONF [RFC8040] server that supports 1673 the YANG 1.1 [RFC7950] module defined in this section. 1675 7.1. API Overview 1677 The following tree diagram provides an overview for the bootstrap 1678 server RESTCONF API. 1680 module: ietf-zerotouch-bootstrap-server 1682 rpcs: 1683 +---x get-bootstrapping-data 1684 | +---w input 1685 | | +---w untrusted-connection? empty 1686 | | +---w hw-model? string 1687 | | +---w os-name? string 1688 | | +---w os-version? string 1689 | | +---w nonce? binary 1690 | +--ro output 1691 | +--ro reporting-level? enumeration 1692 | +--ro zerotouch-information cms 1693 | +--ro owner-certificate? cms 1694 | +--ro ownership-voucher? cms 1695 +---x report-progress 1696 +---w input 1697 +---w progress-type enumeration 1698 +---w message? string 1699 +---w ssh-host-keys 1700 | +---w ssh-host-key* binary 1701 +---w trust-anchor-certs 1702 +---w trust-anchor-cert* cms 1704 7.2. Example Usage 1706 This section presents three examples illustrating the bootstrap 1707 server's API. Two examples are provided for the "get-bootstrapping- 1708 data" RPC (once to an untrusted bootstrap server, and again to a 1709 trusted bootstrap server), and one example for the "report-progress" 1710 RPC. 1712 The following example illustrates a device using the API to fetch its 1713 bootstrapping data from a untrusted bootstrap server. In this 1714 example, the device sends the "untrusted-connection" input parameter 1715 and receives signed data in the response. 1717 REQUEST 1718 ------- 1719 ['\' line wrapping added for formatting only] 1721 POST /restconf/operations/ietf-zerotouch-bootstrap-server:get-boot\ 1722 strapping-data HTTP/1.1 1723 HOST: example.com 1724 Content-Type: application/yang.data+xml 1726 1728 1729 1731 RESPONSE 1732 -------- 1734 HTTP/1.1 200 OK 1735 Date: Sat, 31 Oct 2015 17:02:40 GMT 1736 Server: example-server 1737 Content-Type: application/yang.data+xml 1739 1741 base64encodedvalue== 1742 base64encodedvalue== 1743 base64encodedvalue== 1744 1746 The following example illustrates a device using the API to fetch its 1747 bootstrapping data from a trusted bootstrap server. In this example, 1748 the device sends addition input parameters to the bootstrap server, 1749 which it may use when formulating its response to the device. 1751 REQUEST 1752 ------- 1753 ['\' line wrapping added for formatting only] 1755 POST /restconf/operations/ietf-zerotouch-bootstrap-server:get-boot\ 1756 strapping-data HTTP/1.1 1757 HOST: example.com 1758 Content-Type: application/yang.data+xml 1760 1762 model-x 1763 vendor-os 1764 17.3R2.1 1765 base64encodedvalue== 1766 1768 RESPONSE 1769 -------- 1771 HTTP/1.1 200 OK 1772 Date: Sat, 31 Oct 2015 17:02:40 GMT 1773 Server: example-server 1774 Content-Type: application/yang.data+xml 1776 1778 verbose 1779 base64encodedvalue== 1780 1782 The following example illustrates a device using the API to post a 1783 progress report to a bootstrap server. Illustrated below is the 1784 "bootstrap-complete" message, but the device may send other progress 1785 reports to the server while bootstrapping. In this example, the 1786 device is sending both its SSH host keys and a TLS server 1787 certificate, which the bootstrap server may, for example, pass to an 1788 NMS, as discussed in Appendix C.3. 1790 REQUEST 1791 ------- 1792 ['\' line wrapping added for formatting only] 1794 POST /restconf/operations/ietf-zerotouch-bootstrap-server:report-\ 1795 progress HTTP/1.1 1796 HOST: example.com 1797 Content-Type: application/yang.data+xml 1799 1801 bootstrap-complete 1802 example message 1803 1804 base64encodedvalue== 1805 base64encodedvalue2= 1806 1807 1808 base64encodedvalue== 1809 1810 1812 RESPONSE 1813 -------- 1815 HTTP/1.1 204 No Content 1816 Date: Sat, 31 Oct 2015 17:02:40 GMT 1817 Server: example-server 1819 7.3. YANG Module 1821 The bootstrap server's device-facing API is normatively defined by 1822 the YANG module defined in this section. 1824 This module uses data types defined in [RFC4253], [RFC5652], 1825 [RFC5280], [RFC6960], and [RFC8366], and uses an encoding defined in 1826 [ITU.X690.2015]. 1828 file "ietf-zerotouch-bootstrap-server@2018-09-05.yang" 1829 module ietf-zerotouch-bootstrap-server { 1830 yang-version 1.1; 1831 namespace 1832 "urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server"; 1833 prefix ztbs; 1835 organization 1836 "IETF NETCONF (Network Configuration) Working Group"; 1838 contact 1839 "WG Web: 1840 WG List: 1841 Author: Kent Watsen "; 1843 description 1844 "This module defines an interface for bootstrap servers, as 1845 defined by RFC XXXX: Zero Touch Provisioning for Networking 1846 Devices. 1848 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1849 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', 1850 and 'OPTIONAL' in the module text are to be interpreted as 1851 described in RFC 2119. 1853 Copyright (c) 2018 IETF Trust and the persons identified as 1854 authors of the code. All rights reserved. 1856 Redistribution and use in source and binary forms, with or 1857 without modification, is permitted pursuant to, and subject 1858 to the license terms contained in, the Simplified BSD License 1859 set forth in Section 4.c of the IETF Trust's Legal Provisions 1860 Relating to IETF Documents (http://trustee.ietf.org/license-info) 1862 This version of this YANG module is part of RFC XXXX; see the 1863 RFC itself for full legal notices."; 1865 revision 2018-09-05 { 1866 description 1867 "Initial version"; 1868 reference 1869 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 1870 } 1872 // typedefs 1874 typedef cms { 1875 type binary; 1876 description 1877 "A CMS structure, as specified in RFC 5652, encoded using 1878 ASN.1 distinguished encoding rules (DER), as specified in 1879 ITU-T X.690."; 1880 reference 1881 "RFC 5652: 1882 Cryptographic Message Syntax (CMS) 1883 ITU-T X.690: 1884 Information technology - ASN.1 encoding rules: 1885 Specification of Basic Encoding Rules (BER), 1886 Canonical Encoding Rules (CER) and Distinguished 1887 Encoding Rules (DER)."; 1888 } 1890 // RPCs 1892 rpc get-bootstrapping-data { 1893 description 1894 "This RPC enables a device, as identified by the RESTCONF 1895 username, to obtain bootstrapping data that has been made 1896 available for it."; 1897 input { 1898 leaf untrusted-connection { 1899 type empty; 1900 description 1901 "This optional input parameter enables a device to 1902 communicate to the bootstrap server that it is unable to 1903 authenticate the bootstrap server's TLS certificate. In 1904 such circumstances, the device likely does not send any 1905 of the other input parameters, except for the 'nonce' 1906 parameter. Upon receiving this input parameter, the 1907 bootstrap server should only return unsigned redirect 1908 information or signed data of any type."; 1909 } 1910 leaf hw-model { 1911 type string; 1912 description 1913 "This optional input parameter enables a device to 1914 communicate to the bootstrap server its vendor specific 1915 hardware model number. This parameter may be needed, 1916 for instance, when a device's IDevID certificate does 1917 not include the 'hardwareModelName' value in its 1918 subjectAltName field, as is allowed by 802.1AR-2009."; 1919 reference 1920 "IEEE 802.1AR-2009: IEEE Standard for Local and 1921 metropolitan area networks - Secure Device Identity"; 1922 } 1923 leaf os-name { 1924 type string; 1925 description 1926 "This optional input parameter enables a device to 1927 communicate to the bootstrap server the name of its 1928 operating system. This parameter may be useful if 1929 the device, as identified by its serial number, can 1930 run more than one type of operating system (e.g., 1931 on a white-box system."; 1932 } 1933 leaf os-version { 1934 type string; 1935 description 1936 "This optional input parameter enables a device to 1937 communicate to the bootstrap server the version of its 1938 operating system. This parameter may be used by a 1939 bootstrap server to return an operating system specific 1940 response to the device, thus negating the need for a 1941 potentially expensive boot-image update."; 1942 } 1943 leaf nonce { 1944 type binary { 1945 length "8..32"; 1946 } 1947 description 1948 "This optional input parameter enables a device to 1949 communicate to the bootstrap server a nonce value. 1950 This may be especially useful for devices lacking 1951 an accurate clock, as then the bootstrap server 1952 can dynamically obtain from the manufacturer a 1953 voucher with the nonce value in it, as described 1954 in RFC 8366."; 1955 reference 1956 "RFC 8366: 1957 A Voucher Artifact for Bootstrapping Protocols"; 1958 } 1959 } 1960 output { 1961 leaf reporting-level { 1962 type enumeration { 1963 enum standard { 1964 description 1965 "Send just the progress reports required by RFC XXXX."; 1966 } 1967 enum verbose { 1968 description 1969 "Send additional progress reports that might help 1970 troubleshooting an SZTP bootstrapping issue."; 1971 } 1972 } 1973 default standard; 1974 description 1975 "Specifies the reporting level for progress reports the 1976 bootstrap server would like to receive when processing 1977 onboarding information. Progress reports are not sent 1978 when processing redirect information, or when the 1979 bootstrap server is untrusted (e.g., device sent the 1980 '' input parameter)."; 1981 } 1982 leaf zerotouch-information { 1983 type cms; 1984 mandatory true; 1985 description 1986 "A zero touch information artifact, as described in 1987 Section 3.1 of RFC XXXX."; 1988 reference 1989 "RFC XXXX: 1990 Zero Touch Provisioning for Networking Devices"; 1991 } 1992 leaf owner-certificate { 1993 type cms; 1994 must '../ownership-voucher' { 1995 description 1996 "An ownership voucher must be present whenever an owner 1997 certificate is presented."; 1998 } 1999 description 2000 "An owner certificate artifact, as described in Section 2001 3.2 of RFC XXXX. This leaf is optional because it is 2002 only needed when the zero touch information artifact 2003 is signed."; 2004 reference 2005 "RFC XXXX: 2006 Zero Touch Provisioning for Networking Devices"; 2007 } 2008 leaf ownership-voucher { 2009 type cms; 2010 must '../owner-certificate' { 2011 description 2012 "An owner certificate must be present whenever an 2013 ownership voucher is presented."; 2014 } 2015 description 2016 "An ownership voucher artifact, as described by Section 2017 3.3 of RFC XXXX. This leaf is optional because it is 2018 only needed when the zero touch information artifact 2019 is signed."; 2020 reference 2021 "RFC XXXX: 2022 Zero Touch Provisioning for Networking Devices"; 2023 } 2024 } 2025 } 2027 rpc report-progress { 2028 description 2029 "This RPC enables a device, as identified by the RESTCONF 2030 username, to report its bootstrapping progress to the 2031 bootstrap server. This RPC is expected to be used when 2032 the device obtains onboarding-information from a trusted 2033 bootstap server."; 2034 input { 2035 leaf progress-type { 2036 type enumeration { 2037 enum "bootstrap-initiated" { 2038 description 2039 "Indicates that the device just used the 2040 'get-bootstrapping-data' RPC. The 'message' node 2041 below MAY contain any additional information that 2042 the manufacturer thinks might be useful."; 2043 } 2044 enum "parsing-initiated" { 2045 description 2046 "Indicates that the device is about to start parsing 2047 the onboarding information. This progress type is 2048 only for when parsing is implemented as a distinct 2049 step."; 2050 } 2051 enum "parsing-warning" { 2052 description 2053 "Indicates that the device had a non-fatal error when 2054 parsing the response from the bootstrap server. The 2055 'message' node below SHOULD indicate the specific 2056 warning that occurred."; 2057 } 2058 enum "parsing-error" { 2059 description 2060 "Indicates that the device encountered a fatal error 2061 when parsing the response from the bootstrap server. 2062 For instance, this could be due to malformed encoding, 2063 the device expecting signed data when only unsigned 2064 data is provided, the ownership voucher not listing 2065 the device's serial number, or because the signature 2066 didn't match. The 'message' node below SHOULD 2067 indicate the specific error. This progress type 2068 also indicates that the device has abandoned trying 2069 to bootstrap off this bootstrap server."; 2070 } 2071 enum "parsing-complete" { 2072 description 2073 "Indicates that the device successfully completed 2074 parsing the onboarding information. This progress 2075 type is only for when parsing is implemented as a 2076 distinct step."; 2077 } 2078 enum "boot-image-initiated" { 2079 description 2080 "Indicates that the device is about to start 2081 processing the boot-image information."; 2082 } 2083 enum "boot-image-warning" { 2084 description 2085 "Indicates that the device encountered a non-fatal 2086 error condition when trying to install a boot-image. 2087 A possible reason might include a need to reformat a 2088 partition causing loss of data. The 'message' node 2089 below SHOULD indicate any warning messages that were 2090 generated."; 2091 } 2092 enum "boot-image-error" { 2093 description 2094 "Indicates that the device encountered an error when 2095 trying to install a boot-image, which could be for 2096 reasons such as a file server being unreachable, 2097 file not found, signature mismatch, etc. The 2098 'message' node SHOULD indicate the specific error 2099 that occurred. This progress type also indicates 2100 that the device has abandoned trying to bootstrap 2101 off this bootstrap server."; 2102 } 2103 enum "boot-image-mismatch" { 2104 description 2105 "Indicates that the device that has determined that 2106 it is not running the correct boot image. This 2107 message SHOULD precipitate trying to download 2108 a boot image."; 2109 } 2110 enum "boot-image-installed-rebooting" { 2111 description 2112 "Indicates that the device successfully installed 2113 a new boot image and is about to reboot. After 2114 sending this progress type, the device is not 2115 expected to access the bootstrap server again."; 2116 } 2117 enum "boot-image-complete" { 2118 description 2119 "Indicates that the device believes that it is 2120 running the correct boot-image."; 2121 } 2122 enum "pre-script-initiated" { 2123 description 2124 "Indicates that the device is about to execute the 2125 'pre-configuration-script'."; 2127 } 2128 enum "pre-script-warning" { 2129 description 2130 "Indicates that the device obtained a warning from the 2131 'pre-configuration-script' when it was executed. The 2132 'message' node below SHOULD capture any output the 2133 script produces."; 2134 } 2135 enum "pre-script-error" { 2136 description 2137 "Indicates that the device obtained an error from the 2138 'pre-configuration-script' when it was executed. The 2139 'message' node below SHOULD capture any output the 2140 script produces. This progress type also indicates 2141 that the device has abandoned trying to bootstrap 2142 off this bootstrap server."; 2143 } 2144 enum "pre-script-complete" { 2145 description 2146 "Indicates that the device successfully executed the 2147 'pre-configuration-script'."; 2148 } 2149 enum "config-initiated" { 2150 description 2151 "Indicates that the device is about to commit the 2152 initial configuration."; 2153 } 2154 enum "config-warning" { 2155 description 2156 "Indicates that the device obtained warning messages 2157 when it committed the initial configuration. The 2158 'message' node below SHOULD indicate any warning 2159 messages that were generated."; 2160 } 2161 enum "config-error" { 2162 description 2163 "Indicates that the device obtained error messages 2164 when it committed the initial configuration. The 2165 'message' node below SHOULD indicate the error 2166 messages that were generated. This progress type 2167 also indicates that the device has abandoned trying 2168 to bootstrap off this bootstrap server."; 2169 } 2170 enum "config-complete" { 2171 description 2172 "Indicates that the device successfully committed 2173 the initial configuration."; 2174 } 2175 enum "post-script-initiated" { 2176 description 2177 "Indicates that the device is about to execute the 2178 'post-configuration-script'."; 2179 } 2180 enum "post-script-warning" { 2181 description 2182 "Indicates that the device obtained a warning from the 2183 'post-configuration-script' when it was executed. The 2184 'message' node below SHOULD capture any output the 2185 script produces."; 2186 } 2187 enum "post-script-error" { 2188 description 2189 "Indicates that the device obtained an error from the 2190 'post-configuration-script' when it was executed. The 2191 'message' node below SHOULD capture any output the 2192 script produces. This progress type also indicates 2193 that the device has abandoned trying to bootstrap 2194 off this bootstrap server."; 2195 } 2196 enum "post-script-complete" { 2197 description 2198 "Indicates that the device successfully executed the 2199 'post-configuration-script'."; 2200 } 2201 enum "bootstrap-warning" { 2202 description 2203 "Indicates that a warning condition occurred for which 2204 there no other 'progress-type' enumeration is deemed 2205 suitable. The 'message' node below SHOULD describe 2206 the warning."; 2207 } 2208 enum "bootstrap-error" { 2209 description 2210 "Indicates that an error condition occurred for which 2211 there no other 'progress-type' enumeration is deemed 2212 suitable. The 'message' node below SHOULD describe 2213 the error. This progress type also indicates that 2214 the device has abandoned trying to bootstrap off 2215 this bootstrap server."; 2216 } 2217 enum "bootstrap-complete" { 2218 description 2219 "Indicates that the device successfully processed 2220 all 'onboarding-information' provided, and that it 2221 is ready to be managed. The 'message' node below 2222 MAY contain any additional information that the 2223 manufacturer thinks might be useful. After sending 2224 this progress type, the device is not expected to 2225 access the bootstrap server again."; 2226 } 2227 enum "informational" { 2228 description 2229 "Indicates any additional information not captured 2230 by any of the other progress types. For instance, 2231 a message indicating that the device is about to 2232 reboot after having installed a boot-image could 2233 be provided. The 'message' node below SHOULD 2234 contain information that the manufacturer thinks 2235 might be useful."; 2236 } 2237 } 2238 mandatory true; 2239 description 2240 "The type of progress report provided."; 2241 } 2242 leaf message { 2243 type string; 2244 description 2245 "An optional arbitrary value."; 2246 } 2247 container ssh-host-keys { 2248 when "../progress-type = 'bootstrap-complete'" { 2249 description 2250 "SSH host keys are only sent when the progress type 2251 is 'bootstrap-complete'."; 2252 } 2253 description 2254 "A list of trust anchor certificates an NMS may use to 2255 authenticate subsequent SSH-based connections to this 2256 device (e.g., netconf-ssh, netconf-ch-ssh)."; 2257 leaf-list ssh-host-key { 2258 type binary; 2259 description 2260 "The binary public key data for this SSH key, as 2261 specified by RFC 4253, Section 6.6, i.e.: 2263 string certificate or public key format 2264 identifier 2265 byte[n] key/certificate data."; 2266 reference 2267 "RFC 4253: The Secure Shell (SSH) Transport Layer 2268 Protocol"; 2269 } 2270 } 2271 container trust-anchor-certs { 2272 when "../progress-type = 'bootstrap-complete'" { 2273 description 2274 "Trust anchors are only sent when the progress type 2275 is 'bootstrap-complete'."; 2276 } 2277 description 2278 "A list of trust anchor certificates an NMS may use to 2279 authenticate subsequent certificate-based connections 2280 to this device (e.g., restconf-tls, netconf-tls, or 2281 even netconf-ssh with X.509 support from RFC 6187). 2282 In practice, trust anchors for IDevID certificates do 2283 not need to be conveyed using this mechanism."; 2284 reference 2285 "RFC 6187: 2286 X.509v3 Certificates for Secure Shell Authentication."; 2287 leaf-list trust-anchor-cert { 2288 type cms; 2289 description 2290 "A CMS structure whose top-most content type MUST be the 2291 signed-data content type, as described by Section 5 in 2292 RFC 5652. 2294 The CMS MUST contain the chain of X.509 certificates 2295 needed to authenticate the certificate presented by 2296 the device. 2298 The CMS MUST contain only a single chain of 2299 certificates. The device's end-entity certificate 2300 MUST only authenticate to last intermediate CA 2301 certificate listed in the chain. 2303 In all cases, the chain MUST include a self-signed 2304 root certificate. In the case where the root 2305 certificate is itself the issuer of the device's 2306 end-entity certificate, only one certificate is 2307 present. 2309 This CMS encodes the degenerate form of the SignedData 2310 structure that is commonly used to disseminate X.509 2311 certificates and revocation objects (RFC 5280)."; 2312 reference 2313 "RFC 5280: 2314 Internet X.509 Public Key Infrastructure 2315 Certificate and Certificate Revocation List (CRL) 2316 Profile. 2317 RFC 5652: 2318 Cryptographic Message Syntax (CMS)"; 2320 } 2321 } 2322 } 2323 } 2324 } 2325 2327 8. DHCP Zero Touch Options 2329 This section defines two DHCP options, one for DHCPv4 and one for 2330 DHCPv6. These two options are semantically the same, though 2331 syntactically different. 2333 8.1. DHCPv4 Zero Touch Option 2335 The DHCPv4 Zero Touch Option is used to provision the client with one 2336 or more URIs for bootstrap servers that can be contacted to attempt 2337 further configuration. 2339 DHCPv4 Zero Touch Redirect Option 2341 0 1 2342 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 2343 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2344 | option-code (143) | option-length | 2345 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2346 . . 2347 . bootstrap-server-list (variable length) . 2348 . . 2349 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2351 o option-code: OPTION_V4_ZEROTOUCH_REDIRECT (143) 2352 o option-length: The option length in octets 2353 o bootstrap-server-list: A list of servers for the 2354 client to attempt contacting, in order to obtain 2355 further bootstrapping data, in the format shown 2356 in [common-field-encoding]. 2358 DHCPv4 Client Behavior 2360 Clients MAY request the OPTION_V4_ZEROTOUCH_REDIRECT by including its 2361 option code in the Parameter Request List (55) in DHCP request 2362 messages. 2364 On receipt of a DHCPv4 Reply message which contains the 2365 OPTION_V4_ZEROTOUCH_REDIRECT, the client processes the response 2366 according to Section 5.5, with the understanding that the "address" 2367 and "port" values are encoded in the URIs. 2369 Any invalid URI entries received in the uri-data field are ignored by 2370 the client. If OPTION_V4_ZEROTOUCH_REDIRECT does not contain at 2371 least one valid URI entry in the uri-data field, then the client MUST 2372 discard the option. 2374 As the list of URIs may exceed the maximum allowed length of a single 2375 DHCPv4 option (255 octets), the client MUST implement [RFC3396], 2376 allowing the URI list to be split across a number of 2377 OPTION_V4_ZEROTOUCH_REDIRECT option instances. 2379 DHCPv4 Server Behavior 2381 The DHCPv4 server MAY include a single instance of Option 2382 OPTION_V4_ZEROTOUCH_REDIRECT in DHCP messages it sends. Servers MUST 2383 NOT send more than one instance of the OPTION_V4_ZEROTOUCH_REDIRECT 2384 option. 2386 As the list of URIs may exceed the maximum allowed length of a single 2387 DHCPv4 option (255 octets), the server MUST implement [RFC3396], 2388 allowing the URI list to be split across a number of 2389 OPTION_V4_ZEROTOUCH_REDIRECT option instances. 2391 8.2. DHCPv6 Zero Touch Option 2393 The DHCPv6 Zero Touch Option is used to provision the client with one 2394 or more URIs for bootstrap servers that can be contacted to attempt 2395 further configuration. 2397 DHCPv6 Zero Touch Redirect Option 2399 0 1 2 3 2400 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 2401 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2402 | option-code (136) | option-length | 2403 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2404 . bootstrap-server-list (variable length) . 2405 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2407 o option-code: OPTION_V6_ZEROTOUCH_REDIRECT (136) 2408 o option-length: The option length in octets 2409 o bootstrap-server-list: A list of servers for the client to 2410 attempt contacting, in order to obtain further bootstrapping 2411 data, in the format shown in [common-field-encoding]. 2413 DHCPv6 Client Behavior 2415 Clients MAY request the OPTION_V6_ZEROTOUCH_REDIRECT option, as 2416 defined in [RFC3315], Sections 17.1.1, 18.1.1, 18.1.3, 18.1.4, 2417 18.1.5, and 22.7. As a convenience to the reader, we mention here 2418 that the client includes requested option codes in the Option Request 2419 Option. 2421 On receipt of a DHCPv6 Reply message which contains the 2422 OPTION_V6_ZEROTOUCH_REDIRECT, the client processes the response 2423 according to Section 5.5, with the understanding that the "address" 2424 and "port" values are encoded in the URIs. 2426 Any invalid URI entries received in the uri-data field are ignored by 2427 the client. If OPTION_V6_ZEROTOUCH_REDIRECT does not contain at 2428 least one valid URI entry in the uri-data field, then the client MUST 2429 discard the option. 2431 DHCPv6 Server Behavior 2433 Sections 17.2.2 and 18.2 of [RFC3315] govern server operation 2434 in regard to option assignment. As a convenience to the reader, 2435 we mention here that the server will send a particular option code 2436 only if configured with specific values for that option code and if 2437 the client requested it. 2439 Option OPTION_V6_ZEROTOUCH_REDIRECT is a singleton. Servers MUST NOT 2440 send more than one instance of the OPTION_V6_ZEROTOUCH_REDIRECT 2441 option. 2443 8.3. Common Field Encoding 2445 Both of the DHCPv4 and DHCPv6 options defined in this section encode 2446 a list of bootstrap server URIs. The "URI" structure is an option 2447 that can contain multiple URIs (see [RFC7227], Section 5.7). 2449 bootstrap-server-list: 2451 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 2452 | uri-length | URI | 2453 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 2455 o uri-length: variable, in octets. 2457 o URI: URI of zerotouch bootstrap server, using the HTTPS URI 2458 scheme defined in Section 2.7.2 of RFC7230. URI MUST be in 2459 form "https://[:]". 2461 9. Security Considerations 2463 9.1. Clock Sensitivity 2465 The solution in this document relies on TLS certificates, owner 2466 certificates, and ownership vouchers, all of which require an 2467 accurate clock in order to be processed correctly (e.g., to test 2468 validity dates and revocation status). Implementations SHOULD ensure 2469 devices have an accurate clock when shipped from manufacturing 2470 facilities, and take steps to prevent clock tampering. 2472 If it is not possible to ensure clock accuracy, it is RECOMMENDED 2473 that implementations disable the aspects of the solution having clock 2474 sensitivity. In particular, such implementations should assume that 2475 TLS certificates, ownership vouchers, and owner certificates never 2476 expire and are not revokable. From an ownership voucher perspective, 2477 manufacturers SHOULD issue a single ownership voucher for the 2478 lifetime of such devices. 2480 Implementations SHOULD NOT rely on NTP for time, as NTP is not a 2481 secure protocol. 2483 9.2. Use of IDevID Certificates 2485 IDevID certificates, as defined in [Std-802.1AR-2009], are 2486 RECOMMENDED, both for the TLS-level client certificate used by 2487 devices when connecting to a bootstrap server, as well as for the 2488 device identity certificate used by owners when encrypting the zero 2489 touch artifacts. 2491 9.3. Immutable Storage for Trust Anchors 2493 Devices MUST ensure that all their trust anchor certificates, 2494 including those for connecting to bootstrap servers and verifying 2495 ownership vouchers, are protected from external modification. 2497 It may be necessary to update these certificates over time (e.g., the 2498 manufacturer wants to delegate trust to a new CA). It is therefore 2499 expected that devices MAY update these trust anchors when needed 2500 through a verifiable process, such as a software upgrade using signed 2501 software images. 2503 9.4. Secure Storage for Long-lived Private Keys 2505 Manufacturer-generated device identifiers may have very long 2506 lifetimes. For instance, [Std-802.1AR-2009] recommends using the 2507 "notAfter" value 99991231235959Z in IDevID certificates. Given the 2508 long-lived nature of these private keys, it is paramount that they 2509 are stored so as to resist discovery, such as in a secure 2510 cryptographic processor (e.g., a TPM). 2512 9.5. Blindly Authenticating a Bootstrap Server 2514 This document allows a device to blindly authenticate a bootstrap 2515 server's TLS certificate. It does so to allow for cases where the 2516 redirect information may be obtained in an unsecured manner, which is 2517 desirable to support in some cases. 2519 To compensate for this, this document requires that devices, when 2520 connected to an untrusted bootstrap server, assert that data 2521 downloaded from the server is signed. 2523 9.6. Disclosing Information to Untrusted Servers 2525 This document allows devices to establish connections to untrusted 2526 bootstrap servers. However, since the bootstrap server is untrusted, 2527 it may be under the control of an adversary, and therefore devices 2528 SHOULD be cautious about the data they send to the bootstrap server 2529 in such cases. 2531 Devices send different data to bootstrap servers at each of the 2532 protocol layers TCP, TLS, HTTP, and RESTCONF. 2534 At the TCP protocol layer, devices may relay their IP address, 2535 subject to network translations. Disclosure of this information is 2536 not considered a security risk. 2538 At the TLS protocol layer, devices may use a client certificate to 2539 identify and authenticate themselves to untrusted bootstrap servers. 2540 At a minimum, the client certificate must disclose the device's 2541 serial number, and may disclose additional information such as the 2542 device's manufacturer, hardware model, public key, etc. Knowledge of 2543 this information may provide an adversary with details needed to 2544 launch an attack. It is RECOMMENDED that secrecy of the network 2545 constituency is not relied on for security. 2547 At the HTTP protocol layer, devices may use an HTTP authentication 2548 scheme to identify and authenticate themselves to untrusted bootstrap 2549 servers. At a minimum, the authentication scheme must disclose the 2550 device's serial number and, concerningly, may, depending on the 2551 authentication mechanism used, reveal a secret that is only supposed 2552 to be known to the device (e.g., a password). Devices SHOULD NOT use 2553 an HTTP authentication scheme (e.g., HTTP Basic) with an untrusted 2554 bootstrap server that reveals a secret that is only supposed to be 2555 known to the device. 2557 At the RESTCONF protocol layer, devices use the "get-bootstrapping- 2558 data" RPC, but not the "report-progress" RPC, when connected to an 2559 untrusted bootstrap server. The "get-bootstrapping-data" RPC allows 2560 additional input parameters to be passed to the bootstrap server 2561 (e.g., "os-name", "os-version", "hw-model"). It is RECOMMENDED that 2562 devices only pass the "untrusted-connection" input parameter to an 2563 untrusted bootstrap server. While it is okay for a bootstrap server 2564 to immediately return signed onboarding information, it is 2565 RECOMMENDED that bootstrap servers instead promote the untrusted 2566 connection to a trusted connection, as described in Appendix B, thus 2567 enabling the device to use the "report-progress" RPC while processing 2568 the onboarding information. 2570 9.7. Sequencing Sources of Bootstrapping Data 2572 For devices supporting more than one source for bootstrapping data, 2573 no particular sequencing order has to be observed for security 2574 reasons, as the solution for each source is considered equally 2575 secure. However, from a privacy perspective, it is RECOMMENDED that 2576 devices access local sources before accessing remote sources. 2578 9.8. Safety of Private Keys used for Trust 2580 The solution presented in this document enables bootstrapping data to 2581 be trusted in two ways, either through transport level security or 2582 through the signing of artifacts. 2584 When transport level security (i.e., a trusted bootstrap server) is 2585 used, the private key for the end-entity certificate must be online 2586 in order to establish the TLS connection. 2588 When artifacts are signed, the signing key is required to be online 2589 only when the bootstrap server is returning a dynamically generated 2590 signed-data response. For instance, a bootstrap server, upon 2591 receiving the "untrusted-connection" input parameter to the "get- 2592 bootstrapping-data" RPC, may dynamically generate a response that is 2593 signed. 2595 Bootstrap server administrators are RECOMMENDED to follow best 2596 practice to protect the private key used for any online operation. 2597 Use of an hardware security module (HSM) is RECOMMENDED. If an HSM 2598 is not used, frequent private key refreshes are RECOMMENDED. 2600 For best security, it is RECOMMENDED that owners only provide 2601 bootstrapping data that has been signed, using a private key that is 2602 not accessible to a network of questionable integrity, and encrypted, 2603 using the device's public key from its secure device identity 2604 certificate. 2606 9.9. Infinite Redirection Loops and Sequences 2608 The recursive algorithm described in this document enables redirect 2609 information to lead to more redirect information, which may cause a 2610 device to redirect forever. 2612 Whilst a trusted bootstrap server may be misconfigured to cause a 2613 device to return to it again ad infitum, the greater concern is that 2614 any untrusted source of bootstrapping data could be used by an 2615 adversary to purposely cause this. 2617 Infinite redirections are most easily constructed via loops, where 2618 some bootstrap server redirects back to a previously visited 2619 bootstrap server. Infinite redirections can also be created without 2620 a loop by an adversary dynamically instantiated bootstrap servers on 2621 the fly. 2623 Implementations SHOULD limit the maximum number of recursive 2624 redirects allowed; no more than a half dozen seems reasonable. 2626 9.10. Increased Reliance on Manufacturers 2628 The zero touch bootstrapping protocol presented in this document 2629 shifts some control of initial configuration away from the rightful 2630 owner of the device and towards the manufacturer and its delegates. 2632 The manufacturer maintains the list of well-known bootstrap servers 2633 its devices will trust. By design, if no bootstrapping data is found 2634 via other methods first, the device will try to reach out to the 2635 well-known bootstrap servers. There is no mechanism to prevent this 2636 from occurring other than by using an external firewall to block such 2637 connections. Concerns related to trusted bootstrap servers are 2638 discussed in Section 9.11. 2640 Similarly, the manufacturer maintains the list of voucher signing 2641 authorities its devices will trust. The voucher signing authorities 2642 issue the vouchers that enable a device to trust an owner's domain 2643 certificate. It is vital that manufacturers ensure the integrity of 2644 these voucher signing authorities, so as to avoid incorrect 2645 assignments. 2647 Operators should be aware that this system assumes that they trust 2648 all the pre-configured bootstrap servers and voucher signing 2649 authorities designated by the manufacturers. 2651 9.11. Concerns with Trusted Bootstrap Servers 2653 Trusted bootstrap servers, whether well-known or discovered, have the 2654 potential to cause problems, such as the following. 2656 o A trusted bootstrap server that has been compromised may be 2657 modified to return unsigned data of any sort. For instance, a 2658 bootstrap server that is only suppose to return redirect 2659 information might be modified to return onboarding information. 2660 Similarly, a bootstrap server that is only supposed to return 2661 signed data, may be modified to return unsigned data. In both 2662 cases, the device will accept the response, unaware that it wasn't 2663 supposed to be any different. It is RECOMMENDED that maintainers 2664 of trusted bootstrap servers ensure that their systems are not 2665 easily compromised and, in case of compromise, have mechanisms in 2666 place to detect and remediate the compromise as expediently as 2667 possible. 2669 o A trusted bootstrap server hosting either unsigned or signed but 2670 not encrypted data may disclose information to unwanted parties 2671 (e.g., an administrator of the bootstrap server). This is a 2672 privacy issue only, but could reveal information that might be 2673 used in a subsequent attack. Disclosure of redirect information 2674 has limited exposure (it is just a list of bootstrap servers), 2675 whereas disclosure of onboarding information could be highly 2676 revealing (e.g., network topology, firewall policies, etc.). It 2677 is RECOMMENDED that operators encrypt the bootstrapping data when 2678 its contents are considered sensitive, even to the administrators 2679 of a bootstrap server. 2681 9.12. Validity Period for Zero Touch Information 2683 Zero touch information does not specify a validity period. For 2684 instance, neither redirect information nor onboarding information 2685 enable "not-before" or "not-after" values to be specified, and 2686 neither artifact alone can be revoked. 2688 For unsigned data provided by an untrusted source of bootstrapping 2689 data, it is not meaningful to discuss its validity period when the 2690 information itself has no authenticity and may have come from 2691 anywhere. 2693 For unsigned data provided by a trusted source of bootstrapping data 2694 (i.e., a bootstrap server), the availability of the data is the only 2695 measure of it being current. Since the untrusted data comes from a 2696 trusted source, its current availability is meaningful and, since 2697 bootstrap servers use TLS, the contents of the exchange cannot be 2698 modified or replayed. 2700 For signed data, whether provided by an untrusted or trusted source 2701 of bootstrapping data, the validity is constrained by the validity of 2702 the both the ownership voucher and owner certificate used to 2703 authenticate it. 2705 The ownership voucher's validity is primarily constrained by the 2706 ownership voucher's "created-on" and "expires-on" nodes. While 2707 [RFC8366] recommends short-lived vouchers (see Section 6.1), the 2708 "expires-on" node may be set to any point in the future, or omitted 2709 altogether to indicate that the voucher never expires. The ownership 2710 voucher's validity is secondarily constrained by the manufacturer's 2711 PKI used to sign the voucher; whilst an ownership voucher cannot be 2712 revoked directly, the PKI used to sign it may be. 2714 The owner certificate's validity is primarily constrained by the 2715 X.509's validity field, the "notBefore" and "notAfter" values, as 2716 specified by the certificate authority that signed it. The owner 2717 certificate's validity is secondarily constrained by the validity of 2718 the PKI used to sign the voucher. Owner certificates may be revoked 2719 directly. 2721 For owners that wish to have maximum flexibility in their ability to 2722 specify and constrain the validity of signed data, it is RECOMMENDED 2723 that a unique owner certificate is created for each signed artifact. 2724 Not only does this enable a validity period to be specified, for each 2725 artifact, but it also enables to the validity of each artifact to be 2726 revoke. 2728 9.13. The "ietf-zerotouch-information" YANG Module 2730 The ietf-zerotouch-information module defined in this document 2731 defines a data structure that is always wrapped by a CMS structure. 2732 When accessed by a secure mechanism (e.g., protected by TLS), then 2733 the CMS structure may be unsigned. However, when accessed by an 2734 insecure mechanism (e.g., removable storage device), then the CMS 2735 structure must be signed, in order for the device to trust it. 2737 Implementations should be aware that signed bootstrapping data only 2738 protects the data from modification, the contents are still visible 2739 to others. This doesn't affect security so much as privacy. That 2740 the contents may be read by unintended parties when accessed by 2741 insecure mechanisms is considered next. 2743 The ietf-zerotouch-information module defines a top-level "choice" 2744 statement that declares the contents are either "redirect- 2745 information" or "onboarding-information". Each of these two cases 2746 are now considered. 2748 When the content of the CMS structure is redirect-information, an 2749 observer can learn about the bootstrap servers the device is being 2750 directed to, their IP addresses or hostnames, ports, and trust anchor 2751 certificates. Knowledge of this information could provide an 2752 observer some insight into a network's inner structure. 2754 When the content of the CMS structure is onboarding-information, an 2755 observer could learn considerable information about how the device is 2756 to be provisioned. This information includes the operating system 2757 version, initial configuration, and script contents. This 2758 information should be considered sensitive and precautions should be 2759 taken to protect it (e.g., encrypt artifact with device public key). 2761 9.14. The "ietf-zerotouch-bootstrap-server" YANG Module 2763 The ietf-zerotouch-bootstrap-server module defined in this document 2764 specifies an API for a RESTCONF [RFC8040]. The lowest RESTCONF layer 2765 is HTTPS, and the mandatory-to-implement secure transport is TLS 2766 [RFC8446]. 2768 The NETCONF Access Control Model (NACM) [RFC8341] provides the means 2769 to restrict access for particular users to a preconfigured subset of 2770 all available protocol operations and content. 2772 This module presents no data nodes (only RPCs). There is no need to 2773 discuss the sensitivity of data nodes. 2775 This module defines two RPC operations that may be considered 2776 sensitive in some network environments. These are the operations and 2777 their sensitivity/vulnerability: 2779 get-bootstrapping-data: This RPC is used by devices to obtain their 2780 bootstrapping data. By design, each device, as identified by its 2781 authentication credentials (e.g. client certificate), can only 2782 obtain its own data. NACM is not needed to further constrain 2783 access to this RPC. 2785 report-progress: This RPC is used by devices to report their 2786 bootstrapping progress. By design, each device, as identified by 2787 its authentication credentials (e.g. client certificate), can 2788 only report data for itself. NACM is not needed to further 2789 constrain access to this RPC. 2791 10. IANA Considerations 2792 10.1. The IETF XML Registry 2794 This document registers two URIs in the IETF XML registry [RFC3688]. 2795 Following the format in [RFC3688], the following registrations are 2796 requested: 2798 URI: urn:ietf:params:xml:ns:yang:ietf-zerotouch-information 2799 Registrant Contact: The NETCONF WG of the IETF. 2800 XML: N/A, the requested URI is an XML namespace. 2802 URI: urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server 2803 Registrant Contact: The NETCONF WG of the IETF. 2804 XML: N/A, the requested URI is an XML namespace. 2806 10.2. The YANG Module Names Registry 2808 This document registers two YANG modules in the YANG Module Names 2809 registry [RFC6020]. Following the format defined in [RFC6020], the 2810 the following registrations are requested: 2812 name: ietf-zerotouch-information 2813 namespace: urn:ietf:params:xml:ns:yang:ietf-zerotouch-information 2814 prefix: zti 2815 reference: RFC XXXX 2817 name: ietf-zerotouch-bootstrap-server 2818 namespace: urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-\ 2819 server (note: '\' used for formatting reasons only) 2820 prefix: ztbs 2821 reference: RFC XXXX 2823 10.3. The SMI Security for S/MIME CMS Content Type Registry 2825 IANA is kindly requested to two entries in the "SMI Security for 2826 S/MIME CMS Content Type" registry (1.2.840.113549.1.9.16.1), with 2827 values as follows: 2829 Decimal Description References 2830 ------- -------------------------------------- ---------- 2831 TBD1 id-ct-zerotouchInformationXML [RFCXXXX] 2832 TBD2 id-ct-zerotouchInformationJSON [RFCXXXX] 2834 id-ct-zerotouchInformationXML indicates that the "zerotouch- 2835 information" is encoded using XML. id-ct-zerotouchInformationJSON 2836 indicates that the "zerotouch-information" is encoded using JSON. 2838 10.4. The BOOTP Manufacturer Extensions and DHCP Options Registry 2840 IANA is kindly requested to make permanent the following early code 2841 point allocation in the "BOOTP Manufacturer Extensions and DHCP 2842 Options" registry maintained at http://www.iana.org/assignments/ 2843 bootp-dhcp-parameters: 2845 Tag: 143 2846 Name: OPTION_V4_ZEROTOUCH_REDIRECT 2847 Data Length: N 2848 Meaning: This option provides a list of URIs 2849 for zerotouch bootstrap servers 2850 Reference: [RFCXXXX] 2852 And the following early code point allocation in the "Dynamic Host 2853 Configuration Protocol for IPv6 (DHCPv6)" registry maintained at 2854 http://www.iana.org/assignments/dhcpv6-parameters: 2856 Value: 136 2857 Description: OPTION_V6_ZEROTOUCH_REDIRECT 2858 Reference: [RFCXXXX] 2860 11. References 2862 11.1. Normative References 2864 [I-D.ietf-netmod-yang-data-ext] 2865 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data 2866 Extensions", draft-ietf-netmod-yang-data-ext-01 (work in 2867 progress), March 2018. 2869 [ITU.X690.2015] 2870 International Telecommunication Union, "Information 2871 Technology - ASN.1 encoding rules: Specification of Basic 2872 Encoding Rules (BER), Canonical Encoding Rules (CER) and 2873 Distinguished Encoding Rules (DER)", ITU-T Recommendation 2874 X.690, ISO/IEC 8825-1, August 2015, 2875 . 2877 [RFC1035] Mockapetris, P., "Domain names - implementation and 2878 specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, 2879 November 1987, . 2881 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2882 Requirement Levels", BCP 14, RFC 2119, 2883 DOI 10.17487/RFC2119, March 1997, 2884 . 2886 [RFC3315] Droms, R., Ed., Bound, J., Volz, B., Lemon, T., Perkins, 2887 C., and M. Carney, "Dynamic Host Configuration Protocol 2888 for IPv6 (DHCPv6)", RFC 3315, DOI 10.17487/RFC3315, July 2889 2003, . 2891 [RFC3396] Lemon, T. and S. Cheshire, "Encoding Long Options in the 2892 Dynamic Host Configuration Protocol (DHCPv4)", RFC 3396, 2893 DOI 10.17487/RFC3396, November 2002, 2894 . 2896 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 2897 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, 2898 January 2006, . 2900 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2901 Housley, R., and W. Polk, "Internet X.509 Public Key 2902 Infrastructure Certificate and Certificate Revocation List 2903 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 2904 . 2906 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 2907 RFC 5652, DOI 10.17487/RFC5652, September 2009, 2908 . 2910 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2911 the Network Configuration Protocol (NETCONF)", RFC 6020, 2912 DOI 10.17487/RFC6020, October 2010, 2913 . 2915 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2916 Verification of Domain-Based Application Service Identity 2917 within Internet Public Key Infrastructure Using X.509 2918 (PKIX) Certificates in the Context of Transport Layer 2919 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2920 2011, . 2922 [RFC6762] Cheshire, S. and M. Krochmal, "Multicast DNS", RFC 6762, 2923 DOI 10.17487/RFC6762, February 2013, 2924 . 2926 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 2927 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, 2928 . 2930 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2931 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2932 . 2934 [RFC7227] Hankins, D., Mrugalski, T., Siodelski, M., Jiang, S., and 2935 S. Krishnan, "Guidelines for Creating New DHCPv6 Options", 2936 BCP 187, RFC 7227, DOI 10.17487/RFC7227, May 2014, 2937 . 2939 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2940 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2941 . 2943 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2944 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2945 . 2947 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2948 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2949 May 2017, . 2951 [RFC8366] Watsen, K., Richardson, M., Pritikin, M., and T. Eckert, 2952 "A Voucher Artifact for Bootstrapping Protocols", 2953 RFC 8366, DOI 10.17487/RFC8366, May 2018, 2954 . 2956 [Std-802.1AR-2009] 2957 IEEE SA-Standards Board, "IEEE Standard for Local and 2958 metropolitan area networks - Secure Device Identity", 2959 December 2009, . 2962 11.2. Informative References 2964 [I-D.ietf-netconf-crypto-types] 2965 Watsen, K., "Common YANG Data Types for Cryptography", 2966 draft-ietf-netconf-crypto-types-00 (work in progress), 2967 June 2018. 2969 [I-D.ietf-netconf-trust-anchors] 2970 Watsen, K., "YANG Data Model for Global Trust Anchors", 2971 draft-ietf-netconf-trust-anchors-00 (work in progress), 2972 June 2018. 2974 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2975 DOI 10.17487/RFC3688, January 2004, 2976 . 2978 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 2979 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 2980 DOI 10.17487/RFC6234, May 2011, 2981 . 2983 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2984 and A. Bierman, Ed., "Network Configuration Protocol 2985 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2986 . 2988 [RFC6698] Hoffman, P. and J. Schlyter, "The DNS-Based Authentication 2989 of Named Entities (DANE) Transport Layer Security (TLS) 2990 Protocol: TLSA", RFC 6698, DOI 10.17487/RFC6698, August 2991 2012, . 2993 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 2994 Galperin, S., and C. Adams, "X.509 Internet Public Key 2995 Infrastructure Online Certificate Status Protocol - OCSP", 2996 RFC 6960, DOI 10.17487/RFC6960, June 2013, 2997 . 2999 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 3000 RFC 8071, DOI 10.17487/RFC8071, February 2017, 3001 . 3003 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 3004 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 3005 . 3007 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 3008 Access Control Model", STD 91, RFC 8341, 3009 DOI 10.17487/RFC8341, March 2018, 3010 . 3012 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3013 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3014 . 3016 Appendix A. The Zero Touch Device Data Model 3018 This section defines a non-normative data model that enables the 3019 configuration of zerotouch bootstrapping and discovery of what 3020 parameters are used by a device's bootstrapping logic. 3022 A.1. Data Model Overview 3024 The following tree diagram provides an overview for the zerotouch 3025 device data model. 3027 module: example-zerotouch-device 3028 +--rw zerotouch 3029 +--rw enabled? boolean 3030 +--ro idevid-certificate? 3031 | ct:end-entity-cert-cms {bootstrap-servers}? 3032 +--ro bootstrap-servers {bootstrap-servers}? 3033 | +--ro bootstrap-server* [address] 3034 | +--ro address inet:host 3035 | +--ro port? inet:port-number 3036 +--ro bootstrap-server-pinned-certificates? 3037 | ta:pinned-certificates-ref {bootstrap-servers}? 3038 +--ro voucher-pinned-certificates? 3039 ta:pinned-certificates-ref {signed-data}? 3041 In the above diagram, notice that there is only one configurable node 3042 "enabled". The expectation is that this node would be set to "true" 3043 in device's factory default configuration and that it would either be 3044 set to "false" or deleted when the zerotouch bootstrapping is longer 3045 needed. 3047 A.2. Example Usage 3049 Following is an instance example for this data model. 3051 [Note: '\' line wrapping for formatting only] 3053 3055 true 3056 base64encodedvalue== 3057 3058 3059
phs1.example.com
3060 8443 3061
3062 3063
phs2.example.com
3064 8443 3065
3066 3067
phs3.example.com
3068 8443 3069
3070
3071 manufacturers-root-ca-certs<\ 3072 /bootstrap-server-pinned-certificates> 3073 manufacturers-root-ca-certs 3075
3077 A.3. YANG Module 3079 The device model is defined by the YANG module defined in this 3080 section. 3082 This module uses data types defined in [RFC6991], 3083 [I-D.ietf-netconf-crypto-types], and 3084 [I-D.ietf-netconf-trust-anchors]. 3086 module example-zerotouch-device { 3087 yang-version 1.1; 3088 namespace "https://example.com/zerotouch-device"; 3089 prefix ztd; 3091 import ietf-inet-types { 3092 prefix inet; 3093 reference "RFC 6991: Common YANG Data Types"; 3094 } 3096 import ietf-crypto-types { 3097 prefix ct; 3098 revision-date 2018-06-04; 3099 description 3100 "This revision is defined in the -00 version of 3101 draft-ietf-netconf-crypto-types"; 3102 reference 3103 "draft-ietf-netconf-crypto-types: 3104 Common YANG Data Types for Cryptography"; 3105 } 3107 import ietf-trust-anchors { 3108 prefix ta; 3109 revision-date 2018-06-04; 3110 description 3111 "This revision is defined in -00 version of 3112 draft-ietf-netconf-trust-anchors."; 3113 reference 3114 "draft-ietf-netconf-trust-anchors: 3115 YANG Data Model for Global Trust Anchors"; 3116 } 3118 organization 3119 "Example Corporation"; 3121 contact 3122 "Author: Bootstrap Admin "; 3124 description 3125 "This module defines a data model to enable zerotouch 3126 bootstrapping and discover what parameters are used. 3127 This module assumes the use of an IDevID certificate, 3128 as opposed to any other client certificate, or the 3129 use of an HTTP-based client authentication scheme."; 3131 revision 2018-09-05 { 3132 description 3133 "Initial version"; 3134 reference 3135 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 3136 } 3138 // features 3140 feature bootstrap-servers { 3141 description 3142 "The device supports bootstrapping off bootstrap servers."; 3143 } 3145 feature signed-data { 3146 description 3147 "The device supports bootstrapping off signed data."; 3148 } 3150 // protocol accessible nodes 3152 container zerotouch { 3153 description 3154 "Top-level container for zerotouch data model."; 3155 leaf enabled { 3156 type boolean; 3157 default false; 3158 description 3159 "The 'enabled' leaf controls if zerotouch bootstrapping is 3160 enabled or disabled. The default is 'false' so that, when 3161 not enabled, which is most of the time, no configuration 3162 is needed."; 3163 } 3164 leaf idevid-certificate { 3165 if-feature bootstrap-servers; 3166 type ct:end-entity-cert-cms; 3167 config false; 3168 description 3169 "This CMS structure contains the IEEE 802.1AR-2009 3170 IDevID certificate itself, and all intermediate 3171 certificates leading up to, and optionally including, 3172 the manufacturer's well-known trust anchor certificate 3173 for IDevID certificates. The well-known trust anchor 3174 does not have to be a self-signed certificate."; 3175 reference 3176 "IEEE 802.1AR-2009: 3177 IEEE Standard for Local and metropolitan area 3178 networks - Secure Device Identity."; 3179 } 3180 container bootstrap-servers { 3181 if-feature bootstrap-servers; 3182 config false; 3183 description 3184 "List of bootstrap servers this device will attempt 3185 to reach out to when bootstrapping."; 3186 list bootstrap-server { 3187 key "address"; 3188 description 3189 "A bootstrap server entry."; 3190 leaf address { 3191 type inet:host; 3192 mandatory true; 3193 description 3194 "The IP address or hostname of the bootstrap server the 3195 device should redirect to."; 3196 } 3197 leaf port { 3198 type inet:port-number; 3199 default "443"; 3200 description 3201 "The port number the bootstrap server listens on. If no 3202 port is specified, the IANA-assigned port for 'https' 3203 (443) is used."; 3204 } 3205 } 3206 } 3207 leaf bootstrap-server-pinned-certificates { 3208 if-feature bootstrap-servers; 3209 type ta:pinned-certificates-ref; 3210 config false; 3211 description 3212 "A reference to a list of pinned certificate authority (CA) 3213 certificates that the device uses to validate bootstrap 3214 servers with."; 3215 } 3216 leaf voucher-pinned-certificates { 3217 if-feature signed-data; 3218 type ta:pinned-certificates-ref; 3219 config false; 3220 description 3221 "A reference to a list of pinned certificate authority (CA) 3222 certificates that the device uses to validate ownership 3223 vouchers with."; 3224 } 3225 } 3226 } 3228 Appendix B. Promoting a Connection from Untrusted to Trusted 3230 The following diagram illustrates a sequence of bootstrapping 3231 activities that promote an untrusted connection to a bootstrap server 3232 to a trusted connection to the same bootstrap server. This enables a 3233 device to limit the amount of information it might disclose to an 3234 adversary hosting an untrusted bootstrap server. 3236 +----------+ 3237 |Deployment| 3238 | Specific | 3239 +------+ |Bootstrap | 3240 |Device| | Server | 3241 +------+ +----------+ 3242 | | 3243 | 1. "HTTPS" Request ("untrusted-connection", nonce) | 3244 |------------------------------------------------------->| 3245 | 2. "HTTPS" Response (signed redirect information) | 3246 |<-------------------------------------------------------| 3247 | | 3248 | | 3249 | 3. HTTPS Request (os-name=xyz, os-version=123, etc.) | 3250 |------------------------------------------------------->| 3251 | 4. HTTPS Response (unsigned onboarding information | 3252 |<-------------------------------------------------------| 3253 | | 3255 The interactions in the above diagram are described below. 3257 1. The device initiates an untrusted connection to a bootstrap 3258 server, as is indicated by putting "HTTPS" in double quotes 3259 above. It is still an HTTPS connection, but the device is unable 3260 to authenticate the bootstrap server's TLS certificate. Because 3261 the device is unable to trust the bootstrap server, it sends the 3262 "untrusted-connection" input parameter, and optionally also the 3263 "nonce" input parameter, in the "get-bootstrapping-data" RPC. 3264 The "untrusted-connection" parameter informs the bootstrap server 3265 that the device does not trust it and may be holding back some 3266 additional input parameters from the server (e.g., other input 3267 parameters, progress reports, etc.). The "nonce" input parameter 3268 enables the bootstrap server to dynamically obtain an ownership 3269 voucher from a MASA, which may be important for devices that do 3270 not have a reliable clock. 3272 2. The bootstrap server, seeing the "untrusted-connection" input 3273 parameter, knows that it can either send unsigned redirect 3274 information or signed data of any type. But, in this case, the 3275 bootstrap server has the ability to sign data and chooses to 3276 respond with signed redirect information, not signed onboarding 3277 information as might be expected, securely redirecting the device 3278 back to it again. Not displayed but, if the "nonce" input 3279 parameter was passed, the bootstrap server could dynamically 3280 connect to a download a voucher from the MASA having the nonce 3281 value in it. Details regarding a protocol enabling this 3282 integration is outside the scope of this document. 3284 3. Upon validating the signed redirect information, the device 3285 establishes a secure connection to the bootstrap server. 3286 Unbeknownst to the device, it is the same bootstrap server it was 3287 connected to previously but, because the device is able to 3288 authenticate the bootstrap server this time, it sends its normal 3289 "get-bootstrapping-data" request (i.e., with additional input 3290 parameters) as well as its progress reports (not depicted). 3292 4. This time, because the "untrusted-connection" parameter was not 3293 passed, having access to all of the device's input parameters, 3294 the bootstrap server returns, in this example, unsigned 3295 onboarding information to the device. 3297 Appendix C. Workflow Overview 3299 The zero touch solution presented in this document is conceptualized 3300 to be composed of the non-normative workflows described in this 3301 section. Implementation details are expected to vary. Each diagram 3302 is followed by a detailed description of the steps presented in the 3303 diagram, with further explanation on how implementations may vary. 3305 C.1. Enrollment and Ordering Devices 3307 The following diagram illustrates key interactions that may occur 3308 from when a prospective owner enrolls in a manufacturer's zero touch 3309 program to when the manufacturer ships devices for an order placed by 3310 the prospective owner. 3312 +-----------+ 3313 +------------+ |Prospective| +---+ 3314 |Manufacturer| | Owner | |NMS| 3315 +------------+ +-----------+ +---+ 3316 | | | 3317 | | | 3318 | 1. initiate enrollment | | 3319 #<-----------------------------| | 3320 # | | 3321 # | | 3322 # IDevID trust anchor | | 3323 #-----------------------------># set IDevID trust anchor | 3324 # #--------------------------->| 3325 # | | 3326 # bootstrap server | | 3327 # account credentials | | 3328 #-----------------------------># set credentials | 3329 | #--------------------------->| 3330 | | | 3331 | | | 3332 | 2. set owner certificate trust anchor | 3333 |<----------------------------------------------------------| 3334 | | | 3335 | | | 3336 | 3. place device order | | 3337 |<-----------------------------# model devices | 3338 | #--------------------------->| 3339 | | | 3340 | 4. ship devices and send | | 3341 | device identifiers and | | 3342 | ownership vouchers | | 3343 |-----------------------------># set device identifiers | 3344 | # and ownership vouchers | 3345 | #--------------------------->| 3346 | | | 3348 Each numbered item below corresponds to a numbered item in the 3349 diagram above. 3351 1. A prospective owner of a manufacturer's devices initiates an 3352 enrollment process with the manufacturer. This process includes 3353 the following: 3355 * Regardless how the prospective owner intends to bootstrap 3356 their devices, they will always obtain from the manufacturer 3357 the trust anchor certificate for the IDevID certificates. 3358 This certificate will is installed on the prospective owner's 3359 NMS so that the NMS can authenticate the IDevID certificates 3360 when they are presented to subsequent steps. 3362 * If the manufacturer hosts an Internet based bootstrap server 3363 (e.g., a redirect server) such as described in Section 4.4, 3364 then credentials necessary to configure the bootstrap server 3365 would be provided to the prospective owner. If the bootstrap 3366 server is configurable through an API (outside the scope of 3367 this document), then the credentials might be installed on the 3368 prospective owner's NMS so that the NMS can subsequently 3369 configure the manufacturer-hosted bootstrap server directly. 3371 2. If the manufacturer's devices are able to validate signed data 3372 (Section 5.4), and assuming that the prospective owner's NMS is 3373 able to prepare and sign the bootstrapping data itself, the 3374 prospective owner's NMS might set a trust anchor certificate onto 3375 the manufacturer's bootstrap server, using the credentials 3376 provided in the previous step. This certificate is the trust 3377 anchor certificate that the prospective owner would like the 3378 manufacturer to place into the ownership vouchers it generates, 3379 thereby enabling devices to trust the owner's owner certificate. 3380 How this trust anchor certificate is used to enable devices to 3381 validate signed bootstrapping data is described in Section 5.4. 3383 3. Some time later, the prospective owner places an order with the 3384 manufacturer, perhaps with a special flag checked for zero touch 3385 handling. At this time, or perhaps before placing the order, the 3386 owner may model the devices in their NMS, creating virtual 3387 objects for the devices with no real-world device associations. 3388 For instance the model can be used to simulate the device's 3389 location in the network and the configuration it should have when 3390 fully operational. 3392 4. When the manufacturer fulfills the order, shipping the devices to 3393 their intended locations, they may notify the owner of the 3394 devices' serial numbers and shipping destinations, which the 3395 owner may use to stage the network for when the devices power on. 3396 Additionally, the manufacturer may send one or more ownership 3397 vouchers, cryptographically assigning ownership of those devices 3398 to the owner. The owner may set this information on their NMS, 3399 perhaps binding specific modeled devices to the serial numbers 3400 and ownership vouchers. 3402 C.2. Owner Stages the Network for Bootstrap 3404 The following diagram illustrates how an owner might stage the 3405 network for bootstrapping devices. 3407 +----------+ +------------+ 3408 |Deployment| |Manufacturer| +------+ +------+ 3409 | Specific | | Hosted | | Local| | Local| +---------+ 3410 +---+ |Bootstrap | | Bootstrap | | DNS | | DHCP | |Removable| 3411 |NMS| | Server | | Server | |Server| |Server| | Storage | 3412 +---+ +----------+ +------------+ +------+ +------+ +---------+ 3413 | | | | | | 3414 1. | | | | | | 3415 activate| | | | | | 3416 modeled | | | | | | 3417 device | | | | | | 3418 ------->| | | | | | 3419 | 2. (optional) | | | | 3420 | configure | | | | 3421 | bootstrap | | | | 3422 | server | | | | 3423 |------->| | | | | 3424 | | | | | | 3425 | 3. (optional) configure | | | 3426 | bootstrap server | | | | 3427 |--------------------->| | | | 3428 | | | | | | 3429 | | | | | | 3430 | 4. (optional) configure DNS server| | | 3431 |---------------------------------->| | | 3432 | | | | | | 3433 | | | | | | 3434 | 5. (optional) configure DHCP server | | 3435 |------------------------------------------->| | 3436 | | | | | | 3437 | | | | | | 3438 | 6. (optional) store bootstrapping artifacts on media | 3439 |----------------------------------------------------->| 3440 | | | | | | 3441 | | | | | | 3443 Each numbered item below corresponds to a numbered item in the 3444 diagram above. 3446 1. Having previously modeled the devices, including setting their 3447 fully operational configurations and associating device serial 3448 numbers and (optionally) ownership vouchers, the owner might 3449 "activate" one or more modeled devices. That is, the owner tells 3450 the NMS to perform the steps necessary to prepare for when the 3451 real-world devices power up and initiate the bootstrapping 3452 process. Note that, in some deployments, this step might be 3453 combined with the last step from the previous workflow. Here it 3454 is depicted that an NMS performs the steps, but they may be 3455 performed manually or through some other mechanism. 3457 2. If it is desired to use a deployment specific bootstrap server, 3458 it must be configured to provide the bootstrapping information 3459 for the specific devices. Configuring the bootstrap server may 3460 occur via a programmatic API not defined by this document. 3461 Illustrated here as an external component, the bootstrap server 3462 may be implemented as an internal component of the NMS itself. 3464 3. If it is desired to use a manufacturer hosted bootstrap server, 3465 it must be configured to provide the bootstrapping information 3466 for the specific devices. The configuration must be either 3467 redirect or onboarding information. That is, either the 3468 manufacturer hosted bootstrap server will redirect the device to 3469 another bootstrap server, or provide the device with the 3470 onboarding information itself. The types of bootstrapping 3471 information the manufacturer hosted bootstrap server supports may 3472 vary by implementation; some implementations may only support 3473 redirect information, or only support onboarding information, or 3474 support both redirect and onboarding information. Configuring 3475 the bootstrap server may occur via a programmatic API not defined 3476 by this document. 3478 4. If it is desired to use a DNS server to supply bootstrapping 3479 information, a DNS server needs to be configured. If multicast 3480 DNS-SD is desired, then the server must reside on the local 3481 network, otherwise the DNS server may reside on a remote network. 3482 Please see Section 4.2 for more information about how to 3483 configure DNS servers. Configuring the DNS server may occur via 3484 a programmatic API not defined by this document. 3486 5. If it is desired to use a DHCP server to supply bootstrapping 3487 data, a DHCP server needs to be configured. The DHCP server may 3488 be accessed directly or via a DHCP relay. Please see Section 4.3 3489 for more information about how to configure DHCP servers. 3490 Configuring the DHCP server may occur via a programmatic API not 3491 defined by this document. 3493 6. If it is desired to use a removable storage device (e.g., USB 3494 flash drive) to supply bootstrapping information, the information 3495 would need to be placed onto it. Please see Section 4.1 for more 3496 information about how to configure a removable storage device. 3498 C.3. Device Powers On 3500 The following diagram illustrates the sequence of activities that 3501 occur when a device powers on. 3503 +----------+ 3504 +-----------+ |Deployment| 3505 | Source of | | Specific | 3506 +------+ | Bootstrap | |Bootstrap | +---+ 3507 |Device| | Data | | Server | |NMS| 3508 +------+ +-----------+ +----------+ +---+ 3509 | | | | 3510 | | | | 3511 | 1. if zerotouch bootstrap service | | | 3512 | is not enabled, then exit. | | | 3513 | | | | 3514 | 2. for each source supported, check | | | 3515 | for bootstrapping data. | | | 3516 |------------------------------------>| | | 3517 | | | | 3518 | 3. if onboarding information found, | | | 3519 | initialize self and, only if | | | 3520 | source is a trusted bootstrap | | | 3521 | server, send progress reports. | | | 3522 |------------------------------------># | | 3523 | # webhook | | 3524 | #----------------------->| 3525 | | | 3526 | 4. else if redirect-information found, for each | | 3527 | bootstrap server specified, check for data. | | 3528 |-+------------------------------------------------->| | 3529 | | | | 3530 | | if more redirect-information is found, recurse | | 3531 | | (not depicted), else if onboarding-information | | 3532 | | found, initialize self and post progress reports | | 3533 | +-------------------------------------------------># | 3534 | # webhook | 3535 | #-------->| 3536 | 3537 | 5. retry sources and/or wait for manual provisioning. 3538 | 3540 The interactions in the above diagram are described below. 3542 1. Upon power being applied, the device checks to see if zerotouch 3543 bootstrapping is configured, such as must be the case when 3544 running its "factory default" configuration. If zerotouch 3545 bootstrapping is not configured, then the bootstrapping logic 3546 exits and none of the following interactions occur. 3548 2. For each source of bootstrapping data the device supports, 3549 preferably in order of closeness to the device (e.g., removable 3550 storage before Internet based servers), the device checks to see 3551 if there is any bootstrapping data for it there. 3553 3. If onboarding information is found, the device initializes itself 3554 accordingly (e.g., installing a boot-image and committing an 3555 initial configuration). If the source is a bootstrap server, and 3556 the bootstrap server can be trusted (i.e., TLS-level 3557 authentication), the device also sends progress reports to the 3558 bootstrap server. 3560 * The contents of the initial configuration should configure an 3561 administrator account on the device (e.g., username, ssh-rsa 3562 key, etc.), and should configure the device either to listen 3563 for NETCONF or RESTCONF connections or to initiate call home 3564 connections [RFC8071], and should disable the zerotouch 3565 bootstrapping service (e.g., the "enabled" leaf in data model 3566 presented in Appendix A). 3568 * If the bootstrap server supports forwarding device progress 3569 reports to external systems (e.g., via a webhook), a 3570 "bootstrap-complete" progress report (Section 7.3) informs the 3571 external system to know when it can, for instance, initiate a 3572 connection to the device. To support this scenario further, 3573 the "bootstrap-complete" progress report may also relay the 3574 device's SSH host keys and/or TLS certificates, with which the 3575 external system can use to authenticate subsequent connections 3576 to the device. 3578 If the device successfully completes the bootstrapping process, 3579 it exits the bootstrapping logic without considering any 3580 additional sources of bootstrapping data. 3582 4. Otherwise, if redirect information is found, the device iterates 3583 through the list of specified bootstrap servers, checking to see 3584 if it has bootstrapping data for the device. If the bootstrap 3585 server returns more redirect information, then the device 3586 processes it recursively. Otherwise, if the bootstrap server 3587 returns onboarding information, the device processes it following 3588 the description provided in (3) above. 3590 5. After having tried all supported sources of bootstrapping data, 3591 the device may retry again all the sources and/or provide 3592 manageability interfaces for manual configuration (e.g., CLI, 3593 HTTP, NETCONF, etc.). If manual configuration is allowed, and 3594 such configuration is provided, the configuration should also 3595 disable the zerotouch bootstrapping service, as the need for 3596 bootstrapping would no longer be present. 3598 Appendix D. Change Log 3600 D.1. ID to 00 3602 o Major structural update; the essence is the same. Most every 3603 section was rewritten to some degree. 3605 o Added a Use Cases section 3607 o Added diagrams for "Actors and Roles" and "NMS Precondition" 3608 sections, and greatly improved the "Device Boot Sequence" diagram 3610 o Removed support for physical presence or any ability for 3611 configlets to not be signed. 3613 o Defined the Zero Touch Information DHCP option 3615 o Added an ability for devices to also download images from 3616 configuration servers 3618 o Added an ability for configlets to be encrypted 3620 o Now configuration servers only have to support HTTP/S - no other 3621 schemes possible 3623 D.2. 00 to 01 3625 o Added boot-image and validate-owner annotations to the "Actors and 3626 Roles" diagram. 3628 o Fixed 2nd paragraph in section 7.1 to reflect current use of 3629 anyxml. 3631 o Added encrypted and signed-encrypted examples 3633 o Replaced YANG module with XSD schema 3635 o Added IANA request for the Zero Touch Information DHCP Option 3637 o Added IANA request for media types for boot-image and 3638 configuration 3640 D.3. 01 to 02 3642 o Replaced the need for a configuration signer with the ability for 3643 each NMS to be able to sign its own configurations, using 3644 manufacturer signed ownership vouchers and owner certificates. 3646 o Renamed configuration server to bootstrap server, a more 3647 representative name given the information devices download from 3648 it. 3650 o Replaced the concept of a configlet by defining a southbound 3651 interface for the bootstrap server using YANG. 3653 o Removed the IANA request for the boot-image and configuration 3654 media types 3656 D.4. 02 to 03 3658 o Minor update, mostly just to add an Editor's Note to show how this 3659 draft might integrate with the draft-pritikin-anima-bootstrapping- 3660 keyinfra. 3662 D.5. 03 to 04 3664 o Major update formally introducing unsigned data and support for 3665 Internet-based redirect servers. 3667 o Added many terms to Terminology section. 3669 o Added all new "Guiding Principles" section. 3671 o Added all new "Sources for Bootstrapping Data" section. 3673 o Rewrote the "Interactions" section and renamed it "Workflow 3674 Overview". 3676 D.6. 04 to 05 3678 o Semi-major update, refactoring the document into more logical 3679 parts 3681 o Created new section for information types 3683 o Added support for DNS servers 3685 o Now allows provisional TLS connections 3687 o Bootstrapping data now supports scripts 3688 o Device Details section overhauled 3690 o Security Considerations expanded 3692 o Filled in enumerations for notification types 3694 D.7. 05 to 06 3696 o Minor update 3698 o Added many Normative and Informative references. 3700 o Added new section Other Considerations. 3702 D.8. 06 to 07 3704 o Minor update 3706 o Added an Editorial Note section for RFC Editor. 3708 o Updated the IANA Considerations section. 3710 D.9. 07 to 08 3712 o Minor update 3714 o Updated to reflect review from Michael Richardson. 3716 D.10. 08 to 09 3718 o Added in missing "Signature" artifact example. 3720 o Added recommendation for manufacturers to use interoperable 3721 formats and file naming conventions for removable storage devices. 3723 o Added configuration-handling leaf to guide if config should be 3724 merged, replaced, or processed like an edit-config/yang-patch 3725 document. 3727 o Added a pre-configuration script, in addition to the post- 3728 configuration script from -05 (issue #15). 3730 D.11. 09 to 10 3732 o Factored ownership voucher and voucher revocation to a separate 3733 document: draft-kwatsen-netconf-voucher. (issue #11) 3735 o Removed options "edit-config" and "yang- 3736 patch". (issue #12) 3738 o Defined how a signature over signed-data returned from a bootstrap 3739 server is processed. (issue #13) 3741 o Added recommendation for removable storage devices to use open/ 3742 standard file systems when possible. (issue #14) 3744 o Replaced notifications "script-[warning/error]" with "[pre/post]- 3745 script-[warning/error]". (goes with issue #15) 3747 o switched owner-certificate to be encoded using the PKCS #7 format. 3748 (issue #16) 3750 o Replaced md5/sha1 with sha256 inside a choice statement, for 3751 future extensibility. (issue #17) 3753 o A ton of editorial changes, as I went thru the entire draft with a 3754 fine-toothed comb. 3756 D.12. 10 to 11 3758 o fixed yang validation issues found by IETFYANGPageCompilation. 3759 note: these issues were NOT found by pyang --ietf or by the 3760 submission-time validator... 3762 o fixed a typo in the yang module, someone the config false 3763 statement was removed. 3765 D.13. 11 to 12 3767 o fixed typo that prevented Appendix B from loading the examples 3768 correctly. 3770 o fixed more yang validation issues found by 3771 IETFYANGPageCompilation. note: again, these issues were NOT found 3772 by pyang --ietf or by the submission-time validator... 3774 o updated a few of the notification enumerations to be more 3775 consistent with the other enumerations (following the warning/ 3776 error pattern). 3778 o updated the information-type artifact to state how it is encoded, 3779 matching the language that was in Appendix B. 3781 D.14. 12 to 13 3783 o defined a standalone artifact to encode the old information-type 3784 into a PKCS #7 structure. 3786 o standalone information artifact hardcodes JSON encoding (to match 3787 the voucher draft). 3789 o combined the information and signature PKCS #7 structures into a 3790 single PKCS #7 structure. 3792 o moved the certificate-revocations into the owner-certificate's 3793 PKCS #7 structure. 3795 o eliminated support for voucher-revocations, to reflect the 3796 voucher-draft's switch from revocations to renewals. 3798 D.15. 13 to 14 3800 o Renamed "bootstrap information" to "onboarding information". 3802 o Rewrote DHCP sections to address the packet-size limitation issue, 3803 as discussed in Chicago. 3805 o Added Ian as an author for his text-contributions to the DHCP 3806 sections. 3808 o Removed the Guiding Principles section. 3810 D.16. 14 to 15 3812 o Renamed action "notification" to "update-progress" and, likewise 3813 "notification-type" to "update-type". 3815 o Updated examples to use "base64encodedvalue==" for binary values. 3817 o Greatly simplified the "Artifact Groupings" section, and moved it 3818 as a subsection to the "Artifacts" section. 3820 o Moved the "Workflow Overview" section to the Appendix. 3822 o Renamed "bootstrap information" to "update information". 3824 o Removed "Other Considerations" section. 3826 o Tons of editorial updates. 3828 D.17. 15 to 16 3830 o tweaked language to refer to "initial state" rather than "factory 3831 default configuration", so as accommodate white-box scenarios. 3833 o added a paragraph to Intro regarding how the solution primarily 3834 regards physical machines, but could be extended to VMs by a 3835 future document. 3837 o added a pointer to the Workflow Overview section (recently moved 3838 to the Appendix) to the Intro. 3840 o added a note that, in order to simplify the verification process, 3841 the "Zerotouch Information" PKCS #7 structure MUST also contain 3842 the signing X.509 certificate. 3844 o noted that the owner certificate's must either have no Key Usage 3845 or the Key Usage must set the "digitalSignature" bit. 3847 o noted that the owner certificate's subject and subjectAltName 3848 values are not constrained. 3850 o moved/consolidated some text from the Artifacts section down to 3851 the Device Details section. 3853 o tightened up some ambiguous language, for instance, by referring 3854 to specific leaf names in the Voucher artifact. 3856 o reverted a previously overzealous s/unique-id/serial-number/ 3857 change. 3859 o modified language for when ZTP runs from when factory-default 3860 config is running to when ZTP is configured, which the factory- 3861 defaults should set . 3863 D.18. 16 to 17 3865 o Added an example for how to promote an untrusted connection to a 3866 trusted connection. 3868 o Added a "query parameters" section defining some parameters 3869 enabling scenarios raised in last call. 3871 o Added a "Disclosing Information to Untrusted Servers" section to 3872 the Security Considerations. 3874 D.19. 17 to 18 3876 o Added Security Considerations for each YANG module. 3878 o Reverted back to the device always sending its DevID cert. 3880 o Moved data tree to "get-bootstrapping-data" RPC. 3882 o Moved the "update-progress" action to a "report-progress" RPC. 3884 o Added an "untrusted-connection" parameter to "get-bootstrapping- 3885 data" RPC. 3887 o Added the "ietf-zerotouch-device" module. 3889 o Lots of small updates. 3891 D.20. 18 to 19 3893 o Fixed "must" expressions, by converting "choice" to a "list" of 3894 "image-verification", each of which now points to a base identity 3895 called "hash-algorithm". There's just one algorithm currently 3896 defined (sha-256). Wish there was a standard crypto module that 3897 could identify such identities. 3899 D.21. 19 to 20 3901 o Now references I-D.ietf-netmod-yang-tree-diagrams. 3903 o Fixed tree-diagrams in Section 2 to always reflect current YANG 3904 (now they are now dynamically generated). 3906 o The "redirect-information" container's "trust-anchor" is now a CMS 3907 structure that can contain a chain of certificates, rather than a 3908 single certificate. 3910 o The "onboarding-information" container's support for image 3911 verification reworked to be extensible. 3913 o Added a reference to the "Device Details" section to the new 3914 example-zerotouch-device module. 3916 o Clarified that the device must always pass its IDevID certificate, 3917 even for untrusted bootstrap servers. 3919 o Fixed the description statement for the "script" typedef to refer 3920 to the [pre/post]-script-[warning/error] enums, rather than the 3921 legacy script-[warning/error] enums. 3923 o For the get-bootstrapping-data RPC's input, removed the "remote- 3924 id" and "circuit-id" fields, and added a "hw-model" field. 3926 o Improved DHCP error handling text. 3928 o Added MUST requirement for DHCPv6 client and server implementing 3929 [RFC3396] to handle URI lists longer than 255 octets. 3931 o Changed the "configuration" value in onboarding-information to be 3932 type "binary" instead of "anydata". 3934 o Moved everything from PKCS#7 to CMS (this shows up as a big 3935 change). 3937 o Added the early code point allocation assignments for the DHCP 3938 Options in the IANA Considerations section, and updated the RFC 3939 Editor note accordingly. 3941 o Added RFC Editor request to replace the assigned values for the 3942 CMS content types. 3944 o Relaxed auth requirements from device needing to always send 3945 IDevID cert to device needing to always send authentication 3946 credentials, as this better matches what RFC 8040 Section 2.5 3947 says. 3949 o Moved normative module "ietf-zerotouch-device" to non-normative 3950 module "example-zerotouch-device". 3952 o Updated Title, Abstract, and Introduction per discussion on list. 3954 D.22. 20 to 21 3956 o Now any of the three artifact can be encrypted. 3958 o Fixed some line-too-long issues. 3960 D.23. 21 to 22 3962 o Removed specifics around how scripts indicate warnings or errors 3963 and how scripts emit output. 3965 o Moved the Zero Touch Device Data Model section to the Appendix. 3967 o Modified the YANG module in the Zero Touch Device Data Model 3968 section to reflect the latest trust-anchors and keystore drafts. 3970 o Modified types in other YANG modules to more closely emulate what 3971 is in draft-ietf-netconf-crypto-types. 3973 D.24. 22 to 23 3975 o Rewrote section 5.6 (processing onboboarding information) to be 3976 clearer about error handling and retained state. Specifically: 3978 * Clarified that a script, upon having an error, must gracefully 3979 exit, cleaning up any state that might hinder subsequent 3980 executions. 3982 * Added ability for scripts to be executed again with a flag 3983 enabling them to clean up state from a previous execution. 3985 * Clarified that the conifguration commit is atomic. 3987 * Clarified that any error encountered after committing the 3988 configuration (e.g., in the "post-configuration-script") must 3989 rollback the configuration to the previous configuration. 3991 * Clarified that failure to successfully deliver the "bootstrap- 3992 initiated" and "bootstrap-complete" progress types must be 3993 treated as an error. 3995 * Clarified that "return to bootstrapping sequence" is to be 3996 interpreted in the recursive context. Meaning that the device 3997 rolls-back one loop, rather than start over from scratch. 3999 o Changed how a device verifies a boot-image from just "MUST match 4000 one of the supplied fingerprints" to also allow for the 4001 verification to use an cryptographic signature embedded into the 4002 image itself. 4004 o Added more "progress-type" enums for visibility reasons, enabling 4005 more strongly-typed debug information to be sent to the bootstrap 4006 server. 4008 o Added Security Considerations based on early SecDir review. 4010 o Added recommendation for device to send warning if the initial 4011 config does not disable the bootstrapping process. 4013 D.25. 23 to 24 4015 o Follow-ups from SecDir and Shepherd. 4017 o Added "boot-image-complete" enumeration. 4019 Acknowledgements 4021 The authors would like to thank for following for lively discussions 4022 on list and in the halls (ordered by last name): Michael Behringer, 4023 Dean Bogdanovic, Martin Bjorklund, Joe Clarke, Toerless Eckert, 4024 Stephen Farrell, Stephen Hanna, Wes Hardaker, David Harrington, Radek 4025 Krejci, David Mandelberg, Russ Mundy, Reinaldo Penno, Randy Presuhn, 4026 Max Pritikin, Michael Richardson, Phil Shafer, Juergen Schoenwaelder. 4028 Special thanks goes to Steve Hanna, Russ Mundy, and Wes Hardaker for 4029 brainstorming the original I-D's solution during the IETF 87 meeting 4030 in Berlin. 4032 Authors' Addresses 4034 Kent Watsen 4035 Juniper Networks 4037 EMail: kwatsen@juniper.net 4039 Mikael Abrahamsson 4040 T-Systems 4042 EMail: mikael.abrahamsson@t-systems.se 4044 Ian Farrer 4045 Deutsche Telekom AG 4047 EMail: ian.farrer@telekom.de