idnits 2.17.1 draft-ietf-netconf-zerotouch-16.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 5 instances of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1331 has weird spacing: '...te that devic...' == Line 1496 has weird spacing: '...rmation pkc...' == Line 1506 has weird spacing: '...ey-data str...' == Line 1510 has weird spacing: '...ificate pkc...' == 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 voucher's 'pinned-domain-cert' node. 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 (August 29, 2017) is 2430 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) == Unused Reference: 'RFC7468' is defined on line 2363, but no explicit reference was found in the text == Unused Reference: 'RFC2939' is defined on line 2388, but no explicit reference was found in the text == Outdated reference: A later version (-07) exists of draft-ietf-anima-voucher-04 ** Downref: Normative reference to an Informational RFC: RFC 2315 ** 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 (-36) exists of draft-ietf-netconf-netconf-client-server-04 Summary: 5 errors (**), 0 flaws (~~), 10 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Juniper Networks 4 Intended status: Standards Track M. Abrahamsson 5 Expires: March 2, 2018 T-Systems 6 I. Farrer 7 Deutsche Telekom AG 8 August 29, 2017 10 Zero Touch Provisioning for NETCONF or RESTCONF based Management 11 draft-ietf-netconf-zerotouch-16 13 Abstract 15 This draft presents a secure technique for establishing a NETCONF or 16 RESTCONF connection between a newly deployed device, configured with 17 just its preconfigured initial state (e.g., factory default 18 settings), and its deployment specific network management system 19 (NMS). 21 Editorial Note (To be removed by RFC Editor) 23 This draft contains many placeholder values that need to be replaced 24 with finalized values at the time of publication. This note 25 summarizes all of the substitutions that are needed. Please note 26 that no other RFC Editor instructions are specified anywhere else in 27 this document. 29 Artwork in the IANA Considerations section contains placeholder 30 values for DHCP options pending IANA assignment. Please apply the 31 following replacements: 33 o "OPTION_V4_ZEROTOUCH_REDIRECT" --> the option code assigned for 34 the "DHCPv4 Zero Touch Option" option 36 o "OPTION_V6_ZEROTOUCH_REDIRECT" --> the option code assigned for 37 the "DHCPv6 Zero Touch Option" option 39 Artwork in this document contains shorthand references to drafts in 40 progress. Please apply the following replacements: 42 o "XXXX" --> the assigned RFC value for this draft 44 Artwork in this document contains placeholder values for the date of 45 publication of this draft. Please apply the following replacement: 47 o "2017-08-29" --> the publication date of this draft 48 Please update the following references to reflect their final RFC 49 assignments: 51 o I-D.ieft-netconf-netconf-client-server 53 The following one Appendix section is to be removed prior to 54 publication: 56 o Appendix A. Change Log 58 Status of This Memo 60 This Internet-Draft is submitted in full conformance with the 61 provisions of BCP 78 and BCP 79. 63 Internet-Drafts are working documents of the Internet Engineering 64 Task Force (IETF). Note that other groups may also distribute 65 working documents as Internet-Drafts. The list of current Internet- 66 Drafts is at http://datatracker.ietf.org/drafts/current/. 68 Internet-Drafts are draft documents valid for a maximum of six months 69 and may be updated, replaced, or obsoleted by other documents at any 70 time. It is inappropriate to use Internet-Drafts as reference 71 material or to cite them other than as "work in progress." 73 This Internet-Draft will expire on March 2, 2018. 75 Copyright Notice 77 Copyright (c) 2017 IETF Trust and the persons identified as the 78 document authors. All rights reserved. 80 This document is subject to BCP 78 and the IETF Trust's Legal 81 Provisions Relating to IETF Documents 82 (http://trustee.ietf.org/license-info) in effect on the date of 83 publication of this document. Please review these documents 84 carefully, as they describe your rights and restrictions with respect 85 to this document. Code Components extracted from this document must 86 include Simplified BSD License text as described in Section 4.e of 87 the Trust Legal Provisions and are provided without warranty as 88 described in the Simplified BSD License. 90 Table of Contents 92 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 93 1.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 5 94 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 95 1.3. Requirements Language . . . . . . . . . . . . . . . . . . 7 96 1.4. Tree Diagram Notation . . . . . . . . . . . . . . . . . . 7 97 2. Types of Bootstrapping Information . . . . . . . . . . . . . 8 98 2.1. Redirect Information . . . . . . . . . . . . . . . . . . 8 99 2.2. Onboarding Information . . . . . . . . . . . . . . . . . 9 100 3. Artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . 10 101 3.1. Zero Touch Information . . . . . . . . . . . . . . . . . 10 102 3.2. Owner Certificate . . . . . . . . . . . . . . . . . . . . 10 103 3.3. Ownership Voucher . . . . . . . . . . . . . . . . . . . . 11 104 3.4. Artifact Groupings . . . . . . . . . . . . . . . . . . . 11 105 4. Sources of Bootstrapping Data . . . . . . . . . . . . . . . . 12 106 4.1. Removable Storage . . . . . . . . . . . . . . . . . . . . 12 107 4.2. DNS Server . . . . . . . . . . . . . . . . . . . . . . . 13 108 4.3. DHCP Server . . . . . . . . . . . . . . . . . . . . . . . 14 109 4.4. Bootstrap Server . . . . . . . . . . . . . . . . . . . . 15 110 5. Device Details . . . . . . . . . . . . . . . . . . . . . . . 17 111 5.1. Initial State . . . . . . . . . . . . . . . . . . . . . . 17 112 5.2. Boot Sequence . . . . . . . . . . . . . . . . . . . . . . 18 113 5.3. Processing a Source of Bootstrapping Data . . . . . . . . 19 114 5.4. Validating Signed Data . . . . . . . . . . . . . . . . . 21 115 5.5. Processing Redirect Information . . . . . . . . . . . . . 22 116 5.6. Processing Onboarding Information . . . . . . . . . . . . 22 117 6. The Zero Touch Information Artifact . . . . . . . . . . . . . 23 118 6.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 24 119 6.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 24 120 6.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 27 121 7. The Zero Touch Bootstrap Server API . . . . . . . . . . . . . 32 122 7.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 32 123 7.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 33 124 7.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 35 125 8. DHCP Zero Touch Options . . . . . . . . . . . . . . . . . . . 43 126 8.1. DHCPv4 Zero Touch Option . . . . . . . . . . . . . . . . 43 127 8.2. DHCPv6 Zero Touch Option . . . . . . . . . . . . . . . . 44 128 8.3. Common Field Encoding . . . . . . . . . . . . . . . . . . 46 129 9. Security Considerations . . . . . . . . . . . . . . . . . . . 46 130 9.1. Immutable storage for trust anchors . . . . . . . . . . . 46 131 9.2. Clock Sensitivity . . . . . . . . . . . . . . . . . . . . 47 132 9.3. Blindly authenticating a bootstrap server . . . . . . . . 47 133 9.4. Entropy loss over time . . . . . . . . . . . . . . . . . 47 134 9.5. Serial Numbers . . . . . . . . . . . . . . . . . . . . . 47 135 9.6. Sequencing Sources of Bootstrapping Data . . . . . . . . 48 136 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48 137 10.1. The BOOTP Manufacturer Extensions and DHCP Options 138 Registry . . . . . . . . . . . . . . . . . . . . . . . . 48 139 10.2. The IETF XML Registry . . . . . . . . . . . . . . . . . 48 140 10.3. The YANG Module Names Registry . . . . . . . . . . . . . 48 141 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 49 142 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 49 143 12.1. Normative References . . . . . . . . . . . . . . . . . . 49 144 12.2. Informative References . . . . . . . . . . . . . . . . . 51 145 Appendix A. Workflow Overview . . . . . . . . . . . . . . . . . 53 146 A.1. Enrollment and Ordering Devices . . . . . . . . . . . . . 53 147 A.2. Owner Stages the Network for Bootstrap . . . . . . . . . 55 148 A.3. Device Powers On . . . . . . . . . . . . . . . . . . . . 57 149 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 60 150 B.1. ID to 00 . . . . . . . . . . . . . . . . . . . . . . . . 60 151 B.2. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 60 152 B.3. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 60 153 B.4. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 61 154 B.5. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 61 155 B.6. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 61 156 B.7. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 62 157 B.8. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 62 158 B.9. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 62 159 B.10. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 62 160 B.11. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 62 161 B.12. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 63 162 B.13. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 63 163 B.14. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 63 164 B.15. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 64 165 B.16. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 64 166 B.17. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 64 167 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 65 169 1. Introduction 171 A fundamental business requirement for any network operator is to 172 reduce costs where possible. For network operators, deploying 173 devices to many locations can be a significant cost, as sending 174 trained specialists to each site for installations is both cost 175 prohibitive and does not scale. 177 This document defines a bootstrapping strategy enabling devices to 178 securely obtain bootstrapping data with no installer action beyond 179 physical placement and connecting network and power cables. The 180 ultimate goal of this document is to enable a secure NETCONF 181 [RFC6241] or RESTCONF [RFC8040] connection to a deployment specific 182 network management system (NMS). 184 This document primarily regards physical devices, where the setting 185 of the device's initial state, described in Section 5.1, occurs 186 during the device's manufacturing process. However, the zerotouch 187 solution may be extensible to virtual machines whereby, for instance, 188 the host-system has an IDevID certificate and some ability to verify 189 the virtual machine's image before loading it and also provision a 190 just-in-time IDevID certificate. Details for how this may be 191 accomplished can be defined in future work. 193 1.1. Use Cases 195 o Device connecting to a remotely administered network 197 This use-case involves scenarios, such as a remote branch 198 office or convenience store, whereby a device connects as an 199 access gateway to an ISP's network. Assuming it is not 200 possible to customize the ISP's network to provide any 201 bootstrapping support, and with no other nearby device to 202 leverage, the device has no recourse but to reach out to an 203 Internet-based bootstrap server to bootstrap from. 205 o Device connecting to a locally administered network 207 This use-case covers all other scenarios and differs only in 208 that the device may additionally leverage nearby devices, which 209 may direct it to use a local service to bootstrap from. If no 210 such information is available, or the device is unable to use 211 the information provided, it can then reach out to the network 212 just as it would for the remotely administered network use- 213 case. 215 Conceptual workflows for how zerotouch might be deployed are provided 216 in Appendix A. 218 1.2. Terminology 220 This document uses the following terms (sorted by name): 222 Artifact: The term "artifact" is used throughout to represent any of 223 the three artifacts defined in Section 3 (Zero Touch Information, 224 Ownership Voucher, and Owner Certificate). These artifacts 225 collectively provide all the bootstrapping data a device may use. 227 Bootstrapping Data: The term "bootstrapping data" is used throughout 228 this document to refer to the collection of data that a device 229 may obtain during the bootstrapping process. Specifically, it 230 refers to the three artifacts defined in Section 3. 232 Bootstrap Server: The term "bootstrap server" is used within this 233 document to mean any RESTCONF server implementing the YANG module 234 defined in Section 7.3. 236 Device: The term "device" is used throughout this document to refer 237 to the network element that needs to be bootstrapped. See 238 Section 5 for more information about devices. 240 Initial Secure Device Identifier (IDevID): The term "IDevID" is 241 defined in [Std-802.1AR-2009] as the globally unique secure 242 device identifier (DevID) installed on the device by the 243 manufacturer. This identifier is used in this document to enable 244 a Bootstrap Server to securely identify and authenticate a 245 device. 247 Manufacturer: The term "manufacturer" is used herein to refer to the 248 manufacturer of a device or a delegate of the manufacturer. 250 Network Management System (NMS): The acronym "NMS" is used 251 throughout this document to refer to the deployment specific 252 management system that the bootstrapping process is responsible 253 for introducing devices to. From a device's perspective, when 254 the bootstrapping process has completed, the NMS is a NETCONF or 255 RESTCONF client. 257 Onboarding Information: The term "onboarding information" is used 258 herein to refer to one of the two types of 'zero touch 259 information' (see term) defined in this document, the other being 260 'redirect information'. Specifically, onboarding information is 261 defined by the 'onboarding-information' YANG-data struture in 262 Section 6.3. 264 Owner: The term "owner" is used throughout this document to refer to 265 the person or organization that purchased or otherwise owns a 266 device. 268 Owner Certificate: The term "owner certificate" is used in this 269 document to represent an X.509 certificate that binds an owner 270 identity to a public key, which a device can use to validate a 271 signature over the zero touch information artifacts. The owner 272 certificate is one of the three bootstrapping artifacts described 273 in Section 3. 275 Ownership Voucher: The term "ownership voucher" is used in this 276 document to represent the voucher artifact defined in 277 [I-D.ietf-anima-voucher]. The ownership voucher is used to 278 assign a device to an owner. The ownership voucher is one of the 279 three bootstrapping artifacts described in Section 3. 281 Redirect Information: The term "redirect information" is used herein 282 to refer to one of the two types of 'zero touch information' (see 283 term) defined in this document, the other being 'onboarding 284 information'. Specifically, redirect information is defined by 285 the 'redirect-information' YANG-data structure in Section 6.3. 287 Redirect Server: The term "redirect server" is used to refer to a 288 bootstrap server that only returns redirect information. A 289 redirect server is particularly useful when hosted by a 290 manufacturer, as an Internet-based resource to redirect devices 291 to deployment-specific bootstrap servers. 293 Signed Data: The term "signed data" is used throughout to mean 294 either redirect information or onboarding information that has 295 been signed, specifically by a private key possessed by a 296 device's owner. 298 Unsigned Data: The term "unsigned data" is used throughout to mean 299 either redirect information or onboarding information that has 300 not been signed. 302 Zero Touch Information: The term "zero touch information" is used 303 generally herein to refer either redirect information or 304 onboarding information. Zero touch information is one of the 305 three bootstrapping artifacts described in Section 3. 307 1.3. Requirements Language 309 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 310 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 311 "OPTIONAL" in this document are to be interpreted as described in BCP 312 14 [RFC2119] [RFC8174] when, and only when, they appear in all 313 capitals, as shown here. 315 1.4. Tree Diagram Notation 317 A simplified graphical representation of the data models is used in 318 this document. The meaning of the symbols in these diagrams is as 319 follows: 321 o Brackets "[" and "]" enclose list keys. 323 o Braces "{" and "}" enclose feature names, and indicate that the 324 named feature must be present for the subtree to be present. 326 o Abbreviations before data node names: "rw" (read-write) represents 327 configuration data and "ro" (read-only) represents state data. 329 o Symbols after data node names: "?" means an optional node, "!" 330 means a presence container, and "*" denotes a list and leaf-list. 332 o Parentheses enclose choice and case nodes, and case nodes are also 333 marked with a colon (":"). 335 o Ellipsis ("...") stands for contents of subtrees that are not 336 shown. 338 2. Types of Bootstrapping Information 340 This document defines two types of information that devices access 341 during the bootstrapping process. These information types are 342 described in this section. Examples are provided in Section 6.2 344 2.1. Redirect Information 346 Redirect information redirects a device to another bootstrap server. 347 Redirect information encodes a list of bootstrap servers, each 348 defined by its hostname or IP address, an optional port, and an 349 optional trust anchor certificate. 351 Redirect information is YANG modeled data formally defined by the 352 "redirect-information" container in the YANG module presented in 353 Section 6.3. This container has the tree diagram shown below. 354 Please see Section 1.4 for tree diagram notation. 356 +--:(redirect-information) 357 +--ro redirect-information 358 +--ro bootstrap-server* [address] 359 +--ro address inet:host 360 +--ro port? inet:port-number 361 +--ro trust-anchor? binary 363 Redirect information MAY be trusted or untrusted. The redirect 364 information is trusted whenever it is obtained via a secure 365 connection to a trusted bootstrap server, or whenever it is signed by 366 the device's owner. In all other cases, the redirect information is 367 untrusted. 369 Trusted redirect information is useful for enabling a device to 370 establish a secure connection to a bootstrap server, which is 371 possible when the redirect information includes the bootstrap 372 server's trust anchor certificate. When a device is able to 373 establish a secure connection to a bootstrap server, the data is 374 implicitly trusted, and does not need to be signed. 376 Untrusted redirect information is useful for directing a device to a 377 bootstrap server where signed data has been staged for it to obtain. 378 When the redirect information is untrusted, the device MUST discard 379 any potentially included trust anchor certificates and SHOULD 380 establish a provisional connection (by blindly accepting the TLS 381 certificate) to any of the specified bootstrap servers. In this 382 case, the device MUST NOT trust the bootstrap server, and data 383 provided by the bootstrap server MUST be signed for it to be of any 384 use to the device. 386 How devices process redirect information is described more formally 387 in Section 5.5. 389 2.2. Onboarding Information 391 Bootstrap information provides all the data necessary for a device to 392 bootstrap itself, in order to be considered ready to be managed 393 (e.g., by an NMS). As defined in this document, this data includes 394 information about a boot image the device MUST be running, an initial 395 configuration the device MUST commit, and optional scripts that, if 396 specified, the device MUST successfully execute. 398 Bootstrap information is YANG modeled data formally defined by the 399 "onboarding-information" container in the YANG module presented in 400 Section 6.3. This container has the tree diagram shown below. 401 Please see Section 1.4 for tree diagram notation. 403 +--:(onboarding-information) 404 +--ro onboarding-information 405 +--ro boot-image 406 | +--ro name string 407 | +--ro (hash-algorithm) 408 | | +--:(sha256) 409 | | +--ro sha256? string 410 | +--ro uri* inet:uri 411 +--ro configuration-handling enumeration 412 +--ro pre-configuration-script? script 413 +--ro configuration? 414 +--ro post-configuration-script? script 416 Bootstrap information MUST be trusted for it to be of any use to a 417 device. There is no option for a device to process untrusted 418 onboarding information. 420 Bootstrap information is trusted whenever it is obtained via a secure 421 connection to a trusted bootstrap server, or whenever it is signed by 422 the device's owner. In all other cases, the onboarding information 423 is untrusted. 425 How devices process onboarding information is described more formally 426 in Section 5.6. 428 3. Artifacts 430 This document defines three artifacts that can be made available to 431 devices while they are bootstrapping. Each source of bootstrapping 432 information specifies a means for providing each of the artifacts 433 defined in this section (see Section 4). 435 3.1. Zero Touch Information 437 The zero touch information artifact encodes the essential 438 bootstrapping data for the device. This artifact is used to encode 439 the redirect information and onboarding information types discussed 440 in Section 2. 442 The zero touch information artifact is a PKCS#7 SignedData structure, 443 as specified by Section 9.1 of [RFC2315], encoded using ASN.1 444 distinguished encoding rules (DER), as specified in ITU-T X.690. The 445 PKCS#7 structure MUST contain JSON-encoded content conforming to the 446 YANG module specified in Section 6.3. 448 In order for the zero touch information artifact to be trusted when 449 conveyed over an untrusted transport, the PKCS#7 structure MUST also 450 contain a 'signerInfo' structure, as described in Section 9.1 of 451 [RFC2315], containing a signature generated over the content using 452 the private key associated with the owner certificate (Section 3.2). 453 In order to simplify the verification process, the PKCS#7 structure 454 MUST also contain the signing X.509 certificate. 456 3.2. Owner Certificate 458 The owner certificate artifact is a certificate that is used to 459 identify an 'owner' (e.g., an organization). The owner certificate 460 can be signed by any certificate authority (CA). The owner 461 certificate MUST either have no Key Usage specified, or the Key Usage 462 MUST set the "digitalSignature" bit. The values for the owner 463 certificate's "subject" and/or "subjectAltName" are not constrained 464 by this document. 466 The owner certificate is used by a device to verify the signature for 467 the zero touch information artifact (Section 3.1), the device SHOULD 468 also have received, as described in Section 3.4. In particular, the 469 device verifies signature using the public key in the owner 470 certificate over the content contained within the zero touch 471 information artifact. 473 The owner certificate artifact is formally an unsigned PKCS #7 474 SignedData structure as specified by Section 9.1 in [RFC2315], 475 encoded using ASN.1 distinguished encoding rules (DER), as specified 476 in ITU-T X.690. 478 The owner certificate PKCS#7 structure MUST contain the owner 479 certificate itself, as well as all intermediate certificates leading 480 up to the 'pinned-domain-cert' certificate specified in the ownership 481 voucher. The owner certificate artifact MAY optionally include the 482 trust anchor certificate. 484 Additionally, in order to support devices deployed on private 485 networks, the owner certificate PKCS#7 structure MAY also contain 486 suitably fresh CRLs [RFC5280] and/or OCSP Responses [RFC6960]. 487 Having these revocation objects stapled to the owner certificate 488 precludes the need for the device to have to download them 489 dynamically using the CRL distribution point or an OCSP responder 490 specified in the associated certificates. 492 3.3. Ownership Voucher 494 The ownership voucher artifact is used to securely identify a 495 device's owner, as it is known to the manufacturer. The ownership 496 voucher is signed by the device's manufacturer or delegate. 498 More specifically, the ownership voucher is used to verify the owner 499 certificate (Section 3.2) that the device SHOULD have also received, 500 as described in Section 3.4. In particular, the device verifies that 501 the owner certificate has a chain of trust leading to the trusted 502 certificate included in the ownership voucher, even if it is itself 503 (e.g., self-signed certificate). 505 The ownership voucher artifact, including its encoding, is formally 506 defined in [I-D.ietf-anima-voucher]. 508 3.4. Artifact Groupings 510 This section lists all the possible bootstrapping artifacts, but only 511 certain groupings of these artifacts make sense to return in the 512 various bootstrapping situations described in this document. These 513 groupings are: 515 Unsigned Information: This grouping is useful for cases when 516 transport level security can be used to convey trust (e.g., 517 HTTPS), or when the information can be processed in a 518 provisional manner (i.e. unsigned redirect information). 520 Signed Information, without revocations: The grouping is useful 521 when signed information is needed, because it's obtained from 522 an untrusted source, and it cannot be processed provisionally, 523 and yet either revocations are not needed or they can be 524 obtained dynamically. 526 Signed Information, with revocations: The grouping is useful when 527 signed information is needed, because it's obtained from an 528 untrusted source, and it cannot be processed provisionally, and 529 revocations are needed and cannot be obtained dynamically. 531 The artifacts associated with these groupings are described below: 533 Zero Touch Ownership Owner 534 Grouping Information Voucher Certificate 535 -------------------- ------------- ------------ ----------- 536 Unsigned Information Yes, no sig No No 538 Signed Information, Yes, with sig Yes, without Yes, without 539 without revocations revocations revocations 541 Signed Information, Yes, with sig Yes, with Yes, with 542 with revocations revocations revocations 544 4. Sources of Bootstrapping Data 546 This section defines some sources for zero touch bootstrapping data 547 that a device can access. The list of sources defined here is not 548 meant to be exhaustive. It is left to future documents to define 549 additional sources for obtaining zero touch bootstrapping data. 551 For each source defined in this section, details are given for how 552 each of the three artifacts listed in Section 3 is provided. 554 4.1. Removable Storage 556 A directly attached removable storage device (e.g., a USB flash 557 drive) MAY be used as a source of zero touch bootstrapping data. 559 To use a removable storage device as a source of bootstrapping data, 560 a device need only detect if the removable storage device is plugged 561 in and mount its filesystem. 563 Use of a removable storage device is compelling, as it doesn't 564 require any external infrastructure to work. It is notable that the 565 raw boot image file can be located on the removable storage device, 566 enabling a removable storage device to be a fully self-standing 567 bootstrapping solution. 569 A removable storage device is an untrusted source of bootstrapping 570 data. This means that the information stored on the removable 571 storage device either MUST be signed, or it MUST be information that 572 can be processed provisionally (e.g., unsigned redirect information). 574 From an artifact perspective, since a removable storage device 575 presents itself as a filesystem, the bootstrapping artifacts need to 576 be presented as files. The three artifacts defined in Section 3 are 577 mapped to files below. 579 Artifact to File Mapping: 581 Zero Touch Information: Mapped to a file containing the binary 582 artifact described in Section 3.1 (e.g., zerotouch- 583 information.pkcs7). 585 Owner Certificate: Mapped to a file containing the binary 586 artifact described in Section 3.2 (e.g., owner- 587 certificate.pkcs7). 589 Ownership Voucher: Mapped to a file containing the binary 590 artifact described in Section 3.3 (e.g., ownership- 591 voucher.pkcs7). 593 The format of the removable storage device's filesystem and the 594 naming of the files are outside the scope of this document. However, 595 in order to facilitate interoperability, it is RECOMMENDED devices 596 support open and/or standards based filesystems. It is also 597 RECOMMENDED that devices assume a file naming convention that enables 598 more than one instance of bootstrapping data to exist on a removable 599 storage device. The file naming convention SHOULD be unique to the 600 manufacturer, in order to enable bootstrapping data from multiple 601 manufacturers to exist on a removable storage device. 603 4.2. DNS Server 605 A DNS server MAY be used as a source of zero touch bootstrapping 606 data. 608 Using a DNS server may be a compelling option for deployments having 609 existing DNS infrastructure, as it enables a touchless bootstrapping 610 option that does not entail utilizing an Internet based resource 611 hosted by a 3rd-party. 613 To use a DNS server as a source of bootstrapping data, a device MAY 614 perform a multicast DNS [RFC6762] query searching for the service 615 "_zerotouch._tcp.local.". Alternatively the device MAY perform DNS- 616 SD [RFC6763] via normal DNS operation, using the domain returned to 617 it from the DHCP server; for example, searching for the service 618 "_zerotouch._tcp.example.com". 620 Unsigned DNS records (e.g., not using DNSSEC as described in 621 [RFC6698]) are an untrusted source of bootstrapping data. This means 622 that the information stored in the DNS records either MUST be signed, 623 or it MUST be information that can be processed provisionally (e.g., 624 unsigned redirect information). 626 From an artifact perspective, since a DNS server presents resource 627 records (Section 3.2.1 of [RFC1035]), the bootstrapping artifacts 628 need to be presented as resource records. The three artifacts 629 defined in Section 3 are mapped to resource records below. 631 Artifact to Resource Record Mapping: 633 Zero Touch Information: Mapped to a TXT record called "zt-info" 634 containing the base64-encoding of the binary artifact described 635 in Section 3.1. 637 Owner Certificate: Mapped to a TXT record called "zt-cert" 638 containing the base64-encoding of the binary artifact described 639 in Section 3.2. 641 Ownership Voucher: Mapped to a TXT record called "zt-voucher" 642 containing the base64-encoding of the binary artifact described 643 in Section 3.3. 645 TXT records have an upper size limit of 65535 bytes (Section 3.2.1 in 646 RFC1035), since 'RDLENGTH' is a 16-bit field. Please see 647 Section 3.1.3 in RFC4408 for how a TXT record can achieve this size. 648 Due to this size limitation, some zero touch information artifacts 649 may not fit. In particular, onboarding information could hit this 650 upper bound, depending on the size of the included configuration and 651 scripts. 653 When onboarding information (not redirect information) is provided, 654 it is notable that the URL for the boot-image the device can download 655 would have to point to another server (e.g., http://, ftp://, etc.), 656 as DNS servers do not themselves distribute files. 658 4.3. DHCP Server 660 A DHCP server MAY be used as a source of zero touch bootstrapping 661 data. 663 Using a DHCP server may be a compelling option for deployments having 664 existing DHCP infrastructure, as it enables a touchless bootstrapping 665 option that does not entail utilizing an Internet based resource 666 hosted by a 3rd-party. 668 A DHCP server is an untrusted source of bootstrapping data. Thus the 669 information stored on the DHCP server either MUST be signed, or it 670 MUST be information that can be processed provisionally (e.g., 671 unsigned redirect information). 673 However, unlike other sources of bootstrapping data described in this 674 document, the DHCP protocol (especially DHCP for IPv4) is limited in 675 the amount of data that can be conveyed, to the extent that signed 676 data cannot be communicated. This means only unsigned redirect 677 information can be conveyed. Since the redirect information is 678 unsigned, it SHOULD NOT include the optional trust anchor 679 certificate, as the device would have to discard it anyway. 681 From an artifact perspective, the three artifacts defined in 682 Section 3 are mapped to the DHCP fields specified in Section 8 as 683 follows: 685 Zero Touch Information: This artifact is not supported directly. 686 Instead, the essence of redirect information (not onboarding 687 information) is mapped to the DHCP fields described in 688 Section 8. 690 Owner Certificate: Not supported. There is not enough space in 691 the DHCP packet to hold an owner certificate artifact. 693 Ownership Voucher: Not supported. There is not enough space in 694 the DHCP packet to hold an ownership voucher artifact. 696 4.4. Bootstrap Server 698 A bootstrap server MAY be used as a source of zero touch 699 bootstrapping data. A bootstrap server is defined as a RESTCONF 700 [RFC8040] server implementing the YANG module provided in Section 7. 702 Unlike any other source of bootstrap data described in this document, 703 a bootstrap server is not only a source of data, but it can also 704 receive data from devices using the YANG-defined 'update-progress' 705 action defined in the YANG module (Section 7.3). The data sent from 706 devices both enables visibility into the bootstrapping process (e.g., 707 warnings and errors) as well as provides potentially useful 708 completion status information (e.g., the device's SSH host-keys). 710 To use a bootstrap server as a source of bootstrapping data, a device 711 MUST use the RESTCONF protocol to access the YANG container node 712 /device, passing its unique identifier in the URL as the key to the 713 'device' list. 715 Using a bootstrap server as a source of bootstrapping data is a 716 compelling option as it MAY use transport-level security, in lieu of 717 signed data, which may be easier to deploy in some situations. 718 Additionally, the bootstrap server is able to receive progress 719 updates from devices, which may be critical to some deployments 720 (e.g., the passing of the device's SSH host keys). 722 A bootstrap server may be trusted or an untrusted source of 723 bootstrapping data, depending on how the device learned about the 724 bootstrap server's trust anchor from a trusted source. When a 725 bootstrap server is trusted, the information returned from it MAY be 726 signed. However, when the server is untrusted, in order for its 727 information to be of any use to the device, the bootstrap information 728 MUST either be signed or be information that can be processed 729 provisionally (e.g., unsigned redirect information). 731 When a device is able to trust a bootstrap server, it MUST send its 732 IDevID certificate in the form of a TLS client certificate, and it 733 MUST send progress updates to the bootstrap server. When a device is 734 not able to trust a bootstrap server, it MUST NOT send its IDevID 735 certificate in the form of a TLS client certificate, and it MUST NOT 736 send any progress updates to the bootstrap server. 738 From an artifact perspective, since a bootstrap server presents data 739 as a YANG-modeled data, the bootstrapping artifacts need to be mapped 740 to nodes in the YANG module. The three artifacts defined in 741 Section 3 are mapped to bootstrap server nodes defined in Section 7.3 742 below. 744 Artifact to Bootstrap Server Node Mapping: 746 Zero Touch Information: Mapped to the leaf node /device/ 747 zerotouch-information. 749 Owner Certificate: Mapped to the leaf node /device/owner- 750 certificate. 752 Ownership Voucher: Mapped to the leaf node /device/ownership- 753 voucher. 755 While RESTCONF servers typically support a nested hierarchy of 756 resources, zero touch bootstrap servers only need to support the 757 paths /device and /device/update-progress. The device processing 758 instructions provided in Section 5.3 only uses these two URLs. 760 5. Device Details 762 Devices supporting the bootstrapping strategy described in this 763 document MUST have the preconfigured state and bootstrapping logic 764 described in the following sections. 766 5.1. Initial State 768 +--------------------------------------------------------------+ 769 | | 770 | | 771 | +----------------------------------------------------------+ | 772 | | | | 773 | | | | 774 | | 1. IDevID cert & associated intermediate certificate(s) | | 775 | | 2. list of trusted Internet based bootstrap servers | | 776 | | 3. list of trust anchor certs for bootstrap servers | | 777 | | 4. trust anchor cert for verifying ownership vouchers | | 778 | +----------------------------------------------------------+ | 779 | | 780 | +----------------------+ | 781 | | | | 782 | | | | 783 | | 5. private key | | 784 | +----------------------+ | 785 | | 786 +--------------------------------------------------------------+ 788 Each numbered item below corresponds to a numbered item in the 789 diagram above. 791 1. Devices MUST possess an initial device identifier (IDevID), as 792 defined in [Std-802.1AR-2009]. The IDevID is an X.509 793 certificate, encoding e.g., the device's serial number and 794 hardware manufacturer. The device MUST also possess any 795 intermediate certificates between the IDevID certificate and the 796 IDevID trust anchor certificate, which is provided to prospective 797 owners separately (e.g., Appendix A.1). 799 2. Devices that support loading bootstrapping data from an Internet- 800 based bootstrap server (see Section 4.4) MUST possess: 802 * A configured list of trusted bootstrap servers. Consistent 803 with redirect information (Section 2.1, each bootstrap server 804 MAY be identified by its hostname or IP address, and an 805 optional port. 807 * A configured list of trust anchor certificates that can be 808 used for X.509 certificate path validation ([RFC6125], 809 Section 6) on the bootstrap server's TLS server certificate. 811 3. Devices that support loading signed data (see Section 1.2) MUST 812 possess the manufacturer's trust anchor certificate for 813 validating ownership vouchers. 815 4. Devices MUST possess a private key that corresponds to the public 816 key encoded in the device's IDevID certificate. This private key 817 SHOULD be securely stored, ideally by a cryptographic processor 818 (e.g., a TPM). 820 5.2. Boot Sequence 822 A device claiming to support the bootstrapping strategy defined in 823 this document MUST support the boot sequence described in this 824 section. 826 Power On 827 | 828 v No 829 1. Zerotouch bootstrapping configured --------> Boot normally 830 | 831 | Yes 832 v 833 2. For each supported source of bootstrapping data, 834 try to load bootstrapping data from the source 835 | 836 | 837 v Yes 838 3. Able to bootstrap from any source? ----> Run with new configuration 839 | 840 | No 841 v 842 4. Loop and/or wait for manual provisioning. 844 Each numbered item below corresponds to a numbered item in the 845 diagram above. 847 1. When the device powers on, it first checks to see if zerotouch 848 bootstrapping is configured, as is expected to be the case for 849 the device's preconfigured state. If zerotouch bootstrapping is 850 not configured, then the device boots normally. 852 2. The device iterates over its list of sources for bootstrapping 853 data (Section 4). Details for how to processes a source of 854 bootstrapping data are provided in Section 5.3. 856 3. If the device is able to bootstrap itself from any of the sources 857 of bootstrapping data, it runs with the new bootstrapped 858 configuration. 860 4. Otherwise the device MAY loop back through the list of 861 bootstrapping sources again and/or wait for manual provisioning. 863 5.3. Processing a Source of Bootstrapping Data 865 This section describes a recursive algorithm that devices can use to, 866 ultimately, obtain onboarding information. The algorithm is 867 recursive only because sources of bootstrapping data MAY return 868 redirect information, which causes the algorithm to run again, for 869 the newly discovered sources of information. To be clear, an 870 expression that captures all possible combinations is "(redirect 871 information)* onboarding information". That is, zero or more 872 redirect information responses, followed by one bootstrap information 873 response. 875 An important aspect of the algorithm is knowing when data needs to be 876 signed or not. The following figure provides a summary of options: 878 Untrusted Source Trusted Source 879 Kind of Bootstrapping Data Can Provide? Can Provide? 881 Unsigned Redirect Info : Yes+ Yes 882 Signed Redirect Info : Yes Yes* 883 Unsigned Onboarding Info : No Yes 884 Signed Onboarding Info : Yes Yes* 886 The '+' above denotes that the source redirected to MUST 887 return signed data, or more unsigned redirect information. 889 The '*' above denotes that, while possible, it is generally 890 unnecessary for a trusted source to return signed data. In 891 fact, it's only needed when the '+' case occurs. 893 As an example, imagine a device initially obtains unsigned redirect 894 information, which redirects it to an [untrusted] bootstrap server 895 where it obtains more unsigned redirect information, which redirects 896 it to another [untrusted] bootstrap server where it obtains signed 897 redirect information, which redirects it to a [trusted] bootstrap 898 server where it obtains redirect information (signed or unsigned 899 doesn't matter, its trusted either way), but without an included 900 trust anchor certificate, which is unexpected but possible, so the 901 device can't trust the server it's redirected to, and so on, until 902 finally the device obtains some onboarding information. 904 To support this behavior, this recursive algorithm uses a 905 conceptually global-scoped algorithm variable called "trust-state". 906 The trust-state variable is initialized to FALSE. The ultimate goal 907 of this algorithm is for the device to process onboarding information 908 (Section 2.2) while the trust-state variable is TRUE. 910 If the data source is a bootstrap server, the only source of 911 bootstrapping data defined in this document that can be trusted via 912 transport level security, and the device is able to authenticate the 913 server using X.509 certificate path validation ([RFC6125], Section 6) 914 to one of the device's preconfigured trust anchors, or to a trust 915 anchor that it learned from a previous step, then the device MUST set 916 trust-state to TRUE. 918 If trust-state is TRUE, when connecting to the bootstrap server, the 919 device MUST use its IDevID certificate for client certificate based 920 authentication and MUST post progress updates using the bootstrap 921 server's "update-progress" action. Otherwise, if trust-state is 922 FALSE, when connecting to the bootstrap server, the device MUST NOT 923 use its IDevID certificate for a client certificate based 924 authentication and MUST NOT post progress updates using the bootstrap 925 server's "update-progress" action. 927 When accessing a bootstrap server, the device SHOULD only access its 928 top-level resource, to obtain all the data staged for it in a single 929 GET request. 931 For any source of bootstrapping data (e.g., Section 4), if the data 932 is signed and the device is able to validate the signed data using 933 the algorithm described in Section 5.4, then the device MUST set 934 trust-state to TRUE, else the device MUST set trust-state to FALSE. 935 Note, this is worded to cover the special case when signed data is 936 returned even from a trusted bootstrap server. 938 If the data is onboarding information (not redirect information), and 939 trust-state is FALSE, the device MUST exit the recursive algorithm 940 (as this is not allowed, per the figure above), returning to the 941 state machine described in Section 5.2. Otherwise, the device MUST 942 attempt to process the onboarding information as described in 943 Section 5.6. In either case, success or failure, the device MUST 944 exit the recursive algorithm, returning to the state machine 945 described in Section 5.2, the only difference being in how it 946 responds to the "Able to bootstrap from any source?" conditional 947 described in the figure in the section. 949 If the data is redirect information, the device MUST process the 950 redirect information as described in Section 5.5. This is the 951 recursion step, it will cause to device to reenter this algorithm, 952 but this time the data source will most definitely be a bootstrap 953 server, as that is all redirect information is able to redirect a 954 device to. 956 5.4. Validating Signed Data 958 Whenever a device is presented signed data from an untrusted source, 959 it MUST validate the signed data as described in this section. If 960 the signed data is provided by a trusted source, a redundant trust 961 case, the device MAY skip verifying the signature. 963 Whenever there is signed data, the device MUST also be provided an 964 ownership voucher and an owner certificate. How all the needed 965 artifacts are provided for each source of bootstrapping data is 966 defined in Section 4. 968 The device MUST first authenticate the ownership voucher by 969 validating the signature on it to one of its preconfigured trust 970 anchors (see Section 5.1). If the device has an accurate clock, it 971 MUST ensure that the ownership voucher was created in the past (i.e., 972 'created-on' < now). If the 'expires-on' leaf is present, the device 973 MUST verify that the ownership voucher has not yet expired (i.e., now 974 < 'expires-on'), which requires an accurate clock. The device MUST 975 verify that the ownership voucher's 'assertion' value is acceptable 976 (e.g., some devices may only accept the assertion value 'verified'). 977 The device MUST verify that the ownership voucher specifies the 978 device's serial number in the 'serial-number' leaf. If the 'idevid- 979 issuer' leaf is present, the device MUST verify that the value is set 980 correctly. If the authentication of the ownership voucher is 981 successful, the device extracts the 'pinned-domain-certificate' node, 982 an X.509 certificate, that is needed to verify the owner certificate 983 in the next step. 985 The device MUST next authenticate the owner certificate by performing 986 X.509 certificate path verification to the trusted certificate 987 extracted from the voucher's 'pinned-domain-cert' node. If the 988 ownership voucher's 'domain-cert-revocation-checks' node's value is 989 set to "true", the device MUST verify the revocation status of the 990 certificate chain used to sign the owner certificate and, if the 991 revocation status is not attainable or if it is determined that a 992 certificate has been revoked, the device MUST not validate the owner 993 certificate. 995 Finally the device MUST verify the signature over information 996 artifact was generated by the private key matching the public key 997 from the owner certificate. 999 If any of these steps fail, then the device MUST mark the data as 1000 invalid and not perform any subsequent processing step. 1002 5.5. Processing Redirect Information 1004 In order to process redirect information (Section 2.1), the device 1005 MUST follow the steps presented in this section. 1007 Processing redirect information is straightforward. The device 1008 sequentially steps through the list of provided bootstrap servers 1009 until it can find one it can bootstrap from. 1011 If a hostname is provided, and the hostname's DNS resolution is to 1012 more than one IP address, the device MUST attempt to connect to all 1013 of the DNS resolved addresses at least once, before moving on to the 1014 next bootstrap server. If the device is able to obtain bootstrapping 1015 data from any of the DNS resolved addresses, it MUST immediately 1016 process that data, without attempting to connect to any of the other 1017 DNS resolved addresses. 1019 If the redirect information is trusted (e.g., trust-state is TRUE), 1020 and the bootstrap server entry contains a trust anchor certificate, 1021 then the device MUST authenticate the bootstrap server using X.509 1022 certificate path validation ([RFC6125], Section 6) to the specified 1023 trust anchor. If the device is unable to authenticate the bootstrap 1024 server to the specified trust anchor, the device MUST NOT attempt a 1025 provisional connection to the bootstrap server (i.e., by blindly 1026 accepting its server certificate). 1028 If the redirect information is untrusted (e.g., trust-state is 1029 FALSE), the device MUST discard any trust anchors provided by the 1030 redirect information and establish a provisional connection to the 1031 bootstrap server (i.e., by blindly accepting its TLS server 1032 certificate). 1034 5.6. Processing Onboarding Information 1036 In order to process onboarding information (Section 2.2), the device 1037 MUST follow the steps presented in this section. 1039 When processing onboarding information, the device MUST first process 1040 the boot image information, then execute the pre-configuration script 1041 (if any), then commit the initial configuration, and then execute the 1042 post-configuration script (if any), in that order. If the device 1043 encounters an error at any step, it MUST NOT proceed to the next 1044 step. 1046 First the device MUST determine if the image it is running satisfies 1047 the specified boot image criteria (e.g., name and/or fingerprint 1048 match). If it does not, the device MUST download (using the supplied 1049 URI), verify, and install the specified boot image, and then reboot. 1050 To verify the boot image, the device MUST check that the boot image 1051 file matches the fingerprint (e.g., sha256) supplied by the 1052 bootstrapping information. Upon rebooting, the device MUST still be 1053 in its initial state, causing the bootstrapping process to run again, 1054 which will eventually come to this very point, but this time the 1055 device's running image will satisfy the specified criteria, and thus 1056 the device will move to processing the next step. 1058 Next, for devices that support executing scripts, if a pre- 1059 configuration script has been specified, the device MUST execute the 1060 script and check its exit status code to determine if had any 1061 warnings or errors. In the case of errors, the device MUST reset 1062 itself in such a way that forces a reinstallation of the boot image, 1063 thereby wiping out any bad state the script may have left behind. 1065 Next the device commits the provided initial configuration. Assuming 1066 no errors, the device moves to processing the next step. 1068 Again, for devices that support executing scripts, if a post- 1069 configuration script has been specified, the device MUST execute the 1070 script and check its exit status code to determine if it had any 1071 warnings or errors. In the case of errors, the device MUST reset 1072 itself in such a way that forces a reinstallation of the boot image, 1073 thereby wiping out any bad state the script may have left behind. 1075 At this point, the device has completely processed the bootstrapping 1076 data and is ready to be managed. If the device obtained the 1077 bootstrap information from a trusted bootstrap server, the device 1078 MUST post the 'bootstrap-complete' progress update now, using the 1079 bootstrap server's 'update-progress' action. 1081 At this point the device is running its initial configuration. 1082 Notably, if NETCONF Call Home or RESTCONF Call Home [RFC8071] is 1083 configured, the device initiates trying to establish a call home 1084 connection at this time. 1086 6. The Zero Touch Information Artifact 1088 This section defines a YANG [RFC6020] module that is used to define 1089 the data model for the zero touch information artifact described in 1090 Section 3.1. Examples illustrating this artifact in use are provided 1091 in Section 6.2. 1093 6.1. Tree Diagram 1095 The following tree diagram provides an overview of the data model for 1096 the zero touch information artifact. The syntax used for this tree 1097 diagram is described in Section 1.4. 1099 module: ietf-zerotouch-information 1100 yang-data: 1101 zerotouch-information 1102 +---- (information-type) 1103 +--:(redirect-information) 1104 | +---- redirect-information 1105 | +---- bootstrap-server* [address] 1106 | +---- address inet:host 1107 | +---- port? inet:port-number 1108 | +---- trust-anchor? binary 1109 +--:(onboarding-information) 1110 +---- onboarding-information 1111 +---- boot-image 1112 | +---- name string 1113 | +---- (hash-algorithm) 1114 | | +--:(sha256) 1115 | | +---- sha256? string 1116 | +---- uri* inet:uri 1117 +---- configuration-handling? enumeration 1118 +---- pre-configuration-script? script 1119 +---- configuration? 1120 +---- post-configuration-script? script 1122 6.2. Example Usage 1124 This section presents examples for how the zero touch information 1125 artifact (Section 3.1) can be encoded into a document that can be 1126 distributed outside the bootstrap server's RESTCONF API. 1128 The following example illustrates how redirect information can be 1129 encoded into an artifact. 1131 1133 1134
phs1.example.com
1135 8443 1136 base64encodedvalue== 1137 1138 1139
phs2.example.com
1140 8443 1141 base64encodedvalue== 1142 1143 1144
phs3.example.com
1145 8443 1146 base64encodedvalue== 1147 1148 1150 The following example illustrates how onboarding information can be 1151 encoded into an artifact. This example uses data models from 1152 [RFC7317] and [I-D.ietf-netconf-netconf-client-server]. 1154 1156 1157 boot-image-v3.2R1.6.img 1158 base64encodedvalue== 1159 file:///some/path/to/raw/file 1160 1161 merge 1162 1163 1164 1165 1166 1167 admin 1168 1169 admin's rsa ssh host-key 1170 ssh-rsa 1171 base64encodedvalue== 1172 1173 1174 1175 1176 1177 1179 1180 1181 config-mgr 1182 1183 1184 1185 east-data-center 1186
east.config-mgr.example.com
1187 1188 1189 west-data-center 1190
west.config-mgr.example.com
1191 1192 1193 1194 1195 certificate 1196 builtin-idevid-cert 1197 1198 1199 1200 1201 deployment-specific-ca-certs 1202 1203 1204 explicitly-trusted-client-certs 1205 1206 1207 1208 1209 1210 300 1211 60 1212 1213 1214 1215 last-connected 1216 3 1217 1218 1219 1220 1221 1222 1224 6.3. YANG Module 1226 The zero touch information artifact is normatively defined by the 1227 YANG module defined in this section. 1229 Note: the module defined herein uses data types defined in [RFC5280], 1230 [RFC6234], and [RFC6991]. 1232 file "ietf-zerotouch-information@2017-08-29.yang" 1233 module ietf-zerotouch-information { 1234 yang-version "1.1"; 1236 namespace "urn:ietf:params:xml:ns:yang:ietf-zerotouch-information"; 1237 prefix "zti"; 1239 import ietf-inet-types { 1240 prefix inet; 1241 reference "RFC 6991: Common YANG Data Types"; 1242 } 1244 import ietf-restconf { 1245 prefix rc; 1246 description 1247 "This import statement is only present to access 1248 the yang-data extension defined in RFC 8040."; 1249 reference "RFC 8040: RESTCONF Protocol"; 1250 } 1252 organization 1253 "IETF NETCONF (Network Configuration) Working Group"; 1255 contact 1256 "WG Web: http://tools.ietf.org/wg/netconf 1257 WG List: 1258 Author: Kent Watsen "; 1260 description 1261 "This module defines the data model for the Zero Touch Information 1262 artifact defined by RFC XXXX: Zero Touch Provisioning for NETCONF 1263 or RESTCONF based Management. 1265 Copyright (c) 2017 IETF Trust and the persons identified as 1266 authors of the code. All rights reserved. 1268 Redistribution and use in source and binary forms, with or without 1269 modification, is permitted pursuant to, and subject to the license 1270 terms contained in, the Simplified BSD License set forth in Section 1271 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents 1272 (http://trustee.ietf.org/license-info). 1274 This version of this YANG module is part of RFC XXXX; see the RFC 1275 itself for full legal notices."; 1277 revision "2017-08-29" { 1278 description 1279 "Initial version"; 1280 reference 1281 "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF based 1282 Management"; 1283 } 1285 rc:yang-data zerotouch-information { 1287 choice information-type { 1288 mandatory true; 1289 description 1290 "This choice statement ensures the response only contains 1291 redirect-information or onboarding-information. Note that 1292 this is the only mandatory true node, as the other nodes 1293 are not needed when the device trusts the bootstrap server, 1294 in which case the data does not need to be signed."; 1296 container redirect-information { 1297 description 1298 "Redirect information is described in Section 2.1 in 1299 RFC XXXX. Its purpose is to redirect a device to 1300 another bootstrap server."; 1301 reference 1302 "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF 1303 based Management"; 1305 list bootstrap-server { 1306 key address; 1307 description 1308 "A bootstrap server entry."; 1310 leaf address { 1311 type inet:host; 1312 mandatory true; 1313 description 1314 "The IP address or hostname of the bootstrap server the 1315 device should redirect to."; 1316 } 1317 leaf port { 1318 type inet:port-number; 1319 default 443; 1320 description 1321 "The port number the bootstrap server listens on. If no 1322 port is specified, the IANA-assigned port for 'https' 1323 (443) is used."; 1324 } 1325 leaf trust-anchor { 1326 type binary; 1327 description 1328 "An X.509 v3 certificate structure as specified by RFC 1329 5280, Section 4, encoded using ASN.1 distinguished 1330 encoding rules (DER), as specified in ITU-T X.690. A 1331 certificate that device can use as the trust anchor 1332 to authenticate the bootstrap server the device is 1333 being redirected to."; 1334 reference 1335 "RFC 5280: 1336 Internet X.509 Public Key Infrastructure Certificate 1337 and Certificate Revocation List (CRL) Profile. 1338 ITU-T X.690: 1339 Information technology - ASN.1 encoding rules: 1340 Specification of Basic Encoding Rules (BER), 1341 Canonical Encoding Rules (CER) and Distinguished 1342 Encoding Rules (DER)."; 1343 } 1344 } 1345 } 1347 container onboarding-information { 1348 description 1349 "Bootstrap information is described in Section 2.2 in 1350 RFC XXXX. Its purpose is to provide the device 1351 everything it needs to bootstrap itself."; 1352 reference 1353 "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF 1354 based Management"; 1356 container boot-image { 1357 description 1358 "Specifies criteria for the boot image the device MUST 1359 be running."; 1361 leaf name { 1362 type string; 1363 mandatory true; 1364 description 1365 "The name of a software image that the device MUST 1366 be running in order to process the remaining nodes."; 1367 } 1368 choice hash-algorithm { 1369 mandatory true; 1370 description 1371 "Identifies the hash algorithm used."; 1372 leaf sha256 { 1373 type string; 1374 description 1375 "The hex-encoded SHA-256 hash over the boot 1376 image file. This is used by the device to 1377 verify a downloaded boot image file."; 1378 reference 1379 "RFC 6234: US Secure Hash Algorithms."; 1380 } 1381 } 1382 leaf-list uri { 1383 type inet:uri; 1384 min-elements 1; 1385 description 1386 "An ordered list of URIs to where the boot-image file MAY 1387 be obtained. Deployments MUST know in which URI schemes 1388 (http, ftp, etc.) a device supports. If a secure scheme 1389 (e.g., https) is provided, a device MAY establish a 1390 provisional connection to the server, by blindly 1391 accepting the server's credentials (e.g., its TLS 1392 certificate)"; 1393 } 1394 } 1396 leaf configuration-handling { 1397 type enumeration { 1398 enum merge { 1399 description 1400 "Merge configuration into the running datastore."; 1401 } 1402 enum replace { 1403 description 1404 "Replace the existing running datastore with the 1405 passed configuration."; 1406 } 1407 } 1408 description 1409 "This enumeration indicates how the server should process 1410 the provided configuration. When not specified, the device 1411 MAY determine how to process the configuration using other 1412 means (e.g., vendor-specific metadata)."; 1413 } 1415 leaf pre-configuration-script { 1416 type script; 1417 description 1418 "A script that, when present, is executed before the 1419 configuration has been processed."; 1420 } 1422 anydata configuration { 1423 must "../configuration-handling"; 1424 description 1425 "Any configuration data model known to the device. It may 1426 contain manufacturer-specific and/or standards-based data 1427 models."; 1428 } 1430 leaf post-configuration-script { 1431 type script; 1432 description 1433 "A script that, when present, is executed after the 1434 configuration has been processed."; 1435 } 1436 } 1437 } 1438 } 1440 typedef script { 1441 type binary; 1442 description 1443 "A device specific script that enables the execution of commands 1444 to perform actions not possible thru configuration alone. 1446 No attempt is made to standardize the contents, running context, 1447 or programming language of the script. The contents of the 1448 script are considered specific to the vendor, product line, 1449 and/or model of the device. 1451 If a script is erroneously provided to a device that does not 1452 support the execution of scripts, the device SHOULD send a 1453 'script-warning' notification message, but otherwise continue 1454 processing the bootstrapping data as if the script had not 1455 been present. 1457 The script returns exit status code '0' on success and non-zero 1458 on error, with accompanying stderr/stdout for logging purposes. 1459 In the case of an error, the exit status code will specify what 1460 the device should do. 1462 If the exit status code is greater than zero, then the device 1463 should assume that the script had a soft error, which the 1464 script believes does not affect manageability. If the device 1465 obtained the bootstrap information from a bootstrap server, 1466 it SHOULD send a 'script-warning' notification message. 1468 If the exit status code is less than zero, the device should 1469 assume the script had a hard error, which the script believes 1470 will affect manageability. In this case, the device SHOULD 1471 send a 'script-error' notification message followed by a 1472 reset that will force a new boot-image install (wiping out 1473 anything the script may have done) and restart the entire 1474 bootstrapping process again."; 1475 } 1477 } 1478 1480 7. The Zero Touch Bootstrap Server API 1482 This section defines a YANG [RFC6020] module that is used to define 1483 the RESTCONF [RFC8040] API used by the bootstrap server defined in 1484 Section 4.4. Examples illustrating this API in use are provided in 1485 Section 7.2. 1487 7.1. Tree Diagram 1489 The following tree diagram provides an overview for the bootstrap 1490 server RESTCONF API. The syntax used for this tree diagram is 1491 described in Section 1.4. 1493 module: ietf-zerotouch-bootstrap-server 1494 +--ro device* [unique-id] 1495 +--ro unique-id string 1496 +--ro zerotouch-information pkcs7 1497 +--ro owner-certificate? pkcs7 1498 +--ro ownership-voucher? pkcs7 1499 +---x update-progress 1500 +---w input 1501 +---w update-type enumeration 1502 +---w message? string 1503 +---w ssh-host-keys 1504 | +---w ssh-host-key* 1505 | +---w format enumeration 1506 | +---w key-data string 1507 +---w trust-anchors 1508 +---w trust-anchor* 1509 +---w protocol* enumeration 1510 +---w certificate pkcs7 1512 In the above diagram, notice that all of the protocol accessible 1513 nodes are read-only, to assert that devices can only pull data from 1514 the bootstrap server. 1516 Also notice that the module defines an action statement, which 1517 devices use to provide progress updates to the bootstrap server. 1519 7.2. Example Usage 1521 This section presents some examples illustrating the bootstrap 1522 server's API. Two examples are provided, one illustrating a device 1523 fetching bootstrapping data from the server, and the other 1524 illustrating a data posting a progress updates to the server. 1526 The following example illustrates a device using the API to fetch its 1527 bootstrapping data from the bootstrap server. In this example, the 1528 device receives a signed response; an unsigned response would look 1529 similar except the last two fields (owner-certificate and ownership- 1530 voucher) would be absent in the response. 1532 REQUEST 1533 ------- 1534 ['\' line wrapping added for formatting only] 1536 GET https://example.com/restconf/data/ietf-zerotouch-bootstrap-server:\ 1537 device=123456 HTTP/1.1 1538 HOST: example.com 1539 Accept: application/yang.data+xml 1541 RESPONSE 1542 -------- 1544 HTTP/1.1 200 OK 1545 Date: Sat, 31 Oct 2015 17:02:40 GMT 1546 Server: example-server 1547 Content-Type: application/yang.data+xml 1549 1551 123456789 1552 base64encodedvalue== 1553 base64encodedvalue== 1554 base64encodedvalue== 1555 1557 The following example illustrates a device using the API to post a 1558 progress update to a bootstrap server. Illustrated below is the 1559 'bootstrap-complete' message, but the device may send other progress 1560 updates to the server while bootstrapping (e.g., to provide status 1561 updates). In this message, the device is sending both its SSH host 1562 keys and TLS server certificate, which the bootstrap server may, for 1563 example, pass to an NMS, as discussed in Appendix A.3. 1565 Note that devices that are able to present an IDevID certificate 1566 [Std-802.1AR-2009] when establishing SSH or TLS connections do not 1567 need to include its DevID certificate in the bootstrap-complete 1568 message. It is unnecessary to send the DevID certificate in this 1569 case because the IDevID certificate does not need to be pinned by an 1570 NMS in order to be trusted. 1572 Note that the bootstrap server MUST NOT process a progress update 1573 from a device without first authenticating the device. This is in 1574 contrast to when a device is fetching data from the server, a read- 1575 only operation, in which case device authentication is not strictly 1576 required (e.g., when sending signed information). 1578 REQUEST 1579 ------- 1580 ['\' line wrapping added for formatting only] 1582 POST https://example.com/restconf/data/ietf-zerotouch:\ 1583 device=123456/update-progress HTTP/1.1 1584 HOST: example.com 1585 Content-Type: application/yang.data+xml 1587 1588 1589 1591 123456789 1592 1593 bootstrap-complete 1594 example message 1595 1596 1597 ssh-rsa 1598 base64encodedvalue== 1599 1600 1601 ssh-dss 1602 base64encodedvalue== 1603 1604 1605 1606 1607 netconf-ssh 1608 netconf-tls 1609 restconf-tls 1610 netconf-ch-ssh 1611 netconf-ch-tls 1612 restconf-ch-tls 1613 base64encodedvalue== 1614 1615 1616 1617 1618 1619 1621 RESPONSE 1622 -------- 1624 HTTP/1.1 204 No Content 1625 Date: Sat, 31 Oct 2015 17:02:40 GMT 1626 Server: example-server 1628 7.3. YANG Module 1630 The bootstrap server's device-facing API is normatively defined by 1631 the YANG module defined in this section. 1633 Note: the module defined herein uses data types defined in [RFC2315], 1634 [RFC5280], and [I-D.ietf-anima-voucher]. 1636 file "ietf-zerotouch-bootstrap-server@2017-08-29.yang" 1637 module ietf-zerotouch-bootstrap-server { 1638 yang-version "1.1"; 1640 namespace 1641 "urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server"; 1642 prefix "ztbs"; 1644 organization 1645 "IETF NETCONF (Network Configuration) Working Group"; 1647 contact 1648 "WG Web: 1649 WG List: 1650 Author: Kent Watsen 1651 "; 1653 description 1654 "This module defines an interface for bootstrap servers, as defined 1655 by RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF based 1656 Management. 1658 Copyright (c) 2017 IETF Trust and the persons identified as 1659 authors of the code. All rights reserved. 1661 Redistribution and use in source and binary forms, with or without 1662 modification, is permitted pursuant to, and subject to the license 1663 terms contained in, the Simplified BSD License set forth in Section 1664 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents 1665 (http://trustee.ietf.org/license-info). 1667 This version of this YANG module is part of RFC XXXX; see the RFC 1668 itself for full legal notices."; 1670 revision "2017-08-29" { 1671 description 1672 "Initial version"; 1673 reference 1674 "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF based 1675 Management"; 1676 } 1678 // typedefs 1680 typedef pkcs7 { 1681 type binary; 1682 description 1683 "A PKCS #7 SignedData structure, as specified by Section 9.1 1684 in RFC 2315, encoded using ASN.1 distinguished encoding rules 1685 (DER), as specified in ITU-T X.690."; 1686 reference 1687 "RFC 2315: 1688 PKCS #7: Cryptographic Message Syntax Version 1.5. 1689 ITU-T X.690: 1690 Information technology - ASN.1 encoding rules: 1691 Specification of Basic Encoding Rules (BER), 1692 Canonical Encoding Rules (CER) and Distinguished 1693 Encoding Rules (DER)."; 1694 } 1696 // protocol accessible nodes 1698 list device { 1699 key unique-id; 1700 config false; 1701 description 1702 "A device's record entry. This is the only RESTCONF resource 1703 that a device will GET, as described in Section 8.2 in RFC XXXX. 1704 Getting just this top-level node provides a device with all the 1705 data it needs in a single request."; 1706 reference 1707 "RFC XXXX: Zero Touch Provisioning for NETCONF or 1708 RESTCONF based Management"; 1710 leaf unique-id { 1711 type string; 1712 description 1713 "A unique identifier for the device (e.g., serial number). 1714 Each device accesses its bootstrapping record by its unique 1715 identifier."; 1716 } 1718 leaf zerotouch-information { 1719 type pkcs7; 1720 mandatory true; 1721 description 1722 "A 'zerotouch-information' artifact, as described in Section 1723 4.1 of RFC XXXX. When conveyed over an untrusted transport, in 1724 order to be processed by a device, this PKCS#7 SignedData 1725 structure MUST contain a 'signerInfo' structure, described 1726 in Section 9.1 of RFC 2315, containing a signature generated 1727 using the owner's private key."; 1728 reference 1729 "RFC XXXX: Zero Touch Provisioning for NETCONF or 1730 RESTCONF based Management. 1731 RFC 2315: 1732 PKCS #7: Cryptographic Message Syntax Version 1.5"; 1733 } 1735 leaf owner-certificate { 1736 type pkcs7; 1737 description 1738 "An unsigned PKCS #7 SignedData structure, as specified by 1739 Section 9.1 in RFC 2315, encoded using ASN.1 distinguished 1740 encoding rules (DER), as specified in ITU-T X.690. 1742 This structure MUST contain the owner certificate and all 1743 intermediate certificates leading up to at least the trust 1744 anchor certificate specified in the ownership voucher. 1745 Additionally, if needed by the device, this structure MAY 1746 also contain suitably fresh CRL and or OCSP Responses. 1748 X.509 certificates and CRLs are described in RFC 5280. 1750 OCSP Responses are described in RFC 6960."; 1751 reference 1752 "RFC 2315: 1753 PKCS #7: Cryptographic Message Syntax Version 1.5. 1754 RFC 5280: 1755 Internet X.509 Public Key Infrastructure Certificate 1756 and Certificate Revocation List (CRL) Profile. 1757 RFC 6960: 1758 X.509 Internet Public Key Infrastructure Online 1759 Certificate Status Protocol - OCSP. 1760 ITU-T X.690: 1761 Information technology - ASN.1 encoding rules: 1762 Specification of Basic Encoding Rules (BER), 1763 Canonical Encoding Rules (CER) and Distinguished 1764 Encoding Rules (DER)."; 1765 } 1767 leaf ownership-voucher { 1768 type pkcs7; 1769 must "../owner-certificate" { 1770 description 1771 "An owner certificate must be present whenever an ownership 1772 voucher is presented."; 1773 } 1774 description 1775 "A 'voucher' artifact, as described in Section 5 of 1776 I-D.ietf-anima-voucher. The voucher informs the device 1777 who it's 'owner' is. The voucher encodes the device's 1778 serial number, so that the device can be ensured that 1779 the voucher applies to it. The voucher is signed by 1780 the device's manufacturer or delagate."; 1781 reference 1782 "I-D.etf-anima-voucher: 1783 Voucher and Voucher Revocation Profiles for Bootstrapping 1784 Protocols"; 1785 } 1787 action update-progress { 1788 input { 1789 leaf update-type { 1790 type enumeration { 1791 enum bootstrap-initiated { 1792 description 1793 "Indicates that the device has just accessed the 1794 bootstrap server. The 'message' field below MAY 1795 contain any additional information that the 1796 manufacturer thinks might be useful."; 1797 } 1798 enum parsing-warning { 1799 description 1800 "Indicates that the device had a non-fatal error when 1801 parsing the response from the bootstrap server. The 1802 'message' field below SHOULD indicate the specific 1803 warning that occurred."; 1804 } 1805 enum parsing-error { 1806 description 1807 "Indicates that the device encountered a fatal error 1808 when parsing the response from the bootstrap server. 1809 For instance, this could be due to malformed encoding, 1810 the device expecting signed data when only unsigned 1811 data is provided, because the ownership voucher didn't 1812 include the device's unique identifier, or because the 1813 signature didn't match. The 'message' field below 1814 SHOULD indicate the specific error. This update type 1815 also indicates that the device has abandoned trying to 1816 bootstrap off this bootstrap server."; 1817 } 1818 enum boot-image-warning { 1819 description 1820 "Indicates that the device encountered a non-fatal 1821 error condition when trying to install a boot-image. 1822 A possible reason might include a need to reformat a 1823 partition causing loss of data. The 'message' field 1824 below SHOULD indicate any warning messages that were 1825 generated."; 1826 } 1827 enum boot-image-error { 1828 description 1829 "Indicates that the device encountered an error when 1830 trying to install a boot-image, which could be for 1831 reasons such as a file server being unreachable, 1832 file not found, signature mismatch, etc. The 1833 'message' field SHOULD indicate the specific error 1834 that occurred. This update type also indicates 1835 that the device has abandoned trying to bootstrap 1836 off this bootstrap server."; 1837 } 1838 enum pre-script-warning { 1839 description 1840 "Indicates that the device obtained a greater than 1841 zero exit status code from the script when it was 1842 executed. The 'message' field below SHOULD indicate 1843 both the resulting exit status code, as well as 1844 capture any stdout/stderr messages the script may 1845 have produced."; 1847 } 1848 enum pre-script-error { 1849 description 1850 "Indicates that the device obtained a less than zero 1851 exit status code from the script when it was executed. 1852 The 'message' field below SHOULD indicate both the 1853 resulting exit status code, as well as capture any 1854 stdout/stderr messages the script may have produced. 1855 This update type also indicates that the device has 1856 abandoned trying to bootstrap off this bootstrap 1857 server."; 1858 } 1859 enum config-warning { 1860 description 1861 "Indicates that the device obtained warning messages 1862 when it committed the initial configuration. The 1863 'message' field below SHOULD indicate any warning 1864 messages that were generated."; 1865 } 1866 enum config-error { 1867 description 1868 "Indicates that the device obtained error messages 1869 when it committed the initial configuration. The 1870 'message' field below SHOULD indicate the error 1871 messages that were generated. This update type 1872 also indicates that the device has abandoned trying 1873 to bootstrap off this bootstrap server."; 1874 } 1875 enum post-script-warning { 1876 description 1877 "Indicates that the device obtained a greater than 1878 zero exit status code from the script when it was 1879 executed. The 'message' field below SHOULD indicate 1880 both the resulting exit status code, as well as 1881 capture any stdout/stderr messages the script may 1882 have produced."; 1883 } 1884 enum post-script-error { 1885 description 1886 "Indicates that the device obtained a less than zero 1887 exit status code from the script when it was executed. 1888 The 'message' field below SHOULD indicate both the 1889 resulting exit status code, as well as capture any 1890 stdout/stderr messages the script may have produced. 1891 This update type also indicates that the device has 1892 abandoned trying to bootstrap off this bootstrap 1893 server."; 1894 } 1895 enum bootstrap-complete { 1896 description 1897 "Indicates that the device successfully processed the 1898 all the bootstrapping data and that it is ready to be 1899 managed. The 'message' field below MAY contain any 1900 additional information that the manufacturer thinks 1901 might be useful. After sending this update type, 1902 the device is not expected to access the bootstrap 1903 server again."; 1904 } 1905 enum informational { 1906 description 1907 "Indicates any additional information not captured by 1908 any of the other update type. For instance, a 1909 message indicating that the device is about to reboot 1910 after having installed a boot-image could be provided. 1911 The 'message' field below SHOULD contain information 1912 that the manufacturer thinks might be useful."; 1913 } 1914 } 1915 mandatory true; 1916 description 1917 "The type of update provided."; 1918 } 1919 leaf message { 1920 type string; 1921 description 1922 "An optional human-readable value."; 1923 } 1924 container ssh-host-keys { 1925 when "../update-type = 'bootstrap-complete'" { 1926 description 1927 "SSH host keys are only sent when the update type 1928 is 'bootstrap-complete'."; 1929 } 1930 description 1931 "A list of SSH host keys an NMS may use to authenticate 1932 a NETCONF connection to the device with."; 1933 list ssh-host-key { 1934 description 1935 "An SSH host-key"; 1936 leaf format { 1937 type enumeration { 1938 enum ssh-dss { description "ssh-dss"; } 1939 enum ssh-rsa { description "ssh-rsa"; } 1940 } 1941 mandatory true; 1942 description 1943 "The format of the SSH host key."; 1944 } 1945 leaf key-data { 1946 type string; 1947 mandatory true; 1948 description 1949 "The key data for the SSH host key"; 1950 } 1951 } 1952 } 1953 container trust-anchors { 1954 when "../update-type = 'bootstrap-complete'" { 1955 description 1956 "Trust anchors are only sent when the update type 1957 is 'bootstrap-complete'."; 1958 } 1959 description 1960 "A list of trust anchor certificates an NMS may use to 1961 authenticate a NETCONF or RESTCONF connection to the 1962 device with."; 1963 list trust-anchor { 1964 description 1965 "A list of trust anchor certificates an NMS may use to 1966 authenticate a NETCONF or RESTCONF connection to the 1967 device with."; 1968 leaf-list protocol { 1969 type enumeration { 1970 enum netconf-ssh { description "netconf-ssh"; } 1971 enum netconf-tls { description "netconf-tls"; } 1972 enum restconf-tls { description "restconf-tls"; } 1973 enum netconf-ch-ssh { description "netconf-ch-ssh"; } 1974 enum netconf-ch-tls { description "netconf-ch-tls"; } 1975 enum restconf-ch-tls { description "restconf-ch-tls"; } 1976 } 1977 min-elements 1; 1978 description 1979 "The protocols that this trust anchor secures."; 1980 } 1981 leaf certificate { 1982 type pkcs7; 1983 mandatory true; 1984 description 1985 "An X.509 v3 certificate structure, as specified by 1986 Section 4 in RFC5280, encoded using ASN.1 distinguished 1987 encoding rules (DER), as specified in ITU-T X.690."; 1988 reference 1989 "RFC 5280: 1990 Internet X.509 Public Key Infrastructure Certificate 1991 and Certificate Revocation List (CRL) Profile. 1992 ITU-T X.690: 1993 Information technology - ASN.1 encoding rules: 1994 Specification of Basic Encoding Rules (BER), 1995 Canonical Encoding Rules (CER) and Distinguished 1996 Encoding Rules (DER)."; 1997 } 1998 } 1999 } 2000 } 2001 } // end action 2003 } // end device 2005 } 2006 2008 8. DHCP Zero Touch Options 2010 This section defines two DHCP options, one for DHCPv4 and one for 2011 DHCPv6. These two options are semantically the same, though 2012 syntactically different. 2014 8.1. DHCPv4 Zero Touch Option 2016 The DHCPv4 Zero Touch Option is used to provision the client with one 2017 or more URIs for bootstrap servers that can be contacted to attempt 2018 further configuration. 2020 DHCPv4 Zero Touch Redirect Option 2022 0 1 2023 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 2024 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2025 | option-code (TBD) | option-length | 2026 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2027 . . 2028 . bootstrap-server-list (variable length) . 2029 . . 2030 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2032 o option-code: OPTION_V4_ZEROTOUCH_REDIRECT (TBD) 2033 o option-length: The option length in octets 2034 o bootstrap-server-list: A list of servers for the 2035 client to attempt contacting, in order to obtain 2036 further bootstrapping data, in the format shown 2037 in [common-field-encoding]. 2039 DHCPv4 Client Behavior 2041 Clients MAY request the OPTION_V4_ZEROTOUCH_REDIRECT by including its 2042 option code in the Parameter Request List (55) in DHCP request 2043 messages. 2045 On receipt of a DHCPv4 Reply message which contains the 2046 OPTION_V4_ZEROTOUCH_REDIRECT, the client performs the following 2047 steps: 2049 1. Check the contents of the DHCPv4 message for at least one valid 2050 URI. If there is more than one valid URI in the list, a candidate 2051 list of possible URIs is created. 2053 2. Attempt to connect to the one of the URIs in the candidate list. 2054 The order in which these are processed by the client is 2055 implementation specific and not defined here. 2057 3. If a successful connection to the Zero Touch bootstrap server, 2058 then the client stops processing entries in the list and proceeds 2059 according to Appendix A.3, step(3). 2061 4. If the Zero Touch bootstrap server does not respond, provides 2062 an invalid response, or the transaction otherwise fails, the 2063 client SHOULD attempt to contact another server from the 2064 candidate list. 2066 Any invalid URI entries received in the uri-data field are ignored by 2067 the client. If OPTION_V4_ZEROTOUCH_REDIRECT does not contain at 2068 least one valid URI entry in the uri-data field, then the client MUST 2069 discard the option. 2071 DHCPv4 Server Behavior 2073 The DHCPv4 server MAY include a single instance of Option 2074 OPTION_V4_ZEROTOUCH_REDIRECT in DHCP messages it sends. Servers MUST 2075 NOT send more than one instance of the OPTION_V4_ZEROTOUCH_REDIRECT 2076 option. 2078 8.2. DHCPv6 Zero Touch Option 2080 The DHCPv6 Zero Touch Option is used to provision the client with one 2081 or more URIs for bootstrap servers that can be contacted to attempt 2082 further configuration. 2084 DHCPv6 Zero Touch Redirect Option 2086 0 1 2 3 2087 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 2088 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2089 | option-code (TBD) | option-length | 2090 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2091 . bootstrap-server-list (variable length) . 2092 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2094 o option-code: OPTION_V6_ZEROTOUCH_REDIRECT (TBD) 2095 o option-length: The option length in octets 2096 o bootstrap-server-list: A list of servers for the client to 2097 attempt contacting, in order to obtain further bootstrapping 2098 data, in the format shown in [common-field-encoding]. 2100 DHCPv6 Client Behavior 2102 Clients MAY request the OPTION_V6_ZEROTOUCH_REDIRECT option, as 2103 defined in [RFC3315], Sections 17.1.1, 18.1.1, 18.1.3, 18.1.4, 2104 18.1.5, and 22.7. As a convenience to the reader, we mention here 2105 that the client includes requested option codes in the Option Request 2106 Option. 2108 On receipt of a DHCPv6 reply message which contains the 2109 OPTION_V6_ZEROTOUCH_REDIRECT, the client performs the following 2110 steps: 2112 1. Check the contents of the DHCPv6 message for at least one valid 2113 URI. If there is more than one valid URI in the list, a 2114 candidate list of possible URIs is created. 2116 2. Attempt to connect to the one of the URIs in the candidate list. 2117 The order in which these are processed by the client is 2118 implementation specific and not defined here. 2120 3. If a successful connection to the Netconf Zero Touch Bootstrap 2121 server, then the client stops processing entries in the list and 2122 proceeds according to Appendix A.3, step(3). 2124 4. If the Zero Touch bootstrap server does not respond, provides 2125 and invalid response or the transaction otherwise fails, the 2126 client SHOULD attempt to contact another server from the 2127 candidate list. 2129 Any invalid URI entries received in the uri-data field are ignored by 2130 the client. If OPTION_V6_ZEROTOUCH_REDIRECT does not contain at 2131 least one valid URI entry in the uri-data field, then the client MUST 2132 discard the option. 2134 DHCPv6 Server Behavior 2136 Sections 17.2.2 and 18.2 of [RFC3315] govern server operation 2137 in regard to option assignment. As a convenience to the reader, 2138 we mention here that the server will send a particular option code 2139 only if configured with specific values for that option code and if 2140 the client requested it. 2142 Option OPTION_V6_ZEROTOUCH_REDIRECT is a singleton. Servers MUST NOT 2143 send more than one instance of the OPTION_V6_ZEROTOUCH_REDIRECT 2144 option. 2146 8.3. Common Field Encoding 2148 Both of the DHCPv4 and DHCPv6 options defined in this section encode 2149 a list of bootstrap server URIs. The 'URI' structure is an option 2150 that can contain multiple URIs (see [RFC7227], Section 5.7). 2152 bootstrap-server-list: 2154 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 2155 | uri-length | URI | 2156 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 2158 o uri-length: variable, in octets. 2160 o URI: URI of zerotouch bootstrap server, using the HTTPS URI 2161 scheme defined in Section 2.7.2 of RFC7230. 2163 9. Security Considerations 2165 9.1. Immutable storage for trust anchors 2167 Devices MUST ensure that all their trust anchor certificates, 2168 including those for connecting to bootstrap servers and verifying 2169 ownership vouchers, are protected from external modification. 2171 It may be necessary to update these certificates over time (e.g., the 2172 manufacturer wants to delegate trust to a new CA). It is therefore 2173 expected that devices MAY update these trust anchors when needed 2174 through a verifiable process, such as a software upgrade using signed 2175 software images. 2177 9.2. Clock Sensitivity 2179 The solution in this document relies on TLS certificates, owner 2180 certificates, and ownership vouchers, all of which require an 2181 accurate clock in order to be processed correctly (e.g., to test 2182 validity dates and revocation status). Implementations MUST ensure 2183 devices have an accurate clock when shipped from manufacturing 2184 facilities, and take steps to prevent clock tampering. 2186 If it is not possible to ensure clock accuracy, it is RECOMMENDED 2187 that implementations disable the aspects of the solution having clock 2188 sensitivity. In particular, such implementations should assume that 2189 TLS certificates, ownership vouchers, and owner certificates never 2190 expire and are not revokable. In real-world terms, this means that 2191 manufacturers SHOULD only issue a single ownership voucher for the 2192 lifetime of such devices. 2194 Implementations SHOULD NOT rely on NTP for time, as NTP is not a 2195 secure protocol. 2197 9.3. Blindly authenticating a bootstrap server 2199 This document allows a device to blindly authenticate a bootstrap 2200 server's TLS certificate. It does so to allow for cases where the 2201 redirect information may be obtained in an unsecured manner, which is 2202 desirable to support in some cases. 2204 To compensate for this, this document requires that devices, when 2205 connected to an untrusted bootstrap server, do not send their IDevID 2206 certificate for client authentication, and they do not POST any 2207 progress updates, and they assert that data downloaded from the 2208 server is signed. 2210 9.4. Entropy loss over time 2212 Section 7.2.7.2 of the IEEE Std 802.1AR-2009 standard says that 2213 IDevID certificate should never expire (i.e. having the notAfter 2214 value 99991231235959Z). Given the long-lived nature of these 2215 certificates, it is paramount to use a strong key length (e.g., 2216 512-bit ECC). 2218 9.5. Serial Numbers 2220 This draft uses the device's serial number both in the IDevID 2221 certificate as well as in the bootstrap server API. Serial numbers 2222 are ubiquitous and prominently contained in invoices and on labels 2223 affixed to devices and their packaging. That said, serial numbers 2224 many times encode revealing information, such as the device's model 2225 number, manufacture date, and/or sequence number. Knowledge of this 2226 information may provide an adversary with details needed to launch an 2227 attack. 2229 9.6. Sequencing Sources of Bootstrapping Data 2231 For devices supporting more than one source for bootstrapping data, 2232 no particular sequencing order has to be observed for security 2233 reasons, as the solution for each source is considered equally 2234 secure. However, from a privacy perspective, it is RECOMMENDED that 2235 devices access local sources before accessing remote sources. 2237 10. IANA Considerations 2239 10.1. The BOOTP Manufacturer Extensions and DHCP Options Registry 2241 IANA is kindly requested to allocate a new option code from the 2242 "BOOTP Manufacturer Extensions and DHCP Options" registry maintained 2243 at http://www.iana.org/assignments/bootp-dhcp-parameters: 2245 TBD for OPTION_V4_ZEROTOUCH_REDIRECT 2247 And a new option code from the "Dynamic Host Configuration Protocol 2248 for IPv6 (DHCPv6)" registry maintained at 2249 http://www.iana.org/assignments/dhcpv6-parameters: 2251 TBD for OPTION_V6_ZEROTOUCH_REDIRECT 2253 10.2. The IETF XML Registry 2255 This document registers two URIs in the IETF XML registry [RFC3688]. 2256 Following the format in [RFC3688], the following registrations are 2257 requested: 2259 URI: urn:ietf:params:xml:ns:yang:ietf-zerotouch-information 2260 Registrant Contact: The NETCONF WG of the IETF. 2261 XML: N/A, the requested URI is an XML namespace. 2263 URI: urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server 2264 Registrant Contact: The NETCONF WG of the IETF. 2265 XML: N/A, the requested URI is an XML namespace. 2267 10.3. The YANG Module Names Registry 2269 This document registers two YANG modules in the YANG Module Names 2270 registry [RFC6020]. Following the format defined in [RFC6020], the 2271 the following registrations are requested: 2273 name: ietf-zerotouch-information 2274 namespace: urn:ietf:params:xml:ns:yang:ietf-zerotouch-information 2275 prefix: zti 2276 reference: RFC XXXX 2278 name: ietf-zerotouch-bootstrap-server 2279 namespace: urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server 2280 prefix: ztbs 2281 reference: RFC XXXX 2283 11. Acknowledgements 2285 The authors would like to thank for following for lively discussions 2286 on list and in the halls (ordered by last name): David Harrington, 2287 Michael Behringer, Dean Bogdanovic, Martin Bjorklund, Joe Clarke, 2288 Toerless Eckert, Stephen Farrell, Stephen Hanna, Wes Hardaker, Russ 2289 Mundy, Reinaldo Penno, Randy Presuhn, Max Pritikin, Michael 2290 Richardson, Phil Shafer, Juergen Schoenwaelder. 2292 Special thanks goes to Steve Hanna, Russ Mundy, and Wes Hardaker for 2293 brainstorming the original I-D's solution during the IETF 87 meeting 2294 in Berlin. 2296 12. References 2298 12.1. Normative References 2300 [I-D.ietf-anima-voucher] 2301 Watsen, K., Richardson, M., Pritikin, M., and T. Eckert, 2302 "Voucher Profile for Bootstrapping Protocols", draft-ietf- 2303 anima-voucher-04 (work in progress), July 2017. 2305 [RFC1035] Mockapetris, P., "Domain names - implementation and 2306 specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, 2307 November 1987, . 2309 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2310 Requirement Levels", BCP 14, RFC 2119, 2311 DOI 10.17487/RFC2119, March 1997, . 2314 [RFC2315] Kaliski, B., "PKCS #7: Cryptographic Message Syntax 2315 Version 1.5", RFC 2315, DOI 10.17487/RFC2315, March 1998, 2316 . 2318 [RFC3315] Droms, R., Ed., Bound, J., Volz, B., Lemon, T., Perkins, 2319 C., and M. Carney, "Dynamic Host Configuration Protocol 2320 for IPv6 (DHCPv6)", RFC 3315, DOI 10.17487/RFC3315, July 2321 2003, . 2323 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2324 Housley, R., and W. Polk, "Internet X.509 Public Key 2325 Infrastructure Certificate and Certificate Revocation List 2326 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 2327 . 2329 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2330 the Network Configuration Protocol (NETCONF)", RFC 6020, 2331 DOI 10.17487/RFC6020, October 2010, 2332 . 2334 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2335 Verification of Domain-Based Application Service Identity 2336 within Internet Public Key Infrastructure Using X.509 2337 (PKIX) Certificates in the Context of Transport Layer 2338 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2339 2011, . 2341 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 2342 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 2343 DOI 10.17487/RFC6234, May 2011, 2344 . 2346 [RFC6762] Cheshire, S. and M. Krochmal, "Multicast DNS", RFC 6762, 2347 DOI 10.17487/RFC6762, February 2013, . 2350 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 2351 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, 2352 . 2354 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2355 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2356 . 2358 [RFC7227] Hankins, D., Mrugalski, T., Siodelski, M., Jiang, S., and 2359 S. Krishnan, "Guidelines for Creating New DHCPv6 Options", 2360 BCP 187, RFC 7227, DOI 10.17487/RFC7227, May 2014, 2361 . 2363 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 2364 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 2365 April 2015, . 2367 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2368 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2369 . 2371 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2372 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2373 May 2017, . 2375 [Std-802.1AR-2009] 2376 IEEE SA-Standards Board, "IEEE Standard for Local and 2377 metropolitan area networks - Secure Device Identity", 2378 December 2009, . 2381 12.2. Informative References 2383 [I-D.ietf-netconf-netconf-client-server] 2384 Watsen, K., Wu, G., and J. Schoenwaelder, "NETCONF Client 2385 and Server Models", draft-ietf-netconf-netconf-client- 2386 server-04 (work in progress), July 2017. 2388 [RFC2939] Droms, R., "Procedures and IANA Guidelines for Definition 2389 of New DHCP Options and Message Types", BCP 43, RFC 2939, 2390 DOI 10.17487/RFC2939, September 2000, 2391 . 2393 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2394 DOI 10.17487/RFC3688, January 2004, . 2397 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2398 and A. Bierman, Ed., "Network Configuration Protocol 2399 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2400 . 2402 [RFC6698] Hoffman, P. and J. Schlyter, "The DNS-Based Authentication 2403 of Named Entities (DANE) Transport Layer Security (TLS) 2404 Protocol: TLSA", RFC 6698, DOI 10.17487/RFC6698, August 2405 2012, . 2407 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 2408 Galperin, S., and C. Adams, "X.509 Internet Public Key 2409 Infrastructure Online Certificate Status Protocol - OCSP", 2410 RFC 6960, DOI 10.17487/RFC6960, June 2013, 2411 . 2413 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 2414 System Management", RFC 7317, DOI 10.17487/RFC7317, August 2415 2014, . 2417 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 2418 RFC 8071, DOI 10.17487/RFC8071, February 2017, 2419 . 2421 Appendix A. Workflow Overview 2423 The zero touch solution presented in this document is conceptualized 2424 to be composed of the non-normative workflows described in this 2425 section. Implementations details are expected to vary. Each diagram 2426 is followed by a detailed description of the steps presented in the 2427 diagram, with further explanation on how implementations may vary. 2429 A.1. Enrollment and Ordering Devices 2431 The following diagram illustrates key interactions that may occur 2432 from when a prospective owner enrolls in a manufacturer's zero touch 2433 program to when the manufacturer ships devices for an order placed by 2434 the prospective owner. 2436 +-----------+ 2437 +------------+ |Prospective| +---+ 2438 |Manufacturer| | Owner | |NMS| 2439 +------------+ +-----------+ +---+ 2440 | | | 2441 | | | 2442 | 1. initiate enrollment | | 2443 #<-----------------------------| | 2444 # | | 2445 # | | 2446 # IDevID trust anchor | | 2447 #-----------------------------># set IDevID trust anchor | 2448 # #--------------------------->| 2449 # | | 2450 # bootstrap server | | 2451 # account credentials | | 2452 #-----------------------------># set credentials | 2453 | #--------------------------->| 2454 | | | 2455 | | | 2456 | 2. set owner certificate trust anchor | 2457 |<----------------------------------------------------------| 2458 | | | 2459 | | | 2460 | 3. place device order | | 2461 |<-----------------------------# model devices | 2462 | #--------------------------->| 2463 | | | 2464 | 4. ship devices and send | | 2465 | device identifiers and | | 2466 | ownership vouchers | | 2467 |-----------------------------># set device identifiers | 2468 | # and ownership vouchers | 2469 | #--------------------------->| 2470 | | | 2472 Each numbered item below corresponds to a numbered item in the 2473 diagram above. 2475 1. A prospective owner of a manufacturer's devices, or an existing 2476 owner that wishes to start using zero touch for future device 2477 orders, initiates an enrollment process with the manufacturer or 2478 delegate. This process includes the following: 2480 * Regardless how the prospective owner intends to bootstrap 2481 their devices, they will always obtain from the manufacturer 2482 or delegate the trust anchor certificate for its device's 2483 IDevID certificates. This certificate will need to be 2484 installed on the prospective owner's NMS so that the NMS can 2485 subsequently authenticate the devices' IDevID certificates. 2487 * If the manufacturer hosts an Internet based bootstrap server 2488 (e.g., a redirect server) such as described in Section 4.4, 2489 then credentials necessary to configure the bootstrap server 2490 would be provided to the prospective owner. If the bootstrap 2491 server is configurable through an API (outside the scope of 2492 this document), then the credentials might be installed on the 2493 prospective owner's NMS so that the NMS can subsequently 2494 configure the manufacturer-hosted bootstrap server directly. 2496 2. If the manufacturer's devices are able to validate signed data 2497 (Section 5.4), and assuming that the prospective owner's NMS is 2498 able to prepare and sign the bootstrapping data itself, the 2499 prospective owner's NMS might set a trust anchor certificate onto 2500 the manufacturer's bootstrap server, using the credentials 2501 provided in the previous step. This certificate is the trust 2502 anchor certificate that the prospective owner would like the 2503 manufacturer to place into the ownership vouchers it generates, 2504 thereby enabling devices to trust the owner's owner certificate. 2505 How this trust anchor certifiate is used to enable devices to 2506 validate signed bootstrapping data is described in Section 5.4. 2508 3. Some time later, the prospective owner places an order with the 2509 manufacturer or delegate, perhaps with a special flag checked for 2510 zero touch handling. At this time, or perhaps before placing the 2511 order, the owner may model the devices in their NMS, creating 2512 virtual objects for the devices with no real-world device 2513 associations. For instance the model can be used to simulate the 2514 device's location in the network and the configuration it should 2515 have when fully operational. 2517 4. When the manufacturer or delegate fulfills the order, shipping 2518 the devices to their intended locations, they may notify the 2519 owner of the devices's serial numbers and shipping destinations, 2520 which the owner may use to stage the network for when the devices 2521 power on. Additionally, the manufacturer may send one or more 2522 ownership vouchers, cryptographically assigning ownership of 2523 those devices to the owner. The owner may set this information 2524 on their NMS, perhaps binding specific modeled devices to the 2525 serial numbers and ownership vouchers. 2527 A.2. Owner Stages the Network for Bootstrap 2529 The following diagram illustrates how an owner might stage the 2530 network for bootstrapping devices. 2532 +----------+ +------------+ 2533 |Deployment| |Manufacturer| +------+ +------+ 2534 | Specific | | Hosted | | Local| | Local| +---------+ 2535 +---+ |Bootstrap | | Bootstrap | | DNS | | DHCP | |Removable| 2536 |NMS| | Server | | Server | |Server| |Server| | Storage | 2537 +---+ +----------+ +------------+ +------+ +------+ +---------+ 2538 | | | | | | 2539 activate | | | | | | 2540 modeled | | | | | | 2541 1. device | | | | | | 2542 ----------->| | | | | | 2543 | 2. (optional) | | | | 2544 | configure | | | | 2545 | bootstrap | | | | 2546 | server | | | | 2547 |------->| | | | | 2548 | | | | | | 2549 | 3. (optional) configure | | | 2550 | bootstrap server | | | | 2551 |--------------------->| | | | 2552 | | | | | | 2553 | | | | | | 2554 | 4. (optional) configure DNS server| | | 2555 |---------------------------------->| | | 2556 | | | | | | 2557 | | | | | | 2558 | 5. (optional) configure DHCP server | | 2559 |------------------------------------------->| | 2560 | | | | | | 2561 | | | | | | 2562 | 6. (optional) store bootstrapping artifacts on media | 2563 |----------------------------------------------------->| 2564 | | | | | | 2565 | | | | | | 2567 Each numbered item below corresponds to a numbered item in the 2568 diagram above. 2570 1. Having previously modeled the devices, including setting their 2571 fully operational configurations and associating both device 2572 serial numbers and ownership vouchers, the owner might "activate" 2573 one or more modeled devices. That is, the owner tells the NMS to 2574 perform the steps necessary to prepare for when the real-world 2575 devices power up and initiate the bootstrapping process. Note 2576 that, in some deployments, this step might be combined with the 2577 last step from the previous workflow. Here it is depicted that 2578 an NMS performs the steps, but they may be performed manually or 2579 through some other mechanism. 2581 2. If it is desired to use a deployment specific bootstrap server, 2582 it must be configured to provide the bootstrapping information 2583 for the specific devices. Configuring the bootstrap server may 2584 occur via a programmatic API not defined by this document. 2585 Illustrated here as an external component, the bootstrap server 2586 may be implemented as an internal component of the NMS itself. 2588 3. If it is desired to use a manufacturer (or delegate) hosted 2589 bootstrap server, it must be configured to provide the 2590 bootstrapping information for the specific devices. The 2591 configuration must be either redirect or onboarding information. 2592 That is, either the manufacturer hosted bootstrap server will 2593 redirect the device to another bootstrap server, or provide the 2594 device with its bootstrapping information itself. The types of 2595 bootstrapping information the manufacturer hosted bootstrap 2596 server supports may vary by implementation; some implementations 2597 may only support redirect information, or only support onboarding 2598 information, or support both redirect and onboarding information. 2599 Configuring the bootstrap server may occur via a programmatic API 2600 not defined by this document. 2602 4. If it is desired to use a DNS server to supply bootstrapping 2603 information, a DNS server needs to be configured. If multicast 2604 DNS-SD is desired, then the server must reside on the local 2605 network, otherwise the DNS server may reside on a remote network. 2606 Please see Section 4.2 for more information about how to 2607 configure DNS servers. Configuring the DNS server may occur via 2608 a programmatic API not defined by this document. 2610 5. If it is desired to use a DHCP server to supply bootstrapping 2611 data, a DHCP server needs to be configured. The DHCP server may 2612 be accessed directly or via a DHCP relay. Please see Section 4.3 2613 for more information about how to configure DHCP servers. 2614 Configuring the DHCP server may occur via a programmatic API not 2615 defined by this document. 2617 6. If it is desired to use a removable storage device (e.g., USB 2618 flash drive) to supply bootstrapping information, the information 2619 would need to be placed onto it. Please see Section 4.1 for more 2620 information about how to configure a removable storage device. 2622 A.3. Device Powers On 2624 The following diagram illustrates the sequence of activities that 2625 occur when a device powers on. 2627 +----------+ 2628 +-----------+ |Deployment| 2629 | Source of | | Specific | 2630 +------+ | Bootstrap | |Bootstrap | +---+ 2631 |Device| | Data | | Server | |NMS| 2632 +------+ +-----------+ +----------+ +---+ 2633 | | | | 2634 | | | | 2635 | 1. if zerotouch bootstrap is not | | | 2636 | configured, then exit. | | | 2637 | | | | 2638 | 2. for each source supported, check | | | 2639 |------------------------------------->| | | 2640 | | | | 2641 | 3. if onboarding-information found, | | | 2642 | initialize self and, only if | | | 2643 | source is a bootstrap server, | | | 2644 | send progress updates | | | 2645 |-------------------------------------># | | 2646 | # webhook | | 2647 | #----------------------->| 2648 | | | 2649 | 4. else if redirect-information found, for | | 2650 | each bootstrap server specified, check | | 2651 |-+-------------------------------------------------->| | 2652 | | | | 2653 | | if more redirect-information is found, recurse | | 2654 | | (not depicted), else if onboarding-information | | 2655 | | found, initialize self and post progress updates | | 2656 | +--------------------------------------------------># | 2657 | # webhook | 2658 | #-------->| 2659 | 2660 | 5. retry sources and/or wait for manual provisioning. 2661 | 2663 The interactions in the above diagram are described below. 2665 1. Upon power being applied, the device checks to see if zerotouch 2666 bootstrapping is configured, such as is the case when running its 2667 "factory default" configuration. If zerotouch bootstrapping is 2668 not configured, then the bootstrapping logic exits and none of 2669 the following interactions occur. 2671 2. For each source of bootstrapping data the device supports, 2672 preferably in order of closeness to the device (e.g., removable 2673 storage before Internet based servers), the device checks to see 2674 if there is any bootstrapping data for it there. 2676 3. If onboarding information is found, the device initializes itself 2677 accordingly (e.g., installing a boot-image and committing an 2678 initial configuration). If the source is a bootstrap server, and 2679 the bootstrap server can be trusted (i.e., TLS-level 2680 authentication), the device also sends progress updates to the 2681 bootstrap server. 2683 * The contents of the initial configuration should configure an 2684 administrator account on the device (e.g., username, ssh-rsa 2685 key, etc.) and should configure the device either to listen 2686 for NETCONF or RESTCONF connections or to initiate call home 2687 connections [RFC8071]. 2689 * If the bootstrap server supports forwarding device progress 2690 updates to external systems (e.g., via a webhook), a 2691 "bootstrap-complete" progress update (Section 7.3) informs the 2692 external system to know when it can, for instance, initiate a 2693 connection to the device (assuming it knows the device's 2694 address and the device was configured to listen for 2695 connections). To support this further, the bootstrap-complete 2696 progress update may also relay the device's SSH host keys and/ 2697 or TLS certificates, with which the external system can use to 2698 authenticate subsequent connections to the device. 2700 If the device successfully completes the bootstrapping process 2701 (i.e., zerotouch bootstrapping is no longer configured), it exits 2702 the bootstrapping logic without considering any additional 2703 sources of bootstrapping data. 2705 4. Otherwise, if redirect information is found, the device iterates 2706 through the list of specified bootstrap servers, checking to see 2707 if there is any bootstrapping data for it on them. If the 2708 bootstrap server returns more redirect information, then the 2709 device processes it recursively. Otherwise, if the bootstrap 2710 server returns onboarding information, the device processes it 2711 following the description provided in (3) above. 2713 5. After having tried all supported sources of bootstrapping data, 2714 the device may retry again all the sources and/or provide 2715 manageability interfaces for manual configuration (e.g., CLI, 2716 HTTP, NETCONF, etc.). If manual configuration is allowed, and 2717 such configuration is provided, the device should cease trying to 2718 obtain bootstrapping data, as the need to do so would no longer 2719 be present. 2721 Appendix B. Change Log 2723 B.1. ID to 00 2725 o Major structural update; the essence is the same. Most every 2726 section was rewritten to some degree. 2728 o Added a Use Cases section 2730 o Added diagrams for "Actors and Roles" and "NMS Precondition" 2731 sections, and greatly improved the "Device Boot Sequence" diagram 2733 o Removed support for physical presence or any ability for 2734 configlets to not be signed. 2736 o Defined the Zero Touch Information DHCP option 2738 o Added an ability for devices to also download images from 2739 configuration servers 2741 o Added an ability for configlets to be encrypted 2743 o Now configuration servers only have to support HTTP/S - no other 2744 schemes possible 2746 B.2. 00 to 01 2748 o Added boot-image and validate-owner annotations to the "Actors and 2749 Roles" diagram. 2751 o Fixed 2nd paragraph in section 7.1 to reflect current use of 2752 anyxml. 2754 o Added encrypted and signed-encrypted examples 2756 o Replaced YANG module with XSD schema 2758 o Added IANA request for the Zero Touch Information DHCP Option 2760 o Added IANA request for media types for boot-image and 2761 configuration 2763 B.3. 01 to 02 2765 o Replaced the need for a configuration signer with the ability for 2766 each NMS to be able to sign its own configurations, using 2767 manufacturer signed ownership vouchers and owner certificates. 2769 o Renamed configuration server to bootstrap server, a more 2770 representative name given the information devices download from 2771 it. 2773 o Replaced the concept of a configlet by defining a southbound 2774 interface for the bootstrap server using YANG. 2776 o Removed the IANA request for the boot-image and configuration 2777 media types 2779 B.4. 02 to 03 2781 o Minor update, mostly just to add an Editor's Note to show how this 2782 draft might integrate with the draft-pritikin-anima-bootstrapping- 2783 keyinfra. 2785 B.5. 03 to 04 2787 o Major update formally introducing unsigned data and support for 2788 Internet-based redirect servers. 2790 o Added many terms to Terminology section. 2792 o Added all new "Guiding Principles" section. 2794 o Added all new "Sources for Bootstrapping Data" section. 2796 o Rewrote the "Interactions" section and renamed it "Workflow 2797 Overview". 2799 B.6. 04 to 05 2801 o Semi-major update, refactoring the document into more logical 2802 parts 2804 o Created new section for information types 2806 o Added support for DNS servers 2808 o Now allows provisional TLS connections 2810 o Bootstrapping data now supports scripts 2812 o Device Details section overhauled 2814 o Security Considerations expanded 2816 o Filled in enumerations for notification types 2818 B.7. 05 to 06 2820 o Minor update 2822 o Added many Normative and Informative references. 2824 o Added new section Other Considerations. 2826 B.8. 06 to 07 2828 o Minor update 2830 o Added an Editorial Note section for RFC Editor. 2832 o Updated the IANA Considerations section. 2834 B.9. 07 to 08 2836 o Minor update 2838 o Updated to reflect review from Michael Richardson. 2840 B.10. 08 to 09 2842 o Added in missing "Signature" artifact example. 2844 o Added recommendation for manufacturers to use interoperable 2845 formats and file naming conventions for removable storage devices. 2847 o Added configuration-handling leaf to guide if config should be 2848 merged, replaced, or processed like an edit-config/yang-patch 2849 document. 2851 o Added a pre-configuration script, in addition to the post- 2852 configuration script from -05 (issue #15). 2854 B.11. 09 to 10 2856 o Factored ownership vocher and voucher revocation to a separate 2857 document: draft-kwatsen-netconf-voucher. (issue #11) 2859 o Removed options 'edit-config' and yang- 2860 patch'. (issue #12) 2862 o Defined how a signature over signed-data returned from a bootstrap 2863 server is processed. (issue #13) 2865 o Added recommendation for removable storage devices to use open/ 2866 standard file systems when possible. (issue #14) 2868 o Replaced notifications "script-[warning/error]" with "[pre/post]- 2869 script-[warning/error]". (goes with issue #15) 2871 o switched owner-certificate to be encoded using the pkcs#7 format. 2872 (issue #16) 2874 o Replaced md5/sha1 with sha256 inside a choice statement, for 2875 future extensibility. (issue #17) 2877 o A ton of editorial changes, as I went thru the entire draft with a 2878 fine-toothed comb. 2880 B.12. 10 to 11 2882 o fixed yang validation issues found by IETFYANGPageCompilation. 2883 note: these issues were NOT found by pyang --ietf or by the 2884 submission-time validator... 2886 o fixed a typo in the yang module, someone the config false 2887 statement was removed. 2889 B.13. 11 to 12 2891 o fixed typo that prevented Appendix B from loading the examples 2892 correctly. 2894 o fixed more yang validation issues found by 2895 IETFYANGPageCompilation. note: again, these issues were NOT found 2896 by pyang --ietf or by the submission-time validator... 2898 o updated a few of the notification enumerations to be more 2899 consistent with the other enumerations (following the warning/ 2900 error pattern). 2902 o updated the information-type artifact to state how it's encoded, 2903 matching the language that was in Appendix B. 2905 B.14. 12 to 13 2907 o defined a standalone artifact to encode the old information-type 2908 into a PKCS#7 structure. 2910 o standalone information artifact hardcodes JSON encoding (to match 2911 the voucher draft). 2913 o combined the information and signature PKCS#7 structures into a 2914 single PKCS#7 structure. 2916 o moved the certificate-revocations into the owner-certificate's 2917 PKCS#7 structure. 2919 o eliminated support for voucher-revocations, to reflect the 2920 voucher-draft's switch from revocations to renewals. 2922 B.15. 13 to 14 2924 o Renamed "bootstrap information" to "onboarding information". 2926 o Rewrote DHCP sections to address the packet-size limitation issue, 2927 as discussed in Chicago. 2929 o Added Ian as an author for his text-contributions to the DHCP 2930 sections. 2932 o Removed the Guiding Principles section. 2934 B.16. 14 to 15 2936 o Renamed action 'notification' to 'update-progress' and, likewise 2937 'notification-type' to 'update-type'. 2939 o Updated examples to use "base64encodedvalue==" for binary values. 2941 o Greatly simplified the 'Artifact Groupings' section, and moved it 2942 as a subsection to the 'Artifacts' section. 2944 o Moved the 'Workflow Overview' section to the Appendix. 2946 o Renamed 'bootstrap information' to 'update information'. 2948 o Removed 'Other Considerations' section. 2950 o Tons of editorial updates. 2952 B.17. 15 to 16 2954 o tweaked language to refer to "initial state" rather than "factory 2955 default configuration", so as accomodate white-box scenarios. 2957 o added a paragraph to Intro regarding how the solution primarily 2958 regards physical machines, but could be extended to VMs by a 2959 future document. 2961 o added a pointer to the Workflow Overview section (recently moved 2962 to the Appendix) to the Intro. 2964 o added a note that, in order to simplify the verification process, 2965 the "Zerotouch Information" PKCS#7 structure MUST also contain the 2966 signing X.509 certificate. 2968 o noted that the owner certificate's must either have no Key Usage 2969 or the Key Usage must set the "digitalSignature" bit. 2971 o noted that the owner certificate's subject and subjectAltName 2972 values are not constrained. 2974 o moved/consolidated some text from the Artifacts section down to 2975 the Device Details section. 2977 o tightened up some ambigous language, for instance, by refering to 2978 specific leaf names in the Voucher artifact. 2980 o reverted a previously overzealous s/unique-id/serial-number/ 2981 change. 2983 o modified language for when ZTP runs from when factory-default 2984 config is running to when ZTP is confgured, which the factory- 2985 defaults should set . 2987 Authors' Addresses 2989 Kent Watsen 2990 Juniper Networks 2992 EMail: kwatsen@juniper.net 2994 Mikael Abrahamsson 2995 T-Systems 2997 EMail: mikael.abrahamsson@t-systems.se 2999 Ian Farrer 3000 Deutsche Telekom AG 3002 EMail: ian.farrer@telekom.de