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