idnits 2.17.1 draft-ietf-netconf-zerotouch-26.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 : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 411 has weird spacing: '...gorithm ide...' == Line 1446 has weird spacing: '...gorithm ide...' == Line 1835 has weird spacing: '...rmation cms...' == Line 1844 has weird spacing: '...gorithm str...' == Line 2446 has weird spacing: '... string cer...' == (1 more instance...) -- The document date (December 20, 2018) is 1952 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 3073, but not defined == Unused Reference: 'RFC7230' is defined on line 3158, but no explicit reference was found in the text == 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 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) == Outdated reference: A later version (-34) exists of draft-ietf-netconf-crypto-types-02 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-02 == Outdated reference: A later version (-28) exists of draft-ietf-ntp-using-nts-for-ntp-14 Summary: 2 errors (**), 0 flaws (~~), 14 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: June 23, 2019 T-Systems 6 I. Farrer 7 Deutsche Telekom AG 8 December 20, 2018 10 Zero Touch Provisioning for Networking Devices 11 draft-ietf-netconf-zerotouch-26 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-12-20" --> the publication date of this draft 49 The following one Appendix section is to be removed prior to 50 publication: 52 o Appendix D. 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 June 23, 2019. 71 Copyright Notice 73 Copyright (c) 2018 IETF Trust and the persons identified as the 74 document authors. All rights reserved. 76 This document is subject to BCP 78 and the IETF Trust's Legal 77 Provisions Relating to IETF Documents 78 (https://trustee.ietf.org/license-info) in effect on the date of 79 publication of this document. Please review these documents 80 carefully, as they describe your rights and restrictions with respect 81 to this document. Code Components extracted from this document must 82 include Simplified BSD License text as described in Section 4.e of 83 the Trust Legal Provisions and are provided without warranty as 84 described in the Simplified BSD License. 86 Table of Contents 88 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 89 1.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 5 90 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 91 1.3. Requirements Language . . . . . . . . . . . . . . . . . . 7 92 1.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 8 93 2. Types of Zero Touch Information . . . . . . . . . . . . . . . 8 94 2.1. Redirect Information . . . . . . . . . . . . . . . . . . 8 95 2.2. Onboarding Information . . . . . . . . . . . . . . . . . 9 96 3. Artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . 10 97 3.1. Zero Touch Information . . . . . . . . . . . . . . . . . 10 98 3.2. Owner Certificate . . . . . . . . . . . . . . . . . . . . 11 99 3.3. Ownership Voucher . . . . . . . . . . . . . . . . . . . . 12 100 3.4. Artifact Encryption . . . . . . . . . . . . . . . . . . . 13 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 . . . . . . . . . . . . . . . . . . . . . . . 19 106 4.4. Bootstrap Server . . . . . . . . . . . . . . . . . . . . 19 107 5. Device Details . . . . . . . . . . . . . . . . . . . . . . . 20 108 5.1. Initial State . . . . . . . . . . . . . . . . . . . . . . 21 109 5.2. Boot Sequence . . . . . . . . . . . . . . . . . . . . . . 23 110 5.3. Processing a Source of Bootstrapping Data . . . . . . . . 24 111 5.4. Validating Signed Data . . . . . . . . . . . . . . . . . 26 112 5.5. Processing Redirect Information . . . . . . . . . . . . . 27 113 5.6. Processing Onboarding Information . . . . . . . . . . . . 27 114 6. The Zero Touch Information Data Model . . . . . . . . . . . . 30 115 6.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 30 116 6.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 31 117 6.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 33 118 7. The Zero Touch Bootstrap Server API . . . . . . . . . . . . . 39 119 7.1. API Overview . . . . . . . . . . . . . . . . . . . . . . 39 120 7.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 40 121 7.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 43 122 8. DHCP Zero Touch Options . . . . . . . . . . . . . . . . . . . 55 123 8.1. DHCPv4 Zero Touch Option . . . . . . . . . . . . . . . . 55 124 8.2. DHCPv6 Zero Touch Option . . . . . . . . . . . . . . . . 56 125 8.3. Common Field Encoding . . . . . . . . . . . . . . . . . . 57 126 9. Security Considerations . . . . . . . . . . . . . . . . . . . 58 127 9.1. Clock Sensitivity . . . . . . . . . . . . . . . . . . . . 58 128 9.2. Use of IDevID Certificates . . . . . . . . . . . . . . . 58 129 9.3. Immutable Storage for Trust Anchors . . . . . . . . . . . 58 130 9.4. Secure Storage for Long-lived Private Keys . . . . . . . 58 131 9.5. Blindly Authenticating a Bootstrap Server . . . . . . . . 59 132 9.6. Disclosing Information to Untrusted Servers . . . . . . . 59 133 9.7. Sequencing Sources of Bootstrapping Data . . . . . . . . 60 134 9.8. Safety of Private Keys used for Trust . . . . . . . . . . 60 135 9.9. Increased Reliance on Manufacturers . . . . . . . . . . . 61 136 9.10. Concerns with Trusted Bootstrap Servers . . . . . . . . . 61 137 9.11. Validity Period for Zero Touch Information . . . . . . . 62 138 9.12. The "ietf-zerotouch-information" YANG Module . . . . . . 63 139 9.13. The "ietf-zerotouch-bootstrap-server" YANG Module . . . . 64 140 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 64 141 10.1. The IETF XML Registry . . . . . . . . . . . . . . . . . 64 142 10.2. The YANG Module Names Registry . . . . . . . . . . . . . 65 143 10.3. The SMI Security for S/MIME CMS Content Type Registry . 65 144 10.4. The BOOTP Manufacturer Extensions and DHCP Options 145 Registry . . . . . . . . . . . . . . . . . . . . . . . . 65 146 10.5. The Dynamic Host Configuration Protocol for IPv6 147 (DHCPv6) Registry . . . . . . . . . . . . . . . . . . . 66 148 10.6. The Service Name and Transport Protocol Port Number 149 Registry . . . . . . . . . . . . . . . . . . . . . . . . 66 150 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 67 151 11.1. Normative References . . . . . . . . . . . . . . . . . . 67 152 11.2. Informative References . . . . . . . . . . . . . . . . . 69 153 Appendix A. The Zero Touch Device Data Model . . . . . . . . . . 72 154 A.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 72 155 A.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 72 156 A.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 73 157 Appendix B. Promoting a Connection from Untrusted to Trusted . . 76 158 Appendix C. Workflow Overview . . . . . . . . . . . . . . . . . 78 159 C.1. Enrollment and Ordering Devices . . . . . . . . . . . . . 78 160 C.2. Owner Stages the Network for Bootstrap . . . . . . . . . 80 161 C.3. Device Powers On . . . . . . . . . . . . . . . . . . . . 82 162 Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 85 163 D.1. ID to 00 . . . . . . . . . . . . . . . . . . . . . . . . 85 164 D.2. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 85 165 D.3. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 85 166 D.4. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 86 167 D.5. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 86 168 D.6. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 86 169 D.7. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 87 170 D.8. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 87 171 D.9. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 87 172 D.10. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 87 173 D.11. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 87 174 D.12. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 88 175 D.13. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 88 176 D.14. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 88 177 D.15. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 89 178 D.16. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 89 179 D.17. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 89 180 D.18. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 90 181 D.19. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 90 182 D.20. 18 to 19 . . . . . . . . . . . . . . . . . . . . . . . . 91 183 D.21. 19 to 20 . . . . . . . . . . . . . . . . . . . . . . . . 91 184 D.22. 20 to 21 . . . . . . . . . . . . . . . . . . . . . . . . 92 185 D.23. 21 to 22 . . . . . . . . . . . . . . . . . . . . . . . . 92 186 D.24. 22 to 23 . . . . . . . . . . . . . . . . . . . . . . . . 92 187 D.25. 23 to 24 . . . . . . . . . . . . . . . . . . . . . . . . 93 188 D.26. 24 to 25 . . . . . . . . . . . . . . . . . . . . . . . . 93 189 D.27. 25 to 26 . . . . . . . . . . . . . . . . . . . . . . . . 94 190 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 94 191 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 94 193 1. Introduction 195 A fundamental business requirement for any network operator is to 196 reduce costs where possible. For network operators, deploying 197 devices to many locations can be a significant cost, as sending 198 trained specialists to each site for installations is both cost 199 prohibitive and does not scale. 201 This document defines Secure Zero Touch Provisioning (SZTP), a 202 bootstrapping strategy enabling devices to securely obtain 203 bootstrapping data with no installer action beyond physical placement 204 and connecting network and power cables. As such, SZTP enables non- 205 technical personnel to bring up devices in remote locations without 206 the need for any operator input. 208 The SZTP solution includes updating the boot image, committing an 209 initial configuration, and executing arbitrary scripts to address 210 auxiliary needs. The updated device is subsequently able to 211 establish secure connections with other systems. For instance, a 212 devices may establish NETCONF [RFC8040] and/or RESTCONF [RFC6241] 213 connections with deployment-specific network management systems. 215 This document primarily regards physical devices, where the setting 216 of the device's initial state, described in Section 5.1, occurs 217 during the device's manufacturing process. The SZTP solution may be 218 extended to support virtual machines or other such logical 219 constructs, but details for how this can be accomplished is left for 220 future work. 222 1.1. Use Cases 224 o Device connecting to a remotely administered network 226 This use-case involves scenarios, such as a remote branch 227 office or convenience store, whereby a device connects as an 228 access gateway to an ISP's network. Assuming it is not 229 possible to customize the ISP's network to provide any 230 bootstrapping support, and with no other nearby device to 231 leverage, the device has no recourse but to reach out to an 232 Internet-based bootstrap server to bootstrap from. 234 o Device connecting to a locally administered network 236 This use-case covers all other scenarios and differs only in 237 that the device may additionally leverage nearby devices, which 238 may direct it to use a local service to bootstrap from. If no 239 such information is available, or the device is unable to use 240 the information provided, it can then reach out to the network 241 just as it would for the remotely administered network use- 242 case. 244 Conceptual workflows for how SZTP might be deployed are provided in 245 Appendix C. 247 1.2. Terminology 249 This document uses the following terms (sorted by name): 251 Artifact: The term "artifact" is used throughout to represent any of 252 the three artifacts defined in Section 3 (zero touch information, 253 ownership voucher, and owner certificate). These artifacts 254 collectively provide all the bootstrapping data a device may use. 256 Bootstrapping Data: The term "bootstrapping data" is used throughout 257 this document to refer to the collection of data that a device 258 may obtain during the bootstrapping process. Specifically, it 259 refers to the three artifacts zero touch information, owner 260 certificate, and ownership voucher, as described in Section 3. 262 Bootstrap Server: The term "bootstrap server" is used within this 263 document to mean any RESTCONF server implementing the YANG module 264 defined in Section 7.3. 266 Device: The term "device" is used throughout this document to refer 267 to a network element that needs to be bootstrapped. See 268 Section 5 for more information about devices. 270 Manufacturer: The term "manufacturer" is used herein to refer to the 271 manufacturer of a device or a delegate of the manufacturer. 273 Network Management System (NMS): The acronym "NMS" is used 274 throughout this document to refer to the deployment-specific 275 management system that the bootstrapping process is responsible 276 for introducing devices to. From a device's perspective, when 277 the bootstrapping process has completed, the NMS is a NETCONF or 278 RESTCONF client. 280 Onboarding Information: The term "onboarding information" is used 281 herein to refer to one of the two types of "zero touch 282 information" defined in this document, the other being "redirect 283 information". Onboarding information is formally defined by the 284 "onboarding-information" YANG-data structure in Section 6.3. 286 Onboarding Server: The term "onboarding server" is used herein to 287 refer to a bootstrap server that only returns onboarding 288 information. 290 Owner: The term "owner" is used throughout this document to refer to 291 the person or organization that purchased or otherwise owns a 292 device. 294 Owner Certificate: The term "owner certificate" is used in this 295 document to represent an X.509 certificate that binds an owner 296 identity to a public key, which a device can use to validate a 297 signature over the zero touch information artifact. The owner 298 certificate may be communicated along with its chain of 299 intermediate certificates leading up to a known trust anchor. 300 The owner certificate is one of the three bootstrapping artifacts 301 described in Section 3. 303 Ownership Voucher: The term "ownership voucher" is used in this 304 document to represent the voucher artifact defined in [RFC8366]. 305 The ownership voucher is used to assign a device to an owner. 306 The ownership voucher is one of the three bootstrapping artifacts 307 described in Section 3. 309 Redirect Information: The term "redirect information" is used herein 310 to refer to one of the two types of "zero touch information" 311 defined in this document, the other being "onboarding 312 information". Redirect information is formally defined by the 313 "redirect-information" YANG-data structure in Section 6.3. 315 Redirect Server: The term "redirect server" is used to refer to a 316 bootstrap server that only returns redirect information. A 317 redirect server is particularly useful when hosted by a 318 manufacturer, as a well-known (e.g., Internet-based) resource to 319 redirect devices to deployment-specific bootstrap servers. 321 Signed Data: The term "signed data" is used throughout to mean zero 322 touch information that has been signed, specifically by a private 323 key possessed by a device's owner. 325 Unsigned Data: The term "unsigned data" is used throughout to mean 326 zero touch information that has not been signed. 328 Zero Touch Information: The term "zero touch information" is used 329 herein to refer either redirect information or onboarding 330 information. Zero touch information is one of the three 331 bootstrapping artifacts described in Section 3. 333 1.3. Requirements Language 335 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 336 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 337 "OPTIONAL" in this document are to be interpreted as described in BCP 338 14 [RFC2119] [RFC8174] when, and only when, they appear in all 339 capitals, as shown here. 341 1.4. Tree Diagrams 343 Tree diagrams used in this document follow the notation defined in 344 [RFC8340]. 346 2. Types of Zero Touch Information 348 This document defines two types of zero touch information that 349 devices can access during the bootstrapping process. These zero 350 touch information types are described in this section. Examples are 351 provided in Section 6.2 353 2.1. Redirect Information 355 Redirect information redirects a device to another bootstrap server. 356 Redirect information encodes a list of bootstrap servers, each 357 specifying the bootstrap server's hostname (or IP address), an 358 optional port, and an optional trust anchor certificate that the 359 device can use to authenticate the bootstrap server with. 361 Redirect information is YANG modeled data formally defined by the 362 "redirect-information" container in the YANG module presented in 363 Section 6.3. This container has the tree diagram shown below. 365 +--:(redirect-information) 366 +-- redirect-information 367 +-- bootstrap-server* [address] 368 +-- address inet:host 369 +-- port? inet:port-number 370 +-- trust-anchor? cms 372 Redirect information may be trusted or untrusted. The redirect 373 information is trusted whenever it is obtained via a secure 374 connection to a trusted bootstrap server, or whenever it is signed by 375 the device's owner. In all other cases, the redirect information is 376 untrusted. 378 Trusted redirect information is useful for enabling a device to 379 establish a secure connection to a specified bootstrap server, which 380 is possible when the redirect information includes the bootstrap 381 server's trust anchor certificate. 383 Untrusted redirect information is useful for directing a device to a 384 bootstrap server where signed data has been staged for it to obtain. 386 Note that, when the redirect information is untrusted, devices 387 discard any potentially included trust anchor certificates. 389 How devices process redirect information is described in Section 5.5. 391 2.2. Onboarding Information 393 Onboarding information provides data necessary for a device to 394 bootstrap itself and establish secure connections with other systems. 395 As defined in this document, onboarding information can specify 396 details about the boot image a device must be running, specify an 397 initial configuration the device must commit, and specify scripts 398 that the device must successfully execute. 400 Onboarding information is YANG modeled data formally defined by the 401 "onboarding-information" container in the YANG module presented in 402 Section 6.3. This container has the tree diagram shown below. 404 +--:(onboarding-information) 405 +-- onboarding-information 406 +-- boot-image 407 | +-- os-name? string 408 | +-- os-version? string 409 | +-- download-uri* inet:uri 410 | +-- image-verification* [hash-algorithm] 411 | +-- hash-algorithm identityref 412 | +-- hash-value yang:hex-string 413 +-- configuration-handling? enumeration 414 +-- pre-configuration-script? script 415 +-- configuration? binary 416 +-- post-configuration-script? script 418 Onboarding information must be trusted for it to be of any use to a 419 device. There is no option for a device to process untrusted 420 onboarding information. 422 Onboarding information is trusted whenever it is obtained via a 423 secure connection to a trusted bootstrap server, or whenever it is 424 signed by the device's owner. In all other cases, the onboarding 425 information is untrusted. 427 How devices process onboarding information is described in 428 Section 5.6. 430 3. Artifacts 432 This document defines three artifacts that can be made available to 433 devices while they are bootstrapping. Each source of bootstrapping 434 data specifies how it provides the artifacts defined in this section 435 (see Section 4). 437 3.1. Zero Touch Information 439 The zero touch information artifact encodes the essential 440 bootstrapping data for the device. This artifact is used to encode 441 the redirect information and onboarding information types discussed 442 in Section 2. 444 The zero touch information artifact is a CMS structure, as described 445 in [RFC5652], encoded using ASN.1 distinguished encoding rules (DER), 446 as specified in ITU-T X.690 [ITU.X690.2015]. The CMS structure MUST 447 contain content conforming to the YANG module specified in 448 Section 6.3. 450 The zero touch information CMS structure may encode signed or 451 unsigned bootstrapping data. When the bootstrapping data is signed, 452 it may also be encrypted but, from a terminology perspective, it is 453 still "signed data" Section 1.2. 455 When the zero touch information artifact is unsigned, as it might be 456 when communicated over trusted channels, the CMS structure's top-most 457 content type MUST be one of the OIDs described in Section 10.3 (i.e., 458 id-ct-zerotouchInformationXML or id-ct-zerotouchInformationJSON), or 459 the OID id-data (1.2.840.113549.1.7.1). When the OID id-data is 460 used, the encoding (JSON, XML, etc.) SHOULD be communicated 461 externally. In either case, the associated content is an octet 462 string containing "zerotouch-information" data in the expected 463 encoding. 465 When the zero touch information artifact is signed, as it might be 466 when communicated over untrusted channels, the CMS structure's top- 467 most content type MUST be the OID id-signedData 468 (1.2.840.113549.1.7.2). Furthermore, the inner eContentType MUST be 469 one of the OIDs described in Section 10.3 (i.e., id-ct- 470 zerotouchInformationXML or id-ct-zerotouchInformationJSON), or the 471 OID id-data (1.2.840.113549.1.7.1). When the OID id-data is used, 472 the encoding (JSON, XML, etc.) SHOULD be communicated externally. 473 In either case, the associated content or eContent is an octet string 474 containing "zerotouch-information" data in the expected encoding. 476 When the zero touch information artifact is signed and encrypted, as 477 it might be when communicated over untrusted channels and privacy is 478 important, the CMS structure's top-most content type MUST be the OID 479 id-envelopedData (1.2.840.113549.1.7.3). Furthermore, the 480 encryptedContentInfo's content type MUST be the OID id-signedData 481 (1.2.840.113549.1.7.2), whose eContentType MUST be one of the OIDs 482 described in Section 10.3 (i.e., id-ct-zerotouchInformationXML or id- 483 ct-zerotouchInformationJSON), or the OID id-data 484 (1.2.840.113549.1.7.1). When the OID id-data is used, the encoding 485 (JSON, XML, etc.) SHOULD be communicated externally. In either 486 case, the associated content or eContent is an octet string 487 containing "zerotouch-information" data in the expected encoding. 489 3.2. Owner Certificate 491 The owner certificate artifact is an X.509 certificate [RFC5280] that 492 is used to identify an "owner" (e.g., an organization). The owner 493 certificate can be signed by any certificate authority (CA). The 494 owner certificate either MUST have no Key Usage specified or the Key 495 Usage MUST at least set the "digitalSignature" bit. The values for 496 the owner certificate's "subject" and/or "subjectAltName" are not 497 constrained by this document. 499 The owner certificate is used by a device to verify the signature 500 over the zero touch information artifact (Section 3.1) that the 501 device should have also received, as described in Section 3.5. In 502 particular, the device verifies the signature using the public key in 503 the owner certificate over the content contained within the zero 504 touch information artifact. 506 The owner certificate artifact is formally a CMS structure, as 507 specified by [RFC5652], encoded using ASN.1 distinguished encoding 508 rules (DER), as specified in ITU-T X.690 [ITU.X690.2015]. 510 The owner certificate CMS structure MUST contain the owner 511 certificate itself, as well as all intermediate certificates leading 512 to the "pinned-domain-cert" certificate specified in the ownership 513 voucher. The owner certificate artifact MAY optionally include the 514 "pinned-domain-cert" as well. 516 In order to support devices deployed on private networks, the owner 517 certificate CMS structure MAY also contain suitably fresh, as 518 determined by local policy, revocation objects (e.g., CRLs). Having 519 these revocation objects stapled to the owner certificate may obviate 520 the need for the device to have to download them dynamically using 521 the CRL distribution point or an OCSP responder specified in the 522 associated certificates. 524 When unencrypted, the owner certificate artifact's CMS structure's 525 top-most content type MUST be the OID id-signedData 526 (1.2.840.113549.1.7.2). The inner SignedData structure is the 527 degenerate form, whereby there are no signers, that is commonly used 528 to disseminate certificates and revocation objects. 530 When encrypted, the owner certificate artifact's CMS structure's top- 531 most content type MUST be the OID id-envelopedData 532 (1.2.840.113549.1.7.3), and the encryptedContentInfo's content type 533 MUST be the OID id-signedData (1.2.840.113549.1.7.2), whereby the 534 inner SignedData structure is the degenerate form that has no signers 535 commonly used to disseminate certificates and revocation objects. 537 3.3. Ownership Voucher 539 The ownership voucher artifact is used to securely identify a 540 device's owner, as it is known to the manufacturer. The ownership 541 voucher is signed by the device's manufacturer. 543 The ownership voucher is used to verify the owner certificate 544 (Section 3.2) that the device should have also received, as described 545 in Section 3.5. In particular, the device verifies that the owner 546 certificate has a chain of trust leading to the trusted certificate 547 included in the ownership voucher ("pinned-domain-cert"). Note that 548 this relationship holds even when the owner certificate is a self- 549 signed certificate, and hence also the pinned-domain-cert. 551 When unencrypted, the ownership voucher artifact is as defined in 552 [RFC8366]. As described, it is a CMS structure whose top-most 553 content type MUST be the OID id-signedData (1.2.840.113549.1.7.2), 554 whose eContentType MUST be OID id-ct-animaJSONVoucher 555 (1.2.840.113549.1.9.16.1), or the OID id-data (1.2.840.113549.1.7.1). 556 When the OID id-data is used, the encoding (JSON, XML, etc.) SHOULD 557 be communicated externally. In either case, the associated content 558 is an octet string containing ietf-voucher data in the expected 559 encoding. 561 When encrypted, the ownership voucher artifact's CMS structure's top- 562 most content type MUST be the OID id-envelopedData 563 (1.2.840.113549.1.7.3), and the encryptedContentInfo's content type 564 MUST be the OID id-signedData (1.2.840.113549.1.7.2), whose 565 eContentType MUST be OID id-ct-animaJSONVoucher 566 (1.2.840.113549.1.9.16.1), or the OID id-data (1.2.840.113549.1.7.1). 567 When the OID id-data is used, the encoding (JSON, XML, etc.) SHOULD 568 be communicated externally. In either case, the associated content 569 is an octet string containing ietf-voucher data in the expected 570 encoding. 572 3.4. Artifact Encryption 574 Each of the three artifacts MAY be individually encrypted. 575 Encryption may be important in some environments where the content is 576 considered sensitive. 578 Each of the three artifacts are encrypted in the same way, by the 579 unencrypted form being encapsulated inside a CMS EnvelopedData type. 581 As a consequence, both the zero touch information and ownership 582 voucher artifacts are signed and then encrypted, never encrypted and 583 then signed. 585 This sequencing has the advantage of shrouding the signer's 586 certificate, and ensuring that the owner knows the content being 587 signed. This sequencing further enables the owner to inspect an 588 unencrypted voucher obtained from a manufacturer and then encrypt the 589 voucher later themselves, perhaps while also stapling in current 590 revocation objects, when ready to place the artifact in an unsafe 591 location. 593 When encrypted, the CMS MUST be encrypted using a secure device 594 identity certificate for the device. This certificate MAY be the 595 same as the TLS-level client certificate the device uses when 596 connecting to bootstrap servers. The owner must possess the device's 597 identity certificate at the time of encrypting the data. How the 598 owner comes to posses the device's identity certificate for this 599 purpose is outside the scope of this document. 601 3.5. Artifact Groupings 603 The previous sections discussed the bootstrapping artifacts, but only 604 certain groupings of these artifacts make sense to return in the 605 various bootstrapping situations described in this document. These 606 groupings are: 608 Unsigned Data: This artifact grouping is useful for cases when 609 transport level security can be used to convey trust (e.g., 610 HTTPS), or when the zero touch information can be processed in 611 a provisional manner (i.e. unsigned redirect information). 613 Signed Data, without revocations: This artifact grouping is 614 useful when signed data is needed (i.e., because the data is 615 obtained from an untrusted source and it cannot be processed 616 provisionally) and either revocations are not needed or the 617 revocations can be obtained dynamically. 619 Signed Data, with revocations: This artifact grouping is useful 620 when signed data is needed (i.e., because the data is obtained 621 from an untrusted source and it cannot be processed 622 provisionally), and revocations are needed, and the revocations 623 cannot be obtained dynamically. 625 The presence of each artifact, and any distinguishing 626 characteristics, are identified for each artifact grouping in the 627 table below ("yes/no" regards if the artifact is present in the 628 artifact grouping): 630 +---------------------+---------------+--------------+--------------+ 631 | Artifact | Zero Touch | Ownership | Owner | 632 | Grouping | Information | Voucher | Certificate | 633 +=====================+===============+==============+==============+ 634 | Unsigned Data | Yes, no sig | No | No | 635 +---------------------+---------------+--------------+--------------+ 636 | Signed Data, | Yes, with sig | Yes, without | Yes, without | 637 | without revocations | | revocations | revocations | 638 +---------------------+---------------+--------------+--------------+ 639 | Signed Data, | Yes, with sig | Yes, with | Yes, with | 640 | with revocations | | revocations | revocations | 641 +---------------------+---------------+--------------+--------------+ 643 4. Sources of Bootstrapping Data 645 This section defines some sources for bootstrapping data that a 646 device can access. The list of sources defined here is not meant to 647 be exhaustive. It is left to future documents to define additional 648 sources for obtaining bootstrapping data. 650 For each source of bootstrapping data defined in this section, 651 details are given for how the three artifacts listed in Section 3 are 652 provided. 654 4.1. Removable Storage 656 A directly attached removable storage device (e.g., a USB flash 657 drive) MAY be used as a source of zero touch bootstrapping data. 659 Use of a removable storage device is compelling, as it does not 660 require any external infrastructure to work. It is notable that the 661 raw boot image file can also be located on the removable storage 662 device, enabling a removable storage device to be a fully self- 663 standing bootstrapping solution. 665 To use a removable storage device as a source of bootstrapping data, 666 a device need only detect if the removable storage device is plugged 667 in and mount its filesystem. 669 A removable storage device is an untrusted source of bootstrapping 670 data. This means that the information stored on the removable 671 storage device either MUST be signed or MUST be information that can 672 be processed provisionally (e.g., unsigned redirect information). 674 From an artifact perspective, since a removable storage device 675 presents itself as a filesystem, the bootstrapping artifacts need to 676 be presented as files. The three artifacts defined in Section 3 are 677 mapped to files below. 679 Artifact to File Mapping: 681 Zero Touch Information: Mapped to a file containing the binary 682 artifact described in Section 3.1 (e.g., zerotouch- 683 information.cms). 685 Owner Certificate: Mapped to a file containing the binary 686 artifact described in Section 3.2 (e.g., owner- 687 certificate.cms). 689 Ownership Voucher: Mapped to a file containing the binary 690 artifact described in Section 3.3 (e.g., ownership-voucher.cms 691 or ownership-voucher.vcj). 693 The format of the removable storage device's filesystem and the 694 naming of the files are outside the scope of this document. However, 695 in order to facilitate interoperability, it is RECOMMENDED devices 696 support open and/or standards based filesystems. It is also 697 RECOMMENDED that devices assume a file naming convention that enables 698 more than one instance of bootstrapping data (i.e., for different 699 devices) to exist on a removable storage device. The file naming 700 convention SHOULD additionally be unique to the manufacturer, in 701 order to enable bootstrapping data from multiple manufacturers to 702 exist on a removable storage device. 704 4.2. DNS Server 706 A DNS server MAY be used as a source of zero touch bootstrapping 707 data. 709 Using a DNS server may be a compelling option for deployments having 710 existing DNS infrastructure, as it enables a touchless bootstrapping 711 option that does not entail utilizing an Internet based resource 712 hosted by a 3rd-party. 714 DNS is an untrusted source of bootstrapping data. Even if DNSSEC 715 [RFC6698] is used to authenticate the various DNS resource records 716 (e.g., A, AAAA, CERT, TXT, and TLSA), the device cannot be sure that 717 the domain returned to it from e.g., a DHCP server, belongs to its 718 rightful owner. This means that the information stored in the DNS 719 records either MUST be signed (per this document, not DNSSEC), or 720 MUST be information that can be processed provisionally (e.g., 721 unsigned redirect information). 723 4.2.1. DNS Queries 725 Devices claiming to support DNS as a source of bootstrapping data 726 MUST first query for device-specific DNS records using DNS-SD 727 [RFC6763] and, only if doing so does not result in a successful 728 bootstrap, then query for device-independent records using 729 traditional service discovery [RFC2782]. Furthermore, when issuing 730 the device-specific and device-independent queries, devices MUST 731 first query using multicast DNS [RFC6762] and, only if doing so does 732 not result in a successful bootstrap, then query again using unicast 733 DNS [RFC1035][RFC7766], assuming the address of a DNS server is 734 known. 736 When querying for device-specific DNS records, devices SHOULD 737 immediately query for their instance-specific record, without first 738 querying for PTR records (Section 4.1 of [RFC6763]). Device MUST use 739 their serial number (i.e., the same value as in the device identity 740 certificate) for the "" portion of the service instance 741 name (Section 4.1.1 of [RFC6763]). Device MUST only query for TXT 742 records, in order to access the three bootstrapping artifacts defined 743 in Section 3. 745 When querying for device-independent DNS records, devices MUST only 746 query for SRV records. Multiple SRV records, each specifying an 747 address, port, weight, and priority [RFC2782] is comparable to an 748 unsigned redirect information's list of bootstrap servers. Note that 749 a device-independent response is only able to encode unsigned data, 750 since signed data necessitates the use of a device-specific ownership 751 voucher. Exclusive use of SRV records maximally leverages existing 752 DNS standards for what is likely to be a common case when using a DNS 753 server as a source of bootstrapping data. 755 By example, assuming a device's serial number is "", 756 and that the domain discovered per Section 11 of [RFC6763] is 757 "example.com", the device may issue the following sequence of DNS 758 queries: 760 TXT in ._zerotouch._tcp.local. 761 TXT in ._zerotouch._tcp.example.com. 763 SRV in _zerotouch._tcp.local. 764 SRV in _zerotouch._tcp.example.com. 766 This document registers the service name "zerotouch" in Section 10.6. 768 4.2.2. DNS Response for Device-Specific Queries 770 For device-specific queries, the three bootstrapping artifacts 771 defined in Section 3 are encoded into the TXT records using key/value 772 pairs, as described in Section 6.3 in [RFC6763]. 774 Artifact to TXT Record Mapping: 776 Zero Touch Information: Mapped to a TXT record having the key 777 "zi" and the value being the binary artifact described in 778 Section 3.1. 780 Owner Certificate: Mapped to a TXT record having the key "oc" and 781 the value being the binary artifact described in Section 3.2. 783 Ownership Voucher: Mapped to a TXT record having the key "ov" and 784 the value being the binary artifact described in Section 3.3. 786 Devices MUST ignore any other keys that may be returned. 788 Note that, despite the name, TXT records can and SHOULD (per 789 Section 6.5 of [RFC6763]) encode binary data. 791 Following is an example of a device-specific response, as it might be 792 presented by a user-agent, containing signed data. This example 793 assumes that the device's serial number is "": 795 ._zerotouch._tcp.example.com. 3600 IN TXT "zi=" 796 ._zerotouch._tcp.example.com. 3600 IN TXT "oc=" 797 ._zerotouch._tcp.example.com. 3600 IN TXT "ov=" 799 Note that, in the case that "zi" encodes unsigned data, the "oc" and 800 "ov" keys would not be present in the response. 802 4.2.3. DNS Response for Device-Independent Queries 804 For device-independent queries, the three bootstrapping artifacts 805 defined in Section 3 are encoded into the SVR records as follows. 807 Artifact to SRV Record Mapping: 809 Zero Touch Information: This artifact is not supported directly. 810 Instead, the essence of unsigned redirect information is mapped 811 to SVR records per [RFC2782]. 813 Owner Certificate: Not supported. Device-independent responses 814 are never encode signed data, and hence there is no need for an 815 owner certificate artifact. 817 Ownership Voucher: Not supported. Device-independent responses 818 are never encode signed data, and hence there is no need for an 819 ownership voucher artifact. 821 Following is an example of a device-independent response, as it might 822 be presented by a user-agent, containing (effectively) unsigned 823 redirect information to four bootstrap servers: 825 _zerotouch._tcp.example.com. 1800 IN SRV 0 0 443 sztp1.example.com. 826 _zerotouch._tcp.example.com. 1800 IN SRV 1 0 443 sztp2.example.com. 827 _zerotouch._tcp.example.com. 1800 IN SRV 2 0 443 sztp3.example.com. 828 _zerotouch._tcp.example.com. 1800 IN SRV 2 0 443 sztp4.example.com. 830 Note that, in this example, "sztp3" and "sztp4" have equal priority, 831 and hence effectively represent a clustered pair of bootstrap 832 servers. While "sztp1" and "sztp2" only have a single SRV record 833 each, it may be that the record points to a load-balancer fronting a 834 cluster of bootstrap servers. 836 4.2.4. Size of Signed Data 838 The signed data artifacts are large by DNS conventions. In the 839 smallest-footprint scenario, they are each a few kilobytes in size. 840 However, onboarding information can easily be several kilobytes in 841 size, and has the potential to be many kilobytes in size. 843 All resource records, including TXT records, have an upper size limit 844 of 65535 bytes, since "RDLENGTH" is a 16-bit field (Section 3.2.1 in 845 [RFC1035]). If it is ever desired to encode onboarding information 846 that exceeds this limit, the DNS records returned should instead 847 encode redirect information, to direct the device to a bootstrap 848 server from which the onboarding information can be obtained. 850 Given the expected size of the TXT records, it is unlikely that 851 signed data will fit into a UDP-based DNS packet, even with the 852 EDNS(0) Extensions [RFC6891] enabled. Depending on content, signed 853 data may also not fit into a multicast DNS packet, which bounds the 854 size of the TXT records to 8900 bytes, per Section 6.1 in [RFC6763]. 855 Thus it is expected that DNS Transport over TCP [RFC7766] will be 856 required in order to return signed data. 858 4.3. DHCP Server 860 A DHCP server MAY be used as a source of zero touch bootstrapping 861 data. 863 Using a DHCP server may be a compelling option for deployments having 864 existing DHCP infrastructure, as it enables a touchless bootstrapping 865 option that does not entail utilizing an Internet based resource 866 hosted by a 3rd-party. 868 A DHCP server is an untrusted source of bootstrapping data. Thus the 869 information stored on the DHCP server either MUST be signed, or it 870 MUST be information that can be processed provisionally (e.g., 871 unsigned redirect information). 873 However, unlike other sources of bootstrapping data described in this 874 document, the DHCP protocol (especially DHCP for IPv4) is very 875 limited in the amount of data that can be conveyed, to the extent 876 that signed data cannot be communicated. This means that only 877 unsigned redirect information can be conveyed via DHCP. 879 Since the redirect information is unsigned, it SHOULD NOT include the 880 optional trust anchor certificate, as it takes up space in the DHCP 881 message, and the device would have to discard it anyway. For this 882 reason, the DHCP options defined in Section 8 do not enable the trust 883 anchor certificate to be encoded. 885 From an artifact perspective, the three artifacts defined in 886 Section 3 are mapped to the DHCP fields specified in Section 8 as 887 follows. 889 Artifact to DHCP Option Fields Mapping: 891 Zero Touch Information: This artifact is not supported directly. 892 Instead, the essence of unsigned redirect information is mapped 893 to the DHCP options described in Section 8. 895 Owner Certificate: Not supported. There is not enough space in 896 the DHCP packet to hold an owner certificate artifact. 898 Ownership Voucher: Not supported. There is not enough space in 899 the DHCP packet to hold an ownership voucher artifact. 901 4.4. Bootstrap Server 903 A bootstrap server MAY be used as a source of zero touch 904 bootstrapping data. A bootstrap server is defined as a RESTCONF 905 [RFC8040] server implementing the YANG module provided in Section 7. 907 Using a bootstrap server as a source of bootstrapping data is a 908 compelling option as it MAY use transport-level security, obviating 909 the need for signed data, which may be easier to deploy in some 910 situations. 912 Unlike any other source of bootstrapping data described in this 913 document, a bootstrap server is not only a source of data, but it can 914 also receive data from devices using the YANG-defined "report- 915 progress" RPC defined in the YANG module (Section 7.3). The "report- 916 progress" RPC enables visibility into the bootstrapping process 917 (e.g., warnings and errors), and provides potentially useful 918 information upon completion (e.g., the device's SSH host-keys). 920 A bootstrap server may be a trusted or an untrusted source of 921 bootstrapping data, depending on if the device learned about the 922 bootstrap server's trust anchor from a trusted source. When a 923 bootstrap server is trusted, the zero touch information returned from 924 it MAY be signed. When the bootstrap server is untrusted, the zero 925 touch information either MUST be signed or MUST be information that 926 can be processed provisionally (e.g., unsigned redirect information). 928 From an artifact perspective, since a bootstrap server presents data 929 conforming to a YANG data model, the bootstrapping artifacts need to 930 be mapped to YANG nodes. The three artifacts defined in Section 3 931 are mapped to "output" nodes of the "get-bootstrapping-data" RPC 932 defined in Section 7.3 below. 934 Artifact to Bootstrap Server Mapping: 936 Zero Touch Information: Mapped to the "zerotouch-information" 937 leaf in the output of the "get-bootstrapping-data" RPC. 939 Owner Certificate: Mapped to the "owner-certificate" leaf in the 940 output of the "get-bootstrapping-data" RPC. 942 Ownership Voucher: Mapped to the "ownership-voucher" leaf in the 943 output of the "get-bootstrapping-data" RPC. 945 Zero touch bootstrap servers have only two endpoints, one for the 946 "get-bootstrapping-data" RPC and one for the "report-progress" RPC. 947 These RPCs use the authenticated RESTCONF username to isolate the 948 execution of the RPC from other devices. 950 5. Device Details 952 Devices supporting the bootstrapping strategy described in this 953 document MUST have the preconfigured state and bootstrapping logic 954 described in the following sections. 956 5.1. Initial State 958 +-------------------------------------------------------------+ 959 | | 960 | | 961 | +---------------------------------------------------------+ | 962 | | | | 963 | | | | 964 | | 1. flag to enable zerotouch bootstrapping set to "true" | | 965 | +---------------------------------------------------------+ | 966 | | 967 | +---------------------------------------------------------+ | 968 | | | | 969 | | | | 970 | | 2. TLS client cert & related intermediate certificates | | 971 | | 3. list of trusted well-known bootstrap servers | | 972 | | 4. list of trust anchor certs for bootstrap servers | | 973 | | 5. list of trust anchor certs for ownership vouchers | | 974 | +---------------------------------------------------------+ | 975 | | 976 | +-----------------------------------------------------+ | 977 | | | | 978 | | | | 979 | | 6. private key for TLS client certificate | | 980 | | 7. private key for decrypting zerotouch artifacts | | 981 | +-----------------------------------------------------+ | 982 | | 983 +-------------------------------------------------------------+ 985 Each numbered item below corresponds to a numbered item in the 986 diagram above. 988 1. Devices MUST have a configurable variable that is used to enable/ 989 disable zerotouch bootstrapping. This variable MUST be enabled 990 by default in order for zerotouch bootstrapping to run when the 991 device first powers on. Because it is a goal that the 992 configuration installed by the bootstrapping process disables 993 zerotouch bootstrapping, and because the configuration may be 994 merged into the existing configuration, using a configuration 995 node that relies on presence is NOT RECOMMENDED, as it cannot be 996 removed by the merging process. 998 2. Devices that support loading bootstrapping data from bootstrap 999 servers (see Section 4.4) SHOULD possess a TLS-level client 1000 certificate and any intermediate certificates leading to the 1001 certificate's well-known trust-anchor. The well-known trust 1002 anchor certificate may be an intermediate certificate or a self- 1003 signed root certificate. To support devices not having a client 1004 certificate, devices MAY, alternatively or in addition to, 1005 identify and authenticate themselves to the bootstrap server 1006 using an HTTP authentication scheme, as allowed by Section 2.5 in 1007 [RFC8040]; however, this document does not define a mechanism for 1008 operator input enabling, for example, the entering of a password. 1010 3. Devices that support loading bootstrapping data from well-known 1011 bootstrap servers MUST possess a list of the well-known bootstrap 1012 servers. Consistent with redirect information (Section 2.1, each 1013 bootstrap server can be identified by its hostname or IP address, 1014 and an optional port. 1016 4. Devices that support loading bootstrapping data from well-known 1017 bootstrap servers MUST also possess a list of trust anchor 1018 certificates that can be used to authenticate the well-known 1019 bootstrap servers. For each trust anchor certificate, if it is 1020 not itself a self-signed root certificate, the device SHOULD also 1021 possess the chain of intermediate certificates leading up to and 1022 including the self-signed root certificate. 1024 5. Devices that support loading signed data (see Section 1.2) MUST 1025 possess the trust anchor certificates for validating ownership 1026 vouchers. For each trust anchor certificate, if it is not itself 1027 a self-signed root certificate, the device SHOULD also possess 1028 the chain of intermediate certificates leading up to and 1029 including the self-signed root certificate. 1031 6. Devices that support using a TLS-level client certificate to 1032 identify and authenticate themselves to a bootstrap server MUST 1033 possess the private key that corresponds to the public key 1034 encoded in the TLS-level client certificate. This private key 1035 SHOULD be securely stored, ideally in a cryptographic processor, 1036 such as a trusted platform module (TPM) chip. 1038 7. Devices that support decrypting zerotouch artifacts MUST posses 1039 the private key that corresponds to the public key encoded in the 1040 secure device identity certificate used when encrypting the 1041 artifacts. This private key SHOULD be securely stored, ideally 1042 in a cryptographic processor, such as a trusted platform module 1043 (TPM) chip. This private key MAY be the same as the one 1044 associated to the TLS-level client certificate used when 1045 connecting to bootstrap servers. 1047 A YANG module representing this data is provided in Appendix A. 1049 5.2. Boot Sequence 1051 A device claiming to support the bootstrapping strategy defined in 1052 this document MUST support the boot sequence described in this 1053 section. 1055 Power On 1056 | 1057 v No 1058 1. Zerotouch bootstrapping configured ------> Boot normally 1059 | 1060 | Yes 1061 v 1062 2. For each supported source of bootstrapping data, 1063 try to load bootstrapping data from the source 1064 | 1065 | 1066 v Yes 1067 3. Able to bootstrap from any source? -----> Run with new config 1068 | 1069 | No 1070 v 1071 4. Loop back to Step 1. 1073 Note: At any time, the device MAY be configured via an alternate 1074 provisioning mechanism (e.g., CLI). 1076 Each numbered item below corresponds to a numbered item in the 1077 diagram above. 1079 1. When the device powers on, it first checks to see if zerotouch 1080 bootstrapping is configured, as is expected to be the case for 1081 the device's preconfigured initial state. If zerotouch 1082 bootstrapping is not configured, then the device boots normally. 1084 2. The device iterates over its list of sources for bootstrapping 1085 data (Section 4). Details for how to processes a source of 1086 bootstrapping data are provided in Section 5.3. 1088 3. If the device is able to bootstrap itself from any of the sources 1089 of bootstrapping data, it runs with the new bootstrapped 1090 configuration. 1092 4. Otherwise the device MUST loop back through the list of 1093 bootstrapping sources again. 1095 This document does not limit the simultaneous use of alternate 1096 provisioning mechanisms. Such mechanisms may include, for instance, 1097 a command line interface (CLI), a web-based user interface, or even 1098 another bootstrapping protocol. Regardless how it is configured, the 1099 configuration SHOULD unset the flag enabling zerotouch bootstrapping 1100 discussed in Section 5.1. 1102 5.3. Processing a Source of Bootstrapping Data 1104 This section describes a recursive algorithm that devices can use to, 1105 ultimately, obtain onboarding information. The algorithm is 1106 recursive because sources of bootstrapping data may return redirect 1107 information, which causes the algorithm to run again, for the newly 1108 discovered sources of bootstrapping data. An expression that 1109 captures all possible successful sequences of bootstrapping data is 1110 zero or more redirect information responses, followed by one 1111 onboarding information response. 1113 An important aspect of the algorithm is knowing when data needs to be 1114 signed or not. The following figure provides a summary of options: 1116 Untrusted Source Trusted Source 1117 Kind of Bootstrapping Data Can Provide? Can Provide? 1119 Unsigned Redirect Info : Yes+ Yes 1120 Signed Redirect Info : Yes Yes* 1121 Unsigned Onboarding Info : No Yes 1122 Signed Onboarding Info : Yes Yes* 1124 The '+' above denotes that the source redirected to MUST 1125 return signed data, or more unsigned redirect information. 1127 The '*' above denotes that, while possible, it is generally 1128 unnecessary for a trusted source to return signed data. 1130 The recursive algorithm uses a conceptual global-scoped variable 1131 called "trust-state". The trust-state variable is initialized to 1132 FALSE. The ultimate goal of this algorithm is for the device to 1133 process onboarding information (Section 2.2) while the trust-state 1134 variable is TRUE. 1136 If the source of bootstrapping data (Section 4) is a bootstrap server 1137 (Section 4.4), and the device is able to authenticate the bootstrap 1138 server using X.509 certificate path validation ([RFC6125], Section 6) 1139 to one of the device's preconfigured trust anchors, or to a trust 1140 anchor that it learned from a previous step, then the device MUST set 1141 trust-state to TRUE. 1143 When establishing a connection to a bootstrap server, whether trusted 1144 or untrusted, the device MUST identify and authenticate itself to the 1145 bootstrap server using a TLS-level client certificate and/or an HTTP 1146 authentication scheme, per Section 2.5 in [RFC8040]. If both 1147 authentication mechanisms are used, they MUST both identify the same 1148 serial number. 1150 When sending a client certificate, the device MUST also send all of 1151 the intermediate certificates leading up to, and optionally 1152 including, the client certificate's well-known trust anchor 1153 certificate. 1155 For any source of bootstrapping data (e.g., Section 4), if any 1156 artifact obtained is encrypted, the device MUST first decrypt it 1157 using the private key associated with the device certificate used to 1158 encrypt the artifact. 1160 If the zero touch information artifact is signed, and the device is 1161 able to validate the signed data using the algorithm described in 1162 Section 5.4, then the device MUST set trust-state to TRUE; otherwise, 1163 if the device is unable to validate the signed data, the device MUST 1164 set trust-state to FALSE. Note, this is worded to cover the special 1165 case when signed data is returned even from a trusted source of 1166 bootstrapping data. 1168 If the zero touch information artifact contains redirect information, 1169 the device MUST, within limits of how many recursive loops the device 1170 allows, process the redirect information as described in Section 5.5. 1171 Implementations MUST limit the maximum number of recursive redirects 1172 allowed; the maximum number of recursive redirects allowed SHOULD be 1173 no more than ten. This is the recursion step, it will cause the 1174 device to reenter this algorithm, but this time the data source will 1175 definitely be a bootstrap server, as redirect information is only 1176 able to redirect devices to bootstrap servers. 1178 If the zero touch information artifact contains onboarding 1179 information, and trust-state is FALSE, the device MUST exit the 1180 recursive algorithm (as this is not allowed, see the figure above), 1181 returning to the bootstrapping sequence described in Section 5.2. 1182 Otherwise, the device MUST attempt to process the onboarding 1183 information as described in Section 5.6. In either case, success or 1184 failure, the device MUST exit the recursive algorithm, returning to 1185 the bootstrapping sequence described in Section 5.2, the only 1186 difference being in how it responds to the "Able to bootstrap from 1187 any source?" conditional described in the figure in the section. 1189 5.4. Validating Signed Data 1191 Whenever a device is presented signed data, it MUST validate the 1192 signed data as described in this section. This includes the case 1193 where the signed data is provided by a trusted source. 1195 Whenever there is signed data, the device MUST also be provided an 1196 ownership voucher and an owner certificate. How all the needed 1197 artifacts are provided for each source of bootstrapping data is 1198 described in Section 4. 1200 In order to validate signed data, the device MUST first authenticate 1201 the ownership voucher by validating its signature to one of its 1202 preconfigured trust anchors (see Section 5.1), which may entail using 1203 additional intermediate certificates attached to the ownership 1204 voucher. If the device has an accurate clock, it MUST verify that 1205 the ownership voucher was created in the past (i.e., "created-on" < 1206 now) and, if the "expires-on" leaf is present, the device MUST verify 1207 that the ownership voucher has not yet expired (i.e., now < "expires- 1208 on"). The device MUST verify that the ownership voucher's 1209 "assertion" value is acceptable (e.g., some devices may only accept 1210 the assertion value "verified"). The device MUST verify that the 1211 ownership voucher specifies the device's serial number in the 1212 "serial-number" leaf. If the "idevid-issuer" leaf is present, the 1213 device MUST verify that the value is set correctly. If the 1214 authentication of the ownership voucher is successful, the device 1215 extracts the "pinned-domain-cert" node, an X.509 certificate, that is 1216 needed to verify the owner certificate in the next step. 1218 The device MUST next authenticate the owner certificate by performing 1219 X.509 certificate path verification to the trusted certificate 1220 extracted from the ownership voucher's "pinned-domain-cert" node. 1221 This verification may entail using additional intermediate 1222 certificates attached to the owner certificate artifact. If the 1223 ownership voucher's "domain-cert-revocation-checks" node's value is 1224 set to "true", the device MUST verify the revocation status of the 1225 certificate chain used to sign the owner certificate and, if 1226 suitably-fresh revocation status is unattainable or if it is 1227 determined that a certificate has been revoked, the device MUST NOT 1228 validate the owner certificate. 1230 Finally the device MUST verify the zero touch information artifact 1231 was signed by the validated owner certificate. 1233 If any of these steps fail, the device MUST invalidate the signed 1234 data and not perform any subsequent steps. 1236 5.5. Processing Redirect Information 1238 In order to process redirect information (Section 2.1), the device 1239 MUST follow the steps presented in this section. 1241 Processing redirect information is straightforward; the device 1242 sequentially steps through the list of provided bootstrap servers 1243 until it can find one it can bootstrap from. 1245 If a hostname is provided, and the hostname's DNS resolution is to 1246 more than one IP address, the device MUST attempt to connect to all 1247 of the DNS resolved addresses at least once, before moving on to the 1248 next bootstrap server. If the device is able to obtain bootstrapping 1249 data from any of the DNS resolved addresses, it MUST immediately 1250 process that data, without attempting to connect to any of the other 1251 DNS resolved addresses. 1253 If the redirect information is trusted (e.g., trust-state is TRUE), 1254 and the bootstrap server entry contains a trust anchor certificate, 1255 then the device MUST authenticate the specified bootstrap server's 1256 TLS server certificate using X.509 certificate path validation 1257 ([RFC6125], Section 6) to the specified trust anchor. If the 1258 bootstrap server entry does not contain a trust anchor certificate 1259 device, the device MUST establish a provisional connection to the 1260 bootstrap server (i.e., by blindly accepting its server certificate), 1261 and set trust-state to FALSE. 1263 If the redirect information is untrusted (e.g., trust-state is 1264 FALSE), the device MUST discard any trust anchors provided by the 1265 redirect information and establish a provisional connection to the 1266 bootstrap server (i.e., by blindly accepting its TLS server 1267 certificate). 1269 5.6. Processing Onboarding Information 1271 In order to process onboarding information (Section 2.2), the device 1272 MUST follow the steps presented in this section. 1274 When processing onboarding information, the device MUST first process 1275 the boot image information (if any), then execute the pre- 1276 configuration script (if any), then commit the initial configuration 1277 (if any), and then execute the post-configuration script (if any), in 1278 that order. 1280 When the onboarding information is obtained from a trusted bootstrap 1281 server, the device MUST send the "bootstrap-initiated" progress 1282 report, and send either a terminating "boot-image-installed- 1283 rebooting", "bootstrap-complete", or error specific progress report. 1285 If the bootstrap server's "get-bootstrapping-data" RPC-reply's 1286 "reporting-level" node is set to "verbose", the device MUST 1287 additionally send all appropriate non-terminating progress reports 1288 (e.g., initiated, warning, complete, etc.). Regardless of the 1289 reporting-level indicated by the bootstrap server, the device MAY 1290 send progress reports beyond the mandatory ones specified for the 1291 given reporting level. 1293 When the onboarding information is obtained from an untrusted 1294 bootstrap server, the device MUST NOT send any progress reports to 1295 the bootstrap server. 1297 If the device encounters an error at any step, it MUST stop 1298 processing the onboarding information and return to the bootstrapping 1299 sequence described in Section 5.2. In the context of a recursive 1300 algorithm, the device MUST return to the enclosing loop, not back to 1301 the very beginning. Some state MAY be retained from the 1302 bootstrapping process (e.g., updated boot image, logs, remnants from 1303 a script, etc.). However, the retained state MUST NOT be active in 1304 any way (e.g., no new configuration or running of software), and MUST 1305 NOT hinder the ability for the device to continue the bootstrapping 1306 sequence (i.e., process onboarding information from another bootstrap 1307 server). 1309 At this point, the specific ordered sequence of actions the device 1310 MUST perform is described. 1312 If the onboarding information is obtained from a trusted bootstrap 1313 server, the device MUST send a "bootstrap-initiated" progress report. 1314 It is an error if the device does not receive back the "204 No 1315 Content" HTTP status line. If an error occurs, the device MUST try 1316 to send a "bootstrap-error" progress report before exiting. 1318 The device MUST parse the provided onboarding information document, 1319 to extract values used in subsequent steps. Whether using a stream- 1320 based parser or not, if there is an error when parsing the onboarding 1321 information, and the device is connected to a trusted bootstrap 1322 server, the device MUST try to send a "parsing-error" progress report 1323 before exiting. 1325 If boot image criteria are specified, the device MUST first determine 1326 if the boot image it is running satisfies the specified boot image 1327 criteria. If the device is already running the specified boot image, 1328 then it skips the remainder of this step. If the device is not 1329 running the specified boot image, then it MUST download, verify, and 1330 install, in that order, the specified boot image, and then reboot. 1331 If connected to a trusted bootstrap server, the device MAY try to 1332 send a "boot-image-mismatch" progress report. To download the boot 1333 image, the device MUST only use the URIs supplied by the onboarding 1334 information. To verify the boot image, the device MUST either use 1335 one of the verification fingerprints supplied by the onboarding 1336 information, or use a cryptographic signature embedded into the boot 1337 image itself using a mechanism not described by this document. 1338 Before rebooting, if connected to a trusted bootstrap server, the 1339 device MUST try to send a "boot-image-installed-rebooting" progress 1340 report. Upon rebooting, the bootstrapping process runs again, which 1341 will eventually come to this step again, but then the device will be 1342 running the specified boot image, and thus will move to processing 1343 the next step. If an error occurs at any step while the device is 1344 connected to a trusted bootstrap server (i.e., before the reboot), 1345 the device MUST try to send a "boot-image-error" progress report 1346 before exiting. 1348 If a pre-configuration script has been specified, the device MUST 1349 execute the script, capture any output emitted from the script, and 1350 check if the script had any warnings or errors. If an error occurs 1351 while the device is connected to a trusted bootstrap server, the 1352 device MUST try to send a "pre-script-error" progress report before 1353 exiting. 1355 If an initial configuration has been specified, the device MUST 1356 atomically commit the provided initial configuration, using the 1357 approach specified by the "configuration-handling" leaf. If an error 1358 occurs while the device is connected to a trusted bootstrap server, 1359 the device MUST try to send a "config-error" progress report before 1360 exiting. 1362 If a post-configuration script has been specified, the device MUST 1363 execute the script, capture any output emitted from the script, and 1364 check if the script had any warnings or errors. If an error occurs 1365 while the device is connected to a trusted bootstrap server, the 1366 device MUST try to send a "post-script-error" progress report before 1367 exiting. 1369 If the onboarding information was obtained from a trusted bootstrap 1370 server, and the result of the bootstrapping process did not disable 1371 the "flag to enable zerotouch bootstrapping" described in 1372 Section 5.1, the device SHOULD send an "bootstrap-warning" progress 1373 report. 1375 If the onboarding information was obtained from a trusted bootstrap 1376 server, the device MUST send a "bootstrap-complete" progress report. 1377 It is an error if the device does not receive back the "204 No 1378 Content" HTTP status line. If an error occurs, the device MUST try 1379 to send a "bootstrap-error" progress report before exiting. 1381 At this point, the device has completely processed the bootstrapping 1382 data. 1384 The device is now running its initial configuration. Notably, if 1385 NETCONF Call Home or RESTCONF Call Home [RFC8071] is configured, the 1386 device initiates trying to establish the call home connections at 1387 this time. 1389 Implementation Notes: 1391 Implementations may vary in how to ensure no unwanted state is 1392 retained when an error occurs. 1394 Following are some guidelines for if the implementation chooses to 1395 undo previous steps: 1397 * When an error occurs, the device must rollback the current step 1398 and any previous steps. 1400 * Most steps are atomic. For example, the processing 1401 configuration is specified as atomic above, and the processing 1402 scripts is similarly specified as atomic in the "ietf- 1403 zerotouch-information" YANG module. 1405 * In case the error occurs after the initial configuration was 1406 committed, the device must restore the configuration to the 1407 configuration that existed prior to the configuration being 1408 committed. 1410 * In case the error occurs after a script had executed 1411 successfully, it may be helpful for the implementation to 1412 define scripts as being able to take a conceptual input 1413 parameter indicating that the script should remove its 1414 previously set state. 1416 6. The Zero Touch Information Data Model 1418 This section defines a YANG 1.1 [RFC7950] module that is used to 1419 define the data model for the zero touch information artifact 1420 described in Section 3.1. This data model uses the "yang-data" 1421 extension statement defined in [I-D.ietf-netmod-yang-data-ext]. 1422 Examples illustrating this data model are provided in Section 6.2. 1424 6.1. Data Model Overview 1426 The following tree diagram provides an overview of the data model for 1427 the zero touch information artifact. 1429 module: ietf-zerotouch-information 1431 yang-data zerotouch-information: 1432 +-- (information-type) 1433 +--:(redirect-information) 1434 | +-- redirect-information 1435 | +-- bootstrap-server* [address] 1436 | +-- address inet:host 1437 | +-- port? inet:port-number 1438 | +-- trust-anchor? cms 1439 +--:(onboarding-information) 1440 +-- onboarding-information 1441 +-- boot-image 1442 | +-- os-name? string 1443 | +-- os-version? string 1444 | +-- download-uri* inet:uri 1445 | +-- image-verification* [hash-algorithm] 1446 | +-- hash-algorithm identityref 1447 | +-- hash-value yang:hex-string 1448 +-- configuration-handling? enumeration 1449 +-- pre-configuration-script? script 1450 +-- configuration? binary 1451 +-- post-configuration-script? script 1453 6.2. Example Usage 1455 The following example illustrates how redirect information 1456 (Section 2.1) can be encoded using JSON. 1458 { 1459 "ietf-zerotouch-information:redirect-information" : { 1460 "bootstrap-server" : [ 1461 { 1462 "address" : "phs1.example.com", 1463 "port" : 8443, 1464 "trust-anchor" : "base64encodedvalue==" 1465 }, 1466 { 1467 "address" : "phs2.example.com", 1468 "port" : 8443, 1469 "trust-anchor" : "base64encodedvalue==" 1470 }, 1471 { 1472 "address" : "phs3.example.com", 1473 "port" : 8443, 1474 "trust-anchor" : "base64encodedvalue==" 1475 } 1476 ] 1477 } 1478 } 1480 The following example illustrates how onboarding information 1481 (Section 2.2) can be encoded using JSON. 1483 [Note: '\' line wrapping for formatting only] 1485 { 1486 "ietf-zerotouch-information:onboarding-information" : { 1487 "boot-image" : { 1488 "os-name" : "VendorOS", 1489 "os-version" : "17.2R1.6", 1490 "download-uri" : [ "http://some/path/to/raw/file" ], 1491 "image-verification" : [ 1492 { 1493 "hash-algorithm" : "ietf-zerotouch-information:sha-256", 1494 "hash-value" : "ba:ec:cf:a5:67:82:b4:10:77:c6:67:a6:22:ab:\ 1495 7d:50:04:a7:8b:8f:0e:db:02:8b:f4:75:55:fb:c1:13:b2:33" 1496 } 1497 ] 1498 }, 1499 "configuration-handling" : "merge", 1500 "pre-configuration-script" : "base64encodedvalue==", 1501 "configuration" : "base64encodedvalue==", 1502 "post-configuration-script" : "base64encodedvalue==" 1503 } 1504 } 1506 6.3. YANG Module 1508 The zero touch information data model is defined by the YANG module 1509 presented in this section. 1511 This module uses data types defined in [RFC5280], [RFC5652], 1512 [RFC6234], and [RFC6991], an extension statement from 1513 [I-D.ietf-netmod-yang-data-ext], and an encoding defined in 1514 [ITU.X690.2015]. 1516 file "ietf-zerotouch-information@2018-12-20.yang" 1517 module ietf-zerotouch-information { 1518 yang-version 1.1; 1519 namespace "urn:ietf:params:xml:ns:yang:ietf-zerotouch-information"; 1520 prefix zti; 1522 import ietf-yang-types { 1523 prefix yang; 1524 reference "RFC 6991: Common YANG Data Types"; 1525 } 1526 import ietf-inet-types { 1527 prefix inet; 1528 reference "RFC 6991: Common YANG Data Types"; 1529 } 1530 import ietf-yang-data-ext { 1531 prefix yd; 1532 reference "I-D.ietf-netmod-yang-data-ext: YANG Data Extensions"; 1533 } 1535 organization 1536 "IETF NETCONF (Network Configuration) Working Group"; 1538 contact 1539 "WG Web: http://tools.ietf.org/wg/netconf 1540 WG List: 1541 Author: Kent Watsen "; 1543 description 1544 "This module defines the data model for the Zero Touch 1545 Information artifact defined in RFC XXXX: Zero Touch 1546 Provisioning for Networking Devices. 1548 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1549 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1550 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1551 are to be interpreted as described in BCP 14 [RFC2119] 1552 [RFC8174] when, and only when, they appear in all 1553 capitals, as shown here. 1555 Copyright (c) 2019 IETF Trust and the persons identified as 1556 authors of the code. All rights reserved. 1558 Redistribution and use in source and binary forms, with or 1559 without modification, is permitted pursuant to, and subject 1560 to the license terms contained in, the Simplified BSD License 1561 set forth in Section 4.c of the IETF Trust's Legal Provisions 1562 Relating to IETF Documents (http://trustee.ietf.org/license-info) 1564 This version of this YANG module is part of RFC XXXX; see the 1565 RFC itself for full legal notices."; 1567 revision 2018-12-20 { 1568 description 1569 "Initial version"; 1570 reference 1571 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 1572 } 1574 // identities 1576 identity hash-algorithm { 1577 description 1578 "A base identity for hash algorithm verification"; 1579 } 1581 identity sha-256 { 1582 base "hash-algorithm"; 1583 description "The SHA-256 algorithm."; 1584 reference "RFC 6234: US Secure Hash Algorithms."; 1585 } 1587 // typedefs 1589 typedef cms { 1590 type binary; 1591 description 1592 "A ContentInfo structure, as specified in RFC 5652, 1593 encoded using ASN.1 distinguished encoding rules (DER), 1594 as specified in ITU-T X.690."; 1595 reference 1596 "RFC 5652: 1597 Cryptographic Message Syntax (CMS) 1598 ITU-T X.690: 1599 Information technology - ASN.1 encoding rules: 1600 Specification of Basic Encoding Rules (BER), 1601 Canonical Encoding Rules (CER) and Distinguished 1602 Encoding Rules (DER)."; 1604 } 1606 // yang-data 1608 yd:yang-data "zerotouch-information" { 1609 choice information-type { 1610 mandatory true; 1611 description 1612 "This choice statement ensures the response contains 1613 redirect-information or onboarding-information."; 1614 container redirect-information { 1615 description 1616 "Redirect information is described in Section 2.1 in 1617 RFC XXXX. Its purpose is to redirect a device to 1618 another bootstrap server."; 1619 reference 1620 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 1621 list bootstrap-server { 1622 key "address"; 1623 min-elements 1; 1624 description 1625 "A bootstrap server entry."; 1626 leaf address { 1627 type inet:host; 1628 mandatory true; 1629 description 1630 "The IP address or hostname of the bootstrap server the 1631 device should redirect to."; 1632 } 1633 leaf port { 1634 type inet:port-number; 1635 default "443"; 1636 description 1637 "The port number the bootstrap server listens on. If no 1638 port is specified, the IANA-assigned port for 'https' 1639 (443) is used."; 1640 } 1641 leaf trust-anchor { 1642 type cms; 1643 description 1644 "A CMS structure that MUST contain the chain of 1645 X.509 certificates needed to authenticate the TLS 1646 certificate presented by this bootstrap server. 1648 The CMS MUST only contain a single chain of 1649 certificates. The bootstrap server MUST only 1650 authenticate to last intermediate CA certificate 1651 listed in the chain. 1653 In all cases, the chain MUST include a self-signed 1654 root certificate. In the case where the root 1655 certificate is itself the issuer of the bootstrap 1656 server's TLS certificate, only one certificate 1657 is present. 1659 If needed by the device, this CMS structure MAY 1660 also contain suitably fresh revocation objects 1661 with which the device can verify the revocation 1662 status of the certificates. 1664 This CMS encodes the degenerate form of the SignedData 1665 structure that is commonly used to disseminate X.509 1666 certificates and revocation objects (RFC 5280)."; 1667 reference 1668 "RFC 5280: 1669 Internet X.509 Public Key Infrastructure Certificate 1670 and Certificate Revocation List (CRL) Profile."; 1671 } 1672 } 1673 } 1674 container onboarding-information { 1675 description 1676 "Onboarding information is described in Section 2.2 in 1677 RFC XXXX. Its purpose is to provide the device everything 1678 it needs to bootstrap itself."; 1679 reference 1680 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 1681 container boot-image { 1682 description 1683 "Specifies criteria for the boot image the device MUST 1684 be running, as well as information enabling the device 1685 to install the required boot image."; 1686 leaf os-name { 1687 type string; 1688 description 1689 "The name of the operating system software the device 1690 MUST be running in order to not require a software 1691 image upgrade (ex. VendorOS)."; 1692 } 1693 leaf os-version { 1694 type string; 1695 description 1696 "The version of the operating system software the 1697 device MUST be running in order to not require a 1698 software image upgrade (ex. 17.3R2.1)."; 1699 } 1700 leaf-list download-uri { 1701 type inet:uri; 1702 ordered-by user; 1703 description 1704 "An ordered list of URIs to where the same boot image 1705 file may be obtained. How the URI schemes (http, ftp, 1706 etc.) a device supports are known is vendor specific. 1707 If a secure scheme (e.g., https) is provided, a device 1708 MAY establish an untrusted connection to the remote 1709 server, by blindly accepting the server's end-entity 1710 certificate, to obtain the boot image."; 1711 } 1712 list image-verification { 1713 must '../download-uri' { 1714 description 1715 "Download URIs must be provided if an image is to 1716 be verified."; 1717 } 1718 key hash-algorithm; 1719 description 1720 "A list of hash values that a device can use to verify 1721 boot image files with."; 1722 leaf hash-algorithm { 1723 type identityref { 1724 base "hash-algorithm"; 1725 } 1726 description 1727 "Identifies the hash algorithm used."; 1728 } 1729 leaf hash-value { 1730 type yang:hex-string; 1731 mandatory true; 1732 description 1733 "The hex-encoded value of the specified hash 1734 algorithm over the contents of the boot image 1735 file."; 1736 } 1737 } 1738 } 1739 leaf configuration-handling { 1740 type enumeration { 1741 enum "merge" { 1742 description 1743 "Merge configuration into the running datastore."; 1744 } 1745 enum "replace" { 1746 description 1747 "Replace the existing running datastore with the 1748 passed configuration."; 1750 } 1751 } 1752 must '../configuration'; 1753 description 1754 "This enumeration indicates how the server should process 1755 the provided configuration."; 1756 } 1757 leaf pre-configuration-script { 1758 type script; 1759 description 1760 "A script that, when present, is executed before the 1761 configuration has been processed."; 1762 } 1763 leaf configuration { 1764 type binary; 1765 must '../configuration-handling'; 1766 description 1767 "Any configuration known to the device. The use of 1768 the 'binary' type enables e.g., XML-content to be 1769 embedded into a JSON document. The exact encoding 1770 of the content, as with the scripts, is vendor 1771 specific."; 1772 } 1773 leaf post-configuration-script { 1774 type script; 1775 description 1776 "A script that, when present, is executed after the 1777 configuration has been processed."; 1778 } 1779 } 1780 } 1781 } 1783 typedef script { 1784 type binary; 1785 description 1786 "A device specific script that enables the execution of 1787 commands to perform actions not possible thru configuration 1788 alone. 1790 No attempt is made to standardize the contents, running 1791 context, or programming language of the script, other than 1792 that it can indicate if any warnings or errors occurred and 1793 can emit output. The contents of the script are considered 1794 specific to the vendor, product line, and/or model of the 1795 device. 1797 If the script execution indicates that an warning occurred, 1798 then the device MUST assume that the script had a soft error 1799 that the script believes will not affect manageability. 1801 If the script execution indicates that an error occurred, 1802 the device MUST assume the script had a hard error that the 1803 script believes will affect manageability. In this case, 1804 the script is required to gracefully exit, removing any 1805 state that might hinder the device's ability to continue 1806 the bootstrapping sequence (e.g., process onboarding 1807 information obtained from another bootstrap server)."; 1808 } 1809 } 1810 1812 7. The Zero Touch Bootstrap Server API 1814 This section defines the API for bootstrap servers. The API is 1815 defined as that produced by a RESTCONF [RFC8040] server that supports 1816 the YANG 1.1 [RFC7950] module defined in this section. 1818 7.1. API Overview 1820 The following tree diagram provides an overview for the bootstrap 1821 server RESTCONF API. 1823 module: ietf-zerotouch-bootstrap-server 1825 rpcs: 1826 +---x get-bootstrapping-data 1827 | +---w input 1828 | | +---w untrusted-connection? empty 1829 | | +---w hw-model? string 1830 | | +---w os-name? string 1831 | | +---w os-version? string 1832 | | +---w nonce? binary 1833 | +--ro output 1834 | +--ro reporting-level? enumeration 1835 | +--ro zerotouch-information cms 1836 | +--ro owner-certificate? cms 1837 | +--ro ownership-voucher? cms 1838 +---x report-progress 1839 +---w input 1840 +---w progress-type enumeration 1841 +---w message? string 1842 +---w ssh-host-keys 1843 | +---w ssh-host-key* [] 1844 | +---w algorithm string 1845 | +---w key-data binary 1846 +---w trust-anchor-certs 1847 +---w trust-anchor-cert* cms 1849 7.2. Example Usage 1851 This section presents three examples illustrating the bootstrap 1852 server's API. Two examples are provided for the "get-bootstrapping- 1853 data" RPC (once to an untrusted bootstrap server, and again to a 1854 trusted bootstrap server), and one example for the "report-progress" 1855 RPC. 1857 The following example illustrates a device using the API to fetch its 1858 bootstrapping data from a untrusted bootstrap server. In this 1859 example, the device sends the "untrusted-connection" input parameter 1860 and receives signed data in the response. 1862 REQUEST 1863 ------- 1864 ['\' line wrapping added for formatting only] 1866 POST /restconf/operations/ietf-zerotouch-bootstrap-server:get-boot\ 1867 strapping-data HTTP/1.1 1868 HOST: example.com 1869 Content-Type: application/yang.data+xml 1871 1873 1874 1876 RESPONSE 1877 -------- 1879 HTTP/1.1 200 OK 1880 Date: Sat, 31 Oct 2015 17:02:40 GMT 1881 Server: example-server 1882 Content-Type: application/yang.data+xml 1884 1886 base64encodedvalue== 1887 base64encodedvalue== 1888 base64encodedvalue== 1889 1891 The following example illustrates a device using the API to fetch its 1892 bootstrapping data from a trusted bootstrap server. In this example, 1893 the device sends addition input parameters to the bootstrap server, 1894 which it may use when formulating its response to the device. 1896 REQUEST 1897 ------- 1898 ['\' line wrapping added for formatting only] 1900 POST /restconf/operations/ietf-zerotouch-bootstrap-server:get-boot\ 1901 strapping-data HTTP/1.1 1902 HOST: example.com 1903 Content-Type: application/yang.data+xml 1905 1907 model-x 1908 vendor-os 1909 17.3R2.1 1910 base64encodedvalue== 1911 1913 RESPONSE 1914 -------- 1916 HTTP/1.1 200 OK 1917 Date: Sat, 31 Oct 2015 17:02:40 GMT 1918 Server: example-server 1919 Content-Type: application/yang.data+xml 1921 1923 verbose 1924 base64encodedvalue== 1925 1927 The following example illustrates a device using the API to post a 1928 progress report to a bootstrap server. Illustrated below is the 1929 "bootstrap-complete" message, but the device may send other progress 1930 reports to the server while bootstrapping. In this example, the 1931 device is sending both its SSH host keys and a TLS server 1932 certificate, which the bootstrap server may, for example, pass to an 1933 NMS, as discussed in Appendix C.3. 1935 REQUEST 1936 ------- 1937 ['\' line wrapping added for formatting only] 1939 POST /restconf/operations/ietf-zerotouch-bootstrap-server:report-\ 1940 progress HTTP/1.1 1941 HOST: example.com 1942 Content-Type: application/yang.data+xml 1944 1946 bootstrap-complete 1947 example message 1948 1949 1950 ssh-rsa 1951 base64encodedvalue== 1952 1953 1954 rsa-sha2-256 1955 base64encodedvalue== 1956 1957 1958 1959 base64encodedvalue== 1960 1961 1963 RESPONSE 1964 -------- 1966 HTTP/1.1 204 No Content 1967 Date: Sat, 31 Oct 2015 17:02:40 GMT 1968 Server: example-server 1970 7.3. YANG Module 1972 The bootstrap server's device-facing API is normatively defined by 1973 the YANG module defined in this section. 1975 This module uses data types defined in [RFC4253], [RFC5652], 1976 [RFC5280], [RFC6960], and [RFC8366], uses an encoding defined in 1977 [ITU.X690.2015], and makes a reference to [RFC4250] and [RFC6187]. 1979 file "ietf-zerotouch-bootstrap-server@2018-12-20.yang" 1980 module ietf-zerotouch-bootstrap-server { 1981 yang-version 1.1; 1982 namespace 1983 "urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server"; 1984 prefix ztbs; 1986 organization 1987 "IETF NETCONF (Network Configuration) Working Group"; 1989 contact 1990 "WG Web: 1991 WG List: 1992 Author: Kent Watsen "; 1994 description 1995 "This module defines an interface for bootstrap servers, as 1996 defined by RFC XXXX: Zero Touch Provisioning for Networking 1997 Devices. 1999 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 2000 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 2001 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 2002 are to be interpreted as described in BCP 14 [RFC2119] 2003 [RFC8174] when, and only when, they appear in all 2004 capitals, as shown here. 2006 Copyright (c) 2019 IETF Trust and the persons identified as 2007 authors of the code. All rights reserved. 2009 Redistribution and use in source and binary forms, with or 2010 without modification, is permitted pursuant to, and subject 2011 to the license terms contained in, the Simplified BSD License 2012 set forth in Section 4.c of the IETF Trust's Legal Provisions 2013 Relating to IETF Documents (http://trustee.ietf.org/license-info) 2015 This version of this YANG module is part of RFC XXXX; see the 2016 RFC itself for full legal notices."; 2018 revision 2018-12-20 { 2019 description 2020 "Initial version"; 2021 reference 2022 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 2023 } 2025 // typedefs 2027 typedef cms { 2028 type binary; 2029 description 2030 "A CMS structure, as specified in RFC 5652, encoded using 2031 ASN.1 distinguished encoding rules (DER), as specified in 2032 ITU-T X.690."; 2033 reference 2034 "RFC 5652: 2035 Cryptographic Message Syntax (CMS) 2036 ITU-T X.690: 2037 Information technology - ASN.1 encoding rules: 2038 Specification of Basic Encoding Rules (BER), 2039 Canonical Encoding Rules (CER) and Distinguished 2040 Encoding Rules (DER)."; 2041 } 2043 // RPCs 2045 rpc get-bootstrapping-data { 2046 description 2047 "This RPC enables a device, as identified by the RESTCONF 2048 username, to obtain bootstrapping data that has been made 2049 available for it."; 2050 input { 2051 leaf untrusted-connection { 2052 type empty; 2053 description 2054 "This optional input parameter enables a device to 2055 communicate to the bootstrap server that it is unable to 2056 authenticate the bootstrap server's TLS certificate. In 2057 such circumstances, the device likely does not send any 2058 of the other input parameters, except for the 'nonce' 2059 parameter. Upon receiving this input parameter, the 2060 bootstrap server should only return unsigned redirect 2061 information or signed data of any type."; 2062 } 2063 leaf hw-model { 2064 type string; 2065 description 2066 "This optional input parameter enables a device to 2067 communicate to the bootstrap server its vendor specific 2068 hardware model number. This parameter may be needed, 2069 for instance, when a device's IDevID certificate does 2070 not include the 'hardwareModelName' value in its 2071 subjectAltName field, as is allowed by 802.1AR-2009."; 2072 reference 2073 "IEEE 802.1AR-2009: IEEE Standard for Local and 2074 metropolitan area networks - Secure Device Identity"; 2075 } 2076 leaf os-name { 2077 type string; 2078 description 2079 "This optional input parameter enables a device to 2080 communicate to the bootstrap server the name of its 2081 operating system. This parameter may be useful if 2082 the device, as identified by its serial number, can 2083 run more than one type of operating system (e.g., 2084 on a white-box system."; 2085 } 2086 leaf os-version { 2087 type string; 2088 description 2089 "This optional input parameter enables a device to 2090 communicate to the bootstrap server the version of its 2091 operating system. This parameter may be used by a 2092 bootstrap server to return an operating system specific 2093 response to the device, thus negating the need for a 2094 potentially expensive boot-image update."; 2095 } 2096 leaf nonce { 2097 type binary { 2098 length "8..32"; 2099 } 2100 description 2101 "This optional input parameter enables a device to 2102 communicate to the bootstrap server a nonce value. 2103 This may be especially useful for devices lacking 2104 an accurate clock, as then the bootstrap server 2105 can dynamically obtain from the manufacturer a 2106 voucher with the nonce value in it, as described 2107 in RFC 8366."; 2108 reference 2109 "RFC 8366: 2110 A Voucher Artifact for Bootstrapping Protocols"; 2111 } 2112 } 2113 output { 2114 leaf reporting-level { 2115 type enumeration { 2116 enum standard { 2117 description 2118 "Send just the progress reports required by RFC XXXX."; 2119 } 2120 enum verbose { 2121 description 2122 "Send additional progress reports that might help 2123 troubleshooting an SZTP bootstrapping issue."; 2124 } 2125 } 2126 default standard; 2127 description 2128 "Specifies the reporting level for progress reports the 2129 bootstrap server would like to receive when processing 2130 onboarding information. Progress reports are not sent 2131 when processing redirect information, or when the 2132 bootstrap server is untrusted (e.g., device sent the 2133 '' input parameter)."; 2134 } 2135 leaf zerotouch-information { 2136 type cms; 2137 mandatory true; 2138 description 2139 "A zero touch information artifact, as described in 2140 Section 3.1 of RFC XXXX."; 2141 reference 2142 "RFC XXXX: 2143 Zero Touch Provisioning for Networking Devices"; 2144 } 2145 leaf owner-certificate { 2146 type cms; 2147 must '../ownership-voucher' { 2148 description 2149 "An ownership voucher must be present whenever an owner 2150 certificate is presented."; 2151 } 2152 description 2153 "An owner certificate artifact, as described in Section 2154 3.2 of RFC XXXX. This leaf is optional because it is 2155 only needed when the zero touch information artifact 2156 is signed."; 2157 reference 2158 "RFC XXXX: 2159 Zero Touch Provisioning for Networking Devices"; 2160 } 2161 leaf ownership-voucher { 2162 type cms; 2163 must '../owner-certificate' { 2164 description 2165 "An owner certificate must be present whenever an 2166 ownership voucher is presented."; 2167 } 2168 description 2169 "An ownership voucher artifact, as described by Section 2170 3.3 of RFC XXXX. This leaf is optional because it is 2171 only needed when the zero touch information artifact 2172 is signed."; 2173 reference 2174 "RFC XXXX: 2176 Zero Touch Provisioning for Networking Devices"; 2177 } 2178 } 2179 } 2181 rpc report-progress { 2182 description 2183 "This RPC enables a device, as identified by the RESTCONF 2184 username, to report its bootstrapping progress to the 2185 bootstrap server. This RPC is expected to be used when 2186 the device obtains onboarding-information from a trusted 2187 bootstap server."; 2188 input { 2189 leaf progress-type { 2190 type enumeration { 2191 enum "bootstrap-initiated" { 2192 description 2193 "Indicates that the device just used the 2194 'get-bootstrapping-data' RPC. The 'message' node 2195 below MAY contain any additional information that 2196 the manufacturer thinks might be useful."; 2197 } 2198 enum "parsing-initiated" { 2199 description 2200 "Indicates that the device is about to start parsing 2201 the onboarding information. This progress type is 2202 only for when parsing is implemented as a distinct 2203 step."; 2204 } 2205 enum "parsing-warning" { 2206 description 2207 "Indicates that the device had a non-fatal error when 2208 parsing the response from the bootstrap server. The 2209 'message' node below SHOULD indicate the specific 2210 warning that occurred."; 2211 } 2212 enum "parsing-error" { 2213 description 2214 "Indicates that the device encountered a fatal error 2215 when parsing the response from the bootstrap server. 2216 For instance, this could be due to malformed encoding, 2217 the device expecting signed data when only unsigned 2218 data is provided, the ownership voucher not listing 2219 the device's serial number, or because the signature 2220 didn't match. The 'message' node below SHOULD 2221 indicate the specific error. This progress type 2222 also indicates that the device has abandoned trying 2223 to bootstrap off this bootstrap server."; 2225 } 2226 enum "parsing-complete" { 2227 description 2228 "Indicates that the device successfully completed 2229 parsing the onboarding information. This progress 2230 type is only for when parsing is implemented as a 2231 distinct step."; 2232 } 2233 enum "boot-image-initiated" { 2234 description 2235 "Indicates that the device is about to start 2236 processing the boot-image information."; 2237 } 2238 enum "boot-image-warning" { 2239 description 2240 "Indicates that the device encountered a non-fatal 2241 error condition when trying to install a boot-image. 2242 A possible reason might include a need to reformat a 2243 partition causing loss of data. The 'message' node 2244 below SHOULD indicate any warning messages that were 2245 generated."; 2246 } 2247 enum "boot-image-error" { 2248 description 2249 "Indicates that the device encountered an error when 2250 trying to install a boot-image, which could be for 2251 reasons such as a file server being unreachable, 2252 file not found, signature mismatch, etc. The 2253 'message' node SHOULD indicate the specific error 2254 that occurred. This progress type also indicates 2255 that the device has abandoned trying to bootstrap 2256 off this bootstrap server."; 2257 } 2258 enum "boot-image-mismatch" { 2259 description 2260 "Indicates that the device that has determined that 2261 it is not running the correct boot image. This 2262 message SHOULD precipitate trying to download 2263 a boot image."; 2264 } 2265 enum "boot-image-installed-rebooting" { 2266 description 2267 "Indicates that the device successfully installed 2268 a new boot image and is about to reboot. After 2269 sending this progress type, the device is not 2270 expected to access the bootstrap server again 2271 for this bootrapping attempt. The device may 2272 access this bootstrap server after rebooting 2273 and restarting the zerotouch bootstrapping 2274 process."; 2275 } 2276 enum "boot-image-complete" { 2277 description 2278 "Indicates that the device believes that it is 2279 running the correct boot-image."; 2280 } 2281 enum "pre-script-initiated" { 2282 description 2283 "Indicates that the device is about to execute the 2284 'pre-configuration-script'."; 2285 } 2286 enum "pre-script-warning" { 2287 description 2288 "Indicates that the device obtained a warning from the 2289 'pre-configuration-script' when it was executed. The 2290 'message' node below SHOULD capture any output the 2291 script produces."; 2292 } 2293 enum "pre-script-error" { 2294 description 2295 "Indicates that the device obtained an error from the 2296 'pre-configuration-script' when it was executed. The 2297 'message' node below SHOULD capture any output the 2298 script produces. This progress type also indicates 2299 that the device has abandoned trying to bootstrap 2300 off this bootstrap server."; 2301 } 2302 enum "pre-script-complete" { 2303 description 2304 "Indicates that the device successfully executed the 2305 'pre-configuration-script'."; 2306 } 2307 enum "config-initiated" { 2308 description 2309 "Indicates that the device is about to commit the 2310 initial configuration."; 2311 } 2312 enum "config-warning" { 2313 description 2314 "Indicates that the device obtained warning messages 2315 when it committed the initial configuration. The 2316 'message' node below SHOULD indicate any warning 2317 messages that were generated."; 2318 } 2319 enum "config-error" { 2320 description 2321 "Indicates that the device obtained error messages 2322 when it committed the initial configuration. The 2323 'message' node below SHOULD indicate the error 2324 messages that were generated. This progress type 2325 also indicates that the device has abandoned trying 2326 to bootstrap off this bootstrap server."; 2327 } 2328 enum "config-complete" { 2329 description 2330 "Indicates that the device successfully committed 2331 the initial configuration."; 2332 } 2333 enum "post-script-initiated" { 2334 description 2335 "Indicates that the device is about to execute the 2336 'post-configuration-script'."; 2337 } 2338 enum "post-script-warning" { 2339 description 2340 "Indicates that the device obtained a warning from the 2341 'post-configuration-script' when it was executed. The 2342 'message' node below SHOULD capture any output the 2343 script produces."; 2344 } 2345 enum "post-script-error" { 2346 description 2347 "Indicates that the device obtained an error from the 2348 'post-configuration-script' when it was executed. The 2349 'message' node below SHOULD capture any output the 2350 script produces. This progress type also indicates 2351 that the device has abandoned trying to bootstrap 2352 off this bootstrap server."; 2353 } 2354 enum "post-script-complete" { 2355 description 2356 "Indicates that the device successfully executed the 2357 'post-configuration-script'."; 2358 } 2359 enum "bootstrap-warning" { 2360 description 2361 "Indicates that a warning condition occurred for which 2362 there no other 'progress-type' enumeration is deemed 2363 suitable. The 'message' node below SHOULD describe 2364 the warning."; 2365 } 2366 enum "bootstrap-error" { 2367 description 2368 "Indicates that an error condition occurred for which 2369 there no other 'progress-type' enumeration is deemed 2370 suitable. The 'message' node below SHOULD describe 2371 the error. This progress type also indicates that 2372 the device has abandoned trying to bootstrap off 2373 this bootstrap server."; 2374 } 2375 enum "bootstrap-complete" { 2376 description 2377 "Indicates that the device successfully processed 2378 all 'onboarding-information' provided, and that it 2379 is ready to be managed. The 'message' node below 2380 MAY contain any additional information that the 2381 manufacturer thinks might be useful. After sending 2382 this progress type, the device is not expected to 2383 access the bootstrap server again."; 2384 } 2385 enum "informational" { 2386 description 2387 "Indicates any additional information not captured 2388 by any of the other progress types. For instance, 2389 a message indicating that the device is about to 2390 reboot after having installed a boot-image could 2391 be provided. The 'message' node below SHOULD 2392 contain information that the manufacturer thinks 2393 might be useful."; 2394 } 2395 } 2396 mandatory true; 2397 description 2398 "The type of progress report provided."; 2399 } 2400 leaf message { 2401 type string; 2402 description 2403 "An optional arbitrary value."; 2404 } 2405 container ssh-host-keys { 2406 when "../progress-type = 'bootstrap-complete'" { 2407 description 2408 "SSH host keys are only sent when the progress type 2409 is 'bootstrap-complete'."; 2410 } 2411 description 2412 "A list of SSH host keys an NMS may use to authenticate 2413 subsequent SSH-based connections to this device (e.g., 2414 netconf-ssh, netconf-ch-ssh)."; 2415 list ssh-host-key { 2416 description 2417 "An SSH host key an NMS may use to authenticate 2418 subsequent SSH-based connections to this device 2419 (e.g., netconf-ssh, netconf-ch-ssh)."; 2420 reference 2421 "RFC 4253: The Secure Shell (SSH) Transport Layer 2422 Protocol"; 2423 leaf algorithm { 2424 type string; 2425 mandatory true; 2426 description 2427 "The public key algorithm name for this SSH key. 2429 Valid values are listed in the 'Public Key Algorithm 2430 Names' subregistry of the 'Secure Shell (SSH) Protocol 2431 Parameters' registry maintained by IANA."; 2432 reference 2433 "RFC 4250: The Secure Shell (SSH) Protocol Assigned 2434 Numbers 2435 IANA URL: https://www.iana.org/assignments/ssh-param\\ 2436 eters/ssh-parameters.xhtml#ssh-parameters-19 2437 ('\\' added for formatting reasons)"; 2438 } 2439 leaf key-data { 2440 type binary; 2441 mandatory true; 2442 description 2443 "The binary public key data for this SSH key, as 2444 specified by RFC 4253, Section 6.6, i.e.: 2446 string certificate or public key format 2447 identifier 2448 byte[n] key/certificate data."; 2449 reference 2450 "RFC 4253: The Secure Shell (SSH) Transport Layer 2451 Protocol"; 2452 } 2453 } 2454 } 2455 container trust-anchor-certs { 2456 when "../progress-type = 'bootstrap-complete'" { 2457 description 2458 "Trust anchors are only sent when the progress type 2459 is 'bootstrap-complete'."; 2460 } 2461 description 2462 "A list of trust anchor certificates an NMS may use to 2463 authenticate subsequent certificate-based connections 2464 to this device (e.g., restconf-tls, netconf-tls, or 2465 even netconf-ssh with X.509 support from RFC 6187). 2466 In practice, trust anchors for IDevID certificates do 2467 not need to be conveyed using this mechanism."; 2468 reference 2469 "RFC 6187: 2470 X.509v3 Certificates for Secure Shell Authentication."; 2471 leaf-list trust-anchor-cert { 2472 type cms; 2473 description 2474 "A CMS structure whose top-most content type MUST be the 2475 signed-data content type, as described by Section 5 in 2476 RFC 5652. 2478 The CMS MUST contain the chain of X.509 certificates 2479 needed to authenticate the certificate presented by 2480 the device. 2482 The CMS MUST contain only a single chain of 2483 certificates. The device's end-entity certificate 2484 MUST only authenticate to the last intermediate CA 2485 certificate listed in the chain. 2487 In all cases, the chain MUST include a self-signed 2488 root certificate. In the case where the root 2489 certificate is itself the issuer of the device's 2490 end-entity certificate, only one certificate is 2491 present. 2493 This CMS encodes the degenerate form of the SignedData 2494 structure that is commonly used to disseminate X.509 2495 certificates and revocation objects (RFC 5280)."; 2496 reference 2497 "RFC 5280: 2498 Internet X.509 Public Key Infrastructure 2499 Certificate and Certificate Revocation List (CRL) 2500 Profile. 2501 RFC 5652: 2502 Cryptographic Message Syntax (CMS)"; 2503 } 2504 } 2505 } 2506 } 2507 } 2508 2510 8. DHCP Zero Touch Options 2512 This section defines two DHCP options, one for DHCPv4 and one for 2513 DHCPv6. These two options are semantically the same, though 2514 syntactically different. 2516 8.1. DHCPv4 Zero Touch Option 2518 The DHCPv4 Zero Touch Option is used to provision the client with one 2519 or more URIs for bootstrap servers that can be contacted to attempt 2520 further configuration. 2522 DHCPv4 Zero Touch Redirect Option 2524 0 1 2525 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 2526 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2527 | option-code (143) | option-length | 2528 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2529 . . 2530 . bootstrap-server-list (variable length) . 2531 . . 2532 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2534 o option-code: OPTION_V4_ZEROTOUCH_REDIRECT (143) 2535 o option-length: The option length in octets. 2536 o bootstrap-server-list: A list of servers for the 2537 client to attempt contacting, in order to obtain 2538 further bootstrapping data, in the format shown 2539 in Section 8.3. 2541 DHCPv4 Client Behavior 2543 Clients MAY request the OPTION_V4_ZEROTOUCH_REDIRECT by including its 2544 option code in the Parameter Request List (55) in DHCP request 2545 messages. 2547 On receipt of a DHCPv4 Reply message which contains the 2548 OPTION_V4_ZEROTOUCH_REDIRECT, the client processes the response 2549 according to Section 5.5, with the understanding that the "address" 2550 and "port" values are encoded in the URIs. 2552 Any invalid URI entries received in the uri-data field are ignored by 2553 the client. If OPTION_V4_ZEROTOUCH_REDIRECT does not contain at 2554 least one valid URI entry in the uri-data field, then the client MUST 2555 discard the option. 2557 As the list of URIs may exceed the maximum allowed length of a single 2558 DHCPv4 option (255 octets), the client MUST implement [RFC3396], 2559 allowing the URI list to be split across a number of 2560 OPTION_V4_ZEROTOUCH_REDIRECT option instances. 2562 DHCPv4 Server Behavior 2564 The DHCPv4 server MAY include a single instance of Option 2565 OPTION_V4_ZEROTOUCH_REDIRECT in DHCP messages it sends. Servers MUST 2566 NOT send more than one instance of the OPTION_V4_ZEROTOUCH_REDIRECT 2567 option. 2569 The server's DHCP message MUST contain only a single instance of the 2570 OPTION_V4_ZEROTOUCH_REDIRECT's 'bootstrap-server-list' field. 2571 However, the list of URIs in this field may exceed the maximum 2572 allowed length of a single DHCPv4 option (per [RFC3396]). 2574 If the length of 'bootstrap-server-list' is small enough to fit into 2575 a single instance of OPTION_V4_ZEROTOUCH_REDIRECT, the server MUST 2576 NOT send more than one instance of this option. 2578 If the length of the 'bootstrap-server-list' field is too large to 2579 fit into a single option, then OPTION_V4_ZEROTOUCH_REDIRECT MUST be 2580 split into multiple instances of the option according to the process 2581 described in [RFC3396]. 2583 8.2. DHCPv6 Zero Touch Option 2585 The DHCPv6 Zero Touch Option is used to provision the client with one 2586 or more URIs for bootstrap servers that can be contacted to attempt 2587 further configuration. 2589 DHCPv6 Zero Touch Redirect Option 2591 0 1 2 3 2592 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 2593 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2594 | option-code (136) | option-length | 2595 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2596 . bootstrap-server-list (variable length) . 2597 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2599 o option-code: OPTION_V6_ZEROTOUCH_REDIRECT (136) 2600 o option-length: The option length in octets. 2601 o bootstrap-server-list: A list of servers for the client to 2602 attempt contacting, in order to obtain further bootstrapping 2603 data, in the format shown in Section 8.3. 2605 DHCPv6 Client Behavior 2607 Clients MAY request the OPTION_V6_ZEROTOUCH_REDIRECT option, as 2608 defined in [RFC8415], Sections 18.2.1, 18.2.2, 18.2.4, 18.2.5, 2609 18.2.6, and 21.7. As a convenience to the reader, we mention here 2610 that the client includes requested option codes in the Option Request 2611 Option. 2613 On receipt of a DHCPv6 Reply message which contains the 2614 OPTION_V6_ZEROTOUCH_REDIRECT, the client processes the response 2615 according to Section 5.5, with the understanding that the "address" 2616 and "port" values are encoded in the URIs. 2618 Any invalid URI entries received in the uri-data field are ignored by 2619 the client. If OPTION_V6_ZEROTOUCH_REDIRECT does not contain at 2620 least one valid URI entry in the uri-data field, then the client MUST 2621 discard the option. 2623 DHCPv6 Server Behavior 2625 Section 18.3 of [RFC8415] governs server operation in regard to 2626 option assignment. As a convenience to the reader, we mention here 2627 that the server will send a particular option code only if configured 2628 with specific values for that option code and if the client requested 2629 it. 2631 Option OPTION_V6_ZEROTOUCH_REDIRECT is a singleton. Servers MUST NOT 2632 send more than one instance of the OPTION_V6_ZEROTOUCH_REDIRECT 2633 option. 2635 8.3. Common Field Encoding 2637 Both of the DHCPv4 and DHCPv6 options defined in this section encode 2638 a list of bootstrap server URIs. The "URI" structure is an option 2639 that can contain multiple URIs (see [RFC7227], Section 5.7). Each 2640 URI entry in the bootstrap-server-list is structured as follows: 2642 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 2643 | uri-length | URI | 2644 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 2646 o uri-length: 2 octets long, specifies the length of the URI data. 2648 o URI: URI of zerotouch bootstrap server, using the HTTPS URI 2649 scheme defined in Section 2.7.2 of RFC7230. URI MUST be in 2650 form "https://[:]". 2652 9. Security Considerations 2654 9.1. Clock Sensitivity 2656 The solution in this document relies on TLS certificates, owner 2657 certificates, and ownership vouchers, all of which require an 2658 accurate clock in order to be processed correctly (e.g., to test 2659 validity dates and revocation status). Implementations SHOULD ensure 2660 devices have an accurate clock when shipped from manufacturing 2661 facilities, and take steps to prevent clock tampering. 2663 If it is not possible to ensure clock accuracy, it is RECOMMENDED 2664 that implementations disable the aspects of the solution having clock 2665 sensitivity. In particular, such implementations should assume that 2666 TLS certificates, ownership vouchers, and owner certificates never 2667 expire and are not revokable. From an ownership voucher perspective, 2668 manufacturers SHOULD issue a single ownership voucher for the 2669 lifetime of such devices. 2671 Implementations SHOULD NOT rely on NTP for time, as NTP is not a 2672 secure protocol at this time. Note, there is an IETF work-in- 2673 progress to secure NTP [I-D.ietf-ntp-using-nts-for-ntp]. 2675 9.2. Use of IDevID Certificates 2677 IDevID certificates, as defined in [Std-802.1AR-2009], are 2678 RECOMMENDED, both for the TLS-level client certificate used by 2679 devices when connecting to a bootstrap server, as well as for the 2680 device identity certificate used by owners when encrypting the zero 2681 touch artifacts. 2683 9.3. Immutable Storage for Trust Anchors 2685 Devices MUST ensure that all their trust anchor certificates, 2686 including those for connecting to bootstrap servers and verifying 2687 ownership vouchers, are protected from external modification. 2689 It may be necessary to update these certificates over time (e.g., the 2690 manufacturer wants to delegate trust to a new CA). It is therefore 2691 expected that devices MAY update these trust anchors when needed 2692 through a verifiable process, such as a software upgrade using signed 2693 software images. 2695 9.4. Secure Storage for Long-lived Private Keys 2697 Manufacturer-generated device identifiers may have very long 2698 lifetimes. For instance, [Std-802.1AR-2009] recommends using the 2699 "notAfter" value 99991231235959Z in IDevID certificates. Given the 2700 long-lived nature of these private keys, it is paramount that they 2701 are stored so as to resist discovery, such as in a secure 2702 cryptographic processor, such as a trusted platform module (TPM) 2703 chip. 2705 9.5. Blindly Authenticating a Bootstrap Server 2707 This document allows a device to blindly authenticate a bootstrap 2708 server's TLS certificate. It does so to allow for cases where the 2709 redirect information may be obtained in an unsecured manner, which is 2710 desirable to support in some cases. 2712 To compensate for this, this document requires that devices, when 2713 connected to an untrusted bootstrap server, assert that data 2714 downloaded from the server is signed. 2716 9.6. Disclosing Information to Untrusted Servers 2718 This document allows devices to establish connections to untrusted 2719 bootstrap servers. However, since the bootstrap server is untrusted, 2720 it may be under the control of an adversary, and therefore devices 2721 SHOULD be cautious about the data they send to the bootstrap server 2722 in such cases. 2724 Devices send different data to bootstrap servers at each of the 2725 protocol layers TCP, TLS, HTTP, and RESTCONF. 2727 At the TCP protocol layer, devices may relay their IP address, 2728 subject to network translations. Disclosure of this information is 2729 not considered a security risk. 2731 At the TLS protocol layer, devices may use a client certificate to 2732 identify and authenticate themselves to untrusted bootstrap servers. 2733 At a minimum, the client certificate must disclose the device's 2734 serial number, and may disclose additional information such as the 2735 device's manufacturer, hardware model, public key, etc. Knowledge of 2736 this information may provide an adversary with details needed to 2737 launch an attack. It is RECOMMENDED that secrecy of the network 2738 constituency is not relied on for security. 2740 At the HTTP protocol layer, devices may use an HTTP authentication 2741 scheme to identify and authenticate themselves to untrusted bootstrap 2742 servers. At a minimum, the authentication scheme must disclose the 2743 device's serial number and, concerningly, may, depending on the 2744 authentication mechanism used, reveal a secret that is only supposed 2745 to be known to the device (e.g., a password). Devices SHOULD NOT use 2746 an HTTP authentication scheme (e.g., HTTP Basic) with an untrusted 2747 bootstrap server that reveals a secret that is only supposed to be 2748 known to the device. 2750 At the RESTCONF protocol layer, devices use the "get-bootstrapping- 2751 data" RPC, but not the "report-progress" RPC, when connected to an 2752 untrusted bootstrap server. The "get-bootstrapping-data" RPC allows 2753 additional input parameters to be passed to the bootstrap server 2754 (e.g., "os-name", "os-version", "hw-model"). It is RECOMMENDED that 2755 devices only pass the "untrusted-connection" input parameter to an 2756 untrusted bootstrap server. While it is okay for a bootstrap server 2757 to immediately return signed onboarding information, it is 2758 RECOMMENDED that bootstrap servers instead promote the untrusted 2759 connection to a trusted connection, as described in Appendix B, thus 2760 enabling the device to use the "report-progress" RPC while processing 2761 the onboarding information. 2763 9.7. Sequencing Sources of Bootstrapping Data 2765 For devices supporting more than one source for bootstrapping data, 2766 no particular sequencing order has to be observed for security 2767 reasons, as the solution for each source is considered equally 2768 secure. However, from a privacy perspective, it is RECOMMENDED that 2769 devices access local sources before accessing remote sources. 2771 9.8. Safety of Private Keys used for Trust 2773 The solution presented in this document enables bootstrapping data to 2774 be trusted in two ways, either through transport level security or 2775 through the signing of artifacts. 2777 When transport level security (i.e., a trusted bootstrap server) is 2778 used, the private key for the end-entity certificate must be online 2779 in order to establish the TLS connection. 2781 When artifacts are signed, the signing key is required to be online 2782 only when the bootstrap server is returning a dynamically generated 2783 signed-data response. For instance, a bootstrap server, upon 2784 receiving the "untrusted-connection" input parameter to the "get- 2785 bootstrapping-data" RPC, may dynamically generate a response that is 2786 signed. 2788 Bootstrap server administrators are RECOMMENDED to follow best 2789 practice to protect the private key used for any online operation. 2790 For instance, use of a hardware security module (HSM) is RECOMMENDED. 2791 If an HSM is not used, frequent private key refreshes are 2792 RECOMMENDED, assuming all bootstrapping devices have an accurate 2793 clock (see Section 9.1). 2795 For best security, it is RECOMMENDED that owners only provide 2796 bootstrapping data that has been signed, using a protected private 2797 key, and encrypted, using the device's public key from its secure 2798 device identity certificate. 2800 9.9. Increased Reliance on Manufacturers 2802 The zero touch bootstrapping protocol presented in this document 2803 shifts some control of initial configuration away from the rightful 2804 owner of the device and towards the manufacturer and its delegates. 2806 The manufacturer maintains the list of well-known bootstrap servers 2807 its devices will trust. By design, if no bootstrapping data is found 2808 via other methods first, the device will try to reach out to the 2809 well-known bootstrap servers. There is no mechanism to prevent this 2810 from occurring other than by using an external firewall to block such 2811 connections. Concerns related to trusted bootstrap servers are 2812 discussed in Section 9.10. 2814 Similarly, the manufacturer maintains the list of voucher signing 2815 authorities its devices will trust. The voucher signing authorities 2816 issue the vouchers that enable a device to trust an owner's domain 2817 certificate. It is vital that manufacturers ensure the integrity of 2818 these voucher signing authorities, so as to avoid incorrect 2819 assignments. 2821 Operators should be aware that this system assumes that they trust 2822 all the pre-configured bootstrap servers and voucher signing 2823 authorities designated by the manufacturers. While operators may use 2824 points in the network to block access to the well-known bootstrap 2825 servers, operators cannot prevent voucher signing authorities from 2826 generating vouchers for their devices. 2828 9.10. Concerns with Trusted Bootstrap Servers 2830 Trusted bootstrap servers, whether well-known or discovered, have the 2831 potential to cause problems, such as the following. 2833 o A trusted bootstrap server that has been compromised may be 2834 modified to return unsigned data of any sort. For instance, a 2835 bootstrap server that is only suppose to return redirect 2836 information might be modified to return onboarding information. 2837 Similarly, a bootstrap server that is only supposed to return 2838 signed data, may be modified to return unsigned data. In both 2839 cases, the device will accept the response, unaware that it wasn't 2840 supposed to be any different. It is RECOMMENDED that maintainers 2841 of trusted bootstrap servers ensure that their systems are not 2842 easily compromised and, in case of compromise, have mechanisms in 2843 place to detect and remediate the compromise as expediently as 2844 possible. 2846 o A trusted bootstrap server hosting either unsigned or signed but 2847 not encrypted data may disclose information to unwanted parties 2848 (e.g., an administrator of the bootstrap server). This is a 2849 privacy issue only, but could reveal information that might be 2850 used in a subsequent attack. Disclosure of redirect information 2851 has limited exposure (it is just a list of bootstrap servers), 2852 whereas disclosure of onboarding information could be highly 2853 revealing (e.g., network topology, firewall policies, etc.). It 2854 is RECOMMENDED that operators encrypt the bootstrapping data when 2855 its contents are considered sensitive, even to the administrators 2856 of a bootstrap server. 2858 9.11. Validity Period for Zero Touch Information 2860 Zero touch information does not specify a validity period. For 2861 instance, neither redirect information nor onboarding information 2862 enable "not-before" or "not-after" values to be specified, and 2863 neither artifact alone can be revoked. 2865 For unsigned data provided by an untrusted source of bootstrapping 2866 data, it is not meaningful to discuss its validity period when the 2867 information itself has no authenticity and may have come from 2868 anywhere. 2870 For unsigned data provided by a trusted source of bootstrapping data 2871 (i.e., a bootstrap server), the availability of the data is the only 2872 measure of it being current. Since the untrusted data comes from a 2873 trusted source, its current availability is meaningful and, since 2874 bootstrap servers use TLS, the contents of the exchange cannot be 2875 modified or replayed. 2877 For signed data, whether provided by an untrusted or trusted source 2878 of bootstrapping data, the validity is constrained by the validity of 2879 the both the ownership voucher and owner certificate used to 2880 authenticate it. 2882 The ownership voucher's validity is primarily constrained by the 2883 ownership voucher's "created-on" and "expires-on" nodes. While 2884 [RFC8366] recommends short-lived vouchers (see Section 6.1), the 2885 "expires-on" node may be set to any point in the future, or omitted 2886 altogether to indicate that the voucher never expires. The ownership 2887 voucher's validity is secondarily constrained by the manufacturer's 2888 PKI used to sign the voucher; whilst an ownership voucher cannot be 2889 revoked directly, the PKI used to sign it may be. 2891 The owner certificate's validity is primarily constrained by the 2892 X.509's validity field, the "notBefore" and "notAfter" values, as 2893 specified by the certificate authority that signed it. The owner 2894 certificate's validity is secondarily constrained by the validity of 2895 the PKI used to sign the voucher. Owner certificates may be revoked 2896 directly. 2898 For owners that wish to have maximum flexibility in their ability to 2899 specify and constrain the validity of signed data, it is RECOMMENDED 2900 that a unique owner certificate is created for each signed artifact. 2901 Not only does this enable a validity period to be specified, for each 2902 artifact, but it also enables to the validity of each artifact to be 2903 revoked. 2905 9.12. The "ietf-zerotouch-information" YANG Module 2907 The ietf-zerotouch-information module defined in this document 2908 defines a data structure that is always wrapped by a CMS structure. 2909 When accessed by a secure mechanism (e.g., protected by TLS), then 2910 the CMS structure may be unsigned. However, when accessed by an 2911 insecure mechanism (e.g., removable storage device), then the CMS 2912 structure must be signed, in order for the device to trust it. 2914 Implementations should be aware that signed bootstrapping data only 2915 protects the data from modification, and that the contents are still 2916 visible to others. This doesn't affect security so much as privacy. 2917 That the contents may be read by unintended parties when accessed by 2918 insecure mechanisms is considered next. 2920 The ietf-zerotouch-information module defines a top-level "choice" 2921 statement that declares the contents are either "redirect- 2922 information" or "onboarding-information". Each of these two cases 2923 are now considered. 2925 When the content of the CMS structure is redirect-information, an 2926 observer can learn about the bootstrap servers the device is being 2927 directed to, their IP addresses or hostnames, ports, and trust anchor 2928 certificates. Knowledge of this information could provide an 2929 observer some insight into a network's inner structure. 2931 When the content of the CMS structure is onboarding information, an 2932 observer could learn considerable information about how the device is 2933 to be provisioned. This information includes the operating system 2934 version, initial configuration, and script contents. This 2935 information should be considered sensitive and precautions should be 2936 taken to protect it (e.g., encrypt the artifact using the device's 2937 public key). 2939 9.13. The "ietf-zerotouch-bootstrap-server" YANG Module 2941 The ietf-zerotouch-bootstrap-server module defined in this document 2942 specifies an API for a RESTCONF [RFC8040]. The lowest RESTCONF layer 2943 is HTTPS, and the mandatory-to-implement secure transport is TLS 2944 [RFC8446]. 2946 The NETCONF Access Control Model (NACM) [RFC8341] provides the means 2947 to restrict access for particular users to a preconfigured subset of 2948 all available protocol operations and content. 2950 This module presents no data nodes (only RPCs). There is no need to 2951 discuss the sensitivity of data nodes. 2953 This module defines two RPC operations that may be considered 2954 sensitive in some network environments. These are the operations and 2955 their sensitivity/vulnerability: 2957 get-bootstrapping-data: This RPC is used by devices to obtain their 2958 bootstrapping data. By design, each device, as identified by its 2959 authentication credentials (e.g. client certificate), can only 2960 obtain its own data. NACM is not needed to further constrain 2961 access to this RPC. 2963 report-progress: This RPC is used by devices to report their 2964 bootstrapping progress. By design, each device, as identified by 2965 its authentication credentials (e.g. client certificate), can 2966 only report data for itself. NACM is not needed to further 2967 constrain access to this RPC. 2969 10. IANA Considerations 2971 10.1. The IETF XML Registry 2973 This document registers two URIs in the "ns" subregistry of the IETF 2974 XML Registry [RFC3688] maintained at 2975 https://www.iana.org/assignments/xml-registry/xml-registry.xhtml#ns. 2976 Following the format in [RFC3688], the following registrations are 2977 requested: 2979 URI: urn:ietf:params:xml:ns:yang:ietf-zerotouch-information 2980 Registrant Contact: The NETCONF WG of the IETF. 2981 XML: N/A, the requested URI is an XML namespace. 2983 URI: urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server 2984 Registrant Contact: The NETCONF WG of the IETF. 2985 XML: N/A, the requested URI is an XML namespace. 2987 10.2. The YANG Module Names Registry 2989 This document registers two YANG modules in the YANG Module Names 2990 registry [RFC6020] maintained at https://www.iana.org/assignments/ 2991 yang-parameters/yang-parameters.xhtml. Following the format defined 2992 in [RFC6020], the below registrations are requested: 2994 name: ietf-zerotouch-information 2995 namespace: urn:ietf:params:xml:ns:yang:ietf-zerotouch-information 2996 prefix: zti 2997 reference: RFC XXXX 2999 name: ietf-zerotouch-bootstrap-server 3000 namespace: urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-\ 3001 server (note: '\' used for formatting reasons only) 3002 prefix: ztbs 3003 reference: RFC XXXX 3005 10.3. The SMI Security for S/MIME CMS Content Type Registry 3007 This document registers two SMI security codes in the "SMI Security 3008 for S/MIME CMS Content Type" registry (1.2.840.113549.1.9.16.1) 3009 maintained at https://www.iana.org/assignments/smi-numbers/smi- 3010 numbers.xhtml#security-smime-1. Following the format used in 3011 Section 3.4 of [RFC7107], the below registrations are requested: 3013 Decimal Description References 3014 ------- -------------------------------------- ---------- 3015 TBD1 id-ct-zerotouchInformationXML [RFCXXXX] 3016 TBD2 id-ct-zerotouchInformationJSON [RFCXXXX] 3018 id-ct-zerotouchInformationXML indicates that the "zerotouch- 3019 information" is encoded using XML. id-ct-zerotouchInformationJSON 3020 indicates that the "zerotouch-information" is encoded using JSON. 3022 10.4. The BOOTP Manufacturer Extensions and DHCP Options Registry 3024 This document registers one DHCP code point in the "BOOTP 3025 Manufacturer Extensions and DHCP Options" registry maintained at 3026 http://www.iana.org/assignments/bootp-dhcp-parameters. Following the 3027 format used by other registrations, the below registration is 3028 requested: 3030 Tag: 143 3031 Name: OPTION_V4_ZEROTOUCH_REDIRECT 3032 Data Length: N 3033 Meaning: This option provides a list of URIs 3034 for zero touch bootstrap servers 3035 Reference: [RFCXXXX] 3037 Note: this request is to make permanent a previously registered early 3038 code point allocation. 3040 10.5. The Dynamic Host Configuration Protocol for IPv6 (DHCPv6) 3041 Registry 3043 This document registers one DHCP code point in "Option Codes" 3044 subregistry of the "Dynamic Host Configuration Protocol for IPv6 3045 (DHCPv6)" registry maintained at http://www.iana.org/assignments/ 3046 dhcpv6-parameters. Following the format used by other registrations, 3047 the below registration is requested: 3049 Value: 136 3050 Description: OPTION_V6_ZEROTOUCH_REDIRECT 3051 Client ORO: Yes 3052 Singleton Option: Yes 3053 Reference: [RFCXXXX] 3055 Note: this request is to make permanent a previously registered early 3056 code point allocation. 3058 10.6. The Service Name and Transport Protocol Port Number Registry 3060 This document registers one service name in the Service Name and 3061 Transport Protocol Port Number Registry [RFC6335] maintained at 3062 https://www.iana.org/assignments/service-names-port-numbers/service- 3063 names-port-numbers.xhtml. Following the format defined in 3064 Section 8.1.1 of [RFC6335], the below registration is requested: 3066 Service Name: zerotouch 3067 Transport Protocol(s): TCP 3068 Assignee: IESG 3069 Contact: IETF Chair 3070 Description: This service name is used to construct the 3071 SRV service label "_zerotouch" for discovery 3072 of zero touch bootstrap servers. 3073 Reference: [RFCXXXX] 3074 Port Number: N/A 3075 Service Code: N/A 3076 Known Unauthorized Uses: N/A 3077 Assignment Notes: This protocol uses HTTPS as a substrate. 3079 11. References 3081 11.1. Normative References 3083 [I-D.ietf-netmod-yang-data-ext] 3084 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data 3085 Extensions", draft-ietf-netmod-yang-data-ext-01 (work in 3086 progress), March 2018. 3088 [ITU.X690.2015] 3089 International Telecommunication Union, "Information 3090 Technology - ASN.1 encoding rules: Specification of Basic 3091 Encoding Rules (BER), Canonical Encoding Rules (CER) and 3092 Distinguished Encoding Rules (DER)", ITU-T Recommendation 3093 X.690, ISO/IEC 8825-1, August 2015, 3094 . 3096 [RFC1035] Mockapetris, P., "Domain names - implementation and 3097 specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, 3098 November 1987, . 3100 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3101 Requirement Levels", BCP 14, RFC 2119, 3102 DOI 10.17487/RFC2119, March 1997, 3103 . 3105 [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for 3106 specifying the location of services (DNS SRV)", RFC 2782, 3107 DOI 10.17487/RFC2782, February 2000, 3108 . 3110 [RFC3396] Lemon, T. and S. Cheshire, "Encoding Long Options in the 3111 Dynamic Host Configuration Protocol (DHCPv4)", RFC 3396, 3112 DOI 10.17487/RFC3396, November 2002, 3113 . 3115 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 3116 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, 3117 January 2006, . 3119 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3120 Housley, R., and W. Polk, "Internet X.509 Public Key 3121 Infrastructure Certificate and Certificate Revocation List 3122 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3123 . 3125 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 3126 RFC 5652, DOI 10.17487/RFC5652, September 2009, 3127 . 3129 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 3130 the Network Configuration Protocol (NETCONF)", RFC 6020, 3131 DOI 10.17487/RFC6020, October 2010, 3132 . 3134 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3135 Verification of Domain-Based Application Service Identity 3136 within Internet Public Key Infrastructure Using X.509 3137 (PKIX) Certificates in the Context of Transport Layer 3138 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 3139 2011, . 3141 [RFC6762] Cheshire, S. and M. Krochmal, "Multicast DNS", RFC 6762, 3142 DOI 10.17487/RFC6762, February 2013, 3143 . 3145 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 3146 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, 3147 . 3149 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 3150 RFC 6991, DOI 10.17487/RFC6991, July 2013, 3151 . 3153 [RFC7227] Hankins, D., Mrugalski, T., Siodelski, M., Jiang, S., and 3154 S. Krishnan, "Guidelines for Creating New DHCPv6 Options", 3155 BCP 187, RFC 7227, DOI 10.17487/RFC7227, May 2014, 3156 . 3158 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3159 Protocol (HTTP/1.1): Message Syntax and Routing", 3160 RFC 7230, DOI 10.17487/RFC7230, June 2014, 3161 . 3163 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 3164 RFC 7950, DOI 10.17487/RFC7950, August 2016, 3165 . 3167 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 3168 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 3169 . 3171 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3172 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3173 May 2017, . 3175 [RFC8366] Watsen, K., Richardson, M., Pritikin, M., and T. Eckert, 3176 "A Voucher Artifact for Bootstrapping Protocols", 3177 RFC 8366, DOI 10.17487/RFC8366, May 2018, 3178 . 3180 [RFC8415] Mrugalski, T., Siodelski, M., Volz, B., Yourtchenko, A., 3181 Richardson, M., Jiang, S., Lemon, T., and T. Winters, 3182 "Dynamic Host Configuration Protocol for IPv6 (DHCPv6)", 3183 RFC 8415, DOI 10.17487/RFC8415, November 2018, 3184 . 3186 [Std-802.1AR-2009] 3187 IEEE SA-Standards Board, "IEEE Standard for Local and 3188 metropolitan area networks - Secure Device Identity", 3189 December 2009, . 3192 11.2. Informative References 3194 [I-D.ietf-netconf-crypto-types] 3195 Watsen, K. and H. Wang, "Common YANG Data Types for 3196 Cryptography", draft-ietf-netconf-crypto-types-02 (work in 3197 progress), October 2018. 3199 [I-D.ietf-netconf-trust-anchors] 3200 Watsen, K., "YANG Data Model for Global Trust Anchors", 3201 draft-ietf-netconf-trust-anchors-02 (work in progress), 3202 October 2018. 3204 [I-D.ietf-ntp-using-nts-for-ntp] 3205 Franke, D., Sibold, D., Teichel, K., Dansarie, M., and R. 3206 Sundblad, "Network Time Security for the Network Time 3207 Protocol", draft-ietf-ntp-using-nts-for-ntp-14 (work in 3208 progress), October 2018. 3210 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3211 DOI 10.17487/RFC3688, January 2004, 3212 . 3214 [RFC4250] Lehtinen, S. and C. Lonvick, Ed., "The Secure Shell (SSH) 3215 Protocol Assigned Numbers", RFC 4250, 3216 DOI 10.17487/RFC4250, January 2006, 3217 . 3219 [RFC6187] Igoe, K. and D. Stebila, "X.509v3 Certificates for Secure 3220 Shell Authentication", RFC 6187, DOI 10.17487/RFC6187, 3221 March 2011, . 3223 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 3224 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 3225 DOI 10.17487/RFC6234, May 2011, 3226 . 3228 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 3229 and A. Bierman, Ed., "Network Configuration Protocol 3230 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 3231 . 3233 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 3234 Cheshire, "Internet Assigned Numbers Authority (IANA) 3235 Procedures for the Management of the Service Name and 3236 Transport Protocol Port Number Registry", BCP 165, 3237 RFC 6335, DOI 10.17487/RFC6335, August 2011, 3238 . 3240 [RFC6698] Hoffman, P. and J. Schlyter, "The DNS-Based Authentication 3241 of Named Entities (DANE) Transport Layer Security (TLS) 3242 Protocol: TLSA", RFC 6698, DOI 10.17487/RFC6698, August 3243 2012, . 3245 [RFC6891] Damas, J., Graff, M., and P. Vixie, "Extension Mechanisms 3246 for DNS (EDNS(0))", STD 75, RFC 6891, 3247 DOI 10.17487/RFC6891, April 2013, 3248 . 3250 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 3251 Galperin, S., and C. Adams, "X.509 Internet Public Key 3252 Infrastructure Online Certificate Status Protocol - OCSP", 3253 RFC 6960, DOI 10.17487/RFC6960, June 2013, 3254 . 3256 [RFC7107] Housley, R., "Object Identifier Registry for the S/MIME 3257 Mail Security Working Group", RFC 7107, 3258 DOI 10.17487/RFC7107, January 2014, 3259 . 3261 [RFC7766] Dickinson, J., Dickinson, S., Bellis, R., Mankin, A., and 3262 D. Wessels, "DNS Transport over TCP - Implementation 3263 Requirements", RFC 7766, DOI 10.17487/RFC7766, March 2016, 3264 . 3266 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 3267 RFC 8071, DOI 10.17487/RFC8071, February 2017, 3268 . 3270 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 3271 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 3272 . 3274 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 3275 Access Control Model", STD 91, RFC 8341, 3276 DOI 10.17487/RFC8341, March 2018, 3277 . 3279 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3280 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3281 . 3283 Appendix A. The Zero Touch Device Data Model 3285 This section defines a non-normative data model that enables the 3286 configuration of zerotouch bootstrapping and discovery of what 3287 parameters are used by a device's bootstrapping logic. 3289 A.1. Data Model Overview 3291 The following tree diagram provides an overview for the zerotouch 3292 device data model. 3294 module: example-zerotouch-device 3295 +--rw zerotouch 3296 +--rw enabled? boolean 3297 +--ro idevid-certificate? 3298 | ct:end-entity-cert-cms {bootstrap-servers}? 3299 +--ro bootstrap-servers {bootstrap-servers}? 3300 | +--ro bootstrap-server* [address] 3301 | +--ro address inet:host 3302 | +--ro port? inet:port-number 3303 +--ro bootstrap-server-pinned-certificates? 3304 | ta:pinned-certificates-ref {bootstrap-servers}? 3305 +--ro voucher-pinned-certificates? 3306 ta:pinned-certificates-ref {signed-data}? 3308 In the above diagram, notice that there is only one configurable node 3309 "enabled". The expectation is that this node would be set to "true" 3310 in device's factory default configuration and that it would either be 3311 set to "false" or deleted when the zerotouch bootstrapping is longer 3312 needed. 3314 A.2. Example Usage 3316 Following is an instance example for this data model. 3318 [Note: '\' line wrapping for formatting only] 3320 3322 true 3323 base64encodedvalue== 3324 3325 3326
phs1.example.com
3327 8443 3328 3329 3330
phs2.example.com
3331 8443 3332 3333 3334
phs3.example.com
3335 8443 3336 3337 3338 manufacturers-root-ca-certs<\ 3339 /bootstrap-server-pinned-certificates> 3340 manufacturers-root-ca-certs 3342 3344 A.3. YANG Module 3346 The device model is defined by the YANG module defined in this 3347 section. 3349 This module uses data types defined in [RFC6991], 3350 [I-D.ietf-netconf-crypto-types], and 3351 [I-D.ietf-netconf-trust-anchors]. 3353 module example-zerotouch-device { 3354 yang-version 1.1; 3355 namespace "https://example.com/zerotouch-device"; 3356 prefix ztd; 3358 import ietf-inet-types { 3359 prefix inet; 3360 reference "RFC 6991: Common YANG Data Types"; 3361 } 3363 import ietf-crypto-types { 3364 prefix ct; 3365 revision-date 2018-06-04; 3366 description 3367 "This revision is defined in the -00 version of 3368 draft-ietf-netconf-crypto-types"; 3369 reference 3370 "draft-ietf-netconf-crypto-types: 3371 Common YANG Data Types for Cryptography"; 3372 } 3374 import ietf-trust-anchors { 3375 prefix ta; 3376 revision-date 2018-06-04; 3377 description 3378 "This revision is defined in -00 version of 3379 draft-ietf-netconf-trust-anchors."; 3380 reference 3381 "draft-ietf-netconf-trust-anchors: 3382 YANG Data Model for Global Trust Anchors"; 3383 } 3385 organization 3386 "Example Corporation"; 3388 contact 3389 "Author: Bootstrap Admin "; 3391 description 3392 "This module defines a data model to enable zerotouch 3393 bootstrapping and discover what parameters are used. 3394 This module assumes the use of an IDevID certificate, 3395 as opposed to any other client certificate, or the 3396 use of an HTTP-based client authentication scheme."; 3398 revision 2018-12-20 { 3399 description 3400 "Initial version"; 3401 reference 3402 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 3403 } 3405 // features 3407 feature bootstrap-servers { 3408 description 3409 "The device supports bootstrapping off bootstrap servers."; 3410 } 3412 feature signed-data { 3413 description 3414 "The device supports bootstrapping off signed data."; 3415 } 3417 // protocol accessible nodes 3419 container zerotouch { 3420 description 3421 "Top-level container for zerotouch data model."; 3422 leaf enabled { 3423 type boolean; 3424 default false; 3425 description 3426 "The 'enabled' leaf controls if zerotouch bootstrapping is 3427 enabled or disabled. The default is 'false' so that, when 3428 not enabled, which is most of the time, no configuration 3429 is needed."; 3430 } 3431 leaf idevid-certificate { 3432 if-feature bootstrap-servers; 3433 type ct:end-entity-cert-cms; 3434 config false; 3435 description 3436 "This CMS structure contains the IEEE 802.1AR-2009 3437 IDevID certificate itself, and all intermediate 3438 certificates leading up to, and optionally including, 3439 the manufacturer's well-known trust anchor certificate 3440 for IDevID certificates. The well-known trust anchor 3441 does not have to be a self-signed certificate."; 3442 reference 3443 "IEEE 802.1AR-2009: 3444 IEEE Standard for Local and metropolitan area 3445 networks - Secure Device Identity."; 3446 } 3447 container bootstrap-servers { 3448 if-feature bootstrap-servers; 3449 config false; 3450 description 3451 "List of bootstrap servers this device will attempt 3452 to reach out to when bootstrapping."; 3453 list bootstrap-server { 3454 key "address"; 3455 description 3456 "A bootstrap server entry."; 3457 leaf address { 3458 type inet:host; 3459 mandatory true; 3460 description 3461 "The IP address or hostname of the bootstrap server the 3462 device should redirect to."; 3463 } 3464 leaf port { 3465 type inet:port-number; 3466 default "443"; 3467 description 3468 "The port number the bootstrap server listens on. If no 3469 port is specified, the IANA-assigned port for 'https' 3470 (443) is used."; 3471 } 3472 } 3473 } 3474 leaf bootstrap-server-pinned-certificates { 3475 if-feature bootstrap-servers; 3476 type ta:pinned-certificates-ref; 3477 config false; 3478 description 3479 "A reference to a list of pinned certificate authority (CA) 3480 certificates that the device uses to validate bootstrap 3481 servers with."; 3482 } 3483 leaf voucher-pinned-certificates { 3484 if-feature signed-data; 3485 type ta:pinned-certificates-ref; 3486 config false; 3487 description 3488 "A reference to a list of pinned certificate authority (CA) 3489 certificates that the device uses to validate ownership 3490 vouchers with."; 3491 } 3492 } 3493 } 3495 Appendix B. Promoting a Connection from Untrusted to Trusted 3497 The following diagram illustrates a sequence of bootstrapping 3498 activities that promote an untrusted connection to a bootstrap server 3499 to a trusted connection to the same bootstrap server. This enables a 3500 device to limit the amount of information it might disclose to an 3501 adversary hosting an untrusted bootstrap server. 3503 +----------+ 3504 |Deployment| 3505 | Specific | 3506 +------+ |Bootstrap | 3507 |Device| | Server | 3508 +------+ +----------+ 3509 | | 3510 | 1. "HTTPS" Request ("untrusted-connection", nonce) | 3511 |------------------------------------------------------->| 3512 | 2. "HTTPS" Response (signed redirect information) | 3513 |<-------------------------------------------------------| 3514 | | 3515 | | 3516 | 3. HTTPS Request (os-name=xyz, os-version=123, etc.) | 3517 |------------------------------------------------------->| 3518 | 4. HTTPS Response (unsigned onboarding information | 3519 |<-------------------------------------------------------| 3520 | | 3522 The interactions in the above diagram are described below. 3524 1. The device initiates an untrusted connection to a bootstrap 3525 server, as is indicated by putting "HTTPS" in double quotes 3526 above. It is still an HTTPS connection, but the device is unable 3527 to authenticate the bootstrap server's TLS certificate. Because 3528 the device is unable to trust the bootstrap server, it sends the 3529 "untrusted-connection" input parameter, and optionally also the 3530 "nonce" input parameter, in the "get-bootstrapping-data" RPC. 3531 The "untrusted-connection" parameter informs the bootstrap server 3532 that the device does not trust it and may be holding back some 3533 additional input parameters from the server (e.g., other input 3534 parameters, progress reports, etc.). The "nonce" input parameter 3535 enables the bootstrap server to dynamically obtain an ownership 3536 voucher from a MASA, which may be important for devices that do 3537 not have a reliable clock. 3539 2. The bootstrap server, seeing the "untrusted-connection" input 3540 parameter, knows that it can either send unsigned redirect 3541 information or signed data of any type. But, in this case, the 3542 bootstrap server has the ability to sign data and chooses to 3543 respond with signed redirect information, not signed onboarding 3544 information as might be expected, securely redirecting the device 3545 back to it again. Not displayed but, if the "nonce" input 3546 parameter was passed, the bootstrap server could dynamically 3547 connect to a download a voucher from the MASA having the nonce 3548 value in it. Details regarding a protocol enabling this 3549 integration is outside the scope of this document. 3551 3. Upon validating the signed redirect information, the device 3552 establishes a secure connection to the bootstrap server. 3553 Unbeknownst to the device, it is the same bootstrap server it was 3554 connected to previously but, because the device is able to 3555 authenticate the bootstrap server this time, it sends its normal 3556 "get-bootstrapping-data" request (i.e., with additional input 3557 parameters) as well as its progress reports (not depicted). 3559 4. This time, because the "untrusted-connection" parameter was not 3560 passed, having access to all of the device's input parameters, 3561 the bootstrap server returns, in this example, unsigned 3562 onboarding information to the device. Note also that, because 3563 the bootstrap server is now trusted, the device will send 3564 progress reports to the server. 3566 Appendix C. Workflow Overview 3568 The zero touch solution presented in this document is conceptualized 3569 to be composed of the non-normative workflows described in this 3570 section. Implementation details are expected to vary. Each diagram 3571 is followed by a detailed description of the steps presented in the 3572 diagram, with further explanation on how implementations may vary. 3574 C.1. Enrollment and Ordering Devices 3576 The following diagram illustrates key interactions that may occur 3577 from when a prospective owner enrolls in a manufacturer's zero touch 3578 program to when the manufacturer ships devices for an order placed by 3579 the prospective owner. 3581 +-----------+ 3582 +------------+ |Prospective| +---+ 3583 |Manufacturer| | Owner | |NMS| 3584 +------------+ +-----------+ +---+ 3585 | | | 3586 | | | 3587 | 1. initiate enrollment | | 3588 #<-----------------------------| | 3589 # | | 3590 # | | 3591 # IDevID trust anchor | | 3592 #-----------------------------># set IDevID trust anchor | 3593 # #--------------------------->| 3594 # | | 3595 # bootstrap server | | 3596 # account credentials | | 3597 #-----------------------------># set credentials | 3598 | #--------------------------->| 3599 | | | 3600 | | | 3601 | 2. set owner certificate trust anchor | 3602 |<----------------------------------------------------------| 3603 | | | 3604 | | | 3605 | 3. place device order | | 3606 |<-----------------------------# model devices | 3607 | #--------------------------->| 3608 | | | 3609 | 4. ship devices and send | | 3610 | device identifiers and | | 3611 | ownership vouchers | | 3612 |-----------------------------># set device identifiers | 3613 | # and ownership vouchers | 3614 | #--------------------------->| 3615 | | | 3617 Each numbered item below corresponds to a numbered item in the 3618 diagram above. 3620 1. A prospective owner of a manufacturer's devices initiates an 3621 enrollment process with the manufacturer. This process includes 3622 the following: 3624 * Regardless how the prospective owner intends to bootstrap 3625 their devices, they will always obtain from the manufacturer 3626 the trust anchor certificate for the IDevID certificates. 3627 This certificate will is installed on the prospective owner's 3628 NMS so that the NMS can authenticate the IDevID certificates 3629 when they are presented to subsequent steps. 3631 * If the manufacturer hosts an Internet based bootstrap server 3632 (e.g., a redirect server) such as described in Section 4.4, 3633 then credentials necessary to configure the bootstrap server 3634 would be provided to the prospective owner. If the bootstrap 3635 server is configurable through an API (outside the scope of 3636 this document), then the credentials might be installed on the 3637 prospective owner's NMS so that the NMS can subsequently 3638 configure the manufacturer-hosted bootstrap server directly. 3640 2. If the manufacturer's devices are able to validate signed data 3641 (Section 5.4), and assuming that the prospective owner's NMS is 3642 able to prepare and sign the bootstrapping data itself, the 3643 prospective owner's NMS might set a trust anchor certificate onto 3644 the manufacturer's bootstrap server, using the credentials 3645 provided in the previous step. This certificate is the trust 3646 anchor certificate that the prospective owner would like the 3647 manufacturer to place into the ownership vouchers it generates, 3648 thereby enabling devices to trust the owner's owner certificate. 3649 How this trust anchor certificate is used to enable devices to 3650 validate signed bootstrapping data is described in Section 5.4. 3652 3. Some time later, the prospective owner places an order with the 3653 manufacturer, perhaps with a special flag checked for zero touch 3654 handling. At this time, or perhaps before placing the order, the 3655 owner may model the devices in their NMS, creating virtual 3656 objects for the devices with no real-world device associations. 3657 For instance the model can be used to simulate the device's 3658 location in the network and the configuration it should have when 3659 fully operational. 3661 4. When the manufacturer fulfills the order, shipping the devices to 3662 their intended locations, they may notify the owner of the 3663 devices' serial numbers and shipping destinations, which the 3664 owner may use to stage the network for when the devices power on. 3665 Additionally, the manufacturer may send one or more ownership 3666 vouchers, cryptographically assigning ownership of those devices 3667 to the owner. The owner may set this information on their NMS, 3668 perhaps binding specific modeled devices to the serial numbers 3669 and ownership vouchers. 3671 C.2. Owner Stages the Network for Bootstrap 3673 The following diagram illustrates how an owner might stage the 3674 network for bootstrapping devices. 3676 +----------+ +------------+ 3677 |Deployment| |Manufacturer| +------+ +------+ 3678 | Specific | | Hosted | | Local| | Local| +---------+ 3679 +---+ |Bootstrap | | Bootstrap | | DNS | | DHCP | |Removable| 3680 |NMS| | Server | | Server | |Server| |Server| | Storage | 3681 +---+ +----------+ +------------+ +------+ +------+ +---------+ 3682 | | | | | | 3683 1. | | | | | | 3684 activate| | | | | | 3685 modeled | | | | | | 3686 device | | | | | | 3687 ------->| | | | | | 3688 | 2. (optional) | | | | 3689 | configure | | | | 3690 | bootstrap | | | | 3691 | server | | | | 3692 |------->| | | | | 3693 | | | | | | 3694 | 3. (optional) configure | | | 3695 | bootstrap server | | | | 3696 |--------------------->| | | | 3697 | | | | | | 3698 | | | | | | 3699 | 4. (optional) configure DNS server| | | 3700 |---------------------------------->| | | 3701 | | | | | | 3702 | | | | | | 3703 | 5. (optional) configure DHCP server | | 3704 |------------------------------------------->| | 3705 | | | | | | 3706 | | | | | | 3707 | 6. (optional) store bootstrapping artifacts on media | 3708 |----------------------------------------------------->| 3709 | | | | | | 3710 | | | | | | 3712 Each numbered item below corresponds to a numbered item in the 3713 diagram above. 3715 1. Having previously modeled the devices, including setting their 3716 fully operational configurations and associating device serial 3717 numbers and (optionally) ownership vouchers, the owner might 3718 "activate" one or more modeled devices. That is, the owner tells 3719 the NMS to perform the steps necessary to prepare for when the 3720 real-world devices power up and initiate the bootstrapping 3721 process. Note that, in some deployments, this step might be 3722 combined with the last step from the previous workflow. Here it 3723 is depicted that an NMS performs the steps, but they may be 3724 performed manually or through some other mechanism. 3726 2. If it is desired to use a deployment-specific bootstrap server, 3727 it must be configured to provide the bootstrapping data for the 3728 specific devices. Configuring the bootstrap server may occur via 3729 a programmatic API not defined by this document. Illustrated 3730 here as an external component, the bootstrap server may be 3731 implemented as an internal component of the NMS itself. 3733 3. If it is desired to use a manufacturer hosted bootstrap server, 3734 it must be configured to provide the bootstrapping data for the 3735 specific devices. The configuration must be either redirect or 3736 onboarding information. That is, either the manufacturer hosted 3737 bootstrap server will redirect the device to another bootstrap 3738 server, or provide the device with the onboarding information 3739 itself. The types of bootstrapping data the manufacturer hosted 3740 bootstrap server supports may vary by implementation; some 3741 implementations may only support redirect information, or only 3742 support onboarding information, or support both redirect and 3743 onboarding information. Configuring the bootstrap server may 3744 occur via a programmatic API not defined by this document. 3746 4. If it is desired to use a DNS server to supply bootstrapping 3747 data, a DNS server needs to be configured. If multicast DNS-SD 3748 is desired, then the DNS server must reside on the local network, 3749 otherwise the DNS server may reside on a remote network. Please 3750 see Section 4.2 for more information about how to configure DNS 3751 servers. Configuring the DNS server may occur via a programmatic 3752 API not defined by this document. 3754 5. If it is desired to use a DHCP server to supply bootstrapping 3755 data, a DHCP server needs to be configured. The DHCP server may 3756 be accessed directly or via a DHCP relay. Please see Section 4.3 3757 for more information about how to configure DHCP servers. 3758 Configuring the DHCP server may occur via a programmatic API not 3759 defined by this document. 3761 6. If it is desired to use a removable storage device (e.g., USB 3762 flash drive) to supply bootstrapping data, the data would need to 3763 be placed onto it. Please see Section 4.1 for more information 3764 about how to configure a removable storage device. 3766 C.3. Device Powers On 3768 The following diagram illustrates the sequence of activities that 3769 occur when a device powers on. 3771 +----------+ 3772 +-----------+ |Deployment| 3773 | Source of | | Specific | 3774 +------+ | Bootstrap | |Bootstrap | +---+ 3775 |Device| | Data | | Server | |NMS| 3776 +------+ +-----------+ +----------+ +---+ 3777 | | | | 3778 | | | | 3779 | 1. if zerotouch bootstrap service | | | 3780 | is not enabled, then exit. | | | 3781 | | | | 3782 | 2. for each source supported, check | | | 3783 | for bootstrapping data. | | | 3784 |------------------------------------>| | | 3785 | | | | 3786 | 3. if onboarding information found, | | | 3787 | initialize self and, only if | | | 3788 | source is a trusted bootstrap | | | 3789 | server, send progress reports. | | | 3790 |------------------------------------># | | 3791 | # webhook | | 3792 | #----------------------->| 3793 | | | 3794 | 4. else if redirect-information found, for each | | 3795 | bootstrap server specified, check for data. | | 3796 |-+------------------------------------------------->| | 3797 | | | | 3798 | | if more redirect-information is found, recurse | | 3799 | | (not depicted), else if onboarding information | | 3800 | | found, initialize self and post progress reports | | 3801 | +-------------------------------------------------># | 3802 | # webhook | 3803 | #-------->| 3804 | 3805 | 5. retry sources and/or wait for manual provisioning. 3806 | 3808 The interactions in the above diagram are described below. 3810 1. Upon power being applied, the device checks to see if zerotouch 3811 bootstrapping is configured, such as must be the case when 3812 running its "factory default" configuration. If zerotouch 3813 bootstrapping is not configured, then the bootstrapping logic 3814 exits and none of the following interactions occur. 3816 2. For each source of bootstrapping data the device supports, 3817 preferably in order of closeness to the device (e.g., removable 3818 storage before Internet based servers), the device checks to see 3819 if there is any bootstrapping data for it there. 3821 3. If onboarding information is found, the device initializes itself 3822 accordingly (e.g., installing a boot-image and committing an 3823 initial configuration). If the source is a bootstrap server, and 3824 the bootstrap server can be trusted (i.e., TLS-level 3825 authentication), the device also sends progress reports to the 3826 bootstrap server. 3828 * The contents of the initial configuration should configure an 3829 administrator account on the device (e.g., username, SSH 3830 public key, etc.), and should configure the device either to 3831 listen for NETCONF or RESTCONF connections or to initiate call 3832 home connections [RFC8071], and should disable the zerotouch 3833 bootstrapping service (e.g., the "enabled" leaf in data model 3834 presented in Appendix A). 3836 * If the bootstrap server supports forwarding device progress 3837 reports to external systems (e.g., via a webhook), a 3838 "bootstrap-complete" progress report (Section 7.3) informs the 3839 external system to know when it can, for instance, initiate a 3840 connection to the device. To support this scenario further, 3841 the "bootstrap-complete" progress report may also relay the 3842 device's SSH host keys and/or TLS certificates, with which the 3843 external system can use to authenticate subsequent connections 3844 to the device. 3846 If the device successfully completes the bootstrapping process, 3847 it exits the bootstrapping logic without considering any 3848 additional sources of bootstrapping data. 3850 4. Otherwise, if redirect information is found, the device iterates 3851 through the list of specified bootstrap servers, checking to see 3852 if the bootstrap server has bootstrapping data for the device. 3853 If the bootstrap server returns more redirect information, then 3854 the device processes it recursively. Otherwise, if the bootstrap 3855 server returns onboarding information, the device processes it 3856 following the description provided in (3) above. 3858 5. After having tried all supported sources of bootstrapping data, 3859 the device may retry again all the sources and/or provide 3860 manageability interfaces for manual configuration (e.g., CLI, 3861 HTTP, NETCONF, etc.). If manual configuration is allowed, and 3862 such configuration is provided, the configuration should also 3863 disable the zerotouch bootstrapping service, as the need for 3864 bootstrapping would no longer be present. 3866 Appendix D. Change Log 3868 D.1. ID to 00 3870 o Major structural update; the essence is the same. Most every 3871 section was rewritten to some degree. 3873 o Added a Use Cases section 3875 o Added diagrams for "Actors and Roles" and "NMS Precondition" 3876 sections, and greatly improved the "Device Boot Sequence" diagram 3878 o Removed support for physical presence or any ability for 3879 configlets to not be signed. 3881 o Defined the Zero Touch Information DHCP option 3883 o Added an ability for devices to also download images from 3884 configuration servers 3886 o Added an ability for configlets to be encrypted 3888 o Now configuration servers only have to support HTTP/S - no other 3889 schemes possible 3891 D.2. 00 to 01 3893 o Added boot-image and validate-owner annotations to the "Actors and 3894 Roles" diagram. 3896 o Fixed 2nd paragraph in section 7.1 to reflect current use of 3897 anyxml. 3899 o Added encrypted and signed-encrypted examples 3901 o Replaced YANG module with XSD schema 3903 o Added IANA request for the Zero Touch Information DHCP Option 3905 o Added IANA request for media types for boot-image and 3906 configuration 3908 D.3. 01 to 02 3910 o Replaced the need for a configuration signer with the ability for 3911 each NMS to be able to sign its own configurations, using 3912 manufacturer signed ownership vouchers and owner certificates. 3914 o Renamed configuration server to bootstrap server, a more 3915 representative name given the information devices download from 3916 it. 3918 o Replaced the concept of a configlet by defining a southbound 3919 interface for the bootstrap server using YANG. 3921 o Removed the IANA request for the boot-image and configuration 3922 media types 3924 D.4. 02 to 03 3926 o Minor update, mostly just to add an Editor's Note to show how this 3927 draft might integrate with the draft-pritikin-anima-bootstrapping- 3928 keyinfra. 3930 D.5. 03 to 04 3932 o Major update formally introducing unsigned data and support for 3933 Internet-based redirect servers. 3935 o Added many terms to Terminology section. 3937 o Added all new "Guiding Principles" section. 3939 o Added all new "Sources for Bootstrapping Data" section. 3941 o Rewrote the "Interactions" section and renamed it "Workflow 3942 Overview". 3944 D.6. 04 to 05 3946 o Semi-major update, refactoring the document into more logical 3947 parts 3949 o Created new section for information types 3951 o Added support for DNS servers 3953 o Now allows provisional TLS connections 3955 o Bootstrapping data now supports scripts 3957 o Device Details section overhauled 3959 o Security Considerations expanded 3961 o Filled in enumerations for notification types 3963 D.7. 05 to 06 3965 o Minor update 3967 o Added many Normative and Informative references. 3969 o Added new section Other Considerations. 3971 D.8. 06 to 07 3973 o Minor update 3975 o Added an Editorial Note section for RFC Editor. 3977 o Updated the IANA Considerations section. 3979 D.9. 07 to 08 3981 o Minor update 3983 o Updated to reflect review from Michael Richardson. 3985 D.10. 08 to 09 3987 o Added in missing "Signature" artifact example. 3989 o Added recommendation for manufacturers to use interoperable 3990 formats and file naming conventions for removable storage devices. 3992 o Added configuration-handling leaf to guide if config should be 3993 merged, replaced, or processed like an edit-config/yang-patch 3994 document. 3996 o Added a pre-configuration script, in addition to the post- 3997 configuration script from -05 (issue #15). 3999 D.11. 09 to 10 4001 o Factored ownership voucher and voucher revocation to a separate 4002 document: draft-kwatsen-netconf-voucher. (issue #11) 4004 o Removed options "edit-config" and "yang- 4005 patch". (issue #12) 4007 o Defined how a signature over signed-data returned from a bootstrap 4008 server is processed. (issue #13) 4010 o Added recommendation for removable storage devices to use open/ 4011 standard file systems when possible. (issue #14) 4013 o Replaced notifications "script-[warning/error]" with "[pre/post]- 4014 script-[warning/error]". (goes with issue #15) 4016 o switched owner-certificate to be encoded using the PKCS #7 format. 4017 (issue #16) 4019 o Replaced md5/sha1 with sha256 inside a choice statement, for 4020 future extensibility. (issue #17) 4022 o A ton of editorial changes, as I went thru the entire draft with a 4023 fine-toothed comb. 4025 D.12. 10 to 11 4027 o fixed yang validation issues found by IETFYANGPageCompilation. 4028 note: these issues were NOT found by pyang --ietf or by the 4029 submission-time validator... 4031 o fixed a typo in the yang module, someone the config false 4032 statement was removed. 4034 D.13. 11 to 12 4036 o fixed typo that prevented Appendix B from loading the examples 4037 correctly. 4039 o fixed more yang validation issues found by 4040 IETFYANGPageCompilation. note: again, these issues were NOT found 4041 by pyang --ietf or by the submission-time validator... 4043 o updated a few of the notification enumerations to be more 4044 consistent with the other enumerations (following the warning/ 4045 error pattern). 4047 o updated the information-type artifact to state how it is encoded, 4048 matching the language that was in Appendix B. 4050 D.14. 12 to 13 4052 o defined a standalone artifact to encode the old information-type 4053 into a PKCS #7 structure. 4055 o standalone information artifact hardcodes JSON encoding (to match 4056 the voucher draft). 4058 o combined the information and signature PKCS #7 structures into a 4059 single PKCS #7 structure. 4061 o moved the certificate-revocations into the owner-certificate's 4062 PKCS #7 structure. 4064 o eliminated support for voucher-revocations, to reflect the 4065 voucher-draft's switch from revocations to renewals. 4067 D.15. 13 to 14 4069 o Renamed "bootstrap information" to "onboarding information". 4071 o Rewrote DHCP sections to address the packet-size limitation issue, 4072 as discussed in Chicago. 4074 o Added Ian as an author for his text-contributions to the DHCP 4075 sections. 4077 o Removed the Guiding Principles section. 4079 D.16. 14 to 15 4081 o Renamed action "notification" to "update-progress" and, likewise 4082 "notification-type" to "update-type". 4084 o Updated examples to use "base64encodedvalue==" for binary values. 4086 o Greatly simplified the "Artifact Groupings" section, and moved it 4087 as a subsection to the "Artifacts" section. 4089 o Moved the "Workflow Overview" section to the Appendix. 4091 o Renamed "bootstrap information" to "update information". 4093 o Removed "Other Considerations" section. 4095 o Tons of editorial updates. 4097 D.17. 15 to 16 4099 o tweaked language to refer to "initial state" rather than "factory 4100 default configuration", so as accommodate white-box scenarios. 4102 o added a paragraph to Intro regarding how the solution primarily 4103 regards physical machines, but could be extended to VMs by a 4104 future document. 4106 o added a pointer to the Workflow Overview section (recently moved 4107 to the Appendix) to the Intro. 4109 o added a note that, in order to simplify the verification process, 4110 the "Zerotouch Information" PKCS #7 structure MUST also contain 4111 the signing X.509 certificate. 4113 o noted that the owner certificate's must either have no Key Usage 4114 or the Key Usage must set the "digitalSignature" bit. 4116 o noted that the owner certificate's subject and subjectAltName 4117 values are not constrained. 4119 o moved/consolidated some text from the Artifacts section down to 4120 the Device Details section. 4122 o tightened up some ambiguous language, for instance, by referring 4123 to specific leaf names in the Voucher artifact. 4125 o reverted a previously overzealous s/unique-id/serial-number/ 4126 change. 4128 o modified language for when ZTP runs from when factory-default 4129 config is running to when ZTP is configured, which the factory- 4130 defaults should set . 4132 D.18. 16 to 17 4134 o Added an example for how to promote an untrusted connection to a 4135 trusted connection. 4137 o Added a "query parameters" section defining some parameters 4138 enabling scenarios raised in last call. 4140 o Added a "Disclosing Information to Untrusted Servers" section to 4141 the Security Considerations. 4143 D.19. 17 to 18 4145 o Added Security Considerations for each YANG module. 4147 o Reverted back to the device always sending its DevID cert. 4149 o Moved data tree to "get-bootstrapping-data" RPC. 4151 o Moved the "update-progress" action to a "report-progress" RPC. 4153 o Added an "untrusted-connection" parameter to "get-bootstrapping- 4154 data" RPC. 4156 o Added the "ietf-zerotouch-device" module. 4158 o Lots of small updates. 4160 D.20. 18 to 19 4162 o Fixed "must" expressions, by converting "choice" to a "list" of 4163 "image-verification", each of which now points to a base identity 4164 called "hash-algorithm". There's just one algorithm currently 4165 defined (sha-256). Wish there was a standard crypto module that 4166 could identify such identities. 4168 D.21. 19 to 20 4170 o Now references I-D.ietf-netmod-yang-tree-diagrams. 4172 o Fixed tree-diagrams in Section 2 to always reflect current YANG 4173 (now they are now dynamically generated). 4175 o The "redirect-information" container's "trust-anchor" is now a CMS 4176 structure that can contain a chain of certificates, rather than a 4177 single certificate. 4179 o The "onboarding-information" container's support for image 4180 verification reworked to be extensible. 4182 o Added a reference to the "Device Details" section to the new 4183 example-zerotouch-device module. 4185 o Clarified that the device must always pass its IDevID certificate, 4186 even for untrusted bootstrap servers. 4188 o Fixed the description statement for the "script" typedef to refer 4189 to the [pre/post]-script-[warning/error] enums, rather than the 4190 legacy script-[warning/error] enums. 4192 o For the get-bootstrapping-data RPC's input, removed the "remote- 4193 id" and "circuit-id" fields, and added a "hw-model" field. 4195 o Improved DHCP error handling text. 4197 o Added MUST requirement for DHCPv6 client and server implementing 4198 [RFC3396] to handle URI lists longer than 255 octets. 4200 o Changed the "configuration" value in onboarding-information to be 4201 type "binary" instead of "anydata". 4203 o Moved everything from PKCS#7 to CMS (this shows up as a big 4204 change). 4206 o Added the early code point allocation assignments for the DHCP 4207 Options in the IANA Considerations section, and updated the RFC 4208 Editor note accordingly. 4210 o Added RFC Editor request to replace the assigned values for the 4211 CMS content types. 4213 o Relaxed auth requirements from device needing to always send 4214 IDevID cert to device needing to always send authentication 4215 credentials, as this better matches what RFC 8040 Section 2.5 4216 says. 4218 o Moved normative module "ietf-zerotouch-device" to non-normative 4219 module "example-zerotouch-device". 4221 o Updated Title, Abstract, and Introduction per discussion on list. 4223 D.22. 20 to 21 4225 o Now any of the three artifact can be encrypted. 4227 o Fixed some line-too-long issues. 4229 D.23. 21 to 22 4231 o Removed specifics around how scripts indicate warnings or errors 4232 and how scripts emit output. 4234 o Moved the Zero Touch Device Data Model section to the Appendix. 4236 o Modified the YANG module in the Zero Touch Device Data Model 4237 section to reflect the latest trust-anchors and keystore drafts. 4239 o Modified types in other YANG modules to more closely emulate what 4240 is in draft-ietf-netconf-crypto-types. 4242 D.24. 22 to 23 4244 o Rewrote section 5.6 (processing onboboarding information) to be 4245 clearer about error handling and retained state. Specifically: 4247 * Clarified that a script, upon having an error, must gracefully 4248 exit, cleaning up any state that might hinder subsequent 4249 executions. 4251 * Added ability for scripts to be executed again with a flag 4252 enabling them to clean up state from a previous execution. 4254 * Clarified that the conifguration commit is atomic. 4256 * Clarified that any error encountered after committing the 4257 configuration (e.g., in the "post-configuration-script") must 4258 rollback the configuration to the previous configuration. 4260 * Clarified that failure to successfully deliver the "bootstrap- 4261 initiated" and "bootstrap-complete" progress types must be 4262 treated as an error. 4264 * Clarified that "return to bootstrapping sequence" is to be 4265 interpreted in the recursive context. Meaning that the device 4266 rolls-back one loop, rather than start over from scratch. 4268 o Changed how a device verifies a boot-image from just "MUST match 4269 one of the supplied fingerprints" to also allow for the 4270 verification to use an cryptographic signature embedded into the 4271 image itself. 4273 o Added more "progress-type" enums for visibility reasons, enabling 4274 more strongly-typed debug information to be sent to the bootstrap 4275 server. 4277 o Added Security Considerations based on early SecDir review. 4279 o Added recommendation for device to send warning if the initial 4280 config does not disable the bootstrapping process. 4282 D.25. 23 to 24 4284 o Follow-ups from SecDir and Shepherd. 4286 o Added "boot-image-complete" enumeration. 4288 D.26. 24 to 25 4290 o Removed remaining old "bootstrapping information" term usage. 4292 o Fixed DHCP Option length definition. 4294 o Added reference to RFC 6187. 4296 D.27. 25 to 26 4298 o Updated URI structure text (sec 8.3) and added norm. ref to 4299 RFC7230 reflecting Alexey Melnikov's comment. 4301 o Added IANA registration for the 'zerotouch' service, per IESG 4302 review from Adam Roach. 4304 o Clarified device's looping behavior and support for alternative 4305 provisioning mechanisms, per IESG review from Mirja Kuehlewind. 4307 o Updated "ietf-zerotouch-bootstrap-server:ssh-host-key" from leaf- 4308 list to list, per IESG review from Benjamin Kaduk. 4310 o Added option size text to DHCPv4 option size to address Suresh 4311 Krishnan's IESG review discuss point. 4313 o Updated RFC3315 to RFC8415 and associated section references. 4315 o Revamped the DNS Server section, after digging into Alexey 4316 Melnikov comment. 4318 o Fixed IETF terminology template section in both YANG modules. 4320 Acknowledgements 4322 The authors would like to thank for following for lively discussions 4323 on list and in the halls (ordered by last name): Michael Behringer, 4324 Dean Bogdanovic, Martin Bjorklund, Joe Clarke, Toerless Eckert, 4325 Stephen Farrell, Stephen Hanna, Wes Hardaker, David Harrington, Mirja 4326 Kuehlewind, Radek Krejci, Suresh Krishnan, Benjamin Kaduk, David 4327 Mandelberg, Alexey Melnikov, Russ Mundy, Reinaldo Penno, Randy 4328 Presuhn, Max Pritikin, Michael Richardson, Adam Roach, Phil Shafer, 4329 Juergen Schoenwaelder. 4331 Special thanks goes to Steve Hanna, Russ Mundy, and Wes Hardaker for 4332 brainstorming the original I-D's solution during the IETF 87 meeting 4333 in Berlin. 4335 Authors' Addresses 4337 Kent Watsen 4338 Juniper Networks 4340 EMail: kwatsen@juniper.net 4341 Mikael Abrahamsson 4342 T-Systems 4344 EMail: mikael.abrahamsson@t-systems.se 4346 Ian Farrer 4347 Deutsche Telekom AG 4349 EMail: ian.farrer@telekom.de