idnits 2.17.1 draft-ietf-netconf-zerotouch-19.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([I-D.ietf-anima-voucher], [I-D.ietf-netconf-keystore]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1125 has weird spacing: '...gorithm ide...' == Line 1599 has weird spacing: '...rmation pkc...' == Line 1604 has weird spacing: '...ss-type enu...' == Line 1609 has weird spacing: '...ey-data str...' == Line 1612 has weird spacing: '...ificate pkc...' == (1 more instance...) == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The device MUST next authenticate the owner certificate by performing X.509 certificate path verification to the trusted certificate extracted from the ownership voucher's 'pinned-domain-cert' node. This verification may entail using additional intermediate certificates attached to the owner certificate artifact. If the ownership voucher's 'domain-cert-revocation-checks' node's value is set to "true", the device MUST verify the revocation status of the certificate chain used to sign the owner certificate and, if the revocation status is not attainable or if it is determined that a certificate has been revoked, the device MUST not validate the owner certificate. -- The document date (October 18, 2017) is 2382 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) == Outdated reference: A later version (-07) exists of draft-ietf-anima-voucher-05 -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU.X690.1994' ** 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 (-35) exists of draft-ietf-netconf-keystore-02 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-04 -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 6536 (Obsoleted by RFC 8341) Summary: 5 errors (**), 0 flaws (~~), 11 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Juniper Networks 4 Intended status: Standards Track M. Abrahamsson 5 Expires: April 21, 2018 T-Systems 6 I. Farrer 7 Deutsche Telekom AG 8 October 18, 2017 10 Zero Touch Provisioning for NETCONF or RESTCONF based Management 11 draft-ietf-netconf-zerotouch-19 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 o "YYYY" --> the assigned RFC value for [I-D.ietf-netconf-keystore] 46 o "ZZZZ" --> the assigned RFC value for [I-D.ietf-anima-voucher] 47 Artwork in this document contains placeholder values for the date of 48 publication of this draft. Please apply the following replacement: 50 o "2017-10-19" --> the publication date of this draft 52 Please update the following references to reflect their final RFC 53 assignments: 55 o I-D.ietf-netconf-netconf-client-server 57 o I-D.ieft-anima-voucher 59 The following one Appendix section is to be removed prior to 60 publication: 62 o Appendix A. Change Log 64 Status of This Memo 66 This Internet-Draft is submitted in full conformance with the 67 provisions of BCP 78 and BCP 79. 69 Internet-Drafts are working documents of the Internet Engineering 70 Task Force (IETF). Note that other groups may also distribute 71 working documents as Internet-Drafts. The list of current Internet- 72 Drafts is at https://datatracker.ietf.org/drafts/current/. 74 Internet-Drafts are draft documents valid for a maximum of six months 75 and may be updated, replaced, or obsoleted by other documents at any 76 time. It is inappropriate to use Internet-Drafts as reference 77 material or to cite them other than as "work in progress." 79 This Internet-Draft will expire on April 21, 2018. 81 Copyright Notice 83 Copyright (c) 2017 IETF Trust and the persons identified as the 84 document authors. All rights reserved. 86 This document is subject to BCP 78 and the IETF Trust's Legal 87 Provisions Relating to IETF Documents 88 (https://trustee.ietf.org/license-info) in effect on the date of 89 publication of this document. Please review these documents 90 carefully, as they describe your rights and restrictions with respect 91 to this document. Code Components extracted from this document must 92 include Simplified BSD License text as described in Section 4.e of 93 the Trust Legal Provisions and are provided without warranty as 94 described in the Simplified BSD License. 96 Table of Contents 98 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 99 1.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 5 100 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 101 1.3. Requirements Language . . . . . . . . . . . . . . . . . . 7 102 1.4. Tree Diagram Notation . . . . . . . . . . . . . . . . . . 7 103 2. Types of Bootstrapping Information . . . . . . . . . . . . . 8 104 2.1. Redirect Information . . . . . . . . . . . . . . . . . . 8 105 2.2. Onboarding Information . . . . . . . . . . . . . . . . . 9 106 3. Artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . 10 107 3.1. Zero Touch Information . . . . . . . . . . . . . . . . . 10 108 3.2. Owner Certificate . . . . . . . . . . . . . . . . . . . . 10 109 3.3. Ownership Voucher . . . . . . . . . . . . . . . . . . . . 11 110 3.4. Artifact Groupings . . . . . . . . . . . . . . . . . . . 12 111 4. Sources of Bootstrapping Data . . . . . . . . . . . . . . . . 12 112 4.1. Removable Storage . . . . . . . . . . . . . . . . . . . . 13 113 4.2. DNS Server . . . . . . . . . . . . . . . . . . . . . . . 14 114 4.3. DHCP Server . . . . . . . . . . . . . . . . . . . . . . . 15 115 4.4. Bootstrap Server . . . . . . . . . . . . . . . . . . . . 16 116 5. Device Details . . . . . . . . . . . . . . . . . . . . . . . 17 117 5.1. Initial State . . . . . . . . . . . . . . . . . . . . . . 17 118 5.2. Boot Sequence . . . . . . . . . . . . . . . . . . . . . . 18 119 5.3. Processing a Source of Bootstrapping Data . . . . . . . . 19 120 5.4. Validating Signed Data . . . . . . . . . . . . . . . . . 21 121 5.5. Processing Redirect Information . . . . . . . . . . . . . 22 122 5.6. Processing Onboarding Information . . . . . . . . . . . . 22 123 6. The Zero Touch Information Data Model . . . . . . . . . . . . 24 124 6.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 24 125 6.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 24 126 6.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 28 127 7. The Zero Touch Bootstrap Server API . . . . . . . . . . . . . 34 128 7.1. API Overview . . . . . . . . . . . . . . . . . . . . . . 34 129 7.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 34 130 7.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 37 131 8. The Zero Touch Device Data Model . . . . . . . . . . . . . . 47 132 8.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 47 133 8.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 47 134 8.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 48 135 9. DHCP Zero Touch Options . . . . . . . . . . . . . . . . . . . 52 136 9.1. DHCPv4 Zero Touch Option . . . . . . . . . . . . . . . . 52 137 9.2. DHCPv6 Zero Touch Option . . . . . . . . . . . . . . . . 53 138 9.3. Common Field Encoding . . . . . . . . . . . . . . . . . . 55 139 10. Security Considerations . . . . . . . . . . . . . . . . . . . 55 140 10.1. Immutable storage for trust anchors . . . . . . . . . . 55 141 10.2. Clock Sensitivity . . . . . . . . . . . . . . . . . . . 56 142 10.3. Blindly authenticating a bootstrap server . . . . . . . 56 143 10.4. Entropy loss over time . . . . . . . . . . . . . . . . . 56 144 10.5. Disclosing Information to Untrusted Servers . . . . . . 56 145 10.6. Sequencing Sources of Bootstrapping Data . . . . . . . . 57 146 10.7. The "ietf-zerotouch-information" YANG Module . . . . . . 57 147 10.8. The "ietf-zerotouch-bootstrap-server" YANG Module . . . 58 148 10.9. The "ietf-zerotouch-device" YANG Module . . . . . . . . 58 149 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 59 150 11.1. The BOOTP Manufacturer Extensions and DHCP Options 151 Registry . . . . . . . . . . . . . . . . . . . . . . . . 59 152 11.2. The IETF XML Registry . . . . . . . . . . . . . . . . . 59 153 11.3. The YANG Module Names Registry . . . . . . . . . . . . . 60 154 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 60 155 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 61 156 13.1. Normative References . . . . . . . . . . . . . . . . . . 61 157 13.2. Informative References . . . . . . . . . . . . . . . . . 63 158 Appendix A. Workflow Overview . . . . . . . . . . . . . . . . . 65 159 A.1. Enrollment and Ordering Devices . . . . . . . . . . . . . 65 160 A.2. Owner Stages the Network for Bootstrap . . . . . . . . . 67 161 A.3. Device Powers On . . . . . . . . . . . . . . . . . . . . 70 162 Appendix B. Promoting a Connection from Untrusted to Trusted . . 72 163 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 73 164 C.1. ID to 00 . . . . . . . . . . . . . . . . . . . . . . . . 73 165 C.2. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 74 166 C.3. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 74 167 C.4. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 74 168 C.5. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 74 169 C.6. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 75 170 C.7. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 75 171 C.8. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 75 172 C.9. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 75 173 C.10. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 76 174 C.11. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 76 175 C.12. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 76 176 C.13. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 77 177 C.14. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 77 178 C.15. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 77 179 C.16. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 78 180 C.17. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 78 181 C.18. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 79 182 C.19. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 79 183 C.20. 18 to 19 . . . . . . . . . . . . . . . . . . . . . . . . 79 184 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 79 186 1. Introduction 188 A fundamental business requirement for any network operator is to 189 reduce costs where possible. For network operators, deploying 190 devices to many locations can be a significant cost, as sending 191 trained specialists to each site for installations is both cost 192 prohibitive and does not scale. 194 This document defines a bootstrapping strategy enabling devices to 195 securely obtain bootstrapping data with no installer action beyond 196 physical placement and connecting network and power cables. The 197 ultimate goal of this document is to enable a secure NETCONF 198 [RFC6241] or RESTCONF [RFC8040] connection to a deployment specific 199 network management system (NMS). 201 This document primarily regards physical devices, where the setting 202 of the device's initial state, described in Section 5.1, occurs 203 during the device's manufacturing process. However, the zerotouch 204 solution may be extensible to virtual machines or other such logical 205 constructs. Details for how this can be accomplished is left for 206 future work. 208 1.1. Use Cases 210 o Device connecting to a remotely administered network 212 This use-case involves scenarios, such as a remote branch 213 office or convenience store, whereby a device connects as an 214 access gateway to an ISP's network. Assuming it is not 215 possible to customize the ISP's network to provide any 216 bootstrapping support, and with no other nearby device to 217 leverage, the device has no recourse but to reach out to an 218 Internet-based bootstrap server to bootstrap from. 220 o Device connecting to a locally administered network 222 This use-case covers all other scenarios and differs only in 223 that the device may additionally leverage nearby devices, which 224 may direct it to use a local service to bootstrap from. If no 225 such information is available, or the device is unable to use 226 the information provided, it can then reach out to the network 227 just as it would for the remotely administered network use- 228 case. 230 Conceptual workflows for how zerotouch might be deployed are provided 231 in Appendix A. 233 1.2. Terminology 235 This document uses the following terms (sorted by name): 237 Artifact: The term "artifact" is used throughout to represent any of 238 the three artifacts defined in Section 3 (zero touch information, 239 ownership voucher, and owner certificate). These artifacts 240 collectively provide all the bootstrapping data a device may use. 242 Bootstrapping Data: The term "bootstrapping data" is used throughout 243 this document to refer to the collection of data that a device 244 may obtain during the bootstrapping process. Specifically, it 245 refers to the three artifacts zero touch information, owner 246 certificate, and ownership voucher, as described in Section 3. 248 Bootstrap Server: The term "bootstrap server" is used within this 249 document to mean any RESTCONF server implementing the YANG module 250 defined in Section 7.3. 252 Device: The term "device" is used throughout this document to refer 253 to the network element that needs to be bootstrapped. See 254 Section 5 for more information about devices. 256 Initial Secure Device Identifier (IDevID): The term "IDevID" is 257 defined in [Std-802.1AR-2009] as the globally unique secure 258 device identifier (DevID) installed on the device by the 259 manufacturer. This identifier is used in this document to enable 260 a bootstrap server to securely identify and authenticate the 261 device. 263 Manufacturer: The term "manufacturer" is used herein to refer to the 264 manufacturer of a device or a delegate of the manufacturer. 266 Network Management System (NMS): The acronym "NMS" is used 267 throughout this document to refer to the deployment specific 268 management system that the bootstrapping process is responsible 269 for introducing devices to. From a device's perspective, when 270 the bootstrapping process has completed, the NMS is a NETCONF or 271 RESTCONF client. 273 Onboarding Information: The term "onboarding information" is used 274 herein to refer to one of the two types of "zero touch 275 information" defined in this document, the other being "redirect 276 information". Onboarding information is formally defined by the 277 "onboarding-information" YANG-data structure in Section 6.3. 279 Owner: The term "owner" is used throughout this document to refer to 280 the person or organization that purchased or otherwise owns a 281 device. 283 Owner Certificate: The term "owner certificate" is used in this 284 document to represent an X.509 certificate that binds an owner 285 identity to a public key, which a device can use to validate a 286 signature over the zero touch information artifacts. The owner 287 certificate is one of the three bootstrapping artifacts described 288 in Section 3. 290 Ownership Voucher: The term "ownership voucher" is used in this 291 document to represent the voucher artifact defined in 292 [I-D.ietf-anima-voucher]. The ownership voucher is used to 293 assign a device to an owner. The ownership voucher is one of the 294 three bootstrapping artifacts described in Section 3. 296 Redirect Information: The term "redirect information" is used herein 297 to refer to one of the two types of "zero touch information" 298 defined in this document, the other being "onboarding 299 information". Redirect information is formally defined by the 300 "redirect-information" YANG-data structure in Section 6.3. 302 Redirect Server: The term "redirect server" is used to refer to a 303 bootstrap server that only returns redirect information. A 304 redirect server is particularly useful when hosted by a 305 manufacturer, as a well-known (e.g., Internet-based) resource to 306 redirect devices to deployment-specific bootstrap servers. 308 Signed Data: The term "signed data" is used throughout to mean 309 either redirect information or onboarding information that has 310 been signed, specifically by a private key possessed by a 311 device's owner. 313 Unsigned Data: The term "unsigned data" is used throughout to mean 314 either redirect information or onboarding information that has 315 not been signed. 317 Zero Touch Information: The term "zero touch information" is used 318 generally herein to refer either redirect information or 319 onboarding information. Zero touch information is one of the 320 three bootstrapping artifacts described in Section 3. 322 1.3. Requirements Language 324 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 325 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 326 "OPTIONAL" in this document are to be interpreted as described in BCP 327 14 [RFC2119] [RFC8174] when, and only when, they appear in all 328 capitals, as shown here. 330 1.4. Tree Diagram Notation 332 A simplified graphical representation of the data models is used in 333 this document. The meaning of the symbols in these diagrams is as 334 follows: 336 o Brackets "[" and "]" enclose list keys. 338 o Braces "{" and "}" enclose feature names, and indicate that the 339 named feature must be present for the subtree to be present. 341 o Abbreviations before data node names: "rw" (read-write) represents 342 configuration data and "ro" (read-only) represents state data. 344 o Symbols after data node names: "?" means an optional node, "!" 345 means a presence container, and "*" denotes a list and leaf-list. 347 o Parentheses enclose choice and case nodes, and case nodes are also 348 marked with a colon (":"). 350 o Ellipsis ("...") stands for contents of subtrees that are not 351 shown. 353 2. Types of Bootstrapping Information 355 This document defines two types of information that devices access 356 during the bootstrapping process. These information types are 357 described in this section. Examples are provided in Section 6.2 359 2.1. Redirect Information 361 Redirect information redirects a device to another bootstrap server. 362 Redirect information encodes a list of bootstrap servers, each 363 defined by its hostname or IP address, an optional port, and an 364 optional trust anchor certificate. 366 Redirect information is YANG modeled data formally defined by the 367 "redirect-information" container in the YANG module presented in 368 Section 6.3. This container has the tree diagram shown below. 369 Please see Section 1.4 for tree diagram notation. 371 +--:(redirect-information) 372 +--ro redirect-information 373 +--ro bootstrap-server* [address] 374 +--ro address inet:host 375 +--ro port? inet:port-number 376 +--ro trust-anchor? binary 378 Redirect information MAY be trusted or untrusted. The redirect 379 information is trusted whenever it is obtained via a secure 380 connection to a trusted bootstrap server, or whenever it is signed by 381 the device's owner. In all other cases, the redirect information is 382 untrusted. 384 Trusted redirect information is useful for enabling a device to 385 establish a secure connection to a bootstrap server, which is 386 possible when the redirect information includes the bootstrap 387 server's trust anchor certificate. When a device is able to 388 establish a secure connection to a bootstrap server, any data 389 obtained is implicitly trusted, and thus does not need to be signed. 391 Untrusted redirect information is useful for directing a device to a 392 bootstrap server where signed data has been staged for it to obtain. 393 When the redirect information is untrusted, the device MUST discard 394 any potentially included trust anchor certificates and SHOULD 395 establish a provisional connection (by blindly accepting the TLS 396 certificate) to any of the specified bootstrap servers. In this 397 case, the device MUST NOT trust the bootstrap server, and data 398 provided by the bootstrap server MUST be signed for it to be of any 399 use to the device. 401 How devices process redirect information is formally described in 402 Section 5.5. 404 2.2. Onboarding Information 406 Onboarding information provides all the data necessary for a device 407 to bootstrap itself, in order to be considered ready to be managed 408 (e.g., by an NMS). As defined in this document, this data includes 409 information about a boot image the device must be running, an initial 410 configuration the device must commit, and optional scripts that, if 411 specified, the device must successfully execute. 413 Onboarding information is YANG modeled data formally defined by the 414 "onboarding-information" container in the YANG module presented in 415 Section 6.3. This container has the tree diagram shown below. 416 Please see Section 1.4 for tree diagram notation. 418 +--:(onboarding-information) 419 +--ro onboarding-information 420 +--ro boot-image 421 | +--ro name string 422 | +--ro (hash-algorithm) 423 | | +--:(sha256) 424 | | +--ro sha256? string 425 | +--ro uri* inet:uri 426 +--ro configuration-handling enumeration 427 +--ro pre-configuration-script? script 428 +--ro configuration? 429 +--ro post-configuration-script? script 431 Onboarding information MUST be trusted for it to be of any use to a 432 device. There is no option for a device to process untrusted 433 onboarding information. 435 Onboarding information is trusted whenever it is obtained via a 436 secure connection to a trusted bootstrap server, or whenever it is 437 signed by the device's owner. In all other cases, the onboarding 438 information is untrusted. 440 How devices process onboarding information is formally described in 441 Section 5.6. 443 3. Artifacts 445 This document defines three artifacts that can be made available to 446 devices while they are bootstrapping. Each source of bootstrapping 447 information specifies a means for providing each of the artifacts 448 defined in this section (see Section 4). 450 3.1. Zero Touch Information 452 The zero touch information artifact encodes the essential 453 bootstrapping data for the device. This artifact is used to encode 454 the redirect information and onboarding information types discussed 455 in Section 2. 457 The zero touch information artifact is a PKCS#7 SignedData structure, 458 as specified by Section 9.1 of [RFC2315], encoded using ASN.1 459 distinguished encoding rules (DER), as specified in ITU-T X.690 460 [ITU.X690.1994]. The PKCS#7 structure MUST contain JSON-encoded 461 content conforming to the YANG module specified in Section 6.3. 463 In order for the zero touch information artifact to be trusted when 464 conveyed over an untrusted transport, the PKCS#7 structure MUST also 465 contain a "signerInfo" structure, as described in Section 9.1 of 466 [RFC2315], containing a signature generated over the content using 467 the private key associated with the owner certificate (Section 3.2). 468 In order to simplify the verification process, the PKCS#7 structure 469 SHOULD also contain the signing X.509 certificate (i.e. the owner 470 certificate). 472 3.2. Owner Certificate 474 The owner certificate artifact is an X.509 certificate [RFC5280] that 475 is used to identify an "owner" (e.g., an organization). The owner 476 certificate can be signed by any certificate authority (CA). The 477 owner certificate MUST either have no Key Usage specified, or the Key 478 Usage MUST at least set the "digitalSignature" bit. The values for 479 the owner certificate's "subject" and/or "subjectAltName" are not 480 constrained by this document. 482 The owner certificate is used by a device to verify the signature 483 over the zero touch information artifact (Section 3.1) that the 484 device should have also received, as described in Section 3.4. In 485 particular, the device verifies the signature using the public key in 486 the owner certificate over the content contained within the zero 487 touch information artifact. 489 The owner certificate artifact is formally an unsigned PKCS #7 490 SignedData structure, as specified by Section 9.1 in [RFC2315], 491 encoded using ASN.1 distinguished encoding rules (DER), as specified 492 in ITU-T X.690 [ITU.X690.1994]. 494 The owner certificate PKCS#7 structure MUST contain the owner 495 certificate itself, as well as all intermediate certificates leading 496 up to the 'pinned-domain-cert' certificate specified in the ownership 497 voucher. The owner certificate artifact MAY optionally include the 498 'pinned-domain-cert' as well. 500 Additionally, in order to support devices deployed on private 501 networks, the owner certificate PKCS#7 structure MAY also contain 502 suitably fresh CRLs [RFC5280] and/or OCSP Responses [RFC6960]. 503 Having these revocation objects stapled to the owner certificate 504 precludes the need for the device to have to download them 505 dynamically using the CRL distribution point or an OCSP responder 506 specified in the associated certificates. 508 3.3. Ownership Voucher 510 The ownership voucher artifact is used to securely identify a 511 device's owner, as it is known to the manufacturer. The ownership 512 voucher is signed by the device's manufacturer. 514 The ownership voucher is used to verify the owner certificate 515 (Section 3.2) that the device should have also received, as described 516 in Section 3.4. In particular, the device verifies that the owner 517 certificate has a chain of trust leading to the trusted certificate 518 included in the ownership voucher ('pinned-domain-cert'), even if it 519 is itself (e.g., self-signed certificate). 521 The ownership voucher artifact, including its encoding, is formally 522 defined in [I-D.ietf-anima-voucher]. 524 3.4. Artifact Groupings 526 This section lists all the possible bootstrapping artifacts, but only 527 certain groupings of these artifacts make sense to return in the 528 various bootstrapping situations described in this document. These 529 groupings are: 531 Unsigned Information: This grouping is useful for cases when 532 transport level security can be used to convey trust (e.g., 533 HTTPS), or when the information can be processed in a 534 provisional manner (i.e. unsigned redirect information). 536 Signed Information, without revocations: The grouping is useful 537 when signed information is needed, because it's obtained from 538 an untrusted source, and it cannot be processed provisionally, 539 and yet either revocations are not needed or they can be 540 obtained dynamically. 542 Signed Information, with revocations: The grouping is useful when 543 signed information is needed, because it's obtained from an 544 untrusted source, and it cannot be processed provisionally, and 545 revocations are needed and cannot be obtained dynamically. 547 The artifacts associated with these groupings are described below: 549 Zero Touch Ownership Owner 550 Grouping Information Voucher Certificate 551 -------------------- ------------- ------------ ----------- 552 Unsigned Information Yes, no sig No No 554 Signed Information, Yes, with sig Yes, without Yes, without 555 without revocations revocations revocations 557 Signed Information, Yes, with sig Yes, with Yes, with 558 with revocations revocations revocations 560 4. Sources of Bootstrapping Data 562 This section defines some sources for bootstrapping data that a 563 device can access. The list of sources defined here is not meant to 564 be exhaustive. It is left to future documents to define additional 565 sources for obtaining bootstrapping data. 567 For each source of bootstrapping data defined in this section, 568 details are given for how the three artifacts listed in Section 3 are 569 provided. 571 4.1. Removable Storage 573 A directly attached removable storage device (e.g., a USB flash 574 drive) MAY be used as a source of zero touch bootstrapping data. 576 Use of a removable storage device is compelling, as it doesn't 577 require any external infrastructure to work. It is notable that the 578 raw boot image file can also be located on the removable storage 579 device, enabling a removable storage device to be a fully self- 580 standing bootstrapping solution. 582 To use a removable storage device as a source of bootstrapping data, 583 a device need only detect if the removable storage device is plugged 584 in and mount its filesystem. 586 A removable storage device is an untrusted source of bootstrapping 587 data. This means that the information stored on the removable 588 storage device MUST either be signed, or be information that can be 589 processed provisionally (e.g., unsigned redirect information). 591 From an artifact perspective, since a removable storage device 592 presents itself as a filesystem, the bootstrapping artifacts need to 593 be presented as files. The three artifacts defined in Section 3 are 594 mapped to files below. 596 Artifact to File Mapping: 598 Zero Touch Information: Mapped to a file containing the binary 599 artifact described in Section 3.1 (e.g., zerotouch- 600 information.pk7). 602 Owner Certificate: Mapped to a file containing the binary 603 artifact described in Section 3.2 (e.g., owner- 604 certificate.pk7). 606 Ownership Voucher: Mapped to a file containing the binary 607 artifact described in Section 3.3 (e.g., ownership- 608 voucher.pk7). 610 The format of the removable storage device's filesystem and the 611 naming of the files are outside the scope of this document. However, 612 in order to facilitate interoperability, it is RECOMMENDED devices 613 support open and/or standards based filesystems. It is also 614 RECOMMENDED that devices assume a file naming convention that enables 615 more than one instance of bootstrapping data to exist on a removable 616 storage device. The file naming convention SHOULD be unique to the 617 manufacturer, in order to enable bootstrapping data from multiple 618 manufacturers to exist on a removable storage device. 620 4.2. DNS Server 622 A DNS server MAY be used as a source of zero touch bootstrapping 623 data. 625 Using a DNS server may be a compelling option for deployments having 626 existing DNS infrastructure, as it enables a touchless bootstrapping 627 option that does not entail utilizing an Internet based resource 628 hosted by a 3rd-party. 630 To use a DNS server as a source of bootstrapping data, a device MAY 631 perform a multicast DNS [RFC6762] query searching for the service 632 "_zerotouch._tcp.local.". Alternatively the device MAY perform DNS- 633 SD [RFC6763] via normal DNS operation, using the domain returned to 634 it from the DHCP server; for example, searching for the service 635 "_zerotouch._tcp.example.com". 637 Unsigned DNS records (e.g., not using DNSSEC as described in 638 [RFC6698]) are an untrusted source of bootstrapping data. This means 639 that the information stored in the DNS records either MUST be signed, 640 or MUST be information that can be processed provisionally (e.g., 641 unsigned redirect information). 643 From an artifact perspective, since a DNS server presents resource 644 records (Section 3.2.1 of [RFC1035]), the bootstrapping artifacts 645 need to be presented as resource records. The three artifacts 646 defined in Section 3 are mapped to resource records below. 648 Artifact to Resource Record Mapping: 650 Zero Touch Information: Mapped to a TXT record called "zt-info" 651 containing the base64-encoding of the binary artifact described 652 in Section 3.1. 654 Owner Certificate: Mapped to a TXT record called "zt-cert" 655 containing the base64-encoding of the binary artifact described 656 in Section 3.2. 658 Ownership Voucher: Mapped to a TXT record called "zt-voucher" 659 containing the base64-encoding of the binary artifact described 660 in Section 3.3. 662 TXT records have an upper size limit of 65535 bytes (Section 3.2.1 in 663 RFC1035), since "RDLENGTH" is a 16-bit field. Please see 664 Section 3.1.3 in RFC4408 for how a TXT record can achieve this size. 665 Due to this size limitation, some zero touch information artifacts 666 may not fit. In particular, onboarding information could hit this 667 upper bound, depending on the size of the included configuration and 668 scripts. 670 When onboarding information (not redirect information) is provided, 671 the URL for the boot-image the device can download would have to 672 point to another server (e.g., http://, ftp://, etc.), as DNS servers 673 do not themselves distribute files. 675 4.3. DHCP Server 677 A DHCP server MAY be used as a source of zero touch bootstrapping 678 data. 680 Using a DHCP server may be a compelling option for deployments having 681 existing DHCP infrastructure, as it enables a touchless bootstrapping 682 option that does not entail utilizing an Internet based resource 683 hosted by a 3rd-party. 685 A DHCP server is an untrusted source of bootstrapping data. Thus the 686 information stored on the DHCP server either MUST be signed, or it 687 MUST be information that can be processed provisionally (e.g., 688 unsigned redirect information). 690 However, unlike other sources of bootstrapping data described in this 691 document, the DHCP protocol (especially DHCP for IPv4) is limited in 692 the amount of data that can be conveyed, to the extent that signed 693 data cannot be communicated. Thus only unsigned redirect information 694 can be conveyed. 696 Since the redirect information is unsigned, it SHOULD NOT include the 697 optional trust anchor certificate, as the device would have to 698 discard it anyway. The DHCP options defined in Section 9 do not 699 enable the certificate to be communicated. 701 From an artifact perspective, the three artifacts defined in 702 Section 3 are mapped to the DHCP fields specified in Section 9 as 703 follows: 705 Zero Touch Information: This artifact is not supported directly. 706 Instead, the essence of redirect information (not onboarding 707 information) is mapped to the DHCP fields described in 708 Section 9. 710 Owner Certificate: Not supported. There is not enough space in 711 the DHCP packet to hold an owner certificate artifact. 713 Ownership Voucher: Not supported. There is not enough space in 714 the DHCP packet to hold an ownership voucher artifact. 716 4.4. Bootstrap Server 718 A bootstrap server MAY be used as a source of zero touch 719 bootstrapping data. A bootstrap server is defined as a RESTCONF 720 [RFC8040] server implementing the YANG module provided in Section 7. 722 Using a bootstrap server as a source of bootstrapping data is a 723 compelling option as it MAY use transport-level security, in lieu of 724 signed data, which may be easier to deploy in some situations. 725 Additionally, the bootstrap server is able to receive progress 726 updates from devices, which may be critical to some deployments 727 (e.g., the passing of the device's SSH host keys). 729 A bootstrap server may be a trusted or an untrusted source of 730 bootstrapping data, depending on if the device learned about the 731 bootstrap server's trust anchor from a trusted source. When a 732 bootstrap server is trusted, the information returned from it MAY be 733 signed. However, when the server is untrusted, in order for its 734 information to be of any use to the device, the bootstrap information 735 MUST either be signed or be information that can be processed 736 provisionally (e.g., unsigned redirect information). 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 the YANG module. The three artifacts defined in Section 3 are 741 mapped to 'output' node of the 'get-bootstrapping-data' RPC defined 742 in Section 7.3 below. 744 Artifact to Bootstrap Server Mapping: 746 Zero Touch Information: Mapped to the 'zerotouch-information' 747 leaf in the output of the 'get-bootstrapping-data' RPC. 749 Owner Certificate: Mapped to the 'owner-certificate' leaf in the 750 output of the 'get-bootstrapping-data' RPC. 752 Ownership Voucher: Mapped to the 'ownership-voucher' leaf in the 753 output of the 'get-bootstrapping-data' RPC. 755 Unlike any other source of bootstrapping data described in this 756 document, a bootstrap server is not only a source of data, but it can 757 also receive data from devices using the YANG-defined 'report- 758 progress' RPC defined in the YANG module (Section 7.3). The 'report- 759 progress' RPC enables visibility into the bootstrapping process 760 (e.g., warnings and errors), and provides potentially useful 761 completion status information (e.g., the device's SSH host-keys). 763 While RESTCONF servers typically support a nested hierarchy of 764 resources, zero touch bootstrap servers only have the two RPCs 'get- 765 bootstrapping-data' and 'report-progress'. These RPCs use the 766 authenticated RESTCONF username to isolate the execution of the RPC 767 from other devices. 769 5. Device Details 771 Devices supporting the bootstrapping strategy described in this 772 document MUST have the preconfigured state and bootstrapping logic 773 described in the following sections. 775 5.1. Initial State 777 +-------------------------------------------------------------+ 778 | | 779 | | 780 | +---------------------------------------------------------+ | 781 | | | | 782 | | | | 783 | | 1. flag to enable zerotouch bootstrapping set to "true" | | 784 | +---------------------------------------------------------+ | 785 | | 786 | +---------------------------------------------------------+ | 787 | | | | 788 | | | | 789 | | 2. IDevID cert & associated intermediate certificate(s) | | 790 | | 3. list of trusted well-known bootstrap servers | | 791 | | 4. list of trust anchor certs for bootstrap servers | | 792 | | 5. trust anchor cert for verifying ownership vouchers | | 793 | +---------------------------------------------------------+ | 794 | | 795 | +----------------------+ | 796 | | | | 797 | | | | 798 | | 6. private key | | 799 | +----------------------+ | 800 | | 801 +-------------------------------------------------------------+ 803 Each numbered item below corresponds to a numbered item in the 804 diagram above. 806 1. Devices MUST have a configurable variable that is used to enable/ 807 disable the zerotouch bootstrapping. This variable MUST be 808 enabled by default in order for zerotouch bootstrapping to run 809 when the device first powers on. Because it is a goal that the 810 configuration installed by the bootstrapping process is able to 811 disable zerotouch bootstrapping, and because said configuration 812 may be merged into the existing configuration, using a 813 configuration node that relies on presence is NOT RECOMMENDED, as 814 it cannot be removed by the merging process. 816 2. Devices that support loading bootstrapping data from bootstrap 817 servers (see Section 4.4), whether preconfigured or learned 818 through the bootstrapping process, MUST possess an initial device 819 identifier (IDevID), as defined in [Std-802.1AR-2009]. The 820 IDevID is an X.509 certificate encoding, amongst other things, 821 the device's serial number and hardware manufacturer. The device 822 MUST also possess any intermediate certificates between the 823 IDevID certificate and the manufacturer's IDevID trust anchor 824 certificate provided to prospective owners separately (e.g., 825 Appendix A.1). 827 3. Devices that support loading bootstrapping data from well-known 828 bootstrap servers MUST possess a list of the well-known bootstrap 829 servers. Consistent with redirect information (Section 2.1, each 830 bootstrap server MAY be identified by its hostname or IP address, 831 and an optional port. 833 4. Devices that support loading bootstrapping data from well-known 834 bootstrap servers MUST also possess a list of trust anchor 835 certificates that can be used to secure the TLS connection to the 836 well-known bootstrap servers. 838 5. Devices that support loading signed data (see Section 1.2) MUST 839 possess the manufacturer's trust anchor certificate for 840 validating ownership vouchers. 842 6. Devices MUST possess a private key that corresponds to the public 843 key encoded in the device's IDevID certificate. This private key 844 SHOULD be securely stored, ideally in a cryptographic processor 845 (e.g., a TPM). 847 A YANG module representing this data is provided in Section 8. 849 5.2. Boot Sequence 851 A device claiming to support the bootstrapping strategy defined in 852 this document MUST support the boot sequence described in this 853 section. 855 Power On 856 | 857 v No 858 1. Zerotouch bootstrapping configured ------> Boot normally 859 | 860 | Yes 861 v 862 2. For each supported source of bootstrapping data, 863 try to load bootstrapping data from the source 864 | 865 | 866 v Yes 867 3. Able to bootstrap from any source? -----> Run with new config 868 | 869 | No 870 v 871 4. Loop and/or wait for manual provisioning. 873 Each numbered item below corresponds to a numbered item in the 874 diagram above. 876 1. When the device powers on, it first checks to see if zerotouch 877 bootstrapping is configured, as is expected to be the case for 878 the device's preconfigured state. If zerotouch bootstrapping is 879 not configured, then the device boots normally. 881 2. The device iterates over its list of sources for bootstrapping 882 data (Section 4). Details for how to processes a source of 883 bootstrapping data are provided in Section 5.3. 885 3. If the device is able to bootstrap itself from any of the sources 886 of bootstrapping data, it runs with the new bootstrapped 887 configuration. 889 4. Otherwise the device MAY loop back through the list of 890 bootstrapping sources again and/or wait for manual provisioning. 892 5.3. Processing a Source of Bootstrapping Data 894 This section describes a recursive algorithm that devices can use to, 895 ultimately, obtain onboarding information. The algorithm is 896 recursive because sources of bootstrapping data may return redirect 897 information, which causes the algorithm to run again, for the newly 898 discovered sources of bootstrapping information. An expression that 899 captures all possible successful sequences of bootstrapping 900 information is zero or more redirect information responses, followed 901 by one onboarding information response. 903 An important aspect of the algorithm is knowing when data needs to be 904 signed or not. The following figure provides a summary of options: 906 Untrusted Source Trusted Source 907 Kind of Bootstrapping Data Can Provide? Can Provide? 909 Unsigned Redirect Info : Yes+ Yes 910 Signed Redirect Info : Yes Yes* 911 Unsigned Onboarding Info : No Yes 912 Signed Onboarding Info : Yes Yes* 914 The '+' above denotes that the source redirected to MUST 915 return signed data, or more unsigned redirect information. 917 The '*' above denotes that, while possible, it is generally 918 unnecessary for a trusted source to return signed data. 920 The recursive algorithm uses a conceptual global-scoped variable 921 called "trust-state". The trust-state variable is initialized to 922 FALSE. The ultimate goal of this algorithm is for the device to 923 process onboarding information (Section 2.2) while the trust-state 924 variable is TRUE. 926 If the source of bootstrapping data (Section 4) is a bootstrap server 927 (Section 4.4), and the device is able to authenticate the bootstrap 928 server using X.509 certificate path validation ([RFC6125], Section 6) 929 to one of the device's preconfigured trust anchors, or to a trust 930 anchor that it learned from a previous step, then the device MUST set 931 trust-state to TRUE. 933 For any source of bootstrapping data (e.g., Section 4), if the 934 bootstrapping data returned is signed and the device is able to 935 validate the signed data using the algorithm described in 936 Section 5.4, then the device MUST set trust-state to TRUE, else the 937 device MUST set trust-state to FALSE. Note, this is worded to cover 938 the special case when signed data is returned even from a trusted 939 bootstrap server. 941 If the bootstrapping data is onboarding information, and trust-state 942 is FALSE, the device MUST exit the recursive algorithm (as this is 943 not allowed, see the figure above), returning to the state machine 944 described in Section 5.2. Otherwise, the device MUST attempt to 945 process the onboarding information as described in Section 5.6. In 946 either case, success or failure, the device MUST exit the recursive 947 algorithm, returning to the state machine described in Section 5.2, 948 the only difference being in how it responds to the "Able to 949 bootstrap from any source?" conditional described in the figure in 950 the section. 952 If the bootstrapping data is redirect information, the device MUST 953 process the redirect information as described in Section 5.5. This 954 is the recursion step, it will cause the device to reenter this 955 algorithm, but this time the data source will definitely be a 956 bootstrap server, as that is all redirect information is able to 957 redirect a device to. 959 5.4. Validating Signed Data 961 Whenever a device is presented signed data, it MUST validate the 962 signed data as described in this section. This includes the case 963 where the signed data is provided by a trusted source. 965 Whenever there is signed data, the device MUST also be provided an 966 ownership voucher and an owner certificate. How all the needed 967 artifacts are provided for each source of bootstrapping data is 968 defined in Section 4. 970 The device MUST first authenticate the ownership voucher by 971 validating its signature to one of its preconfigured trust anchors 972 (see Section 5.1), which may entail using additional intermediate 973 certificates attached to the ownership voucher. If the device has an 974 accurate clock, it MUST ensure that the ownership voucher was created 975 in the past (i.e., 'created-on' < now). If the 'expires-on' leaf is 976 present, the device MUST verify that the ownership voucher has not 977 yet expired (i.e., now < 'expires-on'), which requires an accurate 978 clock. The device MUST verify that the ownership voucher's 979 'assertion' value is acceptable (e.g., some devices may only accept 980 the assertion value 'verified'). The device MUST verify that the 981 ownership voucher specifies the device's serial number in the 982 'serial-number' leaf. If the 'idevid-issuer' leaf is present, the 983 device MUST verify that the value is set correctly. If the 984 authentication of the ownership voucher is successful, the device 985 extracts the 'pinned-domain-certificate' node, an X.509 certificate, 986 that is needed to verify the owner certificate in the next step. 988 The device MUST next authenticate the owner certificate by performing 989 X.509 certificate path verification to the trusted certificate 990 extracted from the ownership voucher's 'pinned-domain-cert' node. 991 This verification may entail using additional intermediate 992 certificates attached to the owner certificate artifact. If the 993 ownership voucher's 'domain-cert-revocation-checks' node's value is 994 set to "true", the device MUST verify the revocation status of the 995 certificate chain used to sign the owner certificate and, if the 996 revocation status is not attainable or if it is determined that a 997 certificate has been revoked, the device MUST not validate the owner 998 certificate. 1000 Finally the device MUST verify the signature over the information 1001 artifact was generated by the private key matching the public key 1002 from the owner certificate. 1004 If any of these steps fail, then the device MUST invalidate the data 1005 and not perform any subsequent steps. 1007 5.5. Processing Redirect Information 1009 In order to process redirect information (Section 2.1), the device 1010 MUST follow the steps presented in this section. 1012 Processing redirect information is straightforward. The device 1013 sequentially steps through the list of provided bootstrap servers 1014 until it can find one it can bootstrap from. 1016 If a hostname is provided, and the hostname's DNS resolution is to 1017 more than one IP address, the device MUST attempt to connect to all 1018 of the DNS resolved addresses at least once, before moving on to the 1019 next bootstrap server. If the device is able to obtain bootstrapping 1020 data from any of the DNS resolved addresses, it MUST immediately 1021 process that data, without attempting to connect to any of the other 1022 DNS resolved addresses. 1024 If the redirect information is trusted (e.g., trust-state is TRUE), 1025 and the bootstrap server entry contains a trust anchor certificate, 1026 then the device MUST authenticate the specified bootstrap server 1027 RESTCONF TLS server certificate using X.509 certificate path 1028 validation ([RFC6125], Section 6) to the specified trust anchor. If 1029 the device is unable to authenticate the bootstrap server to the 1030 specified trust anchor, the device MAY attempt a provisional 1031 connection to the bootstrap server (i.e., by blindly accepting its 1032 server certificate) and setting trust-state to FALSE. 1034 If the redirect information is untrusted (e.g., trust-state is 1035 FALSE), the device MUST discard any trust anchors provided by the 1036 redirect information and establish a provisional connection to the 1037 bootstrap server (i.e., by blindly accepting its TLS server 1038 certificate). 1040 5.6. Processing Onboarding Information 1042 In order to process onboarding information (Section 2.2), the device 1043 MUST follow the steps presented in this section. 1045 When processing onboarding information, the device MUST first process 1046 the boot image information, then execute the pre-configuration script 1047 (if any), then commit the initial configuration, and then execute the 1048 post-configuration script (if any), in that order. If the device 1049 encounters an error at any step, it MUST NOT proceed to the next 1050 step. When the onboarding information was obtained from a trusted 1051 bootstrap server, the device SHOULD send progress reports throughout 1052 the bootstrapping process using the bootstrap server's 'report- 1053 progress' RPC. 1055 First the device MUST determine if the image it is running satisfies 1056 the specified boot image criteria (e.g., name and/or fingerprint 1057 match). If it does not, the device MUST download (using the supplied 1058 URI), verify, and install the specified boot image, and then reboot. 1059 To verify the downloaded boot image, the device MUST check that the 1060 boot image file matches the fingerprint (e.g., sha256) supplied by 1061 the onboarding information. Upon rebooting, the bootstrapping 1062 process runs again, which will eventually come to this very point, 1063 but this time the device's running image will satisfy the specified 1064 criteria, and thus the device will move to processing the next step. 1066 Next, for devices that support executing scripts, if a pre- 1067 configuration script has been specified, the device MUST execute the 1068 script and check its exit status code to determine if had any 1069 warnings or errors. In the case of errors, the device MUST reset 1070 itself in such a way that wipes out any bad state the script may have 1071 left behind. 1073 Next the device commits the provided initial configuration. Assuming 1074 no errors, the device moves to processing the next step. 1076 Again, for devices that support executing scripts, if a post- 1077 configuration script has been specified, the device MUST execute the 1078 script and check its exit status code to determine if it had any 1079 warnings or errors. In the case of errors, the device MUST reset 1080 itself in such a way that wipes out any bad state the script may have 1081 left behind. 1083 At this point, the device has completely processed the bootstrapping 1084 data and is ready to be managed. If the device obtained the 1085 onboarding information from a trusted bootstrap server, the device 1086 MUST post the 'bootstrap-complete' progress report now, using the 1087 bootstrap server's 'report-progress' RPC. 1089 At this point, the device is running its initial configuration. 1090 Notably, if NETCONF Call Home or RESTCONF Call Home [RFC8071] is 1091 configured, the device initiates trying to establish a call home 1092 connection at this time. 1094 6. The Zero Touch Information Data Model 1096 This section defines a YANG 1.1 [RFC7950] module that is used to 1097 define the data model for the zero touch information artifact 1098 described in Section 3.1. This data model uses the 'yang-data' 1099 extension statement defined in RFC 8040. Examples illustrating this 1100 data model are provided in Section 6.2. 1102 6.1. Data Model Overview 1104 The following tree diagram provides an overview of the data model for 1105 the zero touch information artifact. The syntax used for this tree 1106 diagram is described in Section 1.4. 1108 module: ietf-zerotouch-information 1110 yang-data zerotouch-information: 1111 +---- (information-type) 1112 +--:(redirect-information) 1113 | +---- redirect-information 1114 | +---- bootstrap-server* [address] 1115 | +---- address inet:host 1116 | +---- port? inet:port-number 1117 | +---- trust-anchor? binary 1118 +--:(onboarding-information) 1119 +---- onboarding-information 1120 +---- boot-image 1121 | +---- os-name string 1122 | +---- os-version string 1123 | +---- download-uri* inet:uri 1124 | +---- image-verification* [hash-algorithm] 1125 | +---- hash-algorithm identityref 1126 | +---- hash-value? yang:hex-string 1127 +---- configuration-handling? enumeration 1128 +---- pre-configuration-script? script 1129 +---- configuration? 1130 +---- post-configuration-script? script 1132 6.2. Example Usage 1134 The following example illustrates how redirect information 1135 (Section 2.1) can be encoded using JSON, as is needed by the zero 1136 touch information artifact. 1138 { 1139 "ietf-zerotouch-information:redirect-information" : { 1140 "bootstrap-server" : [ 1141 { 1142 "address" : "phs1.example.com", 1143 "port" : 8443, 1144 "trust-anchor" : "base64encodedvalue==" 1145 }, 1146 { 1147 "address" : "phs2.example.com", 1148 "port" : 8443, 1149 "trust-anchor" : "base64encodedvalue==" 1150 }, 1151 { 1152 "address" : "phs3.example.com", 1153 "port" : 8443, 1154 "trust-anchor" : "base64encodedvalue==" 1155 } 1156 ] 1157 } 1158 } 1160 The following example illustrates how onboarding information 1161 (Section 2.2) can be encoded using JSON, as is needed by the zero 1162 touch information artifact. 1164 Note: the sample configuration used in the below example configures 1165 an administrator account with an SSH public key, configures keystore 1166 with an authentication certificate, configures NETCONF Call Home and, 1167 lastly, disables the zerotouch bootstrapping service. This is 1168 acheived through use of YANG modules "ietf-system" from [RFC7317], 1169 "ietf-keystore" from [I-D.ietf-netconf-keystore], "ietf-netconf- 1170 server" from [I-D.ietf-netconf-netconf-client-server] and "ietf- 1171 zerotouch-device" from this document. 1173 [ note: '\' line wrapping for formatting only] 1175 { 1176 "ietf-zerotouch-information:onboarding-information" : { 1178 "boot-image" : { 1179 "os-name" : "VendorOS", 1180 "os-version" : "17.2R1.6", 1181 "download-uri" : [ "http://some/path/to/raw/file" ], 1182 "image-verification" : [ 1183 { 1184 "hash-algorithm" : "ietf-zerotouch-information:sha-256", 1185 "hash-value" : "ba:ec:cf:a5:67:82:b4:10:77:c6:67:a6:22:ab:\ 1187 7d:50:04:a7:8b:8f:0e:db:02:8b:f4:75:55:fb:c1:13:b2:33" 1188 } 1189 ] 1190 }, 1192 "configuration-handling" : "merge", 1194 "configuration" : { 1195 "ietf-system:system" : { 1196 "authentication" : { 1197 "user" : { 1198 "name" : "admin", 1199 "authorized-key" : { 1200 "name" : "admin's rsa ssh host-key", 1201 "algorithm" : "ssh-rsa", 1202 "key-data" : "base64encodedvalue==" 1203 } 1204 } 1205 } 1206 }, 1207 "ietf-keystore:keystore" : { 1208 "pinned-certificates" : { 1209 "name" : "deployment-specific-ca-certs", 1210 "description" : "Certs used to auth client connections.", 1211 "pinned-certificate" : { 1212 "name" : "ca.example.com", 1213 "data" : "base64encodedvalue==" 1214 } 1215 }, 1216 "pinned-certificates" : { 1217 "name" : "explicitly-trusted-client-certs", 1218 "description" : "Certs for explicitly-trusted clients.", 1219 "pinned-certificate" : { 1220 "name" : "Fred Flintstone", 1221 "data" : "base64encodedvalue==" 1222 } 1223 } 1224 }, 1225 "ietf-netconf-server:netconf-server" : { 1226 "call-home" : { 1227 "netconf-client" : { 1228 "name" : "config-mgr", 1229 "endpoints" : { 1230 "endpoint" : { 1231 "name" : "east-data-center", 1232 "ssh" : { 1233 "address" : "east.config-mgr.example.com", 1234 "host-keys" : { 1235 "host-key" : { 1236 "name" : "certificate", 1237 "certificate" : "builtin-idevid-cert" 1238 } 1239 }, 1240 "client-cert-auth" : { 1241 "trusted-ca-certs" : 1242 "deployment-specific-ca-certs", 1243 "trusted-client-certs" : 1244 "explicitly-trusted-client-certs" 1245 } 1246 } 1247 }, 1248 "endpoint" : { 1249 "name" : "west-data-center", 1250 "ssh" : { 1251 "address" : "west.config-mgr.example.com", 1252 "host-keys" : { 1253 "host-key" : { 1254 "name" : "certificate", 1255 "certificate" : "builtin-idevid-cert" 1256 } 1257 }, 1258 "client-cert-auth" : { 1259 "trusted-ca-certs" : 1260 "deployment-specific-ca-certs", 1261 "trusted-client-certs" : 1262 "explicitly-trusted-client-certs" 1263 } 1264 } 1265 } 1266 }, 1267 "connection-type" : { 1268 "periodic" : { 1269 "idle-timeout" : 300, 1270 "reconnect-timeout" : 60 1271 } 1272 }, 1273 "reconnect-strategy" : { 1274 "start-with" : "last-connected", 1275 "max-attempts" : 3 1276 } 1277 } 1278 } 1279 }, 1280 "ietf-device:zerotouch" : { 1281 "enabled" : false 1282 } 1284 } 1285 } 1286 } 1288 6.3. YANG Module 1290 The zero touch information data model is defined by the YANG module 1291 presented in this section. 1293 Note: the module defined herein uses data types defined in [RFC5280], 1294 [RFC6234], and [RFC6991], and an extension statement from [RFC8040], 1295 and an encoding defined in [ITU.X690.1994]. 1297 file "ietf-zerotouch-information@2017-10-19.yang" 1298 module ietf-zerotouch-information { 1299 yang-version 1.1; 1300 namespace "urn:ietf:params:xml:ns:yang:ietf-zerotouch-information"; 1301 prefix zti; 1303 import ietf-yang-types { 1304 prefix yang; 1305 reference "RFC 6991: Common YANG Data Types"; 1306 } 1307 import ietf-inet-types { 1308 prefix inet; 1309 reference "RFC 6991: Common YANG Data Types"; 1310 } 1311 import ietf-restconf { 1312 prefix rc; 1313 description 1314 "This import statement is only present to access 1315 the yang-data extension defined in RFC 8040."; 1316 reference "RFC 8040: RESTCONF Protocol"; 1317 } 1319 organization 1320 "IETF NETCONF (Network Configuration) Working Group"; 1322 contact 1323 "WG Web: http://tools.ietf.org/wg/netconf 1324 WG List: 1325 Author: Kent Watsen "; 1327 description 1328 "This module defines the data model for the Zero Touch Information 1329 artifact defined by RFC XXXX: Zero Touch Provisioning for NETCONF 1330 or RESTCONF based Management. 1332 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1333 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', 1334 and 'OPTIONAL' in the module text are to be interpreted as 1335 described in RFC 2119. 1337 Copyright (c) 2017 IETF Trust and the persons identified as 1338 authors of the code. All rights reserved. 1340 Redistribution and use in source and binary forms, with or 1341 without modification, is permitted pursuant to, and subject 1342 to the license terms contained in, the Simplified BSD License 1343 set forth in Section 4.c of the IETF Trust's Legal Provisions 1344 Relating to IETF Documents (http://trustee.ietf.org/license-info) 1346 This version of this YANG module is part of RFC XXXX; see the 1347 RFC itself for full legal notices."; 1349 revision 2017-10-19 { 1350 description 1351 "Initial version"; 1352 reference 1353 "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF based 1354 Management"; 1355 } 1357 identity hash-algorithm { 1358 description 1359 "A base identity for hash algorith verification"; 1360 } 1362 identity sha-256 { 1363 base "hash-algorithm"; 1364 description "The SHA-256 algorithm."; 1365 reference "RFC 6234: US Secure Hash Algorithms."; 1366 } 1368 rc:yang-data "zerotouch-information" { 1369 choice information-type { 1370 mandatory true; 1371 description 1372 "This choice statement ensures the response contains 1373 redirect-information or onboarding-information."; 1374 container redirect-information { 1375 description 1376 "Redirect information is described in Section 2.1 in 1377 RFC XXXX. Its purpose is to redirect a device to 1378 another bootstrap server."; 1379 reference 1380 "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF 1381 based Management"; 1382 list bootstrap-server { 1383 key "address"; 1384 min-elements 1; 1385 description 1386 "A bootstrap server entry."; 1387 leaf address { 1388 type inet:host; 1389 mandatory true; 1390 description 1391 "The IP address or hostname of the bootstrap server the 1392 device should redirect to."; 1393 } 1394 leaf port { 1395 type inet:port-number; 1396 default "443"; 1397 description 1398 "The port number the bootstrap server listens on. If no 1399 port is specified, the IANA-assigned port for 'https' 1400 (443) is used."; 1401 } 1402 leaf trust-anchor { 1403 type binary; 1404 description 1405 "An X.509 v3 certificate structure as specified by RFC 1406 5280, Section 4, encoded using ASN.1 distinguished 1407 encoding rules (DER), as specified in ITU-T X.690. A 1408 certificate that the device can use as the trust anchor 1409 to authenticate the bootstrap server the device is 1410 being redirected to. If not specified, the device may 1411 establish a provisional connection to the bootstrap 1412 server, as described in RFC XXXX."; 1413 reference 1414 "RFC 5280: 1415 Internet X.509 Public Key Infrastructure Certificate 1416 and Certificate Revocation List (CRL) Profile. 1417 ITU-T X.690: 1418 Information technology - ASN.1 encoding rules: 1419 Specification of Basic Encoding Rules (BER), 1420 Canonical Encoding Rules (CER) and Distinguished 1421 Encoding Rules (DER). 1422 RFC XXXX: 1423 Zero Touch Provisioning for NETCONF or RESTCONF 1424 based Management."; 1425 } 1426 } 1427 } 1428 container onboarding-information { 1429 description 1430 "Onboarding information is described in Section 2.2 in 1431 RFC XXXX. Its purpose is to provide the device everything 1432 it needs to bootstrap itself."; 1433 reference 1434 "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF 1435 based Management"; 1436 container boot-image { 1437 description 1438 "Specifies criteria for the boot image the device MUST 1439 be running."; 1440 leaf os-name { 1441 type string; 1442 mandatory true; 1443 description 1444 "The name of the operating system software the device 1445 MUST be running in order to not require a software 1446 image upgrade (ex. VendorOS)."; 1447 } 1448 leaf os-version { 1449 type string; 1450 mandatory true; 1451 description 1452 "The version of the operating system software the device 1453 MUST be running in order to not require a software 1454 image upgrade (ex. 17.3R2.1)."; 1455 } 1456 leaf-list download-uri { 1457 type inet:uri; 1458 must '../image-verification' { 1459 description 1460 "Image verification information must be provided if 1461 the device is going to download an image."; 1462 } 1463 ordered-by user; 1464 description 1465 "An ordered list of URIs to where the necessary 1466 boot-image file MAY be obtained. Deployments must 1467 know through out-of-band means which URI schemes 1468 (http, ftp, etc.) the bootstrapping device supports. 1469 If a secure scheme (e.g., https) is provided, a 1470 device MAY establish an untrusted connection to the 1471 remote server to obtain the boot-image."; 1472 } 1473 list image-verification { 1474 key hash-algorithm; 1475 description 1476 "A list of hash values that a device can use to verify 1477 boot image files with."; 1478 leaf hash-algorithm { 1479 type identityref { 1480 base "hash-algorithm"; 1481 } 1482 mandatory true; 1483 description 1484 "Identifies the hash algorithm used."; 1485 } 1486 leaf hash-value { 1487 type yang:hex-string; 1488 description 1489 "The hex-encoded value of the specified hash algorithm 1490 over the contents of the boot image file."; 1491 } 1492 } 1493 } 1494 leaf configuration-handling { 1495 type enumeration { 1496 enum "merge" { 1497 description 1498 "Merge configuration into the running datastore."; 1499 } 1500 enum "replace" { 1501 description 1502 "Replace the existing running datastore with the 1503 passed configuration."; 1504 } 1505 } 1506 must '../configuration'; 1507 description 1508 "This enumeration indicates how the server should process 1509 the provided configuration."; 1510 } 1511 leaf pre-configuration-script { 1512 type script; 1513 description 1514 "A script that, when present, is executed before the 1515 configuration has been processed."; 1516 } 1517 anydata configuration { 1518 must '../configuration-handling'; 1519 description 1520 "Any configuration data model known to the device. It may 1521 contain manufacturer-specific and/or standards-based data 1522 models."; 1523 } 1524 leaf post-configuration-script { 1525 type script; 1526 description 1527 "A script that, when present, is executed after the 1528 configuration has been processed."; 1529 } 1530 } 1531 } 1532 } 1534 typedef script { 1535 type binary; 1536 description 1537 "A device specific script that enables the execution of 1538 commands to perform actions not possible thru configuration 1539 alone. 1541 No attempt is made to standardize the contents, running 1542 context, or programming language of the script, other than 1543 that it can emit an exit status code and stderr/sdtout. The 1544 contents of the script are considered specific to the vendor, 1545 product line, and/or model of the device. 1547 If a script is erroneously provided to a device that does not 1548 support the execution of scripts, the device SHOULD send a 1549 'script-warning' progress report, but otherwise continue 1550 processing the bootstrapping data as if the script had not 1551 been present. 1553 The script returns exit status code '0' on success and non-zero 1554 on error, with accompanying stderr/stdout for logging purposes. 1555 In the case of an error, the exit status code will specify what 1556 the device should do as follows. 1558 If the exit status code is greater than zero, then the device 1559 should assume that the script had a soft error, which the 1560 script believes does not affect manageability. If the device 1561 obtained the bootstrap information from a bootstrap server, 1562 it SHOULD send a 'script-warning' progress report. 1564 If the exit status code is less than zero, the device should 1565 assume the script had a hard error, which the script believes 1566 will affect manageability. In this case, the device SHOULD 1567 send a 'script-error' progress report followed by a reset that 1568 will wipe out anything the script may have done and restart 1569 the entire bootstrapping process again."; 1570 } 1571 } 1572 1574 7. The Zero Touch Bootstrap Server API 1576 This section defines the API for bootstrap servers. The API is 1577 defined as the API produced by a RESTCONF [RFC8040] server that 1578 supports the YANG 1.1 [RFC7950] module defined in this section. 1580 7.1. API Overview 1582 The following tree diagram provides an overview for the bootstrap 1583 server RESTCONF API. The syntax used for this tree diagram is 1584 described in Section 1.4. 1586 module: ietf-zerotouch-bootstrap-server 1588 rpcs: 1589 +---x get-bootstrapping-data 1590 | +---w input 1591 | | +---w untrusted-connection? empty 1592 | | +---w os-name? string 1593 | | +---w os-version? string 1594 | | +---w remote-id? string 1595 | | +---w circuit-id? string 1596 | | +---w nonce? string 1597 | +--ro output 1598 | +--ro bootstrapping-data 1599 | +--ro zerotouch-information pkcs7 1600 | +--ro owner-certificate? pkcs7 1601 | +--ro ownership-voucher? pkcs7 1602 +---x report-progress 1603 +---w input 1604 +---w progress-type enumeration 1605 +---w message? string 1606 +---w ssh-host-keys 1607 | +---w ssh-host-key* 1608 | +---w format enumeration 1609 | +---w key-data string 1610 +---w trust-anchors 1611 +---w trust-anchor* 1612 +---w certificate pkcs7 1614 7.2. Example Usage 1616 This section presents three examples illustrating the bootstrap 1617 server's API. Two examples are provided for the 'get-bootstrapping- 1618 data' RPC (once to an untrusted bootstrap server, and again to a 1619 trusted bootstrap server), and one example for the 'report-progress' 1620 RPC. 1622 The following example illustrates a device using the API to fetch its 1623 bootstrapping data from a untrusted bootstrap server. In this 1624 example, the device sends the 'untrusted-connection' input parameter 1625 and receives signed data in the response. 1627 REQUEST 1628 ------- 1629 ['\' line wrapping added for formatting only] 1631 POST /restconf/operations/ietf-zerotouch-bootstrap-server:get-boot\ 1632 strapping-data HTTP/1.1 1633 HOST: example.com 1634 Content-Type: application/yang.data+xml 1636 1638 1639 1641 RESPONSE 1642 -------- 1644 HTTP/1.1 200 OK 1645 Date: Sat, 31 Oct 2015 17:02:40 GMT 1646 Server: example-server 1647 Content-Type: application/yang.data+xml 1649 1651 base64encodedvalue== 1652 base64encodedvalue== 1653 base64encodedvalue== 1654 1656 The following example illustrates a device using the API to fetch its 1657 bootstrapping data from a trusted bootstrap server. In this example, 1658 the device sends addition input parameters that the bootstrap server 1659 can use when formulating its response to the device. 1661 REQUEST 1662 ------- 1663 ['\' line wrapping added for formatting only] 1665 POST /restconf/operations/ietf-zerotouch-bootstrap-server:get-boot\ 1666 strapping-data HTTP/1.1 1667 HOST: example.com 1668 Content-Type: application/yang.data+xml 1670 1672 VendorOS 1673 17.3R2.1 1674 32 1675 2 1676 base64encodedvalue== 1677 1679 RESPONSE 1680 -------- 1682 HTTP/1.1 200 OK 1683 Date: Sat, 31 Oct 2015 17:02:40 GMT 1684 Server: example-server 1685 Content-Type: application/yang.data+xml 1687 1689 base64encodedvalue== 1690 1692 The following example illustrates a device using the API to post a 1693 progress update to a bootstrap server. Illustrated below is the 1694 'bootstrap-complete' message, but the device may send other progress 1695 reports to the server while bootstrapping. In this example, the 1696 device is sending both its SSH host keys and a TLS server 1697 certificate, which the bootstrap server may, for example, pass to an 1698 NMS, as discussed in Appendix A.3. 1700 REQUEST 1701 ------- 1702 ['\' line wrapping added for formatting only] 1704 POST /restconf/operations/ietf-zerotouch-bootstrap-server:report-\ 1705 progress HTTP/1.1 1706 HOST: example.com 1707 Content-Type: application/yang.data+xml 1709 1711 bootstrap-complete 1712 example message 1713 1714 1715 ssh-rsa 1716 base64encodedvalue== 1717 1718 1719 ssh-dss 1720 base64encodedvalue== 1721 1722 1723 1724 1725 base64encodedvalue== 1726 1727 1728 1730 RESPONSE 1731 -------- 1733 HTTP/1.1 204 No Content 1734 Date: Sat, 31 Oct 2015 17:02:40 GMT 1735 Server: example-server 1737 7.3. YANG Module 1739 The bootstrap server's device-facing API is normatively defined by 1740 the YANG module defined in this section. 1742 Note: the module defined herein uses data types defined in [RFC2315], 1743 [RFC5280], [RFC6960], and [I-D.ietf-anima-voucher], and uses an 1744 encoding defined in [ITU.X690.1994]. 1746 file "ietf-zerotouch-bootstrap-server@2017-10-19.yang" 1747 module ietf-zerotouch-bootstrap-server { 1748 yang-version 1.1; 1749 namespace 1750 "urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server"; 1751 prefix ztbs; 1753 organization 1754 "IETF NETCONF (Network Configuration) Working Group"; 1756 contact 1757 "WG Web: 1758 WG List: 1759 Author: Kent Watsen "; 1761 description 1762 "This module defines an interface for bootstrap servers, as 1763 defined by RFC XXXX: Zero Touch Provisioning for NETCONF or 1764 RESTCONF based Management. 1766 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1767 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', 1768 and 'OPTIONAL' in the module text are to be interpreted as 1769 described in RFC 2119. 1771 Copyright (c) 2017 IETF Trust and the persons identified as 1772 authors of the code. All rights reserved. 1774 Redistribution and use in source and binary forms, with or 1775 without modification, is permitted pursuant to, and subject 1776 to the license terms contained in, the Simplified BSD License 1777 set forth in Section 4.c of the IETF Trust's Legal Provisions 1778 Relating to IETF Documents (http://trustee.ietf.org/license-info) 1780 This version of this YANG module is part of RFC XXXX; see the 1781 RFC itself for full legal notices."; 1783 revision 2017-10-19 { 1784 description 1785 "Initial version"; 1786 reference 1787 "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF based 1788 Management"; 1789 } 1791 // typedefs 1793 typedef pkcs7 { 1794 type binary; 1795 description 1796 "A PKCS #7 SignedData structure, as specified by Section 9.1 1797 in RFC 2315, encoded using ASN.1 distinguished encoding rules 1798 (DER), as specified in ITU-T X.690."; 1799 reference 1800 "RFC 2315: 1801 PKCS #7: Cryptographic Message Syntax Version 1.5. 1802 ITU-T X.690: 1803 Information technology - ASN.1 encoding rules: 1804 Specification of Basic Encoding Rules (BER), 1805 Canonical Encoding Rules (CER) and Distinguished 1806 Encoding Rules (DER)."; 1807 } 1809 // RPCs 1811 rpc get-bootstrapping-data { 1812 description 1813 "This RPC enables a device, as identified by its RESTCONF 1814 username, to obtain bootstrapping data that has been made 1815 available for it."; 1816 input { 1817 leaf untrusted-connection { 1818 type empty; 1819 description 1820 "This optional input parameter enables a device to 1821 communicate to the bootstrap server that it is unable 1822 to authenticate the bootstrap server's TLS certificate. 1823 In such circumstances, the device likely did not send 1824 any of the other input parameters. The bootstrap server 1825 needs to return either unsigned redirect information or 1826 signed data."; 1827 } 1828 leaf os-name { 1829 type string; 1830 description 1831 "This optional input parameter enables a device to 1832 communicate to the bootstrap server the name of its 1833 operating system. This parameter may be useful if 1834 the device, as identified by its IDevID certificate, 1835 to run more than one type of operating system (e.g., 1836 on a white-box system."; 1837 } 1838 leaf os-version { 1839 type string; 1840 description 1841 "This optional input parameter enables a device to 1842 communicate to the bootstrap server the version of 1843 its operating system. This parameter may be useful 1844 to a server that wants to return a response optimized 1845 for the device, negating, for instance, the need for 1846 a potentially expensive boot-image update."; 1847 } 1848 leaf remote-id { 1849 type string; 1850 must "../circuit-id"; 1851 description 1852 "This optional input parameter enables a device to 1853 communicate to the bootstrap server the 'remote-id' 1854 value it learned from a DHCP server via Option 82, 1855 as described in Section 2.0 or RFC 3046. 1857 This information, along with the circuit-id, enables 1858 the bootstrap server to return a deployment-specific 1859 response independent of the device's IDevID identity."; 1860 reference 1861 "RFC 3046: DHCP Relay Agent Information Option"; 1862 } 1863 leaf circuit-id { 1864 type string; 1865 must "../remote-id"; 1866 description 1867 "This optional input parameter enables a device to 1868 communicate to the bootstrap server the 'circuit-id' 1869 value it learned from a DHCP server via Option 82, 1870 as described in Section 2.0 or RFC 3046. 1872 This information, along with the remote-id, enables 1873 the bootstrap server to return a deployment-specific 1874 response independent of the device's IDevID identity."; 1875 reference 1876 "RFC 3046: DHCP Relay Agent Information Option"; 1877 } 1878 leaf nonce { 1879 type string; 1880 description 1881 "This optional input parameter enables a device to 1882 communicate to the bootstrap server a nonce value. 1883 This may be especially useful for devices lacking 1884 an accurate clock, as then the bootstrap server can 1885 then dynamically obtain from the manufacturer a 1886 voucher with the nonce value in it, as described 1887 in I-D.ietf-anima-voucher."; 1888 reference 1889 "RFC ZZZZ: Voucher Profile for Bootstrapping Protocols."; 1890 } 1891 } 1892 output { 1893 container bootstrapping-data { 1894 description 1895 "Top-level node for the bootstrapping data."; 1896 leaf zerotouch-information { 1897 type pkcs7; 1898 mandatory true; 1899 description 1900 "A 'zerotouch-information' artifact, as described in 1901 Section 4.1 of RFC XXXX. In order to be processed by a 1902 device, when conveyed over an untrusted transport, the 1903 PKCS#7 SignedData structure MUST contain a 'signerInfo' 1904 structure, described in Section 9.1 of RFC 2315, 1905 containing a signature generated using the private key 1906 associated with the 'owner-certificate'."; 1907 reference 1908 "RFC XXXX: Zero Touch Provisioning for NETCONF or 1909 RESTCONF based Management. 1910 RFC 2315: 1911 PKCS #7: Cryptographic Message Syntax Version 1.5"; 1912 } 1913 leaf owner-certificate { 1914 type pkcs7; 1915 must '../ownership-voucher' { 1916 description 1917 "An ownership voucher must be present whenever an owner 1918 certificate is presented."; 1919 } 1920 description 1921 "This PKCS#7 structure MUST contain the owner certificate 1922 and all intermediate certificates leading up to, and 1923 optionally including, the trust anchor certificate 1924 specified in the ownership voucher. Additionally, if 1925 needed by the device, this structure MAY also contain 1926 suitably fresh CRL and/or OCSP Responses with which to 1927 verify the revocation status of the certificates. 1929 X.509 certificates and CRLs are described in RFC 5280. 1930 OCSP Responses are described in RFC 6960."; 1931 reference 1932 "RFC 2315: 1933 PKCS #7: Cryptographic Message Syntax Version 1.5. 1934 RFC 5280: 1935 Internet X.509 Public Key Infrastructure Certificate 1936 and Certificate Revocation List (CRL) Profile. 1937 RFC 6960: 1938 X.509 Internet Public Key Infrastructure Online 1939 Certificate Status Protocol - OCSP. 1941 ITU-T X.690: 1942 Information technology - ASN.1 encoding rules: 1943 Specification of Basic Encoding Rules (BER), 1944 Canonical Encoding Rules (CER) and Distinguished 1945 Encoding Rules (DER)."; 1946 } 1947 leaf ownership-voucher { 1948 type pkcs7; 1949 must '../owner-certificate' { 1950 description 1951 "An owner certificate must be present whenever an 1952 ownership voucher is presented."; 1953 } 1954 description 1955 "A 'voucher' artifact, as described in Section 5 of 1956 I-D.ietf-anima-voucher. The voucher informs the device 1957 who its owner is. The voucher encodes the device's 1958 serial number, so that the device can ensure the 1959 voucher applies to it. The voucher is signed by the 1960 device's manufacturer."; 1961 reference 1962 "I-D.ietf-anima-voucher: 1963 Voucher and Voucher Revocation Profiles for 1964 Bootstrapping Protocols"; 1965 } 1966 } 1967 } 1968 } 1970 rpc report-progress { 1971 description 1972 "This RPC enables a device, as identified by its RESTCONF 1973 username, to report its bootstrapping progress to the 1974 bootstrap server."; 1975 input { 1976 leaf progress-type { 1977 type enumeration { 1978 enum "bootstrap-initiated" { 1979 description 1980 "Indicates that the device just used the 1981 'get-bootstrapping-data' RPC. The 'message' field 1982 below MAY contain any additional information that 1983 the manufacturer thinks might be useful."; 1984 } 1985 enum "parsing-warning" { 1986 description 1987 "Indicates that the device had a non-fatal error when 1988 parsing the response from the bootstrap server. The 1989 'message' field below SHOULD indicate the specific 1990 warning that occurred."; 1991 } 1992 enum "parsing-error" { 1993 description 1994 "Indicates that the device encountered a fatal error 1995 when parsing the response from the bootstrap server. 1996 For instance, this could be due to malformed 1997 encoding, the device expecting signed data when 1998 only unsigned data is provided, because the 1999 ownership voucher didn't include the device's 2000 unique identifier, or because the signature didn't 2001 match. The 'message' field below SHOULD indicate 2002 the specific error. This progress type also indicates 2003 that the device has abandoned trying to bootstrap 2004 off this bootstrap server."; 2005 } 2006 enum "boot-image-warning" { 2007 description 2008 "Indicates that the device encountered a non-fatal 2009 error condition when trying to install a boot-image. 2010 A possible reason might include a need to reformat a 2011 partition causing loss of data. The 'message' field 2012 below SHOULD indicate any warning messages that were 2013 generated."; 2014 } 2015 enum "boot-image-error" { 2016 description 2017 "Indicates that the device encountered an error when 2018 trying to install a boot-image, which could be for 2019 reasons such as a file server being unreachable, 2020 file not found, signature mismatch, etc. The 2021 'message' field SHOULD indicate the specific error 2022 that occurred. This progress type also indicates 2023 that the device has abandoned trying to bootstrap 2024 off this bootstrap server."; 2025 } 2026 enum "pre-script-warning" { 2027 description 2028 "Indicates that the device obtained a greater than 2029 zero exit status code from the script when it was 2030 executed. The 'message' field below SHOULD indicate 2031 both the resulting exit status code, as well as 2032 capture any stdout/stderr messages the script may 2033 have produced."; 2034 } 2035 enum "pre-script-error" { 2036 description 2037 "Indicates that the device obtained a less than 2038 zero exit status code from the script when it was 2039 executed. The 'message' field below SHOULD indicate 2040 both the resulting exit status code, as well as 2041 capture any stdout/stderr messages the script may 2042 have produced. This progress type also indicates 2043 that the device has abandoned trying to bootstrap 2044 off this bootstrap server."; 2045 } 2046 enum "config-warning" { 2047 description 2048 "Indicates that the device obtained warning messages 2049 when it committed the initial configuration. The 2050 'message' field below SHOULD indicate any warning 2051 messages that were generated."; 2052 } 2053 enum "config-error" { 2054 description 2055 "Indicates that the device obtained error messages 2056 when it committed the initial configuration. The 2057 'message' field below SHOULD indicate the error 2058 messages that were generated. This progress type 2059 also indicates that the device has abandoned trying 2060 to bootstrap off this bootstrap server."; 2061 } 2062 enum "post-script-warning" { 2063 description 2064 "Indicates that the device obtained a greater than 2065 zero exit status code from the script when it was 2066 executed. The 'message' field below SHOULD indicate 2067 both the resulting exit status code, as well as 2068 capture any stdout/stderr messages the script may 2069 have produced."; 2070 } 2071 enum "post-script-error" { 2072 description 2073 "Indicates that the device obtained a less than 2074 zero exit status code from the script when it was 2075 executed. The 'message' field below SHOULD indicate 2076 both the resulting exit status code, as well as 2077 capture any stdout/stderr messages the script may 2078 have produced. This progress type also indicates 2079 that the device has abandoned trying to bootstrap 2080 off this bootstrap server."; 2081 } 2082 enum "bootstrap-complete" { 2083 description 2084 "Indicates that the device successfully processed all 2085 'onboarding-information' provided, and that it is ready 2086 to be managed. The 'message' field below MAY contain 2087 any additional information that the manufacturer thinks 2088 might be useful. After sending this progress type, 2089 the device is not expected to access the bootstrap 2090 server again."; 2091 } 2092 enum "informational" { 2093 description 2094 "Indicates any additional information not captured 2095 by any of the other progress types. For instance, a 2096 message indicating that the device is about to 2097 reboot after having installed a boot-image could 2098 be provided. The 'message' field below SHOULD 2099 contain information that the manufacturer thinks 2100 might be useful."; 2101 } 2102 } 2103 mandatory true; 2104 description 2105 "The type of progress report provided."; 2106 } 2107 leaf message { 2108 type string; 2109 description 2110 "An optional arbitrary value."; 2111 } 2112 container ssh-host-keys { 2113 when "../progress-type = 'bootstrap-complete'" { 2114 description 2115 "SSH host keys are only sent when the progress type 2116 is 'bootstrap-complete'."; 2117 } 2118 description 2119 "A list of trust anchor certificates an NMS may use to 2120 authenticate subsequent SSH-based connections to this 2121 device (e.g., netconf-ssh, netconf-ch-ssh)."; 2122 list ssh-host-key { 2123 description 2124 "An SSH host-key."; 2125 leaf format { 2126 type enumeration { 2127 enum "ssh-dss" { 2128 description 2129 "ssh-dss"; 2130 } 2131 enum "ssh-rsa" { 2132 description 2133 "ssh-rsa"; 2134 } 2135 } 2136 mandatory true; 2137 description 2138 "The format of the SSH host key."; 2139 } 2140 leaf key-data { 2141 type string; 2142 mandatory true; 2143 description 2144 "The key data for the SSH host key"; 2145 } 2146 } 2147 } 2148 container trust-anchors { 2149 when "../progress-type = 'bootstrap-complete'" { 2150 description 2151 "Trust anchors are only sent when the progress type 2152 is 'bootstrap-complete'."; 2153 } 2154 description 2155 "A list of trust anchor certificates an NMS may use to 2156 authenticate subsequent certificate-based connections 2157 to this device (e.g., restconf-tls, netconf-tls, or 2158 even netconf-ssh with X.509 support from RFC 6187)."; 2159 reference 2160 "RFC 6187: 2161 X.509v3 Certificates for Secure Shell Authentication."; 2162 list trust-anchor { 2163 description 2164 "A trust anchor."; 2165 leaf certificate { 2166 type pkcs7; 2167 mandatory true; 2168 description 2169 "An X.509 v3 certificate structure, as specified 2170 by Section 4 in RFC 5280, encoded using ASN.1 2171 distinguished encoding rules (DER), as specified 2172 in ITU-T X.690."; 2173 reference 2174 "RFC 5280: 2175 Internet X.509 Public Key Infrastructure 2176 Certificate and Certificate Revocation List (CRL) 2177 Profile. 2178 ITU-T X.690: 2179 Information technology - ASN.1 encoding rules: 2180 Specification of Basic Encoding Rules (BER), 2181 Canonical Encoding Rules (CER) and Distinguished 2182 Encoding Rules (DER)."; 2183 } 2184 } 2185 } 2186 } 2187 } 2188 } 2189 2191 8. The Zero Touch Device Data Model 2193 This section defines a data model that devices can implement to 2194 enable the configuration of zerotouch bootstrapping and discovery of 2195 what parameters are used by its bootstrapping logic. 2197 8.1. Data Model Overview 2199 The following tree diagram provides an overview for the zerotouch 2200 device data model The syntax used for this tree diagram is described 2201 in Section 1.4. 2203 module: ietf-zerotouch-device 2204 +--rw zerotouch 2205 +--rw enabled? boolean 2206 +--ro devid-certificate? pkcs7 2207 | {bootstrap-servers}? 2208 +--ro bootstrap-servers {bootstrap-servers}? 2209 | +--ro bootstrap-server* [address] 2210 | +--ro address inet:host 2211 | +--ro port? inet:port-number 2212 +--ro bootstrap-server-ta-certificates? 2213 | -> /ks:keystore/pinned-certificates/name 2214 | {bootstrap-servers}? 2215 +--ro voucher-ta-certificates? 2216 -> /ks:keystore/pinned-certificates/name {signed-data}? 2218 In the above diagram, notice that there is only one configurable node 2219 'enabled'. The expectation is that this node would be set to 'true' 2220 in device's factory default configuration and that it would either be 2221 set to 'false' or deleted when the zerotouch bootstrapping is longer 2222 needed. 2224 8.2. Example Usage 2226 Following is an instance example for this data model. 2228 [ note: '\' line wrapping for formatting only] 2230 2232 true 2233 base64encodedvalue== 2234 2235 2236
phs1.example.com
2237 8443 2238 2239 2240
phs2.example.com
2241 8443 2242 2243 2244
phs3.example.com
2245 8443 2246 2247 2248 manufacturers-root-ca-certs 2250 manufacturers-root-ca-certs 2252 2254 8.3. YANG Module 2256 The device model is normatively defined by the YANG module defined in 2257 this section. 2259 Note: the module defined herein uses data types defined in [RFC2315] 2260 and [RFC6991], and uses an encoding defined in [ITU.X690.1994]. 2262 file "ietf-zerotouch-device@2017-10-19.yang" 2263 module ietf-zerotouch-device { 2264 yang-version 1.1; 2265 namespace 2266 "urn:ietf:params:xml:ns:yang:ietf-zerotouch-device"; 2267 prefix ztd; 2269 import ietf-inet-types { 2270 prefix inet; 2271 reference "RFC 6991: Common YANG Data Types"; 2272 } 2273 import ietf-keystore { 2274 prefix ks; 2275 reference 'RFC YYYY: YANG Data Model for a "Keystore" Mechanism'; 2277 } 2279 organization 2280 "IETF NETCONF (Network Configuration) Working Group"; 2282 contact 2283 "WG Web: 2284 WG List: 2285 Author: Kent Watsen "; 2287 description 2288 "This module defines a data model to enable zerotouch 2289 bootstrapping and discover what parameters are used. 2291 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 2292 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', 2293 and 'OPTIONAL' in the module text are to be interpreted as 2294 described in RFC 2119. 2296 Copyright (c) 2017 IETF Trust and the persons identified as 2297 authors of the code. All rights reserved. 2299 Redistribution and use in source and binary forms, with or 2300 without modification, is permitted pursuant to, and subject 2301 to the license terms contained in, the Simplified BSD License 2302 set forth in Section 4.c of the IETF Trust's Legal Provisions 2303 Relating to IETF Documents (http://trustee.ietf.org/license-info) 2305 This version of this YANG module is part of RFC XXXX; see the 2306 RFC itself for full legal notices."; 2308 revision 2017-10-19 { 2309 description 2310 "Initial version"; 2311 reference 2312 "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF based 2313 Management"; 2314 } 2316 // features 2318 feature bootstrap-servers { 2319 description 2320 "The device supports bootstrapping off bootstrap servers."; 2321 } 2323 feature signed-data { 2324 description 2325 "The device supports bootstrapping off signed data."; 2326 } 2328 // typedefs 2330 typedef pkcs7 { 2331 type binary; 2332 description 2333 "A PKCS #7 SignedData structure, as specified by Section 9.1 2334 in RFC 2315, encoded using ASN.1 distinguished encoding rules 2335 (DER), as specified in ITU-T X.690."; 2336 reference 2337 "RFC 2315: 2338 PKCS #7: Cryptographic Message Syntax Version 1.5. 2339 ITU-T X.690: 2340 Information technology - ASN.1 encoding rules: 2341 Specification of Basic Encoding Rules (BER), 2342 Canonical Encoding Rules (CER) and Distinguished 2343 Encoding Rules (DER)."; 2344 } 2346 // protocol accessible nodes 2348 container zerotouch { 2349 description 2350 "Top-level container for zerotouch data model."; 2351 leaf enabled { 2352 type boolean; 2353 default false; 2354 description 2355 "The 'enabled' leaf controls if zerotouch bootstrapping is 2356 enabled or disabled. The default is 'false' so that, when 2357 not enabled, which is most of the time, no configuration 2358 needs to be returned."; 2359 } 2360 leaf devid-certificate { 2361 if-feature bootstrap-servers; 2362 type pkcs7; 2363 config false; 2364 description 2365 "An unsigned PKCS #7 SignedData structure, as specified by 2366 Section 9.1 in RFC 2315, encoded using ASN.1 distinguished 2367 encoding rules (DER), as specified in ITU-T X.690. 2369 This structure contains the IDevID certificate and all 2370 intermediate certificates leading up to the manufacturer's 2371 well-known trust anchor certificate. IDevID certificates 2372 are described in IEEE 802.1AR-2009."; 2374 reference 2375 "RFC 2315: 2376 PKCS #7: Cryptographic Message Syntax Version 1.5. 2377 ITU-T X.690: 2378 Information technology - ASN.1 encoding rules: 2379 Specification of Basic Encoding Rules (BER), 2380 Canonical Encoding Rules (CER) and Distinguished 2381 Encoding Rules (DER). 2382 IEEE 802.1AR-2009: 2383 IEEE Standard for Local and metropolitan area 2384 networks - Secure Device Identity."; 2385 } 2386 container bootstrap-servers { 2387 if-feature bootstrap-servers; 2388 config false; 2389 description 2390 "Default list of bootstrap servers this device is 2391 configured to reach out to when bootstrapping."; 2392 list bootstrap-server { 2393 key "address"; 2394 description 2395 "A bootstrap server entry."; 2396 leaf address { 2397 type inet:host; 2398 mandatory true; 2399 description 2400 "The IP address or hostname of the bootstrap server the 2401 device should redirect to."; 2402 } 2403 leaf port { 2404 type inet:port-number; 2405 default "443"; 2406 description 2407 "The port number the bootstrap server listens on. If no 2408 port is specified, the IANA-assigned port for 'https' 2409 (443) is used."; 2410 } 2411 } 2412 } 2413 leaf bootstrap-server-ta-certificates { 2414 if-feature bootstrap-servers; 2415 type leafref { 2416 path "/ks:keystore/ks:pinned-certificates/ks:name"; 2417 } 2418 config false; 2419 description 2420 "A reference to a list of pinned certificate authority (CA) 2421 certificates that the device uses to validate bootstrap 2422 servers with."; 2423 } 2424 leaf voucher-ta-certificates { 2425 if-feature signed-data; 2426 type leafref { 2427 path "/ks:keystore/ks:pinned-certificates/ks:name"; 2428 } 2429 config false; 2430 description 2431 "A reference to a list of pinned certificate authority (CA) 2432 certificates that the device uses to validate ownership 2433 vouchers with."; 2434 } 2435 } 2436 } 2438 2440 9. DHCP Zero Touch Options 2442 This section defines two DHCP options, one for DHCPv4 and one for 2443 DHCPv6. These two options are semantically the same, though 2444 syntactically different. 2446 9.1. DHCPv4 Zero Touch Option 2448 The DHCPv4 Zero Touch Option is used to provision the client with one 2449 or more URIs for bootstrap servers that can be contacted to attempt 2450 further configuration. 2452 DHCPv4 Zero Touch Redirect Option 2454 0 1 2455 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 2456 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2457 | option-code (TBD) | option-length | 2458 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2459 . . 2460 . bootstrap-server-list (variable length) . 2461 . . 2462 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2464 o option-code: OPTION_V4_ZEROTOUCH_REDIRECT (TBD) 2465 o option-length: The option length in octets 2466 o bootstrap-server-list: A list of servers for the 2467 client to attempt contacting, in order to obtain 2468 further bootstrapping data, in the format shown 2469 in [common-field-encoding]. 2471 DHCPv4 Client Behavior 2473 Clients MAY request the OPTION_V4_ZEROTOUCH_REDIRECT by including its 2474 option code in the Parameter Request List (55) in DHCP request 2475 messages. 2477 On receipt of a DHCPv4 Reply message which contains the 2478 OPTION_V4_ZEROTOUCH_REDIRECT, the client performs the following 2479 steps: 2481 1. Check the contents of the DHCPv4 message for at least one valid 2482 URI. If there is more than one valid URI in the list, a candidate 2483 list of possible URIs is created. 2485 2. Attempt to connect to the one of the URIs in the candidate list. 2486 The order in which these are processed by the client is 2487 implementation specific and not defined here. 2489 3. If a successful connection to the zerotouch bootstrap server, 2490 then the client stops processing entries in the list and proceeds 2491 according to Appendix A.3, step(3). 2493 4. If the zerotouch bootstrap server does not respond, provides 2494 an invalid response, or the transaction otherwise fails, the 2495 client SHOULD attempt to contact another server from the 2496 candidate list. 2498 Any invalid URI entries received in the uri-data field are ignored by 2499 the client. If OPTION_V4_ZEROTOUCH_REDIRECT does not contain at 2500 least one valid URI entry in the uri-data field, then the client MUST 2501 discard the option. 2503 DHCPv4 Server Behavior 2505 The DHCPv4 server MAY include a single instance of Option 2506 OPTION_V4_ZEROTOUCH_REDIRECT in DHCP messages it sends. Servers MUST 2507 NOT send more than one instance of the OPTION_V4_ZEROTOUCH_REDIRECT 2508 option. 2510 9.2. DHCPv6 Zero Touch Option 2512 The DHCPv6 Zero Touch Option is used to provision the client with one 2513 or more URIs for bootstrap servers that can be contacted to attempt 2514 further configuration. 2516 DHCPv6 Zero Touch Redirect Option 2518 0 1 2 3 2519 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 2520 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2521 | option-code (TBD) | option-length | 2522 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2523 . bootstrap-server-list (variable length) . 2524 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2526 o option-code: OPTION_V6_ZEROTOUCH_REDIRECT (TBD) 2527 o option-length: The option length in octets 2528 o bootstrap-server-list: A list of servers for the client to 2529 attempt contacting, in order to obtain further bootstrapping 2530 data, in the format shown in [common-field-encoding]. 2532 DHCPv6 Client Behavior 2534 Clients MAY request the OPTION_V6_ZEROTOUCH_REDIRECT option, as 2535 defined in [RFC3315], Sections 17.1.1, 18.1.1, 18.1.3, 18.1.4, 2536 18.1.5, and 22.7. As a convenience to the reader, we mention here 2537 that the client includes requested option codes in the Option Request 2538 Option. 2540 On receipt of a DHCPv6 reply message which contains the 2541 OPTION_V6_ZEROTOUCH_REDIRECT, the client performs the following 2542 steps: 2544 1. Check the contents of the DHCPv6 message for at least one valid 2545 URI. If there is more than one valid URI in the list, a 2546 candidate list of possible URIs is created. 2548 2. Attempt to connect to the one of the URIs in the candidate list. 2549 The order in which these are processed by the client is 2550 implementation specific and not defined here. 2552 3. If a successful connection to the zerotouch bootstrap server, 2553 then the client stops processing entries in the list and proceeds 2554 according to Appendix A.3, step(3). 2556 4. If the zerotouch bootstrap server does not respond, provides 2557 and invalid response or the transaction otherwise fails, the 2558 client SHOULD attempt to contact another server from the 2559 candidate list. 2561 Any invalid URI entries received in the uri-data field are ignored by 2562 the client. If OPTION_V6_ZEROTOUCH_REDIRECT does not contain at 2563 least one valid URI entry in the uri-data field, then the client MUST 2564 discard the option. 2566 DHCPv6 Server Behavior 2568 Sections 17.2.2 and 18.2 of [RFC3315] govern server operation 2569 in regard to option assignment. As a convenience to the reader, 2570 we mention here that the server will send a particular option code 2571 only if configured with specific values for that option code and if 2572 the client requested it. 2574 Option OPTION_V6_ZEROTOUCH_REDIRECT is a singleton. Servers MUST NOT 2575 send more than one instance of the OPTION_V6_ZEROTOUCH_REDIRECT 2576 option. 2578 9.3. Common Field Encoding 2580 Both of the DHCPv4 and DHCPv6 options defined in this section encode 2581 a list of bootstrap server URIs. The "URI" structure is an option 2582 that can contain multiple URIs (see [RFC7227], Section 5.7). 2584 bootstrap-server-list: 2586 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 2587 | uri-length | URI | 2588 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 2590 o uri-length: variable, in octets. 2592 o URI: URI of zerotouch bootstrap server, using the HTTPS URI 2593 scheme defined in Section 2.7.2 of RFC7230. URI MUST be in 2594 form "https://[:]". 2596 10. Security Considerations 2598 10.1. Immutable storage for trust anchors 2600 Devices MUST ensure that all their trust anchor certificates, 2601 including those for connecting to bootstrap servers and verifying 2602 ownership vouchers, are protected from external modification. 2604 It may be necessary to update these certificates over time (e.g., the 2605 manufacturer wants to delegate trust to a new CA). It is therefore 2606 expected that devices MAY update these trust anchors when needed 2607 through a verifiable process, such as a software upgrade using signed 2608 software images. 2610 10.2. Clock Sensitivity 2612 The solution in this document relies on TLS certificates, owner 2613 certificates, and ownership vouchers, all of which require an 2614 accurate clock in order to be processed correctly (e.g., to test 2615 validity dates and revocation status). Implementations SHOULD ensure 2616 devices have an accurate clock when shipped from manufacturing 2617 facilities, and take steps to prevent clock tampering. 2619 If it is not possible to ensure clock accuracy, it is RECOMMENDED 2620 that implementations disable the aspects of the solution having clock 2621 sensitivity. In particular, such implementations should assume that 2622 TLS certificates, ownership vouchers, and owner certificates never 2623 expire and are not revokable. From an ownership voucher perspective, 2624 manufacturers SHOULD issue a single ownership voucher for the 2625 lifetime of such devices. 2627 Implementations SHOULD NOT rely on NTP for time, as NTP is not a 2628 secure protocol. 2630 10.3. Blindly authenticating a bootstrap server 2632 This document allows a device to blindly authenticate a bootstrap 2633 server's TLS certificate. It does so to allow for cases where the 2634 redirect information may be obtained in an unsecured manner, which is 2635 desirable to support in some cases. 2637 To compensate for this, this document requires that devices, when 2638 connected to an untrusted bootstrap server, assert that data 2639 downloaded from the server is signed. 2641 10.4. Entropy loss over time 2643 Section 7.2.7.2 of the IEEE Std 802.1AR-2009 standard says that 2644 IDevID certificate should never expire (i.e. having the notAfter 2645 value 99991231235959Z). Given the long-lived nature of these 2646 certificates, it is paramount to use a strong key length (e.g., 2647 512-bit ECC). 2649 10.5. Disclosing Information to Untrusted Servers 2651 This document enables devices to establish provisional connections to 2652 bootstrap servers, in order for the bootstrap server to provide 2653 either unsigned redirect information or signed data to the device. 2654 However, since the server is untrusted, it may be under the control 2655 of an adversary, and therefore devices should be cautious about the 2656 data they send in such cases. 2658 Already this document requires devices send their IDevID certificate 2659 to untrusted bootstrap servers, which means that the device's serial 2660 number and hardware manufacturer may be disclosed to an adversary. 2661 Serial numbers are ubiquitous and prominently contained in invoices 2662 and on labels affixed to devices and their packaging. That said, 2663 serial numbers many times encode revealing information, such as the 2664 device's model number, manufacture date, and/or manufacturing 2665 sequence number. Knowledge of this information may provide an 2666 adversary with details needed to launch an attack. 2668 In addition to the IDevID certificate, there are other potentially 2669 identifying values that may be disclosed to an untrusted server, 2670 including 'os-name', 'os-version', 'remote-id', 'circuit-id', and 2671 progress reports. In order to address this issue, it is RECOMMENDED 2672 that implementations first promote the untrusted connection to a 2673 trusted connection, as described in Appendix B. 2675 10.6. Sequencing Sources of Bootstrapping Data 2677 For devices supporting more than one source for bootstrapping data, 2678 no particular sequencing order has to be observed for security 2679 reasons, as the solution for each source is considered equally 2680 secure. However, from a privacy perspective, it is RECOMMENDED that 2681 devices access local sources before accessing remote sources. 2683 10.7. The "ietf-zerotouch-information" YANG Module 2685 The ietf-zerotouch-information module defined in this document 2686 defines a data structure that is always wrapped by a PKCS#7 2687 structure. When accessed by a secure mechanism (e.g., protected by 2688 TLS), then the PKCS#7 structure may be unsigned. However, when 2689 accessed by an insecure mechanism (e.g., removable storage device), 2690 then the PKCS#7 structure must be signed, in order for the device to 2691 trust it. 2693 Implementations should be aware that signed bootstrapping data only 2694 protects the data from modification, the contents are still visible 2695 to others. This doesn't affect Security so much as Privacy. That 2696 the contents may be read by unintended parties when accessed by 2697 insecure mechanisms is considered next. 2699 The ietf-zerotouch-information module defines a top-level 'choice' 2700 statement that declares the contents are either "redirect- 2701 information" or "onboarding-information". Each of these two cases 2702 are now considered. 2704 When the contents of the PKCS#7 structure are redirect-information, 2705 an observer can learn about the bootstrap servers the device is being 2706 directed, their IP addresses or hostnames, ports, and trust anchor 2707 certificates. Knowledge of this information could provide an 2708 observer some insight into a network's inner structure. 2710 When the contents of the PKCS#7 structure are onboarding-information, 2711 as observer could learn considerable information about how the device 2712 is to be provisioned. This information includes the specific 2713 operating system version, the initial configuration, and the specific 2714 scripts that the device is to run. All of this information should be 2715 considered highly sensitive and precautions should be taken to 2716 protect it from falling into the wrong hands. 2718 10.8. The "ietf-zerotouch-bootstrap-server" YANG Module 2720 The ietf-zerotouch-bootstrap-server module defined in this document 2721 is specifies an API for a RESTCONF [RFC8040]. The lowest RESTCONF 2722 layer is HTTPS, and the mandatory-to-implement secure transport is 2723 TLS [RFC5246]. 2725 The NETCONF Access Control Model (NACM) [RFC6536] provides the means 2726 to restrict access for particular users to a preconfigured subset of 2727 all available protocol operations and content. 2729 This module presents no data nodes (only RPCs). There is no need to 2730 discuss the sensitivity of data nodes. 2732 This module defines two RPC operations that may be considered 2733 sensitive in some network environments. These are the operations and 2734 their sensitivity/vulnerability: 2736 get-bootstrapping-data: This RPC is used by devices to obtain their 2737 bootstrapping data. By design, each device, as identified by its 2738 IDevID certificate, can only obtain its own data. NACM is not 2739 needed to further constrain access to this RPC. 2741 report-bootstrapping-progress: This RPC is used by devices to report 2742 their bootstrapping progress. By design, each device, as 2743 identified by its IDevID certificate, can only report data for 2744 itself. NACM is not needed to further constrain access to this 2745 RPC. 2747 10.9. The "ietf-zerotouch-device" YANG Module 2749 The ietf-zerotouch-device module defined in this document is designed 2750 to be accessed via network management protocols such as NETCONF 2751 [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the 2752 secure transport layer, and the mandatory-to-implement secure 2753 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 2754 is HTTPS, and the mandatory-to-implement secure transport is TLS 2755 [RFC5246]. 2757 The NETCONF access control model [RFC6536] provides the means to 2758 restrict access for particular NETCONF or RESTCONF users to a 2759 preconfigured subset of all available NETCONF or RESTCONF protocol 2760 operations and content. 2762 There is a data node defined in this YANG module that is 2763 writable/creatable/deletable (i.e., config true, which is the 2764 default). This data node may be considered sensitive or vulnerable 2765 in some network environments. Write operations (e.g., edit-config) 2766 to this data node without proper protection can have a negative 2767 effect on network operations. This is the data node and its 2768 sensitivity/vulnerability: 2770 /enabled: This data node is used to enable/disable the zerotouch 2771 bootstrapping mechanism on a device. NACM rules or equivalent 2772 should be used to restrict write-access to this node to 2773 authenticated clients. 2775 11. IANA Considerations 2777 11.1. The BOOTP Manufacturer Extensions and DHCP Options Registry 2779 IANA is kindly requested to allocate a new option code from the 2780 "BOOTP Manufacturer Extensions and DHCP Options" registry maintained 2781 at http://www.iana.org/assignments/bootp-dhcp-parameters: 2783 TBD for OPTION_V4_ZEROTOUCH_REDIRECT 2785 And a new option code from the "Dynamic Host Configuration Protocol 2786 for IPv6 (DHCPv6)" registry maintained at 2787 http://www.iana.org/assignments/dhcpv6-parameters: 2789 TBD for OPTION_V6_ZEROTOUCH_REDIRECT 2791 11.2. The IETF XML Registry 2793 This document registers three URIs in the IETF XML registry 2794 [RFC3688]. Following the format in [RFC3688], the following 2795 registrations are requested: 2797 URI: urn:ietf:params:xml:ns:yang:ietf-zerotouch-information 2798 Registrant Contact: The NETCONF WG of the IETF. 2799 XML: N/A, the requested URI is an XML namespace. 2801 URI: urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server 2802 Registrant Contact: The NETCONF WG of the IETF. 2803 XML: N/A, the requested URI is an XML namespace. 2805 URI: urn:ietf:params:xml:ns:yang:ietf-zerotouch-device 2806 Registrant Contact: The NETCONF WG of the IETF. 2807 XML: N/A, the requested URI is an XML namespace. 2809 11.3. The YANG Module Names Registry 2811 This document registers three YANG modules in the YANG Module Names 2812 registry [RFC6020]. Following the format defined in [RFC6020], the 2813 the following registrations are requested: 2815 name: ietf-zerotouch-information 2816 namespace: urn:ietf:params:xml:ns:yang:ietf-zerotouch-information 2817 prefix: zti 2818 reference: RFC XXXX 2820 name: ietf-zerotouch-bootstrap-server 2821 namespace: urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-\ 2822 server (note: '\' used for formatting reasons only) 2823 prefix: ztbs 2824 reference: RFC XXXX 2826 name: ietf-zerotouch-device 2827 namespace: urn:ietf:params:xml:ns:yang:ietf-zerotouch-device 2828 prefix: ztd 2829 reference: RFC XXXX 2831 12. Acknowledgements 2833 The authors would like to thank for following for lively discussions 2834 on list and in the halls (ordered by last name): David Harrington, 2835 Michael Behringer, Dean Bogdanovic, Martin Bjorklund, Joe Clarke, 2836 Toerless Eckert, Stephen Farrell, Stephen Hanna, Wes Hardaker, Radek 2837 Krejci, Russ Mundy, Reinaldo Penno, Randy Presuhn, Max Pritikin, 2838 Michael Richardson, Phil Shafer, Juergen Schoenwaelder. 2840 Special thanks goes to Steve Hanna, Russ Mundy, and Wes Hardaker for 2841 brainstorming the original I-D's solution during the IETF 87 meeting 2842 in Berlin. 2844 13. References 2846 13.1. Normative References 2848 [I-D.ietf-anima-voucher] 2849 Watsen, K., Richardson, M., Pritikin, M., and T. Eckert, 2850 "Voucher Profile for Bootstrapping Protocols", draft-ietf- 2851 anima-voucher-05 (work in progress), August 2017. 2853 [ITU.X690.1994] 2854 International Telecommunications Union, "Information 2855 Technology - ASN.1 encoding rules: Specification of Basic 2856 Encoding Rules (BER), Canonical Encoding Rules (CER) and 2857 Distinguished Encoding Rules (DER)", ITU-T Recommendation 2858 X.690, 1994. 2860 [RFC1035] Mockapetris, P., "Domain names - implementation and 2861 specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, 2862 November 1987, . 2864 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2865 Requirement Levels", BCP 14, RFC 2119, 2866 DOI 10.17487/RFC2119, March 1997, 2867 . 2869 [RFC2315] Kaliski, B., "PKCS #7: Cryptographic Message Syntax 2870 Version 1.5", RFC 2315, DOI 10.17487/RFC2315, March 1998, 2871 . 2873 [RFC3315] Droms, R., Ed., Bound, J., Volz, B., Lemon, T., Perkins, 2874 C., and M. Carney, "Dynamic Host Configuration Protocol 2875 for IPv6 (DHCPv6)", RFC 3315, DOI 10.17487/RFC3315, July 2876 2003, . 2878 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2879 Housley, R., and W. Polk, "Internet X.509 Public Key 2880 Infrastructure Certificate and Certificate Revocation List 2881 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 2882 . 2884 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2885 the Network Configuration Protocol (NETCONF)", RFC 6020, 2886 DOI 10.17487/RFC6020, October 2010, 2887 . 2889 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2890 Verification of Domain-Based Application Service Identity 2891 within Internet Public Key Infrastructure Using X.509 2892 (PKIX) Certificates in the Context of Transport Layer 2893 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2894 2011, . 2896 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 2897 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 2898 DOI 10.17487/RFC6234, May 2011, 2899 . 2901 [RFC6762] Cheshire, S. and M. Krochmal, "Multicast DNS", RFC 6762, 2902 DOI 10.17487/RFC6762, February 2013, 2903 . 2905 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 2906 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, 2907 . 2909 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2910 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2911 . 2913 [RFC7227] Hankins, D., Mrugalski, T., Siodelski, M., Jiang, S., and 2914 S. Krishnan, "Guidelines for Creating New DHCPv6 Options", 2915 BCP 187, RFC 7227, DOI 10.17487/RFC7227, May 2014, 2916 . 2918 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2919 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2920 . 2922 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2923 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2924 . 2926 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2927 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2928 May 2017, . 2930 [Std-802.1AR-2009] 2931 IEEE SA-Standards Board, "IEEE Standard for Local and 2932 metropolitan area networks - Secure Device Identity", 2933 December 2009, . 2936 13.2. Informative References 2938 [I-D.ietf-netconf-keystore] 2939 Watsen, K., "Keystore Model", draft-ietf-netconf- 2940 keystore-02 (work in progress), June 2017. 2942 [I-D.ietf-netconf-netconf-client-server] 2943 Watsen, K., Wu, G., and J. Schoenwaelder, "NETCONF Client 2944 and Server Models", draft-ietf-netconf-netconf-client- 2945 server-04 (work in progress), July 2017. 2947 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2948 DOI 10.17487/RFC3688, January 2004, 2949 . 2951 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2952 (TLS) Protocol Version 1.2", RFC 5246, 2953 DOI 10.17487/RFC5246, August 2008, 2954 . 2956 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2957 and A. Bierman, Ed., "Network Configuration Protocol 2958 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2959 . 2961 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2962 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2963 . 2965 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2966 Protocol (NETCONF) Access Control Model", RFC 6536, 2967 DOI 10.17487/RFC6536, March 2012, 2968 . 2970 [RFC6698] Hoffman, P. and J. Schlyter, "The DNS-Based Authentication 2971 of Named Entities (DANE) Transport Layer Security (TLS) 2972 Protocol: TLSA", RFC 6698, DOI 10.17487/RFC6698, August 2973 2012, . 2975 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 2976 Galperin, S., and C. Adams, "X.509 Internet Public Key 2977 Infrastructure Online Certificate Status Protocol - OCSP", 2978 RFC 6960, DOI 10.17487/RFC6960, June 2013, 2979 . 2981 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 2982 System Management", RFC 7317, DOI 10.17487/RFC7317, August 2983 2014, . 2985 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 2986 RFC 8071, DOI 10.17487/RFC8071, February 2017, 2987 . 2989 Appendix A. Workflow Overview 2991 The zero touch solution presented in this document is conceptualized 2992 to be composed of the non-normative workflows described in this 2993 section. Implementation details are expected to vary. Each diagram 2994 is followed by a detailed description of the steps presented in the 2995 diagram, with further explanation on how implementations may vary. 2997 A.1. Enrollment and Ordering Devices 2999 The following diagram illustrates key interactions that may occur 3000 from when a prospective owner enrolls in a manufacturer's zero touch 3001 program to when the manufacturer ships devices for an order placed by 3002 the prospective owner. 3004 +-----------+ 3005 +------------+ |Prospective| +---+ 3006 |Manufacturer| | Owner | |NMS| 3007 +------------+ +-----------+ +---+ 3008 | | | 3009 | | | 3010 | 1. initiate enrollment | | 3011 #<-----------------------------| | 3012 # | | 3013 # | | 3014 # IDevID trust anchor | | 3015 #-----------------------------># set IDevID trust anchor | 3016 # #--------------------------->| 3017 # | | 3018 # bootstrap server | | 3019 # account credentials | | 3020 #-----------------------------># set credentials | 3021 | #--------------------------->| 3022 | | | 3023 | | | 3024 | 2. set owner certificate trust anchor | 3025 |<----------------------------------------------------------| 3026 | | | 3027 | | | 3028 | 3. place device order | | 3029 |<-----------------------------# model devices | 3030 | #--------------------------->| 3031 | | | 3032 | 4. ship devices and send | | 3033 | device identifiers and | | 3034 | ownership vouchers | | 3035 |-----------------------------># set device identifiers | 3036 | # and ownership vouchers | 3037 | #--------------------------->| 3038 | | | 3040 Each numbered item below corresponds to a numbered item in the 3041 diagram above. 3043 1. A prospective owner of a manufacturer's devices initiates an 3044 enrollment process with the manufacturer. This process includes 3045 the following: 3047 * Regardless how the prospective owner intends to bootstrap 3048 their devices, they will always obtain from the manufacturer 3049 the trust anchor certificate for the IDevID certificates. 3050 This certificate will is installed on the prospective owner's 3051 NMS so that the NMS can authenticate the IDevID certificates 3052 when they're presented to subsequent steps. 3054 * If the manufacturer hosts an Internet based bootstrap server 3055 (e.g., a redirect server) such as described in Section 4.4, 3056 then credentials necessary to configure the bootstrap server 3057 would be provided to the prospective owner. If the bootstrap 3058 server is configurable through an API (outside the scope of 3059 this document), then the credentials might be installed on the 3060 prospective owner's NMS so that the NMS can subsequently 3061 configure the manufacturer-hosted bootstrap server directly. 3063 2. If the manufacturer's devices are able to validate signed data 3064 (Section 5.4), and assuming that the prospective owner's NMS is 3065 able to prepare and sign the bootstrapping data itself, the 3066 prospective owner's NMS might set a trust anchor certificate onto 3067 the manufacturer's bootstrap server, using the credentials 3068 provided in the previous step. This certificate is the trust 3069 anchor certificate that the prospective owner would like the 3070 manufacturer to place into the ownership vouchers it generates, 3071 thereby enabling devices to trust the owner's owner certificate. 3072 How this trust anchor certificate is used to enable devices to 3073 validate signed bootstrapping data is described in Section 5.4. 3075 3. Some time later, the prospective owner places an order with the 3076 manufacturer, perhaps with a special flag checked for zero touch 3077 handling. At this time, or perhaps before placing the order, the 3078 owner may model the devices in their NMS, creating virtual 3079 objects for the devices with no real-world device associations. 3080 For instance the model can be used to simulate the device's 3081 location in the network and the configuration it should have when 3082 fully operational. 3084 4. When the manufacturer fulfills the order, shipping the devices to 3085 their intended locations, they may notify the owner of the 3086 devices's serial numbers and shipping destinations, which the 3087 owner may use to stage the network for when the devices power on. 3088 Additionally, the manufacturer may send one or more ownership 3089 vouchers, cryptographically assigning ownership of those devices 3090 to the owner. The owner may set this information on their NMS, 3091 perhaps binding specific modeled devices to the serial numbers 3092 and ownership vouchers. 3094 A.2. Owner Stages the Network for Bootstrap 3096 The following diagram illustrates how an owner might stage the 3097 network for bootstrapping devices. 3099 +----------+ +------------+ 3100 |Deployment| |Manufacturer| +------+ +------+ 3101 | Specific | | Hosted | | Local| | Local| +---------+ 3102 +---+ |Bootstrap | | Bootstrap | | DNS | | DHCP | |Removable| 3103 |NMS| | Server | | Server | |Server| |Server| | Storage | 3104 +---+ +----------+ +------------+ +------+ +------+ +---------+ 3105 | | | | | | 3106 1. | | | | | | 3107 activate | | | | | | 3108 modeled | | | | | | 3109 device | | | | | | 3110 -------->| | | | | | 3111 | 2. (optional) | | | | 3112 | configure | | | | 3113 | bootstrap | | | | 3114 | server | | | | 3115 |------->| | | | | 3116 | | | | | | 3117 | 3. (optional) configure | | | 3118 | bootstrap server | | | | 3119 |--------------------->| | | | 3120 | | | | | | 3121 | | | | | | 3122 | 4. (optional) configure DNS server| | | 3123 |---------------------------------->| | | 3124 | | | | | | 3125 | | | | | | 3126 | 5. (optional) configure DHCP server | | 3127 |------------------------------------------->| | 3128 | | | | | | 3129 | | | | | | 3130 | 6. (optional) store bootstrapping artifacts on media | 3131 |----------------------------------------------------->| 3132 | | | | | | 3133 | | | | | | 3135 Each numbered item below corresponds to a numbered item in the 3136 diagram above. 3138 1. Having previously modeled the devices, including setting their 3139 fully operational configurations and associating device serial 3140 numbers and (optionally) ownership vouchers, the owner might 3141 "activate" one or more modeled devices. That is, the owner tells 3142 the NMS to perform the steps necessary to prepare for when the 3143 real-world devices power up and initiate the bootstrapping 3144 process. Note that, in some deployments, this step might be 3145 combined with the last step from the previous workflow. Here it 3146 is depicted that an NMS performs the steps, but they may be 3147 performed manually or through some other mechanism. 3149 2. If it is desired to use a deployment specific bootstrap server, 3150 it must be configured to provide the bootstrapping information 3151 for the specific devices. Configuring the bootstrap server may 3152 occur via a programmatic API not defined by this document. 3153 Illustrated here as an external component, the bootstrap server 3154 may be implemented as an internal component of the NMS itself. 3156 3. If it is desired to use a manufacturer hosted bootstrap server, 3157 it must be configured to provide the bootstrapping information 3158 for the specific devices. The configuration must be either 3159 redirect or onboarding information. That is, either the 3160 manufacturer hosted bootstrap server will redirect the device to 3161 another bootstrap server, or provide the device with the 3162 onboarding information itself. The types of bootstrapping 3163 information the manufacturer hosted bootstrap server supports may 3164 vary by implementation; some implementations may only support 3165 redirect information, or only support onboarding information, or 3166 support both redirect and onboarding information. Configuring 3167 the bootstrap server may occur via a programmatic API not defined 3168 by this document. 3170 4. If it is desired to use a DNS server to supply bootstrapping 3171 information, a DNS server needs to be configured. If multicast 3172 DNS-SD is desired, then the server must reside on the local 3173 network, otherwise the DNS server may reside on a remote network. 3174 Please see Section 4.2 for more information about how to 3175 configure DNS servers. Configuring the DNS server may occur via 3176 a programmatic API not defined by this document. 3178 5. If it is desired to use a DHCP server to supply bootstrapping 3179 data, a DHCP server needs to be configured. The DHCP server may 3180 be accessed directly or via a DHCP relay. Please see Section 4.3 3181 for more information about how to configure DHCP servers. 3182 Configuring the DHCP server may occur via a programmatic API not 3183 defined by this document. 3185 6. If it is desired to use a removable storage device (e.g., USB 3186 flash drive) to supply bootstrapping information, the information 3187 would need to be placed onto it. Please see Section 4.1 for more 3188 information about how to configure a removable storage device. 3190 A.3. Device Powers On 3192 The following diagram illustrates the sequence of activities that 3193 occur when a device powers on. 3195 +----------+ 3196 +-----------+ |Deployment| 3197 | Source of | | Specific | 3198 +------+ | Bootstrap | |Bootstrap | +---+ 3199 |Device| | Data | | Server | |NMS| 3200 +------+ +-----------+ +----------+ +---+ 3201 | | | | 3202 | | | | 3203 | 1. if zerotouch bootstrap service | | | 3204 | is not enabled, then exit. | | | 3205 | | | | 3206 | 2. for each source supported, check | | | 3207 | for bootstrapping data. | | | 3208 |------------------------------------->| | | 3209 | | | | 3210 | 3. if onboarding information found, | | | 3211 | initialize self and, only if | | | 3212 | source is a bootstrap server, | | | 3213 | send progress updates. | | | 3214 |-------------------------------------># | | 3215 | # webhook | | 3216 | #----------------------->| 3217 | | | 3218 | 4. else if redirect-information found, for each | | 3219 | bootstrap server specified, check for data. | | 3220 |-+-------------------------------------------------->| | 3221 | | | | 3222 | | if more redirect-information is found, recurse | | 3223 | | (not depicted), else if onboarding-information | | 3224 | | found, initialize self and post progress reports | | 3225 | +--------------------------------------------------># | 3226 | # webhook | 3227 | #-------->| 3228 | 3229 | 5. retry sources and/or wait for manual provisioning. 3230 | 3232 The interactions in the above diagram are described below. 3234 1. Upon power being applied, the device checks to see if zerotouch 3235 bootstrapping is configured, such as must be the case when 3236 running its "factory default" configuration. If zerotouch 3237 bootstrapping is not configured, then the bootstrapping logic 3238 exits and none of the following interactions occur. 3240 2. For each source of bootstrapping data the device supports, 3241 preferably in order of closeness to the device (e.g., removable 3242 storage before Internet based servers), the device checks to see 3243 if there is any bootstrapping data for it there. 3245 3. If onboarding information is found, the device initializes itself 3246 accordingly (e.g., installing a boot-image and committing an 3247 initial configuration). If the source is a bootstrap server, and 3248 the bootstrap server can be trusted (i.e., TLS-level 3249 authentication), the device also sends progress reports to the 3250 bootstrap server. 3252 * The contents of the initial configuration should configure an 3253 administrator account on the device (e.g., username, ssh-rsa 3254 key, etc.), and should configure the device either to listen 3255 for NETCONF or RESTCONF connections or to initiate call home 3256 connections [RFC8071], and should disable the zerotouch 3257 bootstrapping service. 3259 * If the bootstrap server supports forwarding device progress 3260 updates to external systems (e.g., via a webhook), a 3261 "bootstrap-complete" progress report (Section 7.3) informs the 3262 external system to know when it can, for instance, initiate a 3263 connection to the device. To support this scenario further, 3264 the 'bootstrap-complete' progress update may also relay the 3265 device's SSH host keys and/or TLS certificates, with which the 3266 external system can use to authenticate subsequent connections 3267 to the device. IDevID certificates do not need to be sent as 3268 they do not need to be pinned by an NMS in order for the NMS 3269 to trust the IDevID certificate. 3271 If the device successfully completes the bootstrapping process, 3272 it exits the bootstrapping logic without considering any 3273 additional sources of bootstrapping data. 3275 4. Otherwise, if redirect information is found, the device iterates 3276 through the list of specified bootstrap servers, checking to see 3277 if it has bootstrapping data for the device. If the bootstrap 3278 server returns more redirect information, then the device 3279 processes it recursively. Otherwise, if the bootstrap server 3280 returns onboarding information, the device processes it following 3281 the description provided in (3) above. 3283 5. After having tried all supported sources of bootstrapping data, 3284 the device may retry again all the sources and/or provide 3285 manageability interfaces for manual configuration (e.g., CLI, 3286 HTTP, NETCONF, etc.). If manual configuration is allowed, and 3287 such configuration is provided, the configuration should also 3288 disable the zerotouch bootstrapping service, as the need for 3289 bootstrapping would no longer be present. 3291 Appendix B. Promoting a Connection from Untrusted to Trusted 3293 The following diagram illustrates a sequence of bootstrapping 3294 activities that promote an untrusted connection to a bootstrap server 3295 to a trusted connection to the same bootstrap server. This enables a 3296 device to limit the amount of information it might disclose to an 3297 adversary hosting an untrusted bootstrap server. 3299 +----------+ 3300 |Deployment| 3301 | Specific | 3302 +------+ |Bootstrap | 3303 |Device| | Server | 3304 +------+ +----------+ 3305 | | 3306 | 1. "HTTPS" Request ('untrusted-connection') | 3307 |------------------------------------------------------->| 3308 | 2. "HTTPS" Response (signed redirect information) | 3309 |<-------------------------------------------------------| 3310 | | 3311 | | 3312 | 3. HTTPS Request (os-name=xyz, os-version=123, etc.) | 3313 |------------------------------------------------------->| 3314 | 4. HTTPS Response (unsigned onboarding information | 3315 |<-------------------------------------------------------| 3316 | | 3318 The interactions in the above diagram are described below. 3320 1. The device initiates an untrusted connection to a bootstrap 3321 server, as is indicated by putting "HTTPS" in double quotes 3322 above. It is still an HTTPS connection, but the device is unable 3323 to authenticate the bootstrap server's TLS certificate. Because 3324 the device is unable to trust the bootstrap server, it purposely 3325 only sends the 'untrusted-connection' input parameter to the 3326 'get-bootstrapping-data' RPC, informing the bootstrap server that 3327 it doesn't trust it and may be holding back some information from 3328 the server (e.g., other input parameters, progress reports, 3329 etc.). 3331 2. The bootstrap server, seeing the 'untrusted-connection' input 3332 parameters, knows that it can either send unsigned redirect 3333 information or signed data of any type. But, in this case, the 3334 bootstrap server has the ability to sign data and chooses to 3335 respond with signed redirect information, not signed onboarding 3336 information as might be expected, securely redirecting the device 3337 back to it again. 3339 3. Upon validating the signed redirect information, the device 3340 establishes a secure connection to the bootstrap server. 3341 Unbeknownst to the device, it is the same bootstrap server it was 3342 connected to previously but, because the device is able to 3343 authenticate the bootstrap server tis time, it sends its normal 3344 'get-bootstrapping-data' request (i.e., with additional input 3345 parameters) as well as its progress reports (not depicted). 3347 4. This time, because the 'untrusted-connection' parameter was not 3348 passed, having access to all of the device's input parameters, 3349 the bootstrap server returns unsigned onboarding information to 3350 the device. 3352 Appendix C. Change Log 3354 C.1. ID to 00 3356 o Major structural update; the essence is the same. Most every 3357 section was rewritten to some degree. 3359 o Added a Use Cases section 3361 o Added diagrams for "Actors and Roles" and "NMS Precondition" 3362 sections, and greatly improved the "Device Boot Sequence" diagram 3364 o Removed support for physical presence or any ability for 3365 configlets to not be signed. 3367 o Defined the Zero Touch Information DHCP option 3369 o Added an ability for devices to also download images from 3370 configuration servers 3372 o Added an ability for configlets to be encrypted 3374 o Now configuration servers only have to support HTTP/S - no other 3375 schemes possible 3377 C.2. 00 to 01 3379 o Added boot-image and validate-owner annotations to the "Actors and 3380 Roles" diagram. 3382 o Fixed 2nd paragraph in section 7.1 to reflect current use of 3383 anyxml. 3385 o Added encrypted and signed-encrypted examples 3387 o Replaced YANG module with XSD schema 3389 o Added IANA request for the Zero Touch Information DHCP Option 3391 o Added IANA request for media types for boot-image and 3392 configuration 3394 C.3. 01 to 02 3396 o Replaced the need for a configuration signer with the ability for 3397 each NMS to be able to sign its own configurations, using 3398 manufacturer signed ownership vouchers and owner certificates. 3400 o Renamed configuration server to bootstrap server, a more 3401 representative name given the information devices download from 3402 it. 3404 o Replaced the concept of a configlet by defining a southbound 3405 interface for the bootstrap server using YANG. 3407 o Removed the IANA request for the boot-image and configuration 3408 media types 3410 C.4. 02 to 03 3412 o Minor update, mostly just to add an Editor's Note to show how this 3413 draft might integrate with the draft-pritikin-anima-bootstrapping- 3414 keyinfra. 3416 C.5. 03 to 04 3418 o Major update formally introducing unsigned data and support for 3419 Internet-based redirect servers. 3421 o Added many terms to Terminology section. 3423 o Added all new "Guiding Principles" section. 3425 o Added all new "Sources for Bootstrapping Data" section. 3427 o Rewrote the "Interactions" section and renamed it "Workflow 3428 Overview". 3430 C.6. 04 to 05 3432 o Semi-major update, refactoring the document into more logical 3433 parts 3435 o Created new section for information types 3437 o Added support for DNS servers 3439 o Now allows provisional TLS connections 3441 o Bootstrapping data now supports scripts 3443 o Device Details section overhauled 3445 o Security Considerations expanded 3447 o Filled in enumerations for notification types 3449 C.7. 05 to 06 3451 o Minor update 3453 o Added many Normative and Informative references. 3455 o Added new section Other Considerations. 3457 C.8. 06 to 07 3459 o Minor update 3461 o Added an Editorial Note section for RFC Editor. 3463 o Updated the IANA Considerations section. 3465 C.9. 07 to 08 3467 o Minor update 3469 o Updated to reflect review from Michael Richardson. 3471 C.10. 08 to 09 3473 o Added in missing "Signature" artifact example. 3475 o Added recommendation for manufacturers to use interoperable 3476 formats and file naming conventions for removable storage devices. 3478 o Added configuration-handling leaf to guide if config should be 3479 merged, replaced, or processed like an edit-config/yang-patch 3480 document. 3482 o Added a pre-configuration script, in addition to the post- 3483 configuration script from -05 (issue #15). 3485 C.11. 09 to 10 3487 o Factored ownership voucher and voucher revocation to a separate 3488 document: draft-kwatsen-netconf-voucher. (issue #11) 3490 o Removed options 'edit-config' and 'yang- 3491 patch'. (issue #12) 3493 o Defined how a signature over signed-data returned from a bootstrap 3494 server is processed. (issue #13) 3496 o Added recommendation for removable storage devices to use open/ 3497 standard file systems when possible. (issue #14) 3499 o Replaced notifications "script-[warning/error]" with "[pre/post]- 3500 script-[warning/error]". (goes with issue #15) 3502 o switched owner-certificate to be encoded using the pkcs#7 format. 3503 (issue #16) 3505 o Replaced md5/sha1 with sha256 inside a choice statement, for 3506 future extensibility. (issue #17) 3508 o A ton of editorial changes, as I went thru the entire draft with a 3509 fine-toothed comb. 3511 C.12. 10 to 11 3513 o fixed yang validation issues found by IETFYANGPageCompilation. 3514 note: these issues were NOT found by pyang --ietf or by the 3515 submission-time validator... 3517 o fixed a typo in the yang module, someone the config false 3518 statement was removed. 3520 C.13. 11 to 12 3522 o fixed typo that prevented Appendix B from loading the examples 3523 correctly. 3525 o fixed more yang validation issues found by 3526 IETFYANGPageCompilation. note: again, these issues were NOT found 3527 by pyang --ietf or by the submission-time validator... 3529 o updated a few of the notification enumerations to be more 3530 consistent with the other enumerations (following the warning/ 3531 error pattern). 3533 o updated the information-type artifact to state how it's encoded, 3534 matching the language that was in Appendix B. 3536 C.14. 12 to 13 3538 o defined a standalone artifact to encode the old information-type 3539 into a PKCS#7 structure. 3541 o standalone information artifact hardcodes JSON encoding (to match 3542 the voucher draft). 3544 o combined the information and signature PKCS#7 structures into a 3545 single PKCS#7 structure. 3547 o moved the certificate-revocations into the owner-certificate's 3548 PKCS#7 structure. 3550 o eliminated support for voucher-revocations, to reflect the 3551 voucher-draft's switch from revocations to renewals. 3553 C.15. 13 to 14 3555 o Renamed "bootstrap information" to "onboarding information". 3557 o Rewrote DHCP sections to address the packet-size limitation issue, 3558 as discussed in Chicago. 3560 o Added Ian as an author for his text-contributions to the DHCP 3561 sections. 3563 o Removed the Guiding Principles section. 3565 C.16. 14 to 15 3567 o Renamed action 'notification' to 'update-progress' and, likewise 3568 'notification-type' to 'update-type'. 3570 o Updated examples to use "base64encodedvalue==" for binary values. 3572 o Greatly simplified the "Artifact Groupings" section, and moved it 3573 as a subsection to the "Artifacts" section. 3575 o Moved the "Workflow Overview" section to the Appendix. 3577 o Renamed "bootstrap information" to "update information". 3579 o Removed "Other Considerations" section. 3581 o Tons of editorial updates. 3583 C.17. 15 to 16 3585 o tweaked language to refer to "initial state" rather than "factory 3586 default configuration", so as accommodate white-box scenarios. 3588 o added a paragraph to Intro regarding how the solution primarily 3589 regards physical machines, but could be extended to VMs by a 3590 future document. 3592 o added a pointer to the Workflow Overview section (recently moved 3593 to the Appendix) to the Intro. 3595 o added a note that, in order to simplify the verification process, 3596 the "Zerotouch Information" PKCS#7 structure MUST also contain the 3597 signing X.509 certificate. 3599 o noted that the owner certificate's must either have no Key Usage 3600 or the Key Usage must set the "digitalSignature" bit. 3602 o noted that the owner certificate's subject and subjectAltName 3603 values are not constrained. 3605 o moved/consolidated some text from the Artifacts section down to 3606 the Device Details section. 3608 o tightened up some ambiguous language, for instance, by referring 3609 to specific leaf names in the Voucher artifact. 3611 o reverted a previously overzealous s/unique-id/serial-number/ 3612 change. 3614 o modified language for when ZTP runs from when factory-default 3615 config is running to when ZTP is configured, which the factory- 3616 defaults should set . 3618 C.18. 16 to 17 3620 o Added an example for how to promote an untrusted connection to a 3621 trusted connection. 3623 o Added a "query parameters" section defining some parameters 3624 enabling scenarios raised in last call. 3626 o Added a "Disclosing Information to Untrusted Servers" section to 3627 the Security Considerations. 3629 C.19. 17 to 18 3631 o Added Security Considerations for each YANG module. 3633 o Reverted back to the device always sending its DevID cert. 3635 o Moved data tree to ac'get-bootstrapping-data' RPC. 3637 o Moved the 'update-progress' action to a 'report-progress' RPC. 3639 o Added an 'untrusted-connection' parameter to 'get-bootstrapping- 3640 data' RPC. 3642 o Added the "ietf-zerotouch-device" module. 3644 o Lots of small updates. 3646 C.20. 18 to 19 3648 o Fixed 'must' expressions, by converting 'choice' to a 'list' of 3649 'image-verification', each of which now points to a base identity 3650 called "hash-algorithm". There's just one algorithm currently 3651 defined (sha-256). Wish there was a standard crypto module that 3652 could identify such identities. 3654 Authors' Addresses 3656 Kent Watsen 3657 Juniper Networks 3659 EMail: kwatsen@juniper.net 3660 Mikael Abrahamsson 3661 T-Systems 3663 EMail: mikael.abrahamsson@t-systems.se 3665 Ian Farrer 3666 Deutsche Telekom AG 3668 EMail: ian.farrer@telekom.de