idnits 2.17.1 draft-ietf-netconf-zerotouch-21.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([I-D.ietf-anima-voucher], [RFC6241], [RFC8040]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 405 has weird spacing: '...gorithm ide...' == Line 1239 has weird spacing: '...gorithm ide...' == Line 1635 has weird spacing: '...rmation cms...' == Line 1640 has weird spacing: '...ss-type enu...' == Line 1645 has weird spacing: '...ey-data str...' == (2 more instances...) == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The device MUST next authenticate the owner certificate by performing X.509 certificate path verification to the trusted certificate extracted from the ownership voucher's 'pinned-domain-cert' node. This verification may entail using additional intermediate certificates attached to the owner certificate artifact. If the ownership voucher's 'domain-cert-revocation-checks' node's value is set to "true", the device MUST verify the revocation status of the certificate chain used to sign the owner certificate and, if the revocation status is not attainable or if it is determined that a certificate has been revoked, the device MUST not validate the owner certificate. -- The document date (March 5, 2018) is 2237 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 2785, but not defined == Unused Reference: 'RFC6242' is defined on line 2928, but no explicit reference was found in the text == Outdated reference: A later version (-05) exists of draft-ietf-netmod-yang-data-ext-00 -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU.X690.1994' ** Obsolete normative reference: RFC 3315 (Obsoleted by RFC 8415) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Downref: Normative reference to an Informational RFC: RFC 6234 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-04 -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 6536 (Obsoleted by RFC 8341) Summary: 4 errors (**), 0 flaws (~~), 12 warnings (==), 5 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: September 6, 2018 T-Systems 6 I. Farrer 7 Deutsche Telekom AG 8 March 5, 2018 10 Zero Touch Provisioning for Networking Devices 11 draft-ietf-netconf-zerotouch-21 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 [RFC6241] and/or RESTCONF [RFC8040] 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 o "ZZZZ" --> the assigned numerical RFC value for 46 [I-D.ietf-anima-voucher] 48 Artwork in this document contains placeholder values for the date of 49 publication of this draft. Please apply the following replacement: 51 o "2018-03-05" --> the publication date of this draft 53 Please update the following informative references to reflect its 54 final RFC assignment: 56 o I-D.ietf-netmod-yang-tree-diagrams 58 The following one Appendix section is to be removed prior to 59 publication: 61 o Appendix A. Change Log 63 Status of This Memo 65 This Internet-Draft is submitted in full conformance with the 66 provisions of BCP 78 and BCP 79. 68 Internet-Drafts are working documents of the Internet Engineering 69 Task Force (IETF). Note that other groups may also distribute 70 working documents as Internet-Drafts. The list of current Internet- 71 Drafts is at https://datatracker.ietf.org/drafts/current/. 73 Internet-Drafts are draft documents valid for a maximum of six months 74 and may be updated, replaced, or obsoleted by other documents at any 75 time. It is inappropriate to use Internet-Drafts as reference 76 material or to cite them other than as "work in progress." 78 This Internet-Draft will expire on September 6, 2018. 80 Copyright Notice 82 Copyright (c) 2018 IETF Trust and the persons identified as the 83 document authors. All rights reserved. 85 This document is subject to BCP 78 and the IETF Trust's Legal 86 Provisions Relating to IETF Documents 87 (https://trustee.ietf.org/license-info) in effect on the date of 88 publication of this document. Please review these documents 89 carefully, as they describe your rights and restrictions with respect 90 to this document. Code Components extracted from this document must 91 include Simplified BSD License text as described in Section 4.e of 92 the Trust Legal Provisions and are provided without warranty as 93 described in the Simplified BSD License. 95 Table of Contents 97 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 98 1.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 5 99 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 100 1.3. Requirements Language . . . . . . . . . . . . . . . . . . 7 101 1.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 8 102 2. Types of Bootstrapping Information . . . . . . . . . . . . . 8 103 2.1. Redirect Information . . . . . . . . . . . . . . . . . . 8 104 2.2. Onboarding Information . . . . . . . . . . . . . . . . . 9 105 3. Artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . 9 106 3.1. Zero Touch Information . . . . . . . . . . . . . . . . . 10 107 3.2. Owner Certificate . . . . . . . . . . . . . . . . . . . . 11 108 3.3. Ownership Voucher . . . . . . . . . . . . . . . . . . . . 12 109 3.4. Artifact Encryption . . . . . . . . . . . . . . . . . . . 12 110 3.5. Artifact Groupings . . . . . . . . . . . . . . . . . . . 13 111 4. Sources of Bootstrapping Data . . . . . . . . . . . . . . . . 14 112 4.1. Removable Storage . . . . . . . . . . . . . . . . . . . . 14 113 4.2. DNS Server . . . . . . . . . . . . . . . . . . . . . . . 15 114 4.3. DHCP Server . . . . . . . . . . . . . . . . . . . . . . . 16 115 4.4. Bootstrap Server . . . . . . . . . . . . . . . . . . . . 17 116 5. Device Details . . . . . . . . . . . . . . . . . . . . . . . 18 117 5.1. Initial State . . . . . . . . . . . . . . . . . . . . . . 18 118 5.2. Boot Sequence . . . . . . . . . . . . . . . . . . . . . . 20 119 5.3. Processing a Source of Bootstrapping Data . . . . . . . . 21 120 5.4. Validating Signed Data . . . . . . . . . . . . . . . . . 23 121 5.5. Processing Redirect Information . . . . . . . . . . . . . 24 122 5.6. Processing Onboarding Information . . . . . . . . . . . . 25 123 6. The Zero Touch Information Data Model . . . . . . . . . . . . 26 124 6.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 27 125 6.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 27 126 6.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 29 127 7. The Zero Touch Bootstrap Server API . . . . . . . . . . . . . 35 128 7.1. API Overview . . . . . . . . . . . . . . . . . . . . . . 35 129 7.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 36 130 7.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 39 131 8. The Zero Touch Device Data Model . . . . . . . . . . . . . . 48 132 8.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 48 133 8.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 49 134 8.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 49 135 9. DHCP Zero Touch Options . . . . . . . . . . . . . . . . . . . 53 136 9.1. DHCPv4 Zero Touch Option . . . . . . . . . . . . . . . . 53 137 9.2. DHCPv6 Zero Touch Option . . . . . . . . . . . . . . . . 55 138 9.3. Common Field Encoding . . . . . . . . . . . . . . . . . . 56 139 10. Security Considerations . . . . . . . . . . . . . . . . . . . 56 140 10.1. Immutable Storage for Trust Anchors . . . . . . . . . . 56 141 10.2. Secure Storage for Long-lived Private Keys . . . . . . . 56 142 10.3. Use of IDevID Certificates . . . . . . . . . . . . . . . 57 143 10.4. Clock Sensitivity . . . . . . . . . . . . . . . . . . . 57 144 10.5. Blindly authenticating a bootstrap server . . . . . . . 57 145 10.6. Disclosing Information to Untrusted Servers . . . . . . 57 146 10.7. Sequencing Sources of Bootstrapping Data . . . . . . . . 58 147 10.8. The "ietf-zerotouch-information" YANG Module . . . . . . 58 148 10.9. The "ietf-zerotouch-bootstrap-server" YANG Module . . . 59 149 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 60 150 11.1. The IETF XML Registry . . . . . . . . . . . . . . . . . 60 151 11.2. The YANG Module Names Registry . . . . . . . . . . . . . 60 152 11.3. The SMI Security for S/MIME CMS Content Type Registry . 60 153 11.4. The BOOTP Manufacturer Extensions and DHCP Options 154 Registry . . . . . . . . . . . . . . . . . . . . . . . . 61 155 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 61 156 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 61 157 13.1. Normative References . . . . . . . . . . . . . . . . . . 61 158 13.2. Informative References . . . . . . . . . . . . . . . . . 63 159 Appendix A. Promoting a Connection from Untrusted to Trusted . . 65 160 Appendix B. Workflow Overview . . . . . . . . . . . . . . . . . 66 161 B.1. Enrollment and Ordering Devices . . . . . . . . . . . . . 66 162 B.2. Owner Stages the Network for Bootstrap . . . . . . . . . 68 163 B.3. Device Powers On . . . . . . . . . . . . . . . . . . . . 71 164 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 73 165 C.1. ID to 00 . . . . . . . . . . . . . . . . . . . . . . . . 73 166 C.2. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 73 167 C.3. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 74 168 C.4. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 74 169 C.5. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 74 170 C.6. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 74 171 C.7. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 75 172 C.8. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 75 173 C.9. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 75 174 C.10. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 75 175 C.11. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 75 176 C.12. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 76 177 C.13. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 76 178 C.14. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 77 179 C.15. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 77 180 C.16. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 77 181 C.17. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 78 182 C.18. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 78 183 C.19. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 79 184 C.20. 18 to 19 . . . . . . . . . . . . . . . . . . . . . . . . 79 185 C.21. 19 to 20 . . . . . . . . . . . . . . . . . . . . . . . . 79 186 C.22. 20 to 21 . . . . . . . . . . . . . . . . . . . . . . . . 80 187 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 80 189 1. Introduction 191 A fundamental business requirement for any network operator is to 192 reduce costs where possible. For network operators, deploying 193 devices to many locations can be a significant cost, as sending 194 trained specialists to each site for installations is both cost 195 prohibitive and does not scale. 197 This document defines Secure Zero Touch Provisioning (SZTP), a 198 bootstrapping strategy enabling devices to securely obtain 199 bootstrapping data with no installer action beyond physical placement 200 and connecting network and power cables. As such, SZTP enables non- 201 technical personnel to bring up devices in remote locations without 202 the need for any operator input. 204 The SZTP solution includes updating the boot image, committing an 205 initial configuration, and executing arbitrary scripts to address 206 auxiliary needs. The updated device is subsequently able to 207 establish secure connections with other systems. For instance, a 208 devices may establish NETCONF [RFC8040] and/or RESTCONF [RFC6241] 209 connections with deployment-specific network management systems. 211 This document primarily regards physical devices, where the setting 212 of the device's initial state, described in Section 5.1, occurs 213 during the device's manufacturing process. The SZTP solution may be 214 extended to support virtual machines or other such logical 215 constructs, but details for how this can be accomplished is left for 216 future work. 218 1.1. Use Cases 220 o Device connecting to a remotely administered network 222 This use-case involves scenarios, such as a remote branch 223 office or convenience store, whereby a device connects as an 224 access gateway to an ISP's network. Assuming it is not 225 possible to customize the ISP's network to provide any 226 bootstrapping support, and with no other nearby device to 227 leverage, the device has no recourse but to reach out to an 228 Internet-based bootstrap server to bootstrap from. 230 o Device connecting to a locally administered network 232 This use-case covers all other scenarios and differs only in 233 that the device may additionally leverage nearby devices, which 234 may direct it to use a local service to bootstrap from. If no 235 such information is available, or the device is unable to use 236 the information provided, it can then reach out to the network 237 just as it would for the remotely administered network use- 238 case. 240 Conceptual workflows for how SZTP might be deployed are provided in 241 Appendix B. 243 1.2. Terminology 245 This document uses the following terms (sorted by name): 247 Artifact: The term "artifact" is used throughout to represent any of 248 the three artifacts defined in Section 3 (zero touch information, 249 ownership voucher, and owner certificate). These artifacts 250 collectively provide all the bootstrapping data a device may use. 252 Bootstrapping Data: The term "bootstrapping data" is used throughout 253 this document to refer to the collection of data that a device 254 may obtain during the bootstrapping process. Specifically, it 255 refers to the three artifacts zero touch information, owner 256 certificate, and ownership voucher, as described in Section 3. 258 Bootstrap Server: The term "bootstrap server" is used within this 259 document to mean any RESTCONF server implementing the YANG module 260 defined in Section 7.3. 262 Device: The term "device" is used throughout this document to refer 263 to a network element that needs to be bootstrapped. See 264 Section 5 for more information about devices. 266 Manufacturer: The term "manufacturer" is used herein to refer to the 267 manufacturer of a device or a delegate of the manufacturer. 269 Network Management System (NMS): The acronym "NMS" is used 270 throughout this document to refer to the deployment specific 271 management system that the bootstrapping process is responsible 272 for introducing devices to. From a device's perspective, when 273 the bootstrapping process has completed, the NMS is a NETCONF or 274 RESTCONF client. 276 Onboarding Information: The term "onboarding information" is used 277 herein to refer to one of the two types of "zero touch 278 information" defined in this document, the other being "redirect 279 information". Onboarding information is formally defined by the 280 "onboarding-information" YANG-data structure in Section 6.3. 282 Onboarding Server: The term "onboarding server" is used herein to 283 refer to a bootstrap server that only returns onboarding 284 information. 286 Owner: The term "owner" is used throughout this document to refer to 287 the person or organization that purchased or otherwise owns a 288 device. 290 Owner Certificate: The term "owner certificate" is used in this 291 document to represent an X.509 certificate that binds an owner 292 identity to a public key, which a device can use to validate a 293 signature over the zero touch information artifact. The owner 294 certificate may be communicated along with its chain of 295 intermediate certificates leading up to a known trust anchor. 296 The owner certificate is one of the three bootstrapping artifacts 297 described in Section 3. 299 Ownership Voucher: The term "ownership voucher" is used in this 300 document to represent the voucher artifact defined in 301 [I-D.ietf-anima-voucher]. The ownership voucher is used to 302 assign a device to an owner. The ownership voucher is one of the 303 three bootstrapping artifacts described in Section 3. 305 Redirect Information: The term "redirect information" is used herein 306 to refer to one of the two types of "zero touch information" 307 defined in this document, the other being "onboarding 308 information". Redirect information is formally defined by the 309 "redirect-information" YANG-data structure in Section 6.3. 311 Redirect Server: The term "redirect server" is used to refer to a 312 bootstrap server that only returns redirect information. A 313 redirect server is particularly useful when hosted by a 314 manufacturer, as a well-known (e.g., Internet-based) resource to 315 redirect devices to deployment-specific bootstrap servers. 317 Signed Data: The term "signed data" is used throughout to mean zero 318 touch information that has been signed, specifically by a private 319 key possessed by a device's owner. 321 Unsigned Data: The term "unsigned data" is used throughout to mean 322 zero touch information that has not been signed. 324 Zero Touch Information: The term "zero touch information" is used 325 herein to refer either redirect information or onboarding 326 information. Zero touch information is one of the three 327 bootstrapping artifacts described in Section 3. 329 1.3. Requirements Language 331 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 332 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 333 "OPTIONAL" in this document are to be interpreted as described in BCP 334 14 [RFC2119] [RFC8174] when, and only when, they appear in all 335 capitals, as shown here. 337 1.4. Tree Diagrams 339 Tree diagrams used in this document follow the notation defined in 340 [I-D.ietf-netmod-yang-tree-diagrams]. 342 2. Types of Bootstrapping Information 344 This document defines two types of information that devices can 345 access during the bootstrapping process. These information types are 346 described in this section. Examples are provided in Section 6.2 348 2.1. Redirect Information 350 Redirect information redirects a device to another bootstrap server. 351 Redirect information encodes a list of bootstrap servers, each 352 specifying the bootstrap server's hostname (or IP address), an 353 optional port, and an optional trust anchor certificate that the 354 device can use to authenticate the bootstrap server with. 356 Redirect information is YANG modeled data formally defined by the 357 "redirect-information" container in the YANG module presented in 358 Section 6.3. This container has the tree diagram shown below. 360 +--:(redirect-information) 361 +---- redirect-information 362 +---- bootstrap-server* [address] 363 +---- address inet:host 364 +---- port? inet:port-number 365 +---- trust-anchor? cms 367 Redirect information may be trusted or untrusted. The redirect 368 information is trusted whenever it is obtained via a secure 369 connection to a trusted bootstrap server, or whenever it is signed by 370 the device's owner. In all other cases, the redirect information is 371 untrusted. 373 Trusted redirect information is useful for enabling a device to 374 establish a secure connection to a specified bootstrap server, which 375 is possible when the redirect information includes the bootstrap 376 server's trust anchor certificate. 378 Untrusted redirect information is useful for directing a device to a 379 bootstrap server where signed data has been staged for it to obtain. 380 Note that, when the redirect information is untrusted, devices 381 discard any potentially included trust anchor certificates. 383 How devices process redirect information is described in Section 5.5. 385 2.2. Onboarding Information 387 Onboarding information provides data necessary for a device to 388 bootstrap itself and establish secure connections with other systems. 389 As defined in this document, onboarding information can specify 390 details about the boot image a device must be running, specify an 391 initial configuration the device must commit, and specify scripts 392 that the device must successfully execute. 394 Onboarding information is YANG modeled data formally defined by the 395 "onboarding-information" container in the YANG module presented in 396 Section 6.3. This container has the tree diagram shown below. 398 +--:(onboarding-information) 399 +---- onboarding-information 400 +---- boot-image 401 | +---- os-name? string 402 | +---- os-version? string 403 | +---- download-uri* inet:uri 404 | +---- image-verification* [hash-algorithm] 405 | +---- hash-algorithm identityref 406 | +---- hash-value yang:hex-string 407 +---- configuration-handling? enumeration 408 +---- pre-configuration-script? script 409 +---- configuration? binary 410 +---- post-configuration-script? script 412 Onboarding information must be trusted for it to be of any use to a 413 device. There is no option for a device to process untrusted 414 onboarding information. 416 Onboarding information is trusted whenever it is obtained via a 417 secure connection to a trusted bootstrap server, or whenever it is 418 signed by the device's owner. In all other cases, the onboarding 419 information is untrusted. 421 How devices process onboarding information is described in 422 Section 5.6. 424 3. Artifacts 426 This document defines three artifacts that can be made available to 427 devices while they are bootstrapping. Each source of bootstrapping 428 information specifies how it provides the artifacts defined in this 429 section (see Section 4). 431 3.1. Zero Touch Information 433 The zero touch information artifact encodes the essential 434 bootstrapping data for the device. This artifact is used to encode 435 the redirect information and onboarding information types discussed 436 in Section 2. 438 The zero touch information artifact is a CMS structure, as described 439 in [RFC5652], encoded using ASN.1 distinguished encoding rules (DER), 440 as specified in ITU-T X.690 [ITU.X690.1994]. The CMS structure MUST 441 contain content conforming to the YANG module specified in 442 Section 6.3. 444 The zero touch information CMS structure may encode signed or 445 unsigned bootstrapping data. When the bootstrapping data is signed, 446 it may also be encrypted but, from a terminology perspective, it is 447 still "signed data" Section 1.2. 449 When the zero touch information artifact is unsigned, as it might be 450 when communicated over trusted channels, the CMS structure's top-most 451 content type MUST be one of the OIDs described in Section 11.3, or 452 the OID id_data (1.2.840.113549.1.7.1), in which case the encoding 453 (JSON, XML, etc.) SHOULD be communicated externally. In either 454 case, the associated content is an octet string containing 455 'zerotouch-information' data in the expected encoding. 457 When the zero touch information artifact is signed, as it might be 458 when communicated over untrusted channels, the CMS structure's top- 459 most content type MUST be the OID id-signedData 460 (1.2.840.113549.1.7.2), and its inner eContentType MUST be one of the 461 OIDs described in Section 11.3, or the OID id_data 462 (1.2.840.113549.1.7.1), in which case the encoding (JSON, XML, etc.) 463 SHOULD be communicated externally. In either case, the associated 464 content or eContent is an octet string containing 'zerotouch- 465 information' data in the expected encoding. 467 When the zero touch information artifact is signed and encrypted, as 468 it might be when communicated over untrusted channels and privacy is 469 important, the CMS's structure's top-most content type MUST be the 470 OID id-envelopedData (1.2.840.113549.1.7.3), and the 471 encryptedContentInfo's content type MUST be the OID id-signedData 472 (1.2.840.113549.1.7.2), whose eContentType MUST be one of the OIDs 473 described in Section 11.3, or the OID id_data (1.2.840.113549.1.7.1), 474 in which case the encoding (JSON, XML, etc.) SHOULD be communicated 475 externally. In either case, the associated content or eContent is an 476 octet string containing 'zerotouch-information' data in the expected 477 encoding. 479 3.2. Owner Certificate 481 The owner certificate artifact is an X.509 certificate [RFC5280] that 482 is used to identify an "owner" (e.g., an organization). The owner 483 certificate can be signed by any certificate authority (CA). The 484 owner certificate either MUST have no Key Usage specified or the Key 485 Usage MUST at least set the "digitalSignature" bit. The values for 486 the owner certificate's "subject" and/or "subjectAltName" are not 487 constrained by this document. 489 The owner certificate is used by a device to verify the signature 490 over the zero touch information artifact (Section 3.1) that the 491 device should have also received, as described in Section 3.5. In 492 particular, the device verifies the signature using the public key in 493 the owner certificate over the content contained within the zero 494 touch information artifact. 496 The owner certificate artifact is formally a CMS structure, as 497 specified by [RFC5652], encoded using ASN.1 distinguished encoding 498 rules (DER), as specified in ITU-T X.690 [ITU.X690.1994]. 500 The owner certificate CMS structure MUST contain the owner 501 certificate itself, as well as all intermediate certificates leading 502 to the 'pinned-domain-cert' certificate specified in the ownership 503 voucher. The owner certificate artifact MAY optionally include the 504 'pinned-domain-cert' as well. 506 In order to support devices deployed on private networks, the owner 507 certificate CMS structure MAY also contain suitably fresh, as 508 determined by local policy, revocation objects (e.g., CRLs). Having 509 these revocation objects stapled to the owner certificate may obviate 510 the need for the device to have to download them dynamically using 511 the CRL distribution point or an OCSP responder specified in the 512 associated certificates. 514 When unencrypted, the owner certificate artifact's CMS structure's 515 top-most content type MUST be the OID id-signedData 516 (1.2.840.113549.1.7.2). The inner SignedData structure is the 517 degenerate form, whereby there are no signers, that is commonly used 518 to disseminate certificates and revocation objects. 520 When encrypted, the owner certificate artifact's CMS structure's top- 521 most content type MUST be the OID id-envelopedData 522 (1.2.840.113549.1.7.3), and the encryptedContentInfo's content type 523 MUST be the OID id-signedData (1.2.840.113549.1.7.2), whereby the 524 inner SignedData structure is the degenerate form that has no signers 525 commonly used to disseminate certificates and revocation objects. 527 3.3. Ownership Voucher 529 The ownership voucher artifact is used to securely identify a 530 device's owner, as it is known to the manufacturer. The ownership 531 voucher is signed by the device's manufacturer. 533 The ownership voucher is used to verify the owner certificate 534 (Section 3.2) that the device should have also received, as described 535 in Section 3.5. In particular, the device verifies that the owner 536 certificate has a chain of trust leading to the trusted certificate 537 included in the ownership voucher ('pinned-domain-cert'). Note that 538 this relationship holds even when the owner certificate is a self- 539 signed certificate, and hence also the pinned-domain-cert. 541 When unencrypted, the ownership voucher artifact is as defined in 542 [I-D.ietf-anima-voucher]. As described, it is a CMS structure whose 543 top-most content type MUST be the OID id-signedData 544 (1.2.840.113549.1.7.2), whose eContentType MUST be OID id-ct- 545 animaJSONVoucher (1.2.840.113549.1.9.16.1), or the OID id_data 546 (1.2.840.113549.1.7.1), in which case the encoding (JSON, XML, etc.) 547 SHOULD be communicated externally. In either case, the associated 548 content is an octet string containing ietf-voucher data in the 549 expected encoding. 551 When encrypted, the ownership voucher artifact's CMS structure's top- 552 most content type MUST be the OID id-envelopedData 553 (1.2.840.113549.1.7.3), and the encryptedContentInfo's content type 554 MUST be the OID id-signedData (1.2.840.113549.1.7.2), whose 555 eContentType MUST be OID id-ct-animaJSONVoucher 556 (1.2.840.113549.1.9.16.1), or the OID id_data (1.2.840.113549.1.7.1), 557 in which case the encoding (JSON, XML, etc.) SHOULD be communicated 558 externally. In either case, the associated content is an octet 559 string containing ietf-voucher data in the expected encoding. 561 3.4. Artifact Encryption 563 Each of the three artifacts MAY be individually encrypted. 564 Encryption may be important in some environments where the content is 565 considered sensitive. 567 Each of the three artifacts are encrypted in the same way, by the 568 unencrypted form being encapsulated inside a CMS EnvelopedData type. 570 As a consequence, both the zerotouch-information and ownership 571 voucher artifacts are signed and then encrypted, never encrypted and 572 then signed. 574 This sequencing has the advantage of shrouding the signer's 575 certificate, and ensuring that the owner knows the content being 576 signed. This sequencing further enables the owner to inspect an 577 unencrypted voucher obtained from a manufacturer and then encrypt the 578 voucher later themselves, perhaps while also stapling in current 579 revocation objects, when ready to place the artifact in an unsafe 580 location. 582 When encrypted, the CMS MUST be encrypted using a secure device 583 identity certificate for the device. This certificate MAY be the 584 same as the TLS-level client certificate the device uses when 585 connecting to bootstrap servers. The owner must possess the device's 586 identity certificate at the time of encrypting the data. How the 587 owner comes to posses the device's identity certificate for this 588 purpose is outside the scope of this document. 590 3.5. Artifact Groupings 592 The previous sections discussed the bootstrapping artifacts, but only 593 certain groupings of these artifacts make sense to return in the 594 various bootstrapping situations described in this document. These 595 groupings are: 597 Unsigned Information: This grouping is useful for cases when 598 transport level security can be used to convey trust (e.g., 599 HTTPS), or when the information can be processed in a 600 provisional manner (i.e. unsigned redirect information). 602 Signed Information, without revocations: This grouping is useful 603 when signed information is needed, because it is obtained from 604 an untrusted source, and it cannot be processed provisionally, 605 and yet either revocations are not needed or they can be 606 obtained dynamically. 608 Signed Information, with revocations: This grouping is useful 609 when signed information is needed, because it is obtained from 610 an untrusted source, and it cannot be processed provisionally, 611 and revocations are needed and cannot be obtained dynamically. 613 The artifacts associated with these groupings are described below: 615 Zero Touch Ownership Owner 616 Grouping Information Voucher Certificate 617 -------------------- ------------- ------------ ----------- 618 Unsigned Information Yes, no sig No No 620 Signed Information, Yes, with sig Yes, without Yes, without 621 without revocations revocations revocations 623 Signed Information, Yes, with sig Yes, with Yes, with 624 with revocations revocations revocations 626 4. Sources of Bootstrapping Data 628 This section defines some sources for bootstrapping data that a 629 device can access. The list of sources defined here is not meant to 630 be exhaustive. It is left to future documents to define additional 631 sources for obtaining bootstrapping data. 633 For each source of bootstrapping data defined in this section, 634 details are given for how the three artifacts listed in Section 3 are 635 provided. 637 4.1. Removable Storage 639 A directly attached removable storage device (e.g., a USB flash 640 drive) MAY be used as a source of zero touch bootstrapping data. 642 Use of a removable storage device is compelling, as it does not 643 require any external infrastructure to work. It is notable that the 644 raw boot image file can also be located on the removable storage 645 device, enabling a removable storage device to be a fully self- 646 standing bootstrapping solution. 648 To use a removable storage device as a source of bootstrapping data, 649 a device need only detect if the removable storage device is plugged 650 in and mount its filesystem. 652 A removable storage device is an untrusted source of bootstrapping 653 data. This means that the information stored on the removable 654 storage device either MUST be signed or MUST be information that can 655 be processed provisionally (e.g., unsigned redirect information). 657 From an artifact perspective, since a removable storage device 658 presents itself as a filesystem, the bootstrapping artifacts need to 659 be presented as files. The three artifacts defined in Section 3 are 660 mapped to files below. 662 Artifact to File Mapping: 664 Zero Touch Information: Mapped to a file containing the binary 665 artifact described in Section 3.1 (e.g., zerotouch- 666 information.cms). 668 Owner Certificate: Mapped to a file containing the binary 669 artifact described in Section 3.2 (e.g., owner- 670 certificate.cms). 672 Ownership Voucher: Mapped to a file containing the binary 673 artifact described in Section 3.3 (e.g., ownership-voucher.cms 674 or ownership-voucher.vcj). 676 The format of the removable storage device's filesystem and the 677 naming of the files are outside the scope of this document. However, 678 in order to facilitate interoperability, it is RECOMMENDED devices 679 support open and/or standards based filesystems. It is also 680 RECOMMENDED that devices assume a file naming convention that enables 681 more than one instance of bootstrapping data (i.e., for different 682 devices) to exist on a removable storage device. The file naming 683 convention SHOULD additionally be unique to the manufacturer, in 684 order to enable bootstrapping data from multiple manufacturers to 685 exist on a removable storage device. 687 4.2. DNS Server 689 A DNS server MAY be used as a source of zero touch bootstrapping 690 data. 692 Using a DNS server may be a compelling option for deployments having 693 existing DNS infrastructure, as it enables a touchless bootstrapping 694 option that does not entail utilizing an Internet based resource 695 hosted by a 3rd-party. 697 To use a DNS server as a source of bootstrapping data, a device MAY 698 perform a multicast DNS [RFC6762] query searching for the service 699 "_zerotouch._tcp.local.". Alternatively the device MAY perform DNS- 700 SD [RFC6763] via normal DNS operation, using the domain returned to 701 it from the DHCP server; for example, searching for the service 702 "_zerotouch._tcp.example.com". 704 Unsigned DNS records (e.g., not using DNSSEC as described in 705 [RFC6698]) are an untrusted source of bootstrapping data. This means 706 that the information stored in the DNS records either MUST be signed, 707 or MUST be information that can be processed provisionally (e.g., 708 unsigned redirect information). 710 From an artifact perspective, since a DNS server presents resource 711 records (Section 3.2.1 of [RFC1035]), the bootstrapping artifacts 712 need to be presented as resource records. The three artifacts 713 defined in Section 3 are mapped to resource records below. 715 Artifact to Resource Record Mapping: 717 Zero Touch Information: Mapped to a TXT record called "zt-info" 718 containing the base64-encoding of the binary artifact described 719 in Section 3.1. 721 Owner Certificate: Mapped to a TXT record called "zt-cert" 722 containing the base64-encoding of the binary artifact described 723 in Section 3.2. 725 Ownership Voucher: Mapped to a TXT record called "zt-voucher" 726 containing the base64-encoding of the binary artifact described 727 in Section 3.3. 729 TXT records have an upper size limit of 65535 bytes (Section 3.2.1 in 730 RFC1035), since "RDLENGTH" is a 16-bit field. Please see 731 Section 3.1.3 in RFC4408 for how a TXT record can achieve this size. 732 Due to this size limitation, some zero touch information artifacts 733 may not fit. In particular, onboarding information could hit this 734 upper bound, depending on the size of the included configuration and 735 scripts. 737 4.3. DHCP Server 739 A DHCP server MAY be used as a source of zero touch bootstrapping 740 data. 742 Using a DHCP server may be a compelling option for deployments having 743 existing DHCP infrastructure, as it enables a touchless bootstrapping 744 option that does not entail utilizing an Internet based resource 745 hosted by a 3rd-party. 747 A DHCP server is an untrusted source of bootstrapping data. Thus the 748 information stored on the DHCP server either MUST be signed, or it 749 MUST be information that can be processed provisionally (e.g., 750 unsigned redirect information). 752 However, unlike other sources of bootstrapping data described in this 753 document, the DHCP protocol (especially DHCP for IPv4) is very 754 limited in the amount of data that can be conveyed, to the extent 755 that signed data cannot be communicated. This means that only 756 unsigned redirect information can be conveyed via DHCP. 758 Since the redirect information is unsigned, it SHOULD NOT include the 759 optional trust anchor certificate, as it takes up space in the DHCP 760 message, and the device would have to discard it anyway. For this 761 reason, the DHCP options defined in Section 9 do not enable the trust 762 anchor certificate to be encoded. 764 From an artifact perspective, the three artifacts defined in 765 Section 3 are mapped to the DHCP fields specified in Section 9 as 766 follows: 768 Zero Touch Information: This artifact is not supported directly. 769 Instead, the essence of unsigned redirect information is mapped 770 to the DHCP options described in Section 9. 772 Owner Certificate: Not supported. There is not enough space in 773 the DHCP packet to hold an owner certificate artifact. 775 Ownership Voucher: Not supported. There is not enough space in 776 the DHCP packet to hold an ownership voucher artifact. 778 4.4. Bootstrap Server 780 A bootstrap server MAY be used as a source of zero touch 781 bootstrapping data. A bootstrap server is defined as a RESTCONF 782 [RFC8040] server implementing the YANG module provided in Section 7. 784 Using a bootstrap server as a source of bootstrapping data is a 785 compelling option as it MAY use transport-level security, obviating 786 the need for signed data, which may be easier to deploy in some 787 situations. 789 Unlike any other source of bootstrapping data described in this 790 document, a bootstrap server is not only a source of data, but it can 791 also receive data from devices using the YANG-defined 'report- 792 progress' RPC defined in the YANG module (Section 7.3). The 'report- 793 progress' RPC enables visibility into the bootstrapping process 794 (e.g., warnings and errors), and provides potentially useful 795 information upon completion (e.g., the device's SSH host-keys). 797 A bootstrap server may be a trusted or an untrusted source of 798 bootstrapping data, depending on if the device learned about the 799 bootstrap server's trust anchor from a trusted source. When a 800 bootstrap server is trusted, the information returned from it MAY be 801 signed. However, when the server is untrusted, in order for its 802 information to be of any use to the device, the bootstrap information 803 either MUST be signed or MUST be information that can be processed 804 provisionally (e.g., unsigned redirect information). 806 From an artifact perspective, since a bootstrap server presents data 807 conforming to a YANG data model, the bootstrapping artifacts need to 808 be mapped to YANG nodes. The three artifacts defined in Section 3 809 are mapped to 'output' nodes of the 'get-bootstrapping-data' RPC 810 defined in Section 7.3 below. 812 Artifact to Bootstrap Server Mapping: 814 Zero Touch Information: Mapped to the 'zerotouch-information' 815 leaf in the output of the 'get-bootstrapping-data' RPC. 817 Owner Certificate: Mapped to the 'owner-certificate' leaf in the 818 output of the 'get-bootstrapping-data' RPC. 820 Ownership Voucher: Mapped to the 'ownership-voucher' leaf in the 821 output of the 'get-bootstrapping-data' RPC. 823 Zero touch bootstrap servers have only two endpoints, one for the 824 'get-bootstrapping-data' RPC and one for the 'report-progress' RPC. 825 These RPCs use the authenticated RESTCONF username to isolate the 826 execution of the RPC from other devices. 828 5. Device Details 830 Devices supporting the bootstrapping strategy described in this 831 document MUST have the preconfigured state and bootstrapping logic 832 described in the following sections. 834 5.1. Initial State 835 +-------------------------------------------------------------+ 836 | | 837 | | 838 | +---------------------------------------------------------+ | 839 | | | | 840 | | | | 841 | | 1. flag to enable zerotouch bootstrapping set to "true" | | 842 | +---------------------------------------------------------+ | 843 | | 844 | +---------------------------------------------------------+ | 845 | | | | 846 | | | | 847 | | 2. TLS client cert & related intermediate certificates | | 848 | | 3. list of trusted well-known bootstrap servers | | 849 | | 4. list of trust anchor certs for bootstrap servers | | 850 | | 5. list of trust anchor certs for ownership vouchers | | 851 | +---------------------------------------------------------+ | 852 | | 853 | +-----------------------------------------------------+ | 854 | | | | 855 | | | | 856 | | 6. private key for TLS client certificate | | 857 | | 7. private key for decrypting zerotouch artifacts | | 858 | +-----------------------------------------------------+ | 859 | | 860 +-------------------------------------------------------------+ 862 Each numbered item below corresponds to a numbered item in the 863 diagram above. 865 1. Devices MUST have a configurable variable that is used to enable/ 866 disable zerotouch bootstrapping. This variable MUST be enabled 867 by default in order for zerotouch bootstrapping to run when the 868 device first powers on. Because it is a goal that the 869 configuration installed by the bootstrapping process disables 870 zerotouch bootstrapping, and because the configuration may be 871 merged into the existing configuration, using a configuration 872 node that relies on presence is NOT RECOMMENDED, as it cannot be 873 removed by the merging process. 875 2. Devices that support loading bootstrapping data from bootstrap 876 servers (see Section 4.4) SHOULD possess a TLS-level client 877 certificate and any intermediate certificates leading to the 878 certificate's well-known trust-anchor. The well-known trust 879 anchor certificate may be an intermediate certificate or a self- 880 signed root certificate. To support devices not having a client 881 certificate, devices MAY, alternatively or in addition to, 882 identify and authenticate themselves to the bootstrap server 883 using an HTTP authentication scheme, as allowed by Section 2.5 in 884 [RFC8040]; however, this document does not define a mechanism for 885 operator input enabling, for example, the entering of a password. 887 3. Devices that support loading bootstrapping data from well-known 888 bootstrap servers MUST possess a list of the well-known bootstrap 889 servers. Consistent with redirect information (Section 2.1, each 890 bootstrap server can be identified by its hostname or IP address, 891 and an optional port. 893 4. Devices that support loading bootstrapping data from well-known 894 bootstrap servers MUST also possess a list of trust anchor 895 certificates that can be used to authenticate the well-known 896 bootstrap servers. For each trust anchor certificate, if it is 897 not itself a self-signed root certificate, the device SHOULD also 898 possess the chain of intermediate certificates leading up to and 899 including the self-signed root certificate. 901 5. Devices that support loading signed data (see Section 1.2) MUST 902 possess the trust anchor certificates for validating ownership 903 vouchers. For each trust anchor certificate, if it is not itself 904 a self-signed root certificate, the device SHOULD also possess 905 the chain of intermediate certificates leading up to and 906 including the self-signed root certificate. 908 6. Devices that support using a TLS-level client certificate to 909 identify and authenticate themselves to a bootstrap server MUST 910 possess the private key that corresponds to the public key 911 encoded in the TLS-level client certificate. This private key 912 SHOULD be securely stored, ideally in a cryptographic processor 913 (e.g., a TPM). 915 7. Devices that support decrypting zerotouch artifacts MUST posses 916 the private key that corresponds to the public key encoded in the 917 secure device identity certificate used when encrypting the 918 artifacts. This private key SHOULD be securely stored, ideally 919 in a cryptographic processor (e.g., a TPM). This private key MAY 920 be the same as the one associated to the TLS-level client 921 certificate used when connecting to bootstrap servers. 923 A YANG module representing this data is provided in Section 8. 925 5.2. Boot Sequence 927 A device claiming to support the bootstrapping strategy defined in 928 this document MUST support the boot sequence described in this 929 section. 931 Power On 932 | 933 v No 934 1. Zerotouch bootstrapping configured ------> Boot normally 935 | 936 | Yes 937 v 938 2. For each supported source of bootstrapping data, 939 try to load bootstrapping data from the source 940 | 941 | 942 v Yes 943 3. Able to bootstrap from any source? -----> Run with new config 944 | 945 | No 946 v 947 4. Loop and/or wait for manual provisioning. 949 Each numbered item below corresponds to a numbered item in the 950 diagram above. 952 1. When the device powers on, it first checks to see if zerotouch 953 bootstrapping is configured, as is expected to be the case for 954 the device's preconfigured initial state. If zerotouch 955 bootstrapping is not configured, then the device boots normally. 957 2. The device iterates over its list of sources for bootstrapping 958 data (Section 4). Details for how to processes a source of 959 bootstrapping data are provided in Section 5.3. 961 3. If the device is able to bootstrap itself from any of the sources 962 of bootstrapping data, it runs with the new bootstrapped 963 configuration. 965 4. Otherwise the device MAY loop back through the list of 966 bootstrapping sources again and/or wait for manual provisioning. 968 5.3. Processing a Source of Bootstrapping Data 970 This section describes a recursive algorithm that devices can use to, 971 ultimately, obtain onboarding information. The algorithm is 972 recursive because sources of bootstrapping data may return redirect 973 information, which causes the algorithm to run again, for the newly 974 discovered sources of bootstrapping information. An expression that 975 captures all possible successful sequences of bootstrapping 976 information is zero or more redirect information responses, followed 977 by one onboarding information response. 979 An important aspect of the algorithm is knowing when data needs to be 980 signed or not. The following figure provides a summary of options: 982 Untrusted Source Trusted Source 983 Kind of Bootstrapping Data Can Provide? Can Provide? 985 Unsigned Redirect Info : Yes+ Yes 986 Signed Redirect Info : Yes Yes* 987 Unsigned Onboarding Info : No Yes 988 Signed Onboarding Info : Yes Yes* 990 The '+' above denotes that the source redirected to MUST 991 return signed data, or more unsigned redirect information. 993 The '*' above denotes that, while possible, it is generally 994 unnecessary for a trusted source to return signed data. 996 The recursive algorithm uses a conceptual global-scoped variable 997 called "trust-state". The trust-state variable is initialized to 998 FALSE. The ultimate goal of this algorithm is for the device to 999 process onboarding information (Section 2.2) while the trust-state 1000 variable is TRUE. 1002 If the source of bootstrapping data (Section 4) is a bootstrap server 1003 (Section 4.4), and the device is able to authenticate the bootstrap 1004 server using X.509 certificate path validation ([RFC6125], Section 6) 1005 to one of the device's preconfigured trust anchors, or to a trust 1006 anchor that it learned from a previous step, then the device MUST set 1007 trust-state to TRUE. 1009 When establishing a connection to a trusted bootstrap server (i.e. 1010 trust-state is TRUE), the device MAY, per Section 2.5 in [RFC8040], 1011 identify and authenticate itself to the bootstrap server using a TLS- 1012 level client certificate and/or an HTTP authentication scheme. If 1013 both mechanisms are used, they MUST both identify the same device 1014 using its serial number. 1016 When establishing a connection to an untrusted bootstrap server (i.e. 1017 trust-state is FALSE), it is still necessary for the device to 1018 identify itself, in order to receive device-specific signed data, due 1019 to the ownership voucher encoding the device's serial number. The 1020 device MUST identify and authenticate itself to the bootstrap server 1021 using a TLS-level client certificate and/or an HTTP authentication 1022 scheme. However, because the bootstrap server is untrusted, the 1023 device MUST NOT use an authentication scheme that conveys a shared 1024 secret, such as a password. 1026 When sending a client certificate, the device MUST also send all the 1027 intermediate certificates leading up to, and optionally including, 1028 the client certificate's well-known trust anchor certificate. 1030 For any source of bootstrapping data (e.g., Section 4), if any 1031 artifact obtained is encrypted, the device MUST first decrypt it 1032 using the private key associated with the device certificate used to 1033 encrypt the artifact. 1035 If the zero touch information artifact is signed, and the device is 1036 able to validate the signed data using the algorithm described in 1037 Section 5.4, then the device MUST set trust-state to TRUE; otherwise, 1038 if the device is unable to validate the signed data, the device MUST 1039 set trust-state to FALSE. Note, this is worded to cover the special 1040 case when signed data is returned even from a trusted bootstrap 1041 server. 1043 If the zero touch information artifact contains onboarding 1044 information, and trust-state is FALSE, the device MUST exit the 1045 recursive algorithm (as this is not allowed, see the figure above), 1046 returning to the state machine described in Section 5.2. Otherwise, 1047 the device MUST attempt to process the onboarding information as 1048 described in Section 5.6. In either case, success or failure, the 1049 device MUST exit the recursive algorithm, returning to the state 1050 machine described in Section 5.2, the only difference being in how it 1051 responds to the "Able to bootstrap from any source?" conditional 1052 described in the figure in the section. 1054 If the zero touch information artifact contains redirect information, 1055 the device MUST process the redirect information as described in 1056 Section 5.5. This is the recursion step, it will cause the device to 1057 reenter this algorithm, but this time the data source will definitely 1058 be a bootstrap server, as that is all redirect information is able to 1059 redirect a device to. 1061 5.4. Validating Signed Data 1063 Whenever a device is presented signed data, it MUST validate the 1064 signed data as described in this section. This includes the case 1065 where the signed data is provided by a trusted source. 1067 Whenever there is signed data, the device MUST also be provided an 1068 ownership voucher and an owner certificate. How all the needed 1069 artifacts are provided for each source of bootstrapping data is 1070 described in Section 4. 1072 In order to validate signed data, the device MUST first authenticate 1073 the ownership voucher by validating its signature to one of its 1074 preconfigured trust anchors (see Section 5.1), which may entail using 1075 additional intermediate certificates attached to the ownership 1076 voucher. If the device has an accurate clock, it MUST verify that 1077 the ownership voucher was created in the past (i.e., 'created-on' < 1078 now) and, if the 'expires-on' leaf is present, the device MUST verify 1079 that the ownership voucher has not yet expired (i.e., now < 'expires- 1080 on'). The device MUST verify that the ownership voucher's 1081 'assertion' value is acceptable (e.g., some devices may only accept 1082 the assertion value 'verified'). The device MUST verify that the 1083 ownership voucher specifies the device's serial number in the 1084 'serial-number' leaf. If the 'idevid-issuer' leaf is present, the 1085 device MUST verify that the value is set correctly. If the 1086 authentication of the ownership voucher is successful, the device 1087 extracts the 'pinned-domain-cert' node, an X.509 certificate, that is 1088 needed to verify the owner certificate in the next step. 1090 The device MUST next authenticate the owner certificate by performing 1091 X.509 certificate path verification to the trusted certificate 1092 extracted from the ownership voucher's 'pinned-domain-cert' node. 1093 This verification may entail using additional intermediate 1094 certificates attached to the owner certificate artifact. If the 1095 ownership voucher's 'domain-cert-revocation-checks' node's value is 1096 set to "true", the device MUST verify the revocation status of the 1097 certificate chain used to sign the owner certificate and, if the 1098 revocation status is not attainable or if it is determined that a 1099 certificate has been revoked, the device MUST not validate the owner 1100 certificate. 1102 Finally the device MUST verify the zero touch information artifact 1103 was signed by the validated owner certificate. 1105 If any of these steps fail, the device MUST invalidate the signed 1106 data and not perform any subsequent steps. 1108 5.5. Processing Redirect Information 1110 In order to process redirect information (Section 2.1), the device 1111 MUST follow the steps presented in this section. 1113 Processing redirect information is straightforward, the device 1114 sequentially steps through the list of provided bootstrap servers 1115 until it can find one it can bootstrap from. 1117 If a hostname is provided, and the hostname's DNS resolution is to 1118 more than one IP address, the device MUST attempt to connect to all 1119 of the DNS resolved addresses at least once, before moving on to the 1120 next bootstrap server. If the device is able to obtain bootstrapping 1121 data from any of the DNS resolved addresses, it MUST immediately 1122 process that data, without attempting to connect to any of the other 1123 DNS resolved addresses. 1125 If the redirect information is trusted (e.g., trust-state is TRUE), 1126 and the bootstrap server entry contains a trust anchor certificate, 1127 then the device MUST authenticate the specified bootstrap server's 1128 TLS server certificate using X.509 certificate path validation 1129 ([RFC6125], Section 6) to the specified trust anchor. If the 1130 bootstrap server entry does not contain a trust anchor certificate 1131 device, the device MUST establish a provisional connection to the 1132 bootstrap server (i.e., by blindly accepting its server certificate), 1133 and set trust-state to FALSE. 1135 If the redirect information is untrusted (e.g., trust-state is 1136 FALSE), the device MUST discard any trust anchors provided by the 1137 redirect information and establish a provisional connection to the 1138 bootstrap server (i.e., by blindly accepting its TLS server 1139 certificate). 1141 5.6. Processing Onboarding Information 1143 In order to process onboarding information (Section 2.2), the device 1144 MUST follow the steps presented in this section. 1146 When processing onboarding information, the device MUST first process 1147 the boot image information (if any), then execute the pre- 1148 configuration script (if any), then commit the initial configuration 1149 (if any), and then execute the post-configuration script (if any), in 1150 that order. If the device encounters an error at any step, it MUST 1151 NOT proceed to the next step. 1153 When the onboarding information is obtained from a trusted bootstrap 1154 server, the device SHOULD send progress reports throughout the 1155 bootstrapping process using the bootstrap server's 'report-progress' 1156 RPC. When the onboarding information was obtained from an untrusted 1157 bootstrap server, the device SHOULD NOT send any progress reports to 1158 the bootstrap server, even after validating any signed data it may 1159 have receive from the bootstrap server. 1161 If boot image criteria is specified, the device MUST first determine 1162 if the boot image it is running satisfies the specified boot image 1163 criteria. If the device is not running the specified boot image, 1164 then it MUST install the specified boot image or fail processing the 1165 onboarding information. In order to install the specified boot 1166 image, the device MUST download, verify, and install the specified 1167 boot image, and then reboot. To verify the downloaded boot image, 1168 the device MUST check that the boot image file matches the 1169 verification fingerprint supplied by the onboarding information. 1171 Upon rebooting, the bootstrapping process runs again, which will 1172 eventually come to this very point, but this time the device will be 1173 running the specified boot image, and thus will move to processing 1174 the next step. 1176 Next, for devices that support executing scripts, if a pre- 1177 configuration script has been specified, the device MUST execute the 1178 script and check its exit status code to determine if it had any 1179 warnings or errors. In the case of errors, the device MUST reset 1180 itself in such a way that wipes out any bad state the script may have 1181 left behind. 1183 Next, if an initial configuration has been supplied, the device MUST 1184 commit the provided initial configuration, using the approach 1185 specified by the 'configuration-handling' leaf. If there is an 1186 error, and the device previously executed a pre-configuration script, 1187 the device does not need to reset itself in order to wipe out any 1188 state the script may have left behind; this implies that the pre- 1189 configuration script must be idempotent. 1191 Again, for devices that support executing scripts, if a post- 1192 configuration script has been specified, the device MUST execute the 1193 script and check its exit status code to determine if it had any 1194 warnings or errors. In the case of errors, the device MUST reset 1195 itself in such a way that wipes out any bad state the script may have 1196 left behind. 1198 At this point, the device has completely processed the bootstrapping 1199 data. If the device obtained the onboarding information from a 1200 trusted bootstrap server, the device MUST post the 'bootstrap- 1201 complete' progress report now, using the bootstrap server's 'report- 1202 progress' RPC. 1204 The device is now running its initial configuration. Notably, if 1205 NETCONF Call Home or RESTCONF Call Home [RFC8071] is configured, the 1206 device initiates trying to establish a call home connection at this 1207 time. 1209 6. The Zero Touch Information Data Model 1211 This section defines a YANG 1.1 [RFC7950] module that is used to 1212 define the data model for the zero touch information artifact 1213 described in Section 3.1. This data model uses the 'yang-data' 1214 extension statement defined in [I-D.ietf-netmod-yang-data-ext]. 1215 Examples illustrating this data model are provided in Section 6.2. 1217 6.1. Data Model Overview 1219 The following tree diagram provides an overview of the data model for 1220 the zero touch information artifact. 1222 module: ietf-zerotouch-information 1224 yang-data zerotouch-information: 1225 +---- (information-type) 1226 +--:(redirect-information) 1227 | +---- redirect-information 1228 | +---- bootstrap-server* [address] 1229 | +---- address inet:host 1230 | +---- port? inet:port-number 1231 | +---- trust-anchor? cms 1232 +--:(onboarding-information) 1233 +---- onboarding-information 1234 +---- boot-image 1235 | +---- os-name? string 1236 | +---- os-version? string 1237 | +---- download-uri* inet:uri 1238 | +---- image-verification* [hash-algorithm] 1239 | +---- hash-algorithm identityref 1240 | +---- hash-value yang:hex-string 1241 +---- configuration-handling? enumeration 1242 +---- pre-configuration-script? script 1243 +---- configuration? binary 1244 +---- post-configuration-script? script 1246 6.2. Example Usage 1248 The following example illustrates how redirect information 1249 (Section 2.1) can be encoded using JSON. 1251 { 1252 "ietf-zerotouch-information:redirect-information" : { 1253 "bootstrap-server" : [ 1254 { 1255 "address" : "phs1.example.com", 1256 "port" : 8443, 1257 "trust-anchor" : "base64encodedvalue==" 1258 }, 1259 { 1260 "address" : "phs2.example.com", 1261 "port" : 8443, 1262 "trust-anchor" : "base64encodedvalue==" 1263 }, 1264 { 1265 "address" : "phs3.example.com", 1266 "port" : 8443, 1267 "trust-anchor" : "base64encodedvalue==" 1268 } 1269 ] 1270 } 1271 } 1273 The following example illustrates how onboarding information 1274 (Section 2.2) can be encoded using JSON. 1276 [note: '\' line wrapping for formatting only] 1278 { 1279 "ietf-zerotouch-information:onboarding-information" : { 1280 "boot-image" : { 1281 "os-name" : "VendorOS", 1282 "os-version" : "17.2R1.6", 1283 "download-uri" : [ "http://some/path/to/raw/file" ], 1284 "image-verification" : [ 1285 { 1286 "hash-algorithm" : "ietf-zerotouch-information:sha-256", 1287 "hash-value" : "ba:ec:cf:a5:67:82:b4:10:77:c6:67:a6:22:ab:\ 1288 7d:50:04:a7:8b:8f:0e:db:02:8b:f4:75:55:fb:c1:13:b2:33" 1289 } 1290 ] 1291 }, 1292 "configuration-handling" : "merge", 1293 "pre-configuration-script" : "base64encodedvalue==", 1294 "configuration" : "base64encodedvalue==", 1295 "post-configuration-script" : "base64encodedvalue==" 1296 } 1297 } 1299 6.3. YANG Module 1301 The zero touch information data model is defined by the YANG module 1302 presented in this section. 1304 Note: the module defined herein uses data types defined in [RFC5280], 1305 [RFC6234], and [RFC6991], and an extension statement from 1306 [I-D.ietf-netmod-yang-data-ext], and an encoding defined in 1307 [ITU.X690.1994]. 1309 file "ietf-zerotouch-information@2018-03-05.yang" 1310 module ietf-zerotouch-information { 1311 yang-version 1.1; 1312 namespace "urn:ietf:params:xml:ns:yang:ietf-zerotouch-information"; 1313 prefix zti; 1315 import ietf-yang-types { 1316 prefix yang; 1317 reference "RFC 6991: Common YANG Data Types"; 1318 } 1319 import ietf-inet-types { 1320 prefix inet; 1321 reference "RFC 6991: Common YANG Data Types"; 1322 } 1323 import ietf-yang-data-ext { 1324 prefix yd; 1325 reference "I-D.ietf-netmod-yang-data-ext: YANG Data Extensions"; 1326 } 1328 organization 1329 "IETF NETCONF (Network Configuration) Working Group"; 1331 contact 1332 "WG Web: http://tools.ietf.org/wg/netconf 1333 WG List: 1334 Author: Kent Watsen "; 1336 description 1337 "This module defines the data model for the Zero Touch 1338 Information artifact defined in RFC XXXX: Zero Touch 1339 Provisioning for Networking Devices. 1341 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1342 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', 1343 and 'OPTIONAL' in the module text are to be interpreted as 1344 described in RFC 2119. 1346 Copyright (c) 2018 IETF Trust and the persons identified as 1347 authors of the code. All rights reserved. 1349 Redistribution and use in source and binary forms, with or 1350 without modification, is permitted pursuant to, and subject 1351 to the license terms contained in, the Simplified BSD License 1352 set forth in Section 4.c of the IETF Trust's Legal Provisions 1353 Relating to IETF Documents (http://trustee.ietf.org/license-info) 1355 This version of this YANG module is part of RFC XXXX; see the 1356 RFC itself for full legal notices."; 1358 revision 2018-03-05 { 1359 description 1360 "Initial version"; 1361 reference 1362 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 1363 } 1365 // identities 1367 identity hash-algorithm { 1368 description 1369 "A base identity for hash algorithm verification"; 1370 } 1372 identity sha-256 { 1373 base "hash-algorithm"; 1374 description "The SHA-256 algorithm."; 1375 reference "RFC 6234: US Secure Hash Algorithms."; 1376 } 1378 // typedefs 1380 typedef cms { 1381 type binary; 1382 description 1383 "A CMS structure, as specified in RFC 5652, encoded using 1384 ASN.1 distinguished encoding rules (DER), as specified in 1385 ITU-T X.690."; 1386 reference 1387 "RFC 5652: 1388 Cryptographic Message Syntax (CMS) 1389 ITU-T X.690: 1390 Information technology - ASN.1 encoding rules: 1391 Specification of Basic Encoding Rules (BER), 1392 Canonical Encoding Rules (CER) and Distinguished 1393 Encoding Rules (DER)."; 1394 } 1395 // yang-data 1397 yd:yang-data "zerotouch-information" { 1398 choice information-type { 1399 mandatory true; 1400 description 1401 "This choice statement ensures the response contains 1402 redirect-information or onboarding-information."; 1403 container redirect-information { 1404 description 1405 "Redirect information is described in Section 2.1 in 1406 RFC XXXX. Its purpose is to redirect a device to 1407 another bootstrap server."; 1408 reference 1409 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 1410 list bootstrap-server { 1411 key "address"; 1412 min-elements 1; 1413 description 1414 "A bootstrap server entry."; 1415 leaf address { 1416 type inet:host; 1417 mandatory true; 1418 description 1419 "The IP address or hostname of the bootstrap server the 1420 device should redirect to."; 1421 } 1422 leaf port { 1423 type inet:port-number; 1424 default "443"; 1425 description 1426 "The port number the bootstrap server listens on. If no 1427 port is specified, the IANA-assigned port for 'https' 1428 (443) is used."; 1429 } 1430 leaf trust-anchor { 1431 type cms; 1432 description 1433 "A CMS structure that MUST contain the chain of 1434 X.509 certificates needed to authenticate the TLS 1435 certificate presented by this bootstrap server. 1436 In all cases, the chain MUST include a self-signed 1437 root certificate. In the case where the root 1438 certificate is itself the issuer of the bootstrap 1439 server's TLS certificate, only one X.509 certificate 1440 is present. If needed by the device, this CMS 1441 structure MAY also contain suitably fresh revocation 1442 objects with which the device can verify the 1443 revocation status of the certificates. 1445 This CMS encodes the degenerate form of the SignedData 1446 structure that is commonly used to disseminate X.509 1447 certificates and revocation objects."; 1448 reference 1449 "RFC 5280: 1450 Internet X.509 Public Key Infrastructure Certificate 1451 and Certificate Revocation List (CRL) Profile."; 1452 } 1453 } 1454 } 1455 container onboarding-information { 1456 description 1457 "Onboarding information is described in Section 2.2 in 1458 RFC XXXX. Its purpose is to provide the device everything 1459 it needs to bootstrap itself."; 1460 reference 1461 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 1462 container boot-image { 1463 description 1464 "Specifies criteria for the boot image the device MUST 1465 be running, as well as information enabling the device 1466 to install the required boot image."; 1467 leaf os-name { 1468 type string; 1469 description 1470 "The name of the operating system software the device 1471 MUST be running in order to not require a software 1472 image upgrade (ex. VendorOS)."; 1473 } 1474 leaf os-version { 1475 type string; 1476 description 1477 "The version of the operating system software the 1478 device MUST be running in order to not require a 1479 software image upgrade (ex. 17.3R2.1)."; 1480 } 1481 leaf-list download-uri { 1482 type inet:uri; 1483 must '../image-verification' { 1484 description 1485 "Image verification information must be provided if 1486 the device is going to download an image."; 1487 } 1488 ordered-by user; 1489 description 1490 "An ordered list of URIs to where the necessary 1491 boot-image file may be obtained. Deployments must 1492 know through out-of-band means which URI schemes 1493 (http, ftp, etc.) the bootstrapping device supports. 1494 If a secure scheme (e.g., https) is provided, a 1495 device MAY establish an untrusted connection to the 1496 remote server to obtain the boot-image."; 1497 } 1498 list image-verification { 1499 must '../download-uri' { 1500 description 1501 "Download URIs must be provided if an image is to 1502 be verified."; 1503 } 1504 key hash-algorithm; 1505 description 1506 "A list of hash values that a device can use to verify 1507 boot image files with."; 1508 leaf hash-algorithm { 1509 type identityref { 1510 base "hash-algorithm"; 1511 } 1512 description 1513 "Identifies the hash algorithm used."; 1514 } 1515 leaf hash-value { 1516 type yang:hex-string; 1517 mandatory true; 1518 description 1519 "The hex-encoded value of the specified hash 1520 algorithm over the contents of the boot image 1521 file."; 1522 } 1523 } 1524 } 1525 leaf configuration-handling { 1526 type enumeration { 1527 enum "merge" { 1528 description 1529 "Merge configuration into the running datastore."; 1530 } 1531 enum "replace" { 1532 description 1533 "Replace the existing running datastore with the 1534 passed configuration."; 1535 } 1536 } 1537 must '../configuration'; 1538 description 1539 "This enumeration indicates how the server should process 1540 the provided configuration."; 1541 } 1542 leaf pre-configuration-script { 1543 type script; 1544 description 1545 "A script that, when present, is executed before the 1546 configuration has been processed."; 1547 } 1548 leaf configuration { 1549 type binary; 1550 must '../configuration-handling'; 1551 description 1552 "Any configuration known to the device. The use of 1553 the 'binary' type enables e.g., XML-content to be 1554 embedded into a JSON document. The exact encoding 1555 of the content, as with the scripts, is vendor 1556 specific."; 1557 } 1558 leaf post-configuration-script { 1559 type script; 1560 description 1561 "A script that, when present, is executed after the 1562 configuration has been processed."; 1563 } 1564 } 1565 } 1566 } 1568 typedef script { 1569 type binary; 1570 description 1571 "A device specific script that enables the execution of 1572 commands to perform actions not possible thru configuration 1573 alone. 1575 No attempt is made to standardize the contents, running 1576 context, or programming language of the script, other than 1577 that it can emit an exit status code and stderr/sdtout. The 1578 contents of the script are considered specific to the vendor, 1579 product line, and/or model of the device. 1581 If a script is erroneously provided to a device that does not 1582 support the execution of scripts, and the device obtained the 1583 onboarding information from a trusted bootstrap server, the 1584 device SHOULD send either a 'pre-script-warning' or 1585 'post-script-warning' progress report, based on which kind 1586 of script was presented, but otherwise continue processing 1587 the bootstrapping data as if the script had not been present. 1589 The script returns exit status code zero on success and 1590 non-zero otherwise, with accompanying stderr/stdout for 1591 logging purposes. 1593 If the exit status code is greater than zero, then the device 1594 should assume that the script had a soft error, which the 1595 script believes does not affect manageability. If the device 1596 obtained the bootstrap information from a trusted bootstrap 1597 server, it SHOULD either send a 'pre-script-warning' or 1598 'post-script-warning' progress report, based on which kind of 1599 script was executed. 1601 If the exit status code is less than zero, the device should 1602 assume the script had a hard error, which the script believes 1603 will affect manageability. If the device obtained the 1604 bootstrap information from a trusted bootstrap server, it 1605 SHOULD send a 'pre-script-error' or 'post-script-error' 1606 progress report, based on which kind of script was executed, 1607 followed by a reset that will wipe out any bad state left by 1608 the script, and restart the entire bootstrapping process."; 1609 } 1610 } 1611 1613 7. The Zero Touch Bootstrap Server API 1615 This section defines the API for bootstrap servers. The API is 1616 defined as that produced by a RESTCONF [RFC8040] server that supports 1617 the YANG 1.1 [RFC7950] module defined in this section. 1619 7.1. API Overview 1621 The following tree diagram provides an overview for the bootstrap 1622 server RESTCONF API. 1624 module: ietf-zerotouch-bootstrap-server 1626 rpcs: 1627 +---x get-bootstrapping-data 1628 | +---w input 1629 | | +---w untrusted-connection? empty 1630 | | +---w hw-model? string 1631 | | +---w os-name? string 1632 | | +---w os-version? string 1633 | | +---w nonce? binary 1634 | +--ro output 1635 | +--ro zerotouch-information cms 1636 | +--ro owner-certificate? cms 1637 | +--ro ownership-voucher? cms 1638 +---x report-progress 1639 +---w input 1640 +---w progress-type enumeration 1641 +---w message? string 1642 +---w ssh-host-keys 1643 | +---w ssh-host-key* [] 1644 | +---w format enumeration 1645 | +---w key-data string 1646 +---w trust-anchors 1647 +---w trust-anchor* [] 1648 +---w certificate cms 1650 7.2. Example Usage 1652 This section presents three examples illustrating the bootstrap 1653 server's API. Two examples are provided for the 'get-bootstrapping- 1654 data' RPC (once to an untrusted bootstrap server, and again to a 1655 trusted bootstrap server), and one example for the 'report-progress' 1656 RPC. 1658 The following example illustrates a device using the API to fetch its 1659 bootstrapping data from a untrusted bootstrap server. In this 1660 example, the device sends the 'untrusted-connection' input parameter 1661 and receives signed data in the response. 1663 REQUEST 1664 ------- 1665 ['\' line wrapping added for formatting only] 1667 POST /restconf/operations/ietf-zerotouch-bootstrap-server:get-boot\ 1668 strapping-data HTTP/1.1 1669 HOST: example.com 1670 Content-Type: application/yang.data+xml 1672 1674 1675 1677 RESPONSE 1678 -------- 1680 HTTP/1.1 200 OK 1681 Date: Sat, 31 Oct 2015 17:02:40 GMT 1682 Server: example-server 1683 Content-Type: application/yang.data+xml 1685 1687 base64encodedvalue== 1688 base64encodedvalue== 1689 base64encodedvalue== 1690 1692 The following example illustrates a device using the API to fetch its 1693 bootstrapping data from a trusted bootstrap server. In this example, 1694 the device sends addition input parameters to the bootstrap server, 1695 which it may use when formulating its response to the device. 1697 REQUEST 1698 ------- 1699 ['\' line wrapping added for formatting only] 1701 POST /restconf/operations/ietf-zerotouch-bootstrap-server:get-boot\ 1702 strapping-data HTTP/1.1 1703 HOST: example.com 1704 Content-Type: application/yang.data+xml 1706 1708 model-x 1709 vendor-os 1710 17.3R2.1 1711 base64encodedvalue== 1712 1714 RESPONSE 1715 -------- 1717 HTTP/1.1 200 OK 1718 Date: Sat, 31 Oct 2015 17:02:40 GMT 1719 Server: example-server 1720 Content-Type: application/yang.data+xml 1722 1724 base64encodedvalue== 1725 1727 The following example illustrates a device using the API to post a 1728 progress report to a bootstrap server. Illustrated below is the 1729 'bootstrap-complete' message, but the device may send other progress 1730 reports to the server while bootstrapping. In this example, the 1731 device is sending both its SSH host keys and a TLS server 1732 certificate, which the bootstrap server may, for example, pass to an 1733 NMS, as discussed in Appendix B.3. 1735 REQUEST 1736 ------- 1737 ['\' line wrapping added for formatting only] 1739 POST /restconf/operations/ietf-zerotouch-bootstrap-server:report-\ 1740 progress HTTP/1.1 1741 HOST: example.com 1742 Content-Type: application/yang.data+xml 1744 1746 bootstrap-complete 1747 example message 1748 1749 1750 ssh-rsa 1751 base64encodedvalue== 1752 1753 1754 ssh-dss 1755 base64encodedvalue== 1756 1757 1758 1759 1760 base64encodedvalue== 1761 1762 1763 1765 RESPONSE 1766 -------- 1768 HTTP/1.1 204 No Content 1769 Date: Sat, 31 Oct 2015 17:02:40 GMT 1770 Server: example-server 1772 7.3. YANG Module 1774 The bootstrap server's device-facing API is normatively defined by 1775 the YANG module defined in this section. 1777 Note: the module defined herein uses data types defined in [RFC5652], 1778 [RFC5280], [RFC6960], and [I-D.ietf-anima-voucher], and uses an 1779 encoding defined in [ITU.X690.1994]. 1781 file "ietf-zerotouch-bootstrap-server@2018-03-05.yang" 1782 module ietf-zerotouch-bootstrap-server { 1783 yang-version 1.1; 1784 namespace 1785 "urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server"; 1786 prefix ztbs; 1788 organization 1789 "IETF NETCONF (Network Configuration) Working Group"; 1791 contact 1792 "WG Web: 1793 WG List: 1794 Author: Kent Watsen "; 1796 description 1797 "This module defines an interface for bootstrap servers, as 1798 defined by RFC XXXX: Zero Touch Provisioning for Networking 1799 Devices. 1801 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1802 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', 1803 and 'OPTIONAL' in the module text are to be interpreted as 1804 described in RFC 2119. 1806 Copyright (c) 2018 IETF Trust and the persons identified as 1807 authors of the code. All rights reserved. 1809 Redistribution and use in source and binary forms, with or 1810 without modification, is permitted pursuant to, and subject 1811 to the license terms contained in, the Simplified BSD License 1812 set forth in Section 4.c of the IETF Trust's Legal Provisions 1813 Relating to IETF Documents (http://trustee.ietf.org/license-info) 1815 This version of this YANG module is part of RFC XXXX; see the 1816 RFC itself for full legal notices."; 1818 revision 2018-03-05 { 1819 description 1820 "Initial version"; 1821 reference 1822 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 1823 } 1825 // typedefs 1827 typedef cms { 1828 type binary; 1829 description 1830 "A CMS structure, as specified in RFC 5652, encoded using 1831 ASN.1 distinguished encoding rules (DER), as specified in 1832 ITU-T X.690."; 1833 reference 1834 "RFC 5652: 1835 Cryptographic Message Syntax (CMS) 1836 ITU-T X.690: 1837 Information technology - ASN.1 encoding rules: 1838 Specification of Basic Encoding Rules (BER), 1839 Canonical Encoding Rules (CER) and Distinguished 1840 Encoding Rules (DER)."; 1841 } 1843 // RPCs 1845 rpc get-bootstrapping-data { 1846 description 1847 "This RPC enables a device, as identified by the RESTCONF 1848 username, to obtain bootstrapping data that has been made 1849 available for it."; 1850 input { 1851 leaf untrusted-connection { 1852 type empty; 1853 description 1854 "This optional input parameter enables a device to 1855 communicate to the bootstrap server that it is unable to 1856 authenticate the bootstrap server's TLS certificate. In 1857 such circumstances, the device likely does not send any 1858 of the other input parameters, except for the 'nonce' 1859 parameter. Upon receiving this input parameter, the 1860 bootstrap server should only return unsigned redirect 1861 information or signed data of any type."; 1862 } 1863 leaf hw-model { 1864 type string; 1865 description 1866 "This optional input parameter enables a device to 1867 communicate to the bootstrap server its vendor specific 1868 hardware model number. This parameter may be needed, 1869 for instance, when a device's IDevID certificate does 1870 not include the 'hardwareModelName' value in its 1871 subjectAltName field, as is allowed by 802.1AR-2009."; 1872 reference 1873 "IEEE 802.1AR-2009: IEEE Standard for Local and 1874 metropolitan area networks - Secure Device Identity"; 1875 } 1876 leaf os-name { 1877 type string; 1878 description 1879 "This optional input parameter enables a device to 1880 communicate to the bootstrap server the name of its 1881 operating system. This parameter may be useful if 1882 the device, as identified by its serial number, can 1883 run more than one type of operating system (e.g., 1884 on a white-box system."; 1885 } 1886 leaf os-version { 1887 type string; 1888 description 1889 "This optional input parameter enables a device to 1890 communicate to the bootstrap server the version of its 1891 operating system. This parameter may be used by a 1892 bootstrap server to return an operating system specific 1893 response to the device, thus negating the need for a 1894 potentially expensive boot-image update."; 1895 } 1896 leaf nonce { 1897 type binary { 1898 length "8..32"; 1899 } 1900 description 1901 "This optional input parameter enables a device to 1902 communicate to the bootstrap server a nonce value. 1903 This may be especially useful for devices lacking 1904 an accurate clock, as then the bootstrap server 1905 can dynamically obtain from the manufacturer a 1906 voucher with the nonce value in it, as described 1907 in I-D.ietf-anima-voucher."; 1908 reference 1909 "RFC ZZZZ: Voucher Profile for Bootstrapping Protocols."; 1910 } 1911 } 1912 output { 1913 leaf zerotouch-information { 1914 type cms; 1915 mandatory true; 1916 description 1917 "A zero touch information artifact, as described in 1918 Section 3.1 of RFC XXXX."; 1919 reference 1920 "RFC XXXX: 1921 Zero Touch Provisioning for Networking Devices"; 1922 } 1923 leaf owner-certificate { 1924 type cms; 1925 must '../ownership-voucher' { 1926 description 1927 "An ownership voucher must be present whenever an owner 1928 certificate is presented."; 1929 } 1930 description 1931 "An owner certificate artifact, as described in Section 1932 3.2 of RFC XXXX. This leaf is optional because it is 1933 only needed when the zero touch information artifact 1934 is signed."; 1935 reference 1936 "RFC XXXX: 1937 Zero Touch Provisioning for Networking Devices"; 1938 } 1939 leaf ownership-voucher { 1940 type cms; 1941 must '../owner-certificate' { 1942 description 1943 "An owner certificate must be present whenever an 1944 ownership voucher is presented."; 1945 } 1946 description 1947 "An ownership voucher artifact, as described by Section 1948 3.3 of RFC XXXX. This leaf is optional because it is 1949 only needed when the zero touch information artifact 1950 is signed."; 1951 reference 1952 "RFC XXXX: 1953 Zero Touch Provisioning for Networking Devices"; 1954 } 1955 } 1956 } 1958 rpc report-progress { 1959 description 1960 "This RPC enables a device, as identified by the RESTCONF 1961 username, to report its bootstrapping progress to the 1962 bootstrap server. This RPC is expected to be used when 1963 the device obtains onboarding-information from a trusted 1964 bootstap server."; 1965 input { 1966 leaf progress-type { 1967 type enumeration { 1968 enum "bootstrap-initiated" { 1969 description 1970 "Indicates that the device just used the 1971 'get-bootstrapping-data' RPC. The 'message' node 1972 below MAY contain any additional information that 1973 the manufacturer thinks might be useful."; 1974 } 1975 enum "parsing-warning" { 1976 description 1977 "Indicates that the device had a non-fatal error when 1978 parsing the response from the bootstrap server. The 1979 'message' node below SHOULD indicate the specific 1980 warning that occurred."; 1981 } 1982 enum "parsing-error" { 1983 description 1984 "Indicates that the device encountered a fatal error 1985 when parsing the response from the bootstrap server. 1986 For instance, this could be due to malformed encoding, 1987 the device expecting signed data when only unsigned 1988 data is provided, the ownership voucher not listing 1989 the device's serial number, or because the signature 1990 didn't match. The 'message' node below SHOULD 1991 indicate the specific error. This progress type 1992 also indicates that the device has abandoned trying 1993 to bootstrap off this bootstrap server."; 1994 } 1995 enum "boot-image-warning" { 1996 description 1997 "Indicates that the device encountered a non-fatal 1998 error condition when trying to install a boot-image. 1999 A possible reason might include a need to reformat a 2000 partition causing loss of data. The 'message' node 2001 below SHOULD indicate any warning messages that were 2002 generated."; 2003 } 2004 enum "boot-image-error" { 2005 description 2006 "Indicates that the device encountered an error when 2007 trying to install a boot-image, which could be for 2008 reasons such as a file server being unreachable, 2009 file not found, signature mismatch, etc. The 2010 'message' node SHOULD indicate the specific error 2011 that occurred. This progress type also indicates 2012 that the device has abandoned trying to bootstrap 2013 off this bootstrap server."; 2014 } 2015 enum "pre-script-warning" { 2016 description 2017 "Indicates that the device obtained a greater than 2018 zero exit status code from the script when it was 2019 executed. The 'message' node below SHOULD indicate 2020 both the resulting exit status code, as well as 2021 capture any stdout/stderr messages the script may 2022 have produced."; 2024 } 2025 enum "pre-script-error" { 2026 description 2027 "Indicates that the device obtained a less than 2028 zero exit status code from the script when it was 2029 executed. The 'message' node below SHOULD indicate 2030 both the resulting exit status code, as well as 2031 capture any stdout/stderr messages the script may 2032 have produced. This progress type also indicates 2033 that the device has abandoned trying to bootstrap 2034 off this bootstrap server."; 2035 } 2036 enum "config-warning" { 2037 description 2038 "Indicates that the device obtained warning messages 2039 when it committed the initial configuration. The 2040 'message' node below SHOULD indicate any warning 2041 messages that were generated."; 2042 } 2043 enum "config-error" { 2044 description 2045 "Indicates that the device obtained error messages 2046 when it committed the initial configuration. The 2047 'message' node below SHOULD indicate the error 2048 messages that were generated. This progress type 2049 also indicates that the device has abandoned trying 2050 to bootstrap off this bootstrap server."; 2051 } 2052 enum "post-script-warning" { 2053 description 2054 "Indicates that the device obtained a greater than 2055 zero exit status code from the script when it was 2056 executed. The 'message' node below SHOULD indicate 2057 both the resulting exit status code, as well as 2058 capture any stdout/stderr messages the script may 2059 have produced."; 2060 } 2061 enum "post-script-error" { 2062 description 2063 "Indicates that the device obtained a less than 2064 zero exit status code from the script when it was 2065 executed. The 'message' node below SHOULD indicate 2066 both the resulting exit status code, as well as 2067 capture any stdout/stderr messages the script may 2068 have produced. This progress type also indicates 2069 that the device has abandoned trying to bootstrap 2070 off this bootstrap server."; 2071 } 2072 enum "bootstrap-complete" { 2073 description 2074 "Indicates that the device successfully processed 2075 all 'onboarding-information' provided, and that it 2076 is ready to be managed. The 'message' node below 2077 MAY contain any additional information that the 2078 manufacturer thinks might be useful. After sending 2079 this progress type, the device is not expected to 2080 access the bootstrap server again."; 2081 } 2082 enum "informational" { 2083 description 2084 "Indicates any additional information not captured 2085 by any of the other progress types. For instance, a 2086 message indicating that the device is about to 2087 reboot after having installed a boot-image could 2088 be provided. The 'message' node below SHOULD 2089 contain information that the manufacturer thinks 2090 might be useful."; 2091 } 2092 } 2093 mandatory true; 2094 description 2095 "The type of progress report provided."; 2096 } 2097 leaf message { 2098 type string; 2099 description 2100 "An optional arbitrary value."; 2101 } 2102 container ssh-host-keys { 2103 when "../progress-type = 'bootstrap-complete'" { 2104 description 2105 "SSH host keys are only sent when the progress type 2106 is 'bootstrap-complete'."; 2107 } 2108 description 2109 "A list of trust anchor certificates an NMS may use to 2110 authenticate subsequent SSH-based connections to this 2111 device (e.g., netconf-ssh, netconf-ch-ssh)."; 2112 list ssh-host-key { 2113 description 2114 "An SSH host-key."; 2115 leaf format { 2116 type enumeration { 2117 enum "ssh-dss" { 2118 description 2119 "The SSH host key is a ssh-dss based key."; 2121 } 2122 enum "ssh-rsa" { 2123 description 2124 "The SSH host key is a ssh-rsa based key."; 2125 } 2126 } 2127 mandatory true; 2128 description 2129 "The format of the SSH host key."; 2130 } 2131 leaf key-data { 2132 type string; 2133 mandatory true; 2134 description 2135 "The key data for the SSH host key"; 2136 } 2137 } 2138 } 2139 container trust-anchors { 2140 when "../progress-type = 'bootstrap-complete'" { 2141 description 2142 "Trust anchors are only sent when the progress type 2143 is 'bootstrap-complete'."; 2144 } 2145 description 2146 "A list of trust anchor certificates an NMS may use to 2147 authenticate subsequent certificate-based connections 2148 to this device (e.g., restconf-tls, netconf-tls, or 2149 even netconf-ssh with X.509 support from RFC 6187). 2150 In practice, trust anchors for IDevID certificates do 2151 not need to be conveyed using this mechanism."; 2152 reference 2153 "RFC 6187: 2154 X.509v3 Certificates for Secure Shell Authentication."; 2155 list trust-anchor { 2156 description 2157 "A trust anchor."; 2158 leaf certificate { 2159 type cms; 2160 mandatory true; 2161 description 2162 "An X.509 v3 certificate structure, as specified 2163 by Section 4 in RFC 5280, encoded using ASN.1 2164 distinguished encoding rules (DER), as specified 2165 in ITU-T X.690."; 2166 reference 2167 "RFC 5280: 2168 Internet X.509 Public Key Infrastructure 2169 Certificate and Certificate Revocation List (CRL) 2170 Profile. 2171 ITU-T X.690: 2172 Information technology - ASN.1 encoding rules: 2173 Specification of Basic Encoding Rules (BER), 2174 Canonical Encoding Rules (CER) and Distinguished 2175 Encoding Rules (DER)."; 2176 } 2177 } 2178 } 2179 } 2180 } 2181 } 2182 2184 8. The Zero Touch Device Data Model 2186 This section defines a non-normative data model that enables the 2187 configuration of zerotouch bootstrapping and discovery of what 2188 parameters are used by a device's bootstrapping logic. 2190 8.1. Data Model Overview 2192 The following tree diagram provides an overview for the zerotouch 2193 device data model. 2195 module: example-zerotouch-device 2196 +--rw zerotouch 2197 +--rw enabled? boolean 2198 +--ro idevid-certificate? cms 2199 | {bootstrap-servers}? 2200 +--ro bootstrap-servers {bootstrap-servers}? 2201 | +--ro bootstrap-server* [address] 2202 | +--ro address inet:host 2203 | +--ro port? inet:port-number 2204 +--ro bootstrap-server-pinned-certificates? 2205 | -> /ks:keystore/pinned-certificates/name 2206 | {bootstrap-servers}? 2207 +--ro voucher-pinned-certificates? 2208 -> /ks:keystore/pinned-certificates/name {signed-data}? 2210 In the above diagram, notice that there is only one configurable node 2211 'enabled'. The expectation is that this node would be set to 'true' 2212 in device's factory default configuration and that it would either be 2213 set to 'false' or deleted when the zerotouch bootstrapping is longer 2214 needed. 2216 8.2. Example Usage 2218 Following is an instance example for this data model. 2220 [note: '\' line wrapping for formatting only] 2222 2224 true 2225 base64encodedvalue== 2226 2227 2228
phs1.example.com
2229 8443 2230 2231 2232
phs2.example.com
2233 8443 2234 2235 2236
phs3.example.com
2237 8443 2238 2239 2240 manufacturers-root-ca-certs<\ 2241 /bootstrap-server-pinned-certificates> 2242 manufacturers-root-ca-certs 2244 2246 8.3. YANG Module 2248 The device model is defined by the YANG module defined in this 2249 section. 2251 Note: the module defined herein uses data types defined in [RFC5652], 2252 [RFC6991], and [I-D.ietf-netconf-keystore], and uses an encoding 2253 defined in [ITU.X690.1994]. 2255 module example-zerotouch-device { 2256 yang-version 1.1; 2257 namespace "https://example.com/zerotouch-device"; 2258 prefix ztd; 2260 import ietf-inet-types { 2261 prefix inet; 2262 reference "RFC 6991: Common YANG Data Types"; 2263 } 2264 import ietf-keystore { 2265 prefix ks; 2266 revision-date 2017-10-30; 2267 description 2268 "This revision is defined in draft-ietf-netconf-keystore-04."; 2269 reference 2270 "I-D.ietf-netconf-keystore: 2271 YANG Data Model for a Keystore Mechanism"; 2272 } 2274 organization 2275 "IETF NETCONF (Network Configuration) Working Group"; 2277 contact 2278 "WG Web: 2279 WG List: 2280 Author: Kent Watsen "; 2282 description 2283 "This module defines a data model to enable zerotouch 2284 bootstrapping and discover what parameters are used. 2285 This module assumes the use of an IDevID certificate, 2286 as opposed to any other client certificate, or the 2287 use of an HTTP-based client authentication scheme. 2289 Copyright (c) 2018 IETF Trust and the persons identified as 2290 authors of the code. All rights reserved. 2292 Redistribution and use in source and binary forms, with or 2293 without modification, is permitted pursuant to, and subject 2294 to the license terms contained in, the Simplified BSD License 2295 set forth in Section 4.c of the IETF Trust's Legal Provisions 2296 Relating to IETF Documents (http://trustee.ietf.org/license-info) 2298 This version of this YANG module is part of RFC XXXX; see the 2299 RFC itself for full legal notices."; 2301 revision 2018-03-05 { 2302 description 2303 "Initial version"; 2304 reference 2305 "RFC XXXX: Zero Touch Provisioning for Networking Devices"; 2306 } 2308 // features 2310 feature bootstrap-servers { 2311 description 2312 "The device supports bootstrapping off bootstrap servers."; 2313 } 2315 feature signed-data { 2316 description 2317 "The device supports bootstrapping off signed data."; 2318 } 2320 // typedefs 2322 typedef cms { 2323 type binary; 2324 description 2325 "A CMS structure, as specified in RFC 5652, encoded using 2326 ASN.1 distinguished encoding rules (DER), as specified in 2327 ITU-T X.690."; 2328 reference 2329 "RFC 5652: 2330 Cryptographic Message Syntax (CMS) 2331 ITU-T X.690: 2332 Information technology - ASN.1 encoding rules: 2333 Specification of Basic Encoding Rules (BER), 2334 Canonical Encoding Rules (CER) and Distinguished 2335 Encoding Rules (DER)."; 2336 } 2338 // protocol accessible nodes 2340 container zerotouch { 2341 description 2342 "Top-level container for zerotouch data model."; 2343 leaf enabled { 2344 type boolean; 2345 default false; 2346 description 2347 "The 'enabled' leaf controls if zerotouch bootstrapping is 2348 enabled or disabled. The default is 'false' so that, when 2349 not enabled, which is most of the time, no configuration 2350 is needed."; 2351 } 2352 leaf idevid-certificate { 2353 if-feature bootstrap-servers; 2354 type cms; 2355 config false; 2356 description 2357 "An CMS SignedData structure, as specified by Section 5 of 2358 RFC 5652. This is the degenerate form of the SignedData 2359 structure, whereby there are no signers, that is commonly 2360 used to disseminate certificates. 2362 This CMS structure contains the IEEE 802.1AR-2009 2363 IDevID certificate itself, and all intermediate 2364 certificates leading up to, and optionally including, 2365 the manufacturer's well-known trust anchor certificate 2366 for IDevID certificates. The well-known trust anchor 2367 does not have to be a self-signed certificate."; 2368 reference 2369 "RFC 5652: 2370 Cryptographic Message Syntax (CMS) 2371 IEEE 802.1AR-2009: 2372 IEEE Standard for Local and metropolitan area 2373 networks - Secure Device Identity."; 2374 } 2375 container bootstrap-servers { 2376 if-feature bootstrap-servers; 2377 config false; 2378 description 2379 "List of bootstrap servers this device will attempt 2380 to reach out to when bootstrapping."; 2381 list bootstrap-server { 2382 key "address"; 2383 description 2384 "A bootstrap server entry."; 2385 leaf address { 2386 type inet:host; 2387 mandatory true; 2388 description 2389 "The IP address or hostname of the bootstrap server the 2390 device should redirect to."; 2391 } 2392 leaf port { 2393 type inet:port-number; 2394 default "443"; 2395 description 2396 "The port number the bootstrap server listens on. If no 2397 port is specified, the IANA-assigned port for 'https' 2398 (443) is used."; 2399 } 2400 } 2401 } 2402 leaf bootstrap-server-pinned-certificates { 2403 if-feature bootstrap-servers; 2404 type leafref { 2405 path "/ks:keystore/ks:pinned-certificates/ks:name"; 2406 } 2407 config false; 2408 description 2409 "A reference to a list of pinned certificate authority (CA) 2410 certificates that the device uses to validate bootstrap 2411 servers with."; 2412 } 2413 leaf voucher-pinned-certificates { 2414 if-feature signed-data; 2415 type leafref { 2416 path "/ks:keystore/ks:pinned-certificates/ks:name"; 2417 } 2418 config false; 2419 description 2420 "A reference to a list of pinned certificate authority (CA) 2421 certificates that the device uses to validate ownership 2422 vouchers with."; 2423 } 2424 } 2425 } 2427 9. DHCP Zero Touch Options 2429 This section defines two DHCP options, one for DHCPv4 and one for 2430 DHCPv6. These two options are semantically the same, though 2431 syntactically different. 2433 9.1. DHCPv4 Zero Touch Option 2435 The DHCPv4 Zero Touch Option is used to provision the client with one 2436 or more URIs for bootstrap servers that can be contacted to attempt 2437 further configuration. 2439 DHCPv4 Zero Touch Redirect Option 2441 0 1 2442 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 2443 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2444 | option-code (143) | option-length | 2445 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2446 . . 2447 . bootstrap-server-list (variable length) . 2448 . . 2449 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2451 o option-code: OPTION_V4_ZEROTOUCH_REDIRECT (143) 2452 o option-length: The option length in octets 2453 o bootstrap-server-list: A list of servers for the 2454 client to attempt contacting, in order to obtain 2455 further bootstrapping data, in the format shown 2456 in [common-field-encoding]. 2458 DHCPv4 Client Behavior 2460 Clients MAY request the OPTION_V4_ZEROTOUCH_REDIRECT by including its 2461 option code in the Parameter Request List (55) in DHCP request 2462 messages. 2464 On receipt of a DHCPv4 Reply message which contains the 2465 OPTION_V4_ZEROTOUCH_REDIRECT, the client processes the response 2466 according to Section 5.5, with the understanding that the 'address' 2467 and 'port' values are encoded in the URIs. 2469 Any invalid URI entries received in the uri-data field are ignored by 2470 the client. If OPTION_V4_ZEROTOUCH_REDIRECT does not contain at 2471 least one valid URI entry in the uri-data field, then the client MUST 2472 discard the option. 2474 As the list of URIs may exceed the maximum allowed length of a single 2475 DHCPv4 option (255 octets), the client MUST implement [RFC3396], 2476 allowing the URI list to be split across a number of 2477 OPTION_V4_ZEROTOUCH_REDIRECT option instances. 2479 DHCPv4 Server Behavior 2481 The DHCPv4 server MAY include a single instance of Option 2482 OPTION_V4_ZEROTOUCH_REDIRECT in DHCP messages it sends. Servers MUST 2483 NOT send more than one instance of the OPTION_V4_ZEROTOUCH_REDIRECT 2484 option. 2486 As the list of URIs may exceed the maximum allowed length of a single 2487 DHCPv4 option (255 octets), the server MUST implement [RFC3396], 2488 allowing the URI list to be split across a number of 2489 OPTION_V4_ZEROTOUCH_REDIRECT option instances. 2491 9.2. DHCPv6 Zero Touch Option 2493 The DHCPv6 Zero Touch Option is used to provision the client with one 2494 or more URIs for bootstrap servers that can be contacted to attempt 2495 further configuration. 2497 DHCPv6 Zero Touch Redirect Option 2499 0 1 2 3 2500 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 2501 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2502 | option-code (136) | option-length | 2503 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2504 . bootstrap-server-list (variable length) . 2505 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2507 o option-code: OPTION_V6_ZEROTOUCH_REDIRECT (136) 2508 o option-length: The option length in octets 2509 o bootstrap-server-list: A list of servers for the client to 2510 attempt contacting, in order to obtain further bootstrapping 2511 data, in the format shown in [common-field-encoding]. 2513 DHCPv6 Client Behavior 2515 Clients MAY request the OPTION_V6_ZEROTOUCH_REDIRECT option, as 2516 defined in [RFC3315], Sections 17.1.1, 18.1.1, 18.1.3, 18.1.4, 2517 18.1.5, and 22.7. As a convenience to the reader, we mention here 2518 that the client includes requested option codes in the Option Request 2519 Option. 2521 On receipt of a DHCPv6 Reply message which contains the 2522 OPTION_V6_ZEROTOUCH_REDIRECT, the client processes the response 2523 according to Section 5.5, with the understanding that the 'address' 2524 and 'port' values are encoded in the URIs. 2526 Any invalid URI entries received in the uri-data field are ignored by 2527 the client. If OPTION_V6_ZEROTOUCH_REDIRECT does not contain at 2528 least one valid URI entry in the uri-data field, then the client MUST 2529 discard the option. 2531 DHCPv6 Server Behavior 2532 Sections 17.2.2 and 18.2 of [RFC3315] govern server operation 2533 in regard to option assignment. As a convenience to the reader, 2534 we mention here that the server will send a particular option code 2535 only if configured with specific values for that option code and if 2536 the client requested it. 2538 Option OPTION_V6_ZEROTOUCH_REDIRECT is a singleton. Servers MUST NOT 2539 send more than one instance of the OPTION_V6_ZEROTOUCH_REDIRECT 2540 option. 2542 9.3. Common Field Encoding 2544 Both of the DHCPv4 and DHCPv6 options defined in this section encode 2545 a list of bootstrap server URIs. The "URI" structure is an option 2546 that can contain multiple URIs (see [RFC7227], Section 5.7). 2548 bootstrap-server-list: 2550 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 2551 | uri-length | URI | 2552 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 2554 o uri-length: variable, in octets. 2556 o URI: URI of zerotouch bootstrap server, using the HTTPS URI 2557 scheme defined in Section 2.7.2 of RFC7230. URI MUST be in 2558 form "https://[:]". 2560 10. Security Considerations 2562 10.1. Immutable Storage for Trust Anchors 2564 Devices MUST ensure that all their trust anchor certificates, 2565 including those for connecting to bootstrap servers and verifying 2566 ownership vouchers, are protected from external modification. 2568 It may be necessary to update these certificates over time (e.g., the 2569 manufacturer wants to delegate trust to a new CA). It is therefore 2570 expected that devices MAY update these trust anchors when needed 2571 through a verifiable process, such as a software upgrade using signed 2572 software images. 2574 10.2. Secure Storage for Long-lived Private Keys 2576 Manufacturer-generated device identifiers may have very long 2577 lifetimes. For instance, [Std-802.1AR-2009] recommends using the 2578 "notAfter" value 99991231235959Z in IDevID certificates. Given the 2579 long-lived nature of these private keys, it is paramount that they 2580 are stored so as to resist discovery, such as in a secure 2581 cryptographic processor (e.g., a TPM). 2583 10.3. Use of IDevID Certificates 2585 IDevID certificates, as defined in [Std-802.1AR-2009], are 2586 RECOMMENDED, both for the TLS-level client certificate used by 2587 devices when connecting to a bootstrap server, as well as for the 2588 device identity certificate used by owners when encrypting the 2589 zerotouch artifacts. 2591 10.4. Clock Sensitivity 2593 The solution in this document relies on TLS certificates, owner 2594 certificates, and ownership vouchers, all of which require an 2595 accurate clock in order to be processed correctly (e.g., to test 2596 validity dates and revocation status). Implementations SHOULD ensure 2597 devices have an accurate clock when shipped from manufacturing 2598 facilities, and take steps to prevent clock tampering. 2600 If it is not possible to ensure clock accuracy, it is RECOMMENDED 2601 that implementations disable the aspects of the solution having clock 2602 sensitivity. In particular, such implementations should assume that 2603 TLS certificates, ownership vouchers, and owner certificates never 2604 expire and are not revokable. From an ownership voucher perspective, 2605 manufacturers SHOULD issue a single ownership voucher for the 2606 lifetime of such devices. 2608 Implementations SHOULD NOT rely on NTP for time, as NTP is not a 2609 secure protocol. 2611 10.5. Blindly authenticating a bootstrap server 2613 This document allows a device to blindly authenticate a bootstrap 2614 server's TLS certificate. It does so to allow for cases where the 2615 redirect information may be obtained in an unsecured manner, which is 2616 desirable to support in some cases. 2618 To compensate for this, this document requires that devices, when 2619 connected to an untrusted bootstrap server, assert that data 2620 downloaded from the server is signed. 2622 10.6. Disclosing Information to Untrusted Servers 2624 This document enables devices to establish provisional connections to 2625 bootstrap servers, in order for the bootstrap server to provide 2626 either unsigned redirect information or signed data of any type to 2627 the device. However, since the server is untrusted, it may be under 2628 the control of an adversary, and therefore devices should be cautious 2629 about the data they send in such cases. 2631 This document requires devices identify and authenticate themselves 2632 to untrusted bootstrap servers. Depending on the authentication 2633 mechanisms used, this means that, at a minimum, the device's serial 2634 number may be disclosed to an adversary. Serial numbers are 2635 ubiquitous and prominently contained in invoices and on labels 2636 affixed to devices and their packaging. That said, serial numbers 2637 many times encode revealing information, such as the device's model 2638 number, manufacture date, and/or manufacturing sequence number. 2639 Knowledge of this information may provide an adversary with details 2640 needed to launch an attack. 2642 In addition to the information relayed during the authentication, 2643 other potentially identifying values that may be disclosed to an 2644 untrusted server, including 'os-name', 'os-version', 'hw-model', and 2645 progress reports. In order to address this issue, it is RECOMMENDED 2646 that bootstrap server implementations promote the untrusted 2647 connection to a trusted connection, as described in Appendix A. 2649 10.7. Sequencing Sources of Bootstrapping Data 2651 For devices supporting more than one source for bootstrapping data, 2652 no particular sequencing order has to be observed for security 2653 reasons, as the solution for each source is considered equally 2654 secure. However, from a privacy perspective, it is RECOMMENDED that 2655 devices access local sources before accessing remote sources. 2657 10.8. The "ietf-zerotouch-information" YANG Module 2659 The ietf-zerotouch-information module defined in this document 2660 defines a data structure that is always wrapped by a CMS structure. 2661 When accessed by a secure mechanism (e.g., protected by TLS), then 2662 the CMS structure may be unsigned. However, when accessed by an 2663 insecure mechanism (e.g., removable storage device), then the CMS 2664 structure must be signed, in order for the device to trust it. 2666 Implementations should be aware that signed bootstrapping data only 2667 protects the data from modification, the contents are still visible 2668 to others. This doesn't affect Security so much as Privacy. That 2669 the contents may be read by unintended parties when accessed by 2670 insecure mechanisms is considered next. 2672 The ietf-zerotouch-information module defines a top-level 'choice' 2673 statement that declares the contents are either "redirect- 2674 information" or "onboarding-information". Each of these two cases 2675 are now considered. 2677 When the contents of the CMS structure are redirect-information, an 2678 observer can learn about the bootstrap servers the device is being 2679 directed, their IP addresses or hostnames, ports, and trust anchor 2680 certificates. Knowledge of this information could provide an 2681 observer some insight into a network's inner structure. 2683 When the contents of the CMS structure are onboarding-information, as 2684 observer could learn considerable information about how the device is 2685 to be provisioned. This information includes the specific operating 2686 system version, the initial configuration, and the specific scripts 2687 that the device is to run. All of this information should be 2688 considered highly sensitive and precautions should be taken to 2689 protect it from falling into the wrong hands. 2691 10.9. The "ietf-zerotouch-bootstrap-server" YANG Module 2693 The ietf-zerotouch-bootstrap-server module defined in this document 2694 specifies an API for a RESTCONF [RFC8040]. The lowest RESTCONF layer 2695 is HTTPS, and the mandatory-to-implement secure transport is TLS 2696 [RFC5246]. 2698 The NETCONF Access Control Model (NACM) [RFC6536] provides the means 2699 to restrict access for particular users to a preconfigured subset of 2700 all available protocol operations and content. 2702 This module presents no data nodes (only RPCs). There is no need to 2703 discuss the sensitivity of data nodes. 2705 This module defines two RPC operations that may be considered 2706 sensitive in some network environments. These are the operations and 2707 their sensitivity/vulnerability: 2709 get-bootstrapping-data: This RPC is used by devices to obtain their 2710 bootstrapping data. By design, each device, as identified by its 2711 authentication credentials (e.g. client certificate), can only 2712 obtain its own data. NACM is not needed to further constrain 2713 access to this RPC. 2715 report-progress: This RPC is used by devices to report their 2716 bootstrapping progress. By design, each device, as identified by 2717 its authentication credentials (e.g. client certificate), can 2718 only report data for itself. NACM is not needed to further 2719 constrain access to this RPC. 2721 11. IANA Considerations 2723 11.1. The IETF XML Registry 2725 This document registers two URIs in the IETF XML registry [RFC3688]. 2726 Following the format in [RFC3688], the following registrations are 2727 requested: 2729 URI: urn:ietf:params:xml:ns:yang:ietf-zerotouch-information 2730 Registrant Contact: The NETCONF WG of the IETF. 2731 XML: N/A, the requested URI is an XML namespace. 2733 URI: urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server 2734 Registrant Contact: The NETCONF WG of the IETF. 2735 XML: N/A, the requested URI is an XML namespace. 2737 11.2. The YANG Module Names Registry 2739 This document registers two YANG modules in the YANG Module Names 2740 registry [RFC6020]. Following the format defined in [RFC6020], the 2741 the following registrations are requested: 2743 name: ietf-zerotouch-information 2744 namespace: urn:ietf:params:xml:ns:yang:ietf-zerotouch-information 2745 prefix: zti 2746 reference: RFC XXXX 2748 name: ietf-zerotouch-bootstrap-server 2749 namespace: urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-\ 2750 server (note: '\' used for formatting reasons only) 2751 prefix: ztbs 2752 reference: RFC XXXX 2754 11.3. The SMI Security for S/MIME CMS Content Type Registry 2756 IANA is kindly requested to two entries in the "SMI Security for 2757 S/MIME CMS Content Type" registry (1.2.840.113549.1.9.16.1), with 2758 values as follows: 2760 Decimal Description References 2761 ------- -------------------------------------- ---------- 2762 TBD1 id-ct-zerotouchInformationXML [RFCXXXX] 2763 TBD2 id-ct-zerotouchInformationJSON [RFCXXXX] 2765 11.4. The BOOTP Manufacturer Extensions and DHCP Options Registry 2767 IANA is kindly requested to make permanent the following early code 2768 point allocation in the "BOOTP Manufacturer Extensions and DHCP 2769 Options" registry maintained at http://www.iana.org/assignments/ 2770 bootp-dhcp-parameters: 2772 Tag: 143 2773 Name: OPTION_V4_ZEROTOUCH_REDIRECT 2774 Data Length: N 2775 Meaning: This option provides a list of URIs 2776 for zerotouch bootstrap servers 2777 Reference: [RFCXXXX] 2779 And the following early code point allocation in the "Dynamic Host 2780 Configuration Protocol for IPv6 (DHCPv6)" registry maintained at 2781 http://www.iana.org/assignments/dhcpv6-parameters: 2783 Value: 136 2784 Description: OPTION_V6_ZEROTOUCH_REDIRECT 2785 Reference: [RFCXXXX] 2787 12. Acknowledgements 2789 The authors would like to thank for following for lively discussions 2790 on list and in the halls (ordered by last name): David Harrington, 2791 Michael Behringer, Dean Bogdanovic, Martin Bjorklund, Joe Clarke, 2792 Toerless Eckert, Stephen Farrell, Stephen Hanna, Wes Hardaker, Radek 2793 Krejci, Russ Mundy, Reinaldo Penno, Randy Presuhn, Max Pritikin, 2794 Michael Richardson, Phil Shafer, Juergen Schoenwaelder. 2796 Special thanks goes to Steve Hanna, Russ Mundy, and Wes Hardaker for 2797 brainstorming the original I-D's solution during the IETF 87 meeting 2798 in Berlin. 2800 13. References 2802 13.1. Normative References 2804 [I-D.ietf-anima-voucher] 2805 Watsen, K., Richardson, M., Pritikin, M., and T. Eckert, 2806 "Voucher Profile for Bootstrapping Protocols", draft-ietf- 2807 anima-voucher-07 (work in progress), January 2018. 2809 [I-D.ietf-netmod-yang-data-ext] 2810 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data 2811 Extensions", draft-ietf-netmod-yang-data-ext-00 (work in 2812 progress), February 2018. 2814 [ITU.X690.1994] 2815 International Telecommunications Union, "Information 2816 Technology - ASN.1 encoding rules: Specification of Basic 2817 Encoding Rules (BER), Canonical Encoding Rules (CER) and 2818 Distinguished Encoding Rules (DER)", ITU-T Recommendation 2819 X.690, 1994. 2821 [RFC1035] Mockapetris, P., "Domain names - implementation and 2822 specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, 2823 November 1987, . 2825 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2826 Requirement Levels", BCP 14, RFC 2119, 2827 DOI 10.17487/RFC2119, March 1997, 2828 . 2830 [RFC3315] Droms, R., Ed., Bound, J., Volz, B., Lemon, T., Perkins, 2831 C., and M. Carney, "Dynamic Host Configuration Protocol 2832 for IPv6 (DHCPv6)", RFC 3315, DOI 10.17487/RFC3315, July 2833 2003, . 2835 [RFC3396] Lemon, T. and S. Cheshire, "Encoding Long Options in the 2836 Dynamic Host Configuration Protocol (DHCPv4)", RFC 3396, 2837 DOI 10.17487/RFC3396, November 2002, 2838 . 2840 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2841 Housley, R., and W. Polk, "Internet X.509 Public Key 2842 Infrastructure Certificate and Certificate Revocation List 2843 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 2844 . 2846 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 2847 RFC 5652, DOI 10.17487/RFC5652, September 2009, 2848 . 2850 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2851 the Network Configuration Protocol (NETCONF)", RFC 6020, 2852 DOI 10.17487/RFC6020, October 2010, 2853 . 2855 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2856 Verification of Domain-Based Application Service Identity 2857 within Internet Public Key Infrastructure Using X.509 2858 (PKIX) Certificates in the Context of Transport Layer 2859 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2860 2011, . 2862 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 2863 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 2864 DOI 10.17487/RFC6234, May 2011, 2865 . 2867 [RFC6762] Cheshire, S. and M. Krochmal, "Multicast DNS", RFC 6762, 2868 DOI 10.17487/RFC6762, February 2013, 2869 . 2871 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 2872 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, 2873 . 2875 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2876 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2877 . 2879 [RFC7227] Hankins, D., Mrugalski, T., Siodelski, M., Jiang, S., and 2880 S. Krishnan, "Guidelines for Creating New DHCPv6 Options", 2881 BCP 187, RFC 7227, DOI 10.17487/RFC7227, May 2014, 2882 . 2884 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2885 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2886 . 2888 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2889 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2890 . 2892 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2893 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2894 May 2017, . 2896 [Std-802.1AR-2009] 2897 IEEE SA-Standards Board, "IEEE Standard for Local and 2898 metropolitan area networks - Secure Device Identity", 2899 December 2009, . 2902 13.2. Informative References 2904 [I-D.ietf-netconf-keystore] 2905 Watsen, K., "YANG Data Model for a "Keystore" Mechanism", 2906 draft-ietf-netconf-keystore-04 (work in progress), October 2907 2017. 2909 [I-D.ietf-netmod-yang-tree-diagrams] 2910 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 2911 ietf-netmod-yang-tree-diagrams-06 (work in progress), 2912 February 2018. 2914 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2915 DOI 10.17487/RFC3688, January 2004, 2916 . 2918 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2919 (TLS) Protocol Version 1.2", RFC 5246, 2920 DOI 10.17487/RFC5246, August 2008, 2921 . 2923 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2924 and A. Bierman, Ed., "Network Configuration Protocol 2925 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2926 . 2928 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2929 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2930 . 2932 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2933 Protocol (NETCONF) Access Control Model", RFC 6536, 2934 DOI 10.17487/RFC6536, March 2012, 2935 . 2937 [RFC6698] Hoffman, P. and J. Schlyter, "The DNS-Based Authentication 2938 of Named Entities (DANE) Transport Layer Security (TLS) 2939 Protocol: TLSA", RFC 6698, DOI 10.17487/RFC6698, August 2940 2012, . 2942 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 2943 Galperin, S., and C. Adams, "X.509 Internet Public Key 2944 Infrastructure Online Certificate Status Protocol - OCSP", 2945 RFC 6960, DOI 10.17487/RFC6960, June 2013, 2946 . 2948 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 2949 RFC 8071, DOI 10.17487/RFC8071, February 2017, 2950 . 2952 Appendix A. Promoting a Connection from Untrusted to Trusted 2954 The following diagram illustrates a sequence of bootstrapping 2955 activities that promote an untrusted connection to a bootstrap server 2956 to a trusted connection to the same bootstrap server. This enables a 2957 device to limit the amount of information it might disclose to an 2958 adversary hosting an untrusted bootstrap server. 2960 +----------+ 2961 |Deployment| 2962 | Specific | 2963 +------+ |Bootstrap | 2964 |Device| | Server | 2965 +------+ +----------+ 2966 | | 2967 | 1. "HTTPS" Request ('untrusted-connection', nonce) | 2968 |------------------------------------------------------->| 2969 | 2. "HTTPS" Response (signed redirect information) | 2970 |<-------------------------------------------------------| 2971 | | 2972 | | 2973 | 3. HTTPS Request (os-name=xyz, os-version=123, etc.) | 2974 |------------------------------------------------------->| 2975 | 4. HTTPS Response (unsigned onboarding information | 2976 |<-------------------------------------------------------| 2977 | | 2979 The interactions in the above diagram are described below. 2981 1. The device initiates an untrusted connection to a bootstrap 2982 server, as is indicated by putting "HTTPS" in double quotes 2983 above. It is still an HTTPS connection, but the device is unable 2984 to authenticate the bootstrap server's TLS certificate. Because 2985 the device is unable to trust the bootstrap server, it sends the 2986 'untrusted-connection' input parameter, and optionally also the 2987 'nonce' input parameter, in the 'get-bootstrapping-data' RPC. 2988 The 'untrusted-connection' parameter informs the bootstrap server 2989 that the device does not trust it and may be holding back some 2990 additional input parameters from the server (e.g., other input 2991 parameters, progress reports, etc.). The 'nonce' input parameter 2992 enables the bootstrap server to dynamically obtain an ownership 2993 voucher from a MASA, which may be important for devices that do 2994 not have a reliable clock. 2996 2. The bootstrap server, seeing the 'untrusted-connection' input 2997 parameter, knows that it can either send unsigned redirect 2998 information or signed data of any type. But, in this case, the 2999 bootstrap server has the ability to sign data and chooses to 3000 respond with signed redirect information, not signed onboarding 3001 information as might be expected, securely redirecting the device 3002 back to it again. Not displayed but, if the 'nonce' input 3003 parameter was passed, the bootstrap server could dynamically 3004 connect to a download a voucher from the MASA having the nonce 3005 value in it. Details regarding a protocol enabling this 3006 integration is outside the scope of this document. 3008 3. Upon validating the signed redirect information, the device 3009 establishes a secure connection to the bootstrap server. 3010 Unbeknownst to the device, it is the same bootstrap server it was 3011 connected to previously but, because the device is able to 3012 authenticate the bootstrap server tis time, it sends its normal 3013 'get-bootstrapping-data' request (i.e., with additional input 3014 parameters) as well as its progress reports (not depicted). 3016 4. This time, because the 'untrusted-connection' parameter was not 3017 passed, having access to all of the device's input parameters, 3018 the bootstrap server returns unsigned onboarding information to 3019 the device. 3021 Appendix B. Workflow Overview 3023 The zero touch solution presented in this document is conceptualized 3024 to be composed of the non-normative workflows described in this 3025 section. Implementation details are expected to vary. Each diagram 3026 is followed by a detailed description of the steps presented in the 3027 diagram, with further explanation on how implementations may vary. 3029 B.1. Enrollment and Ordering Devices 3031 The following diagram illustrates key interactions that may occur 3032 from when a prospective owner enrolls in a manufacturer's zero touch 3033 program to when the manufacturer ships devices for an order placed by 3034 the prospective owner. 3036 +-----------+ 3037 +------------+ |Prospective| +---+ 3038 |Manufacturer| | Owner | |NMS| 3039 +------------+ +-----------+ +---+ 3040 | | | 3041 | | | 3042 | 1. initiate enrollment | | 3043 #<-----------------------------| | 3044 # | | 3045 # | | 3046 # IDevID trust anchor | | 3047 #-----------------------------># set IDevID trust anchor | 3048 # #--------------------------->| 3049 # | | 3050 # bootstrap server | | 3051 # account credentials | | 3052 #-----------------------------># set credentials | 3053 | #--------------------------->| 3054 | | | 3055 | | | 3056 | 2. set owner certificate trust anchor | 3057 |<----------------------------------------------------------| 3058 | | | 3059 | | | 3060 | 3. place device order | | 3061 |<-----------------------------# model devices | 3062 | #--------------------------->| 3063 | | | 3064 | 4. ship devices and send | | 3065 | device identifiers and | | 3066 | ownership vouchers | | 3067 |-----------------------------># set device identifiers | 3068 | # and ownership vouchers | 3069 | #--------------------------->| 3070 | | | 3072 Each numbered item below corresponds to a numbered item in the 3073 diagram above. 3075 1. A prospective owner of a manufacturer's devices initiates an 3076 enrollment process with the manufacturer. This process includes 3077 the following: 3079 * Regardless how the prospective owner intends to bootstrap 3080 their devices, they will always obtain from the manufacturer 3081 the trust anchor certificate for the IDevID certificates. 3082 This certificate will is installed on the prospective owner's 3083 NMS so that the NMS can authenticate the IDevID certificates 3084 when they're presented to subsequent steps. 3086 * If the manufacturer hosts an Internet based bootstrap server 3087 (e.g., a redirect server) such as described in Section 4.4, 3088 then credentials necessary to configure the bootstrap server 3089 would be provided to the prospective owner. If the bootstrap 3090 server is configurable through an API (outside the scope of 3091 this document), then the credentials might be installed on the 3092 prospective owner's NMS so that the NMS can subsequently 3093 configure the manufacturer-hosted bootstrap server directly. 3095 2. If the manufacturer's devices are able to validate signed data 3096 (Section 5.4), and assuming that the prospective owner's NMS is 3097 able to prepare and sign the bootstrapping data itself, the 3098 prospective owner's NMS might set a trust anchor certificate onto 3099 the manufacturer's bootstrap server, using the credentials 3100 provided in the previous step. This certificate is the trust 3101 anchor certificate that the prospective owner would like the 3102 manufacturer to place into the ownership vouchers it generates, 3103 thereby enabling devices to trust the owner's owner certificate. 3104 How this trust anchor certificate is used to enable devices to 3105 validate signed bootstrapping data is described in Section 5.4. 3107 3. Some time later, the prospective owner places an order with the 3108 manufacturer, perhaps with a special flag checked for zero touch 3109 handling. At this time, or perhaps before placing the order, the 3110 owner may model the devices in their NMS, creating virtual 3111 objects for the devices with no real-world device associations. 3112 For instance the model can be used to simulate the device's 3113 location in the network and the configuration it should have when 3114 fully operational. 3116 4. When the manufacturer fulfills the order, shipping the devices to 3117 their intended locations, they may notify the owner of the 3118 devices's serial numbers and shipping destinations, which the 3119 owner may use to stage the network for when the devices power on. 3120 Additionally, the manufacturer may send one or more ownership 3121 vouchers, cryptographically assigning ownership of those devices 3122 to the owner. The owner may set this information on their NMS, 3123 perhaps binding specific modeled devices to the serial numbers 3124 and ownership vouchers. 3126 B.2. Owner Stages the Network for Bootstrap 3128 The following diagram illustrates how an owner might stage the 3129 network for bootstrapping devices. 3131 +----------+ +------------+ 3132 |Deployment| |Manufacturer| +------+ +------+ 3133 | Specific | | Hosted | | Local| | Local| +---------+ 3134 +---+ |Bootstrap | | Bootstrap | | DNS | | DHCP | |Removable| 3135 |NMS| | Server | | Server | |Server| |Server| | Storage | 3136 +---+ +----------+ +------------+ +------+ +------+ +---------+ 3137 | | | | | | 3138 1. | | | | | | 3139 activate| | | | | | 3140 modeled | | | | | | 3141 device | | | | | | 3142 ------->| | | | | | 3143 | 2. (optional) | | | | 3144 | configure | | | | 3145 | bootstrap | | | | 3146 | server | | | | 3147 |------->| | | | | 3148 | | | | | | 3149 | 3. (optional) configure | | | 3150 | bootstrap server | | | | 3151 |--------------------->| | | | 3152 | | | | | | 3153 | | | | | | 3154 | 4. (optional) configure DNS server| | | 3155 |---------------------------------->| | | 3156 | | | | | | 3157 | | | | | | 3158 | 5. (optional) configure DHCP server | | 3159 |------------------------------------------->| | 3160 | | | | | | 3161 | | | | | | 3162 | 6. (optional) store bootstrapping artifacts on media | 3163 |----------------------------------------------------->| 3164 | | | | | | 3165 | | | | | | 3167 Each numbered item below corresponds to a numbered item in the 3168 diagram above. 3170 1. Having previously modeled the devices, including setting their 3171 fully operational configurations and associating device serial 3172 numbers and (optionally) ownership vouchers, the owner might 3173 "activate" one or more modeled devices. That is, the owner tells 3174 the NMS to perform the steps necessary to prepare for when the 3175 real-world devices power up and initiate the bootstrapping 3176 process. Note that, in some deployments, this step might be 3177 combined with the last step from the previous workflow. Here it 3178 is depicted that an NMS performs the steps, but they may be 3179 performed manually or through some other mechanism. 3181 2. If it is desired to use a deployment specific bootstrap server, 3182 it must be configured to provide the bootstrapping information 3183 for the specific devices. Configuring the bootstrap server may 3184 occur via a programmatic API not defined by this document. 3185 Illustrated here as an external component, the bootstrap server 3186 may be implemented as an internal component of the NMS itself. 3188 3. If it is desired to use a manufacturer hosted bootstrap server, 3189 it must be configured to provide the bootstrapping information 3190 for the specific devices. The configuration must be either 3191 redirect or onboarding information. That is, either the 3192 manufacturer hosted bootstrap server will redirect the device to 3193 another bootstrap server, or provide the device with the 3194 onboarding information itself. The types of bootstrapping 3195 information the manufacturer hosted bootstrap server supports may 3196 vary by implementation; some implementations may only support 3197 redirect information, or only support onboarding information, or 3198 support both redirect and onboarding information. Configuring 3199 the bootstrap server may occur via a programmatic API not defined 3200 by this document. 3202 4. If it is desired to use a DNS server to supply bootstrapping 3203 information, a DNS server needs to be configured. If multicast 3204 DNS-SD is desired, then the server must reside on the local 3205 network, otherwise the DNS server may reside on a remote network. 3206 Please see Section 4.2 for more information about how to 3207 configure DNS servers. Configuring the DNS server may occur via 3208 a programmatic API not defined by this document. 3210 5. If it is desired to use a DHCP server to supply bootstrapping 3211 data, a DHCP server needs to be configured. The DHCP server may 3212 be accessed directly or via a DHCP relay. Please see Section 4.3 3213 for more information about how to configure DHCP servers. 3214 Configuring the DHCP server may occur via a programmatic API not 3215 defined by this document. 3217 6. If it is desired to use a removable storage device (e.g., USB 3218 flash drive) to supply bootstrapping information, the information 3219 would need to be placed onto it. Please see Section 4.1 for more 3220 information about how to configure a removable storage device. 3222 B.3. Device Powers On 3224 The following diagram illustrates the sequence of activities that 3225 occur when a device powers on. 3227 +----------+ 3228 +-----------+ |Deployment| 3229 | Source of | | Specific | 3230 +------+ | Bootstrap | |Bootstrap | +---+ 3231 |Device| | Data | | Server | |NMS| 3232 +------+ +-----------+ +----------+ +---+ 3233 | | | | 3234 | | | | 3235 | 1. if zerotouch bootstrap service | | | 3236 | is not enabled, then exit. | | | 3237 | | | | 3238 | 2. for each source supported, check | | | 3239 | for bootstrapping data. | | | 3240 |------------------------------------>| | | 3241 | | | | 3242 | 3. if onboarding information found, | | | 3243 | initialize self and, only if | | | 3244 | source is a bootstrap server, | | | 3245 | send progress updates. | | | 3246 |------------------------------------># | | 3247 | # webhook | | 3248 | #----------------------->| 3249 | | | 3250 | 4. else if redirect-information found, for each | | 3251 | bootstrap server specified, check for data. | | 3252 |-+------------------------------------------------->| | 3253 | | | | 3254 | | if more redirect-information is found, recurse | | 3255 | | (not depicted), else if onboarding-information | | 3256 | | found, initialize self and post progress reports | | 3257 | +-------------------------------------------------># | 3258 | # webhook | 3259 | #-------->| 3260 | 3261 | 5. retry sources and/or wait for manual provisioning. 3262 | 3264 The interactions in the above diagram are described below. 3266 1. Upon power being applied, the device checks to see if zerotouch 3267 bootstrapping is configured, such as must be the case when 3268 running its "factory default" configuration. If zerotouch 3269 bootstrapping is not configured, then the bootstrapping logic 3270 exits and none of the following interactions occur. 3272 2. For each source of bootstrapping data the device supports, 3273 preferably in order of closeness to the device (e.g., removable 3274 storage before Internet based servers), the device checks to see 3275 if there is any bootstrapping data for it there. 3277 3. If onboarding information is found, the device initializes itself 3278 accordingly (e.g., installing a boot-image and committing an 3279 initial configuration). If the source is a bootstrap server, and 3280 the bootstrap server can be trusted (i.e., TLS-level 3281 authentication), the device also sends progress reports to the 3282 bootstrap server. 3284 * The contents of the initial configuration should configure an 3285 administrator account on the device (e.g., username, ssh-rsa 3286 key, etc.), and should configure the device either to listen 3287 for NETCONF or RESTCONF connections or to initiate call home 3288 connections [RFC8071], and should disable the zerotouch 3289 bootstrapping service (e.g., the 'enabled' leaf in data model 3290 presented in Section 8). 3292 * If the bootstrap server supports forwarding device progress 3293 reports to external systems (e.g., via a webhook), a 3294 "bootstrap-complete" progress report (Section 7.3) informs the 3295 external system to know when it can, for instance, initiate a 3296 connection to the device. To support this scenario further, 3297 the 'bootstrap-complete' progress report may also relay the 3298 device's SSH host keys and/or TLS certificates, with which the 3299 external system can use to authenticate subsequent connections 3300 to the device. 3302 If the device successfully completes the bootstrapping process, 3303 it exits the bootstrapping logic without considering any 3304 additional sources of bootstrapping data. 3306 4. Otherwise, if redirect information is found, the device iterates 3307 through the list of specified bootstrap servers, checking to see 3308 if it has bootstrapping data for the device. If the bootstrap 3309 server returns more redirect information, then the device 3310 processes it recursively. Otherwise, if the bootstrap server 3311 returns onboarding information, the device processes it following 3312 the description provided in (3) above. 3314 5. After having tried all supported sources of bootstrapping data, 3315 the device may retry again all the sources and/or provide 3316 manageability interfaces for manual configuration (e.g., CLI, 3317 HTTP, NETCONF, etc.). If manual configuration is allowed, and 3318 such configuration is provided, the configuration should also 3319 disable the zerotouch bootstrapping service, as the need for 3320 bootstrapping would no longer be present. 3322 Appendix C. Change Log 3324 C.1. ID to 00 3326 o Major structural update; the essence is the same. Most every 3327 section was rewritten to some degree. 3329 o Added a Use Cases section 3331 o Added diagrams for "Actors and Roles" and "NMS Precondition" 3332 sections, and greatly improved the "Device Boot Sequence" diagram 3334 o Removed support for physical presence or any ability for 3335 configlets to not be signed. 3337 o Defined the Zero Touch Information DHCP option 3339 o Added an ability for devices to also download images from 3340 configuration servers 3342 o Added an ability for configlets to be encrypted 3344 o Now configuration servers only have to support HTTP/S - no other 3345 schemes possible 3347 C.2. 00 to 01 3349 o Added boot-image and validate-owner annotations to the "Actors and 3350 Roles" diagram. 3352 o Fixed 2nd paragraph in section 7.1 to reflect current use of 3353 anyxml. 3355 o Added encrypted and signed-encrypted examples 3357 o Replaced YANG module with XSD schema 3359 o Added IANA request for the Zero Touch Information DHCP Option 3361 o Added IANA request for media types for boot-image and 3362 configuration 3364 C.3. 01 to 02 3366 o Replaced the need for a configuration signer with the ability for 3367 each NMS to be able to sign its own configurations, using 3368 manufacturer signed ownership vouchers and owner certificates. 3370 o Renamed configuration server to bootstrap server, a more 3371 representative name given the information devices download from 3372 it. 3374 o Replaced the concept of a configlet by defining a southbound 3375 interface for the bootstrap server using YANG. 3377 o Removed the IANA request for the boot-image and configuration 3378 media types 3380 C.4. 02 to 03 3382 o Minor update, mostly just to add an Editor's Note to show how this 3383 draft might integrate with the draft-pritikin-anima-bootstrapping- 3384 keyinfra. 3386 C.5. 03 to 04 3388 o Major update formally introducing unsigned data and support for 3389 Internet-based redirect servers. 3391 o Added many terms to Terminology section. 3393 o Added all new "Guiding Principles" section. 3395 o Added all new "Sources for Bootstrapping Data" section. 3397 o Rewrote the "Interactions" section and renamed it "Workflow 3398 Overview". 3400 C.6. 04 to 05 3402 o Semi-major update, refactoring the document into more logical 3403 parts 3405 o Created new section for information types 3407 o Added support for DNS servers 3409 o Now allows provisional TLS connections 3411 o Bootstrapping data now supports scripts 3412 o Device Details section overhauled 3414 o Security Considerations expanded 3416 o Filled in enumerations for notification types 3418 C.7. 05 to 06 3420 o Minor update 3422 o Added many Normative and Informative references. 3424 o Added new section Other Considerations. 3426 C.8. 06 to 07 3428 o Minor update 3430 o Added an Editorial Note section for RFC Editor. 3432 o Updated the IANA Considerations section. 3434 C.9. 07 to 08 3436 o Minor update 3438 o Updated to reflect review from Michael Richardson. 3440 C.10. 08 to 09 3442 o Added in missing "Signature" artifact example. 3444 o Added recommendation for manufacturers to use interoperable 3445 formats and file naming conventions for removable storage devices. 3447 o Added configuration-handling leaf to guide if config should be 3448 merged, replaced, or processed like an edit-config/yang-patch 3449 document. 3451 o Added a pre-configuration script, in addition to the post- 3452 configuration script from -05 (issue #15). 3454 C.11. 09 to 10 3456 o Factored ownership voucher and voucher revocation to a separate 3457 document: draft-kwatsen-netconf-voucher. (issue #11) 3459 o Removed options 'edit-config' and 'yang- 3460 patch'. (issue #12) 3462 o Defined how a signature over signed-data returned from a bootstrap 3463 server is processed. (issue #13) 3465 o Added recommendation for removable storage devices to use open/ 3466 standard file systems when possible. (issue #14) 3468 o Replaced notifications "script-[warning/error]" with "[pre/post]- 3469 script-[warning/error]". (goes with issue #15) 3471 o switched owner-certificate to be encoded using the PKCS #7 format. 3472 (issue #16) 3474 o Replaced md5/sha1 with sha256 inside a choice statement, for 3475 future extensibility. (issue #17) 3477 o A ton of editorial changes, as I went thru the entire draft with a 3478 fine-toothed comb. 3480 C.12. 10 to 11 3482 o fixed yang validation issues found by IETFYANGPageCompilation. 3483 note: these issues were NOT found by pyang --ietf or by the 3484 submission-time validator... 3486 o fixed a typo in the yang module, someone the config false 3487 statement was removed. 3489 C.13. 11 to 12 3491 o fixed typo that prevented Appendix B from loading the examples 3492 correctly. 3494 o fixed more yang validation issues found by 3495 IETFYANGPageCompilation. note: again, these issues were NOT found 3496 by pyang --ietf or by the submission-time validator... 3498 o updated a few of the notification enumerations to be more 3499 consistent with the other enumerations (following the warning/ 3500 error pattern). 3502 o updated the information-type artifact to state how it's encoded, 3503 matching the language that was in Appendix B. 3505 C.14. 12 to 13 3507 o defined a standalone artifact to encode the old information-type 3508 into a PKCS #7 structure. 3510 o standalone information artifact hardcodes JSON encoding (to match 3511 the voucher draft). 3513 o combined the information and signature PKCS #7 structures into a 3514 single PKCS #7 structure. 3516 o moved the certificate-revocations into the owner-certificate's 3517 PKCS #7 structure. 3519 o eliminated support for voucher-revocations, to reflect the 3520 voucher-draft's switch from revocations to renewals. 3522 C.15. 13 to 14 3524 o Renamed "bootstrap information" to "onboarding information". 3526 o Rewrote DHCP sections to address the packet-size limitation issue, 3527 as discussed in Chicago. 3529 o Added Ian as an author for his text-contributions to the DHCP 3530 sections. 3532 o Removed the Guiding Principles section. 3534 C.16. 14 to 15 3536 o Renamed action 'notification' to 'update-progress' and, likewise 3537 'notification-type' to 'update-type'. 3539 o Updated examples to use "base64encodedvalue==" for binary values. 3541 o Greatly simplified the "Artifact Groupings" section, and moved it 3542 as a subsection to the "Artifacts" section. 3544 o Moved the "Workflow Overview" section to the Appendix. 3546 o Renamed "bootstrap information" to "update information". 3548 o Removed "Other Considerations" section. 3550 o Tons of editorial updates. 3552 C.17. 15 to 16 3554 o tweaked language to refer to "initial state" rather than "factory 3555 default configuration", so as accommodate white-box scenarios. 3557 o added a paragraph to Intro regarding how the solution primarily 3558 regards physical machines, but could be extended to VMs by a 3559 future document. 3561 o added a pointer to the Workflow Overview section (recently moved 3562 to the Appendix) to the Intro. 3564 o added a note that, in order to simplify the verification process, 3565 the "Zerotouch Information" PKCS #7 structure MUST also contain 3566 the signing X.509 certificate. 3568 o noted that the owner certificate's must either have no Key Usage 3569 or the Key Usage must set the "digitalSignature" bit. 3571 o noted that the owner certificate's subject and subjectAltName 3572 values are not constrained. 3574 o moved/consolidated some text from the Artifacts section down to 3575 the Device Details section. 3577 o tightened up some ambiguous language, for instance, by referring 3578 to specific leaf names in the Voucher artifact. 3580 o reverted a previously overzealous s/unique-id/serial-number/ 3581 change. 3583 o modified language for when ZTP runs from when factory-default 3584 config is running to when ZTP is configured, which the factory- 3585 defaults should set . 3587 C.18. 16 to 17 3589 o Added an example for how to promote an untrusted connection to a 3590 trusted connection. 3592 o Added a "query parameters" section defining some parameters 3593 enabling scenarios raised in last call. 3595 o Added a "Disclosing Information to Untrusted Servers" section to 3596 the Security Considerations. 3598 C.19. 17 to 18 3600 o Added Security Considerations for each YANG module. 3602 o Reverted back to the device always sending its DevID cert. 3604 o Moved data tree to ac'get-bootstrapping-data' RPC. 3606 o Moved the 'update-progress' action to a 'report-progress' RPC. 3608 o Added an 'untrusted-connection' parameter to 'get-bootstrapping- 3609 data' RPC. 3611 o Added the "ietf-zerotouch-device" module. 3613 o Lots of small updates. 3615 C.20. 18 to 19 3617 o Fixed 'must' expressions, by converting 'choice' to a 'list' of 3618 'image-verification', each of which now points to a base identity 3619 called "hash-algorithm". There's just one algorithm currently 3620 defined (sha-256). Wish there was a standard crypto module that 3621 could identify such identities. 3623 C.21. 19 to 20 3625 o Now references I-D.ietf-netmod-yang-tree-diagrams. 3627 o Fixed tree-diagrams in Section 2 to always reflect current YANG 3628 (now they are now dynamically generated). 3630 o The "redirect-information" container's "trust-anchor" is now a CMS 3631 structure that can contain a chain of certificates, rather than a 3632 single certificate. 3634 o The "onboarding-information" container's support for image 3635 verification reworked to be extensible. 3637 o Added a reference to the "Device Details" section to the new 3638 example-zerotouch-device module. 3640 o Clarified that the device must always pass its IDevID certificate, 3641 even for untrusted bootstrap servers. 3643 o Fixed the description statement for the "script" typedef to refer 3644 to the [pre/post]-script-[warning/error] enums, rather than the 3645 legacy script-[warning/error] enums. 3647 o For the get-bootstrapping-data RPC's input, removed the "remote- 3648 id" and "circuit-id" fields, and added a "hw-model" field. 3650 o Improved DHCP error handling text. 3652 o Added MUST requirement for DHCPv6 client and server implementing 3653 [RFC3396] to handle URI lists longer than 255 octets. 3655 o Changed the "configuration" value in onboarding-information to be 3656 type 'binary' instead of 'anydata'. 3658 o Moved everything from PKCS#7 to CMS (this shows up as a big 3659 change). 3661 o Added the early code point allocation assignments for the DHCP 3662 Options in the IANA Considerations section, and updated the RFC 3663 Editor note accordingly. 3665 o Added RFC Editor request to replace the assigned values for the 3666 CMS content types. 3668 o Relaxed auth requirements from device needing to always send 3669 IDevID cert to device needing to always send authentication 3670 credentials, as this better matches what RFC 8040 Section 2.5 3671 says. 3673 o Moved normative module "ietf-zerotouch-device" to non-normative 3674 module "example-zerotouch-device". 3676 o Updated Title, Abstract, and Introduction per discussion on list. 3678 C.22. 20 to 21 3680 o Now any of the three artifact can be encrypted. 3682 o Fixed some line-too-long issues. 3684 Authors' Addresses 3686 Kent Watsen 3687 Juniper Networks 3689 EMail: kwatsen@juniper.net 3690 Mikael Abrahamsson 3691 T-Systems 3693 EMail: mikael.abrahamsson@t-systems.se 3695 Ian Farrer 3696 Deutsche Telekom AG 3698 EMail: ian.farrer@telekom.de