idnits 2.17.1 draft-ietf-netconf-zerotouch-18.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 1121 has weird spacing: '...version str...' == Line 1576 has weird spacing: '...rmation pkc...' == Line 1581 has weird spacing: '...ss-type enu...' == Line 1586 has weird spacing: '...ey-data str...' == Line 1589 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 17, 2017) is 2384 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 20, 2018 T-Systems 6 I. Farrer 7 Deutsche Telekom AG 8 October 17, 2017 10 Zero Touch Provisioning for NETCONF or RESTCONF based Management 11 draft-ietf-netconf-zerotouch-18 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-18" --> 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 20, 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 . . . . . . . . . . . . . . . . . . . 11 111 4. Sources of Bootstrapping Data . . . . . . . . . . . . . . . . 12 112 4.1. Removable Storage . . . . . . . . . . . . . . . . . . . . 12 113 4.2. DNS Server . . . . . . . . . . . . . . . . . . . . . . . 13 114 4.3. DHCP Server . . . . . . . . . . . . . . . . . . . . . . . 15 115 4.4. Bootstrap Server . . . . . . . . . . . . . . . . . . . . 15 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 . . . . . . . . . . . . . 33 128 7.1. API Overview . . . . . . . . . . . . . . . . . . . . . . 33 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 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 79 185 1. Introduction 187 A fundamental business requirement for any network operator is to 188 reduce costs where possible. For network operators, deploying 189 devices to many locations can be a significant cost, as sending 190 trained specialists to each site for installations is both cost 191 prohibitive and does not scale. 193 This document defines a bootstrapping strategy enabling devices to 194 securely obtain bootstrapping data with no installer action beyond 195 physical placement and connecting network and power cables. The 196 ultimate goal of this document is to enable a secure NETCONF 197 [RFC6241] or RESTCONF [RFC8040] connection to a deployment specific 198 network management system (NMS). 200 This document primarily regards physical devices, where the setting 201 of the device's initial state, described in Section 5.1, occurs 202 during the device's manufacturing process. However, the zerotouch 203 solution may be extensible to virtual machines or other such logical 204 constructs. Details for how this can be accomplished is left for 205 future work. 207 1.1. Use Cases 209 o Device connecting to a remotely administered network 211 This use-case involves scenarios, such as a remote branch 212 office or convenience store, whereby a device connects as an 213 access gateway to an ISP's network. Assuming it is not 214 possible to customize the ISP's network to provide any 215 bootstrapping support, and with no other nearby device to 216 leverage, the device has no recourse but to reach out to an 217 Internet-based bootstrap server to bootstrap from. 219 o Device connecting to a locally administered network 221 This use-case covers all other scenarios and differs only in 222 that the device may additionally leverage nearby devices, which 223 may direct it to use a local service to bootstrap from. If no 224 such information is available, or the device is unable to use 225 the information provided, it can then reach out to the network 226 just as it would for the remotely administered network use- 227 case. 229 Conceptual workflows for how zerotouch might be deployed are provided 230 in Appendix A. 232 1.2. Terminology 234 This document uses the following terms (sorted by name): 236 Artifact: The term "artifact" is used throughout to represent any of 237 the three artifacts defined in Section 3 (zero touch information, 238 ownership voucher, and owner certificate). These artifacts 239 collectively provide all the bootstrapping data a device may use. 241 Bootstrapping Data: The term "bootstrapping data" is used throughout 242 this document to refer to the collection of data that a device 243 may obtain during the bootstrapping process. Specifically, it 244 refers to the three artifacts zero touch information, owner 245 certificate, and ownership voucher, as described in Section 3. 247 Bootstrap Server: The term "bootstrap server" is used within this 248 document to mean any RESTCONF server implementing the YANG module 249 defined in Section 7.3. 251 Device: The term "device" is used throughout this document to refer 252 to the network element that needs to be bootstrapped. See 253 Section 5 for more information about devices. 255 Initial Secure Device Identifier (IDevID): The term "IDevID" is 256 defined in [Std-802.1AR-2009] as the globally unique secure 257 device identifier (DevID) installed on the device by the 258 manufacturer. This identifier is used in this document to enable 259 a bootstrap server to securely identify and authenticate the 260 device. 262 Manufacturer: The term "manufacturer" is used herein to refer to the 263 manufacturer of a device or a delegate of the manufacturer. 265 Network Management System (NMS): The acronym "NMS" is used 266 throughout this document to refer to the deployment specific 267 management system that the bootstrapping process is responsible 268 for introducing devices to. From a device's perspective, when 269 the bootstrapping process has completed, the NMS is a NETCONF or 270 RESTCONF client. 272 Onboarding Information: The term "onboarding information" is used 273 herein to refer to one of the two types of "zero touch 274 information" defined in this document, the other being "redirect 275 information". Onboarding information is formally defined by the 276 "onboarding-information" YANG-data structure in Section 6.3. 278 Owner: The term "owner" is used throughout this document to refer to 279 the person or organization that purchased or otherwise owns a 280 device. 282 Owner Certificate: The term "owner certificate" is used in this 283 document to represent an X.509 certificate that binds an owner 284 identity to a public key, which a device can use to validate a 285 signature over the zero touch information artifacts. The owner 286 certificate is one of the three bootstrapping artifacts described 287 in Section 3. 289 Ownership Voucher: The term "ownership voucher" is used in this 290 document to represent the voucher artifact defined in 291 [I-D.ietf-anima-voucher]. The ownership voucher is used to 292 assign a device to an owner. The ownership voucher is one of the 293 three bootstrapping artifacts described in Section 3. 295 Redirect Information: The term "redirect information" is used herein 296 to refer to one of the two types of "zero touch information" 297 defined in this document, the other being "onboarding 298 information". Redirect information is formally defined by the 299 "redirect-information" YANG-data structure in Section 6.3. 301 Redirect Server: The term "redirect server" is used to refer to a 302 bootstrap server that only returns redirect information. A 303 redirect server is particularly useful when hosted by a 304 manufacturer, as a well-known (e.g., Internet-based) resource to 305 redirect devices to deployment-specific bootstrap servers. 307 Signed Data: The term "signed data" is used throughout to mean 308 either redirect information or onboarding information that has 309 been signed, specifically by a private key possessed by a 310 device's owner. 312 Unsigned Data: The term "unsigned data" is used throughout to mean 313 either redirect information or onboarding information that has 314 not been signed. 316 Zero Touch Information: The term "zero touch information" is used 317 generally herein to refer either redirect information or 318 onboarding information. Zero touch information is one of the 319 three bootstrapping artifacts described in Section 3. 321 1.3. Requirements Language 323 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 324 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 325 "OPTIONAL" in this document are to be interpreted as described in BCP 326 14 [RFC2119] [RFC8174] when, and only when, they appear in all 327 capitals, as shown here. 329 1.4. Tree Diagram Notation 331 A simplified graphical representation of the data models is used in 332 this document. The meaning of the symbols in these diagrams is as 333 follows: 335 o Brackets "[" and "]" enclose list keys. 337 o Braces "{" and "}" enclose feature names, and indicate that the 338 named feature must be present for the subtree to be present. 340 o Abbreviations before data node names: "rw" (read-write) represents 341 configuration data and "ro" (read-only) represents state data. 343 o Symbols after data node names: "?" means an optional node, "!" 344 means a presence container, and "*" denotes a list and leaf-list. 346 o Parentheses enclose choice and case nodes, and case nodes are also 347 marked with a colon (":"). 349 o Ellipsis ("...") stands for contents of subtrees that are not 350 shown. 352 2. Types of Bootstrapping Information 354 This document defines two types of information that devices access 355 during the bootstrapping process. These information types are 356 described in this section. Examples are provided in Section 6.2 358 2.1. Redirect Information 360 Redirect information redirects a device to another bootstrap server. 361 Redirect information encodes a list of bootstrap servers, each 362 defined by its hostname or IP address, an optional port, and an 363 optional trust anchor certificate. 365 Redirect information is YANG modeled data formally defined by the 366 "redirect-information" container in the YANG module presented in 367 Section 6.3. This container has the tree diagram shown below. 368 Please see Section 1.4 for tree diagram notation. 370 +--:(redirect-information) 371 +--ro redirect-information 372 +--ro bootstrap-server* [address] 373 +--ro address inet:host 374 +--ro port? inet:port-number 375 +--ro trust-anchor? binary 377 Redirect information MAY be trusted or untrusted. The redirect 378 information is trusted whenever it is obtained via a secure 379 connection to a trusted bootstrap server, or whenever it is signed by 380 the device's owner. In all other cases, the redirect information is 381 untrusted. 383 Trusted redirect information is useful for enabling a device to 384 establish a secure connection to a bootstrap server, which is 385 possible when the redirect information includes the bootstrap 386 server's trust anchor certificate. When a device is able to 387 establish a secure connection to a bootstrap server, any data 388 obtained is implicitly trusted, and thus does not need to be signed. 390 Untrusted redirect information is useful for directing a device to a 391 bootstrap server where signed data has been staged for it to obtain. 392 When the redirect information is untrusted, the device MUST discard 393 any potentially included trust anchor certificates and SHOULD 394 establish a provisional connection (by blindly accepting the TLS 395 certificate) to any of the specified bootstrap servers. In this 396 case, the device MUST NOT trust the bootstrap server, and data 397 provided by the bootstrap server MUST be signed for it to be of any 398 use to the device. 400 How devices process redirect information is formally described in 401 Section 5.5. 403 2.2. Onboarding Information 405 Onboarding information provides all the data necessary for a device 406 to bootstrap itself, in order to be considered ready to be managed 407 (e.g., by an NMS). As defined in this document, this data includes 408 information about a boot image the device must be running, an initial 409 configuration the device must commit, and optional scripts that, if 410 specified, the device must successfully execute. 412 Onboarding information is YANG modeled data formally defined by the 413 "onboarding-information" container in the YANG module presented in 414 Section 6.3. This container has the tree diagram shown below. 415 Please see Section 1.4 for tree diagram notation. 417 +--:(onboarding-information) 418 +--ro onboarding-information 419 +--ro boot-image 420 | +--ro name string 421 | +--ro (hash-algorithm) 422 | | +--:(sha256) 423 | | +--ro sha256? string 424 | +--ro uri* inet:uri 425 +--ro configuration-handling enumeration 426 +--ro pre-configuration-script? script 427 +--ro configuration? 428 +--ro post-configuration-script? script 430 Onboarding information MUST be trusted for it to be of any use to a 431 device. There is no option for a device to process untrusted 432 onboarding information. 434 Onboarding information is trusted whenever it is obtained via a 435 secure connection to a trusted bootstrap server, or whenever it is 436 signed by the device's owner. In all other cases, the onboarding 437 information is untrusted. 439 How devices process onboarding information is formally described in 440 Section 5.6. 442 3. Artifacts 444 This document defines three artifacts that can be made available to 445 devices while they are bootstrapping. Each source of bootstrapping 446 information specifies a means for providing each of the artifacts 447 defined in this section (see Section 4). 449 3.1. Zero Touch Information 451 The zero touch information artifact encodes the essential 452 bootstrapping data for the device. This artifact is used to encode 453 the redirect information and onboarding information types discussed 454 in Section 2. 456 The zero touch information artifact is a PKCS#7 SignedData structure, 457 as specified by Section 9.1 of [RFC2315], encoded using ASN.1 458 distinguished encoding rules (DER), as specified in ITU-T X.690 459 [ITU.X690.1994]. The PKCS#7 structure MUST contain JSON-encoded 460 content conforming to the YANG module specified in Section 6.3. 462 In order for the zero touch information artifact to be trusted when 463 conveyed over an untrusted transport, the PKCS#7 structure MUST also 464 contain a "signerInfo" structure, as described in Section 9.1 of 465 [RFC2315], containing a signature generated over the content using 466 the private key associated with the owner certificate (Section 3.2). 467 In order to simplify the verification process, the PKCS#7 structure 468 SHOULD also contain the signing X.509 certificate (i.e. the owner 469 certificate). 471 3.2. Owner Certificate 473 The owner certificate artifact is an X.509 certificate [RFC5280] that 474 is used to identify an "owner" (e.g., an organization). The owner 475 certificate can be signed by any certificate authority (CA). The 476 owner certificate MUST either have no Key Usage specified, or the Key 477 Usage MUST at least set the "digitalSignature" bit. The values for 478 the owner certificate's "subject" and/or "subjectAltName" are not 479 constrained by this document. 481 The owner certificate is used by a device to verify the signature 482 over the zero touch information artifact (Section 3.1) that the 483 device should have also received, as described in Section 3.4. In 484 particular, the device verifies the signature using the public key in 485 the owner certificate over the content contained within the zero 486 touch information artifact. 488 The owner certificate artifact is formally an unsigned PKCS #7 489 SignedData structure, as specified by Section 9.1 in [RFC2315], 490 encoded using ASN.1 distinguished encoding rules (DER), as specified 491 in ITU-T X.690 [ITU.X690.1994]. 493 The owner certificate PKCS#7 structure MUST contain the owner 494 certificate itself, as well as all intermediate certificates leading 495 up to the 'pinned-domain-cert' certificate specified in the ownership 496 voucher. The owner certificate artifact MAY optionally include the 497 'pinned-domain-cert' as well. 499 Additionally, in order to support devices deployed on private 500 networks, the owner certificate PKCS#7 structure MAY also contain 501 suitably fresh CRLs [RFC5280] and/or OCSP Responses [RFC6960]. 502 Having these revocation objects stapled to the owner certificate 503 precludes the need for the device to have to download them 504 dynamically using the CRL distribution point or an OCSP responder 505 specified in the associated certificates. 507 3.3. Ownership Voucher 509 The ownership voucher artifact is used to securely identify a 510 device's owner, as it is known to the manufacturer. The ownership 511 voucher is signed by the device's manufacturer. 513 The ownership voucher is used to verify the owner certificate 514 (Section 3.2) that the device should have also received, as described 515 in Section 3.4. In particular, the device verifies that the owner 516 certificate has a chain of trust leading to the trusted certificate 517 included in the ownership voucher ('pinned-domain-cert'), even if it 518 is itself (e.g., self-signed certificate). 520 The ownership voucher artifact, including its encoding, is formally 521 defined in [I-D.ietf-anima-voucher]. 523 3.4. Artifact Groupings 525 This section lists all the possible bootstrapping artifacts, but only 526 certain groupings of these artifacts make sense to return in the 527 various bootstrapping situations described in this document. These 528 groupings are: 530 Unsigned Information: This grouping is useful for cases when 531 transport level security can be used to convey trust (e.g., 532 HTTPS), or when the information can be processed in a 533 provisional manner (i.e. unsigned redirect information). 535 Signed Information, without revocations: The grouping is useful 536 when signed information is needed, because it's obtained from 537 an untrusted source, and it cannot be processed provisionally, 538 and yet either revocations are not needed or they can be 539 obtained dynamically. 541 Signed Information, with revocations: The grouping is useful when 542 signed information is needed, because it's obtained from an 543 untrusted source, and it cannot be processed provisionally, and 544 revocations are needed and cannot be obtained dynamically. 546 The artifacts associated with these groupings are described below: 548 Zero Touch Ownership Owner 549 Grouping Information Voucher Certificate 550 -------------------- ------------- ------------ ----------- 551 Unsigned Information Yes, no sig No No 553 Signed Information, Yes, with sig Yes, without Yes, without 554 without revocations revocations revocations 556 Signed Information, Yes, with sig Yes, with Yes, with 557 with revocations revocations revocations 559 4. Sources of Bootstrapping Data 561 This section defines some sources for bootstrapping data that a 562 device can access. The list of sources defined here is not meant to 563 be exhaustive. It is left to future documents to define additional 564 sources for obtaining bootstrapping data. 566 For each source of bootstrapping data defined in this section, 567 details are given for how the three artifacts listed in Section 3 are 568 provided. 570 4.1. Removable Storage 572 A directly attached removable storage device (e.g., a USB flash 573 drive) MAY be used as a source of zero touch bootstrapping data. 575 Use of a removable storage device is compelling, as it doesn't 576 require any external infrastructure to work. It is notable that the 577 raw boot image file can also be located on the removable storage 578 device, enabling a removable storage device to be a fully self- 579 standing bootstrapping solution. 581 To use a removable storage device as a source of bootstrapping data, 582 a device need only detect if the removable storage device is plugged 583 in and mount its filesystem. 585 A removable storage device is an untrusted source of bootstrapping 586 data. This means that the information stored on the removable 587 storage device MUST either be signed, or be information that can be 588 processed provisionally (e.g., unsigned redirect information). 590 From an artifact perspective, since a removable storage device 591 presents itself as a filesystem, the bootstrapping artifacts need to 592 be presented as files. The three artifacts defined in Section 3 are 593 mapped to files below. 595 Artifact to File Mapping: 597 Zero Touch Information: Mapped to a file containing the binary 598 artifact described in Section 3.1 (e.g., zerotouch- 599 information.pk7). 601 Owner Certificate: Mapped to a file containing the binary 602 artifact described in Section 3.2 (e.g., owner- 603 certificate.pk7). 605 Ownership Voucher: Mapped to a file containing the binary 606 artifact described in Section 3.3 (e.g., ownership- 607 voucher.pk7). 609 The format of the removable storage device's filesystem and the 610 naming of the files are outside the scope of this document. However, 611 in order to facilitate interoperability, it is RECOMMENDED devices 612 support open and/or standards based filesystems. It is also 613 RECOMMENDED that devices assume a file naming convention that enables 614 more than one instance of bootstrapping data to exist on a removable 615 storage device. The file naming convention SHOULD be unique to the 616 manufacturer, in order to enable bootstrapping data from multiple 617 manufacturers to exist on a removable storage device. 619 4.2. DNS Server 621 A DNS server MAY be used as a source of zero touch bootstrapping 622 data. 624 Using a DNS server may be a compelling option for deployments having 625 existing DNS infrastructure, as it enables a touchless bootstrapping 626 option that does not entail utilizing an Internet based resource 627 hosted by a 3rd-party. 629 To use a DNS server as a source of bootstrapping data, a device MAY 630 perform a multicast DNS [RFC6762] query searching for the service 631 "_zerotouch._tcp.local.". Alternatively the device MAY perform DNS- 632 SD [RFC6763] via normal DNS operation, using the domain returned to 633 it from the DHCP server; for example, searching for the service 634 "_zerotouch._tcp.example.com". 636 Unsigned DNS records (e.g., not using DNSSEC as described in 637 [RFC6698]) are an untrusted source of bootstrapping data. This means 638 that the information stored in the DNS records either MUST be signed, 639 or MUST be information that can be processed provisionally (e.g., 640 unsigned redirect information). 642 From an artifact perspective, since a DNS server presents resource 643 records (Section 3.2.1 of [RFC1035]), the bootstrapping artifacts 644 need to be presented as resource records. The three artifacts 645 defined in Section 3 are mapped to resource records below. 647 Artifact to Resource Record Mapping: 649 Zero Touch Information: Mapped to a TXT record called "zt-info" 650 containing the base64-encoding of the binary artifact described 651 in Section 3.1. 653 Owner Certificate: Mapped to a TXT record called "zt-cert" 654 containing the base64-encoding of the binary artifact described 655 in Section 3.2. 657 Ownership Voucher: Mapped to a TXT record called "zt-voucher" 658 containing the base64-encoding of the binary artifact described 659 in Section 3.3. 661 TXT records have an upper size limit of 65535 bytes (Section 3.2.1 in 662 RFC1035), since "RDLENGTH" is a 16-bit field. Please see 663 Section 3.1.3 in RFC4408 for how a TXT record can achieve this size. 664 Due to this size limitation, some zero touch information artifacts 665 may not fit. In particular, onboarding information could hit this 666 upper bound, depending on the size of the included configuration and 667 scripts. 669 When onboarding information (not redirect information) is provided, 670 the URL for the boot-image the device can download would have to 671 point to another server (e.g., http://, ftp://, etc.), as DNS servers 672 do not themselves distribute files. 674 4.3. DHCP Server 676 A DHCP server MAY be used as a source of zero touch bootstrapping 677 data. 679 Using a DHCP server may be a compelling option for deployments having 680 existing DHCP infrastructure, as it enables a touchless bootstrapping 681 option that does not entail utilizing an Internet based resource 682 hosted by a 3rd-party. 684 A DHCP server is an untrusted source of bootstrapping data. Thus the 685 information stored on the DHCP server either MUST be signed, or it 686 MUST be information that can be processed provisionally (e.g., 687 unsigned redirect information). 689 However, unlike other sources of bootstrapping data described in this 690 document, the DHCP protocol (especially DHCP for IPv4) is limited in 691 the amount of data that can be conveyed, to the extent that signed 692 data cannot be communicated. Thus only unsigned redirect information 693 can be conveyed. 695 Since the redirect information is unsigned, it SHOULD NOT include the 696 optional trust anchor certificate, as the device would have to 697 discard it anyway. The DHCP options defined in Section 9 do not 698 enable the certificate to be communicated. 700 From an artifact perspective, the three artifacts defined in 701 Section 3 are mapped to the DHCP fields specified in Section 9 as 702 follows: 704 Zero Touch Information: This artifact is not supported directly. 705 Instead, the essence of redirect information (not onboarding 706 information) is mapped to the DHCP fields described in 707 Section 9. 709 Owner Certificate: Not supported. There is not enough space in 710 the DHCP packet to hold an owner certificate artifact. 712 Ownership Voucher: Not supported. There is not enough space in 713 the DHCP packet to hold an ownership voucher artifact. 715 4.4. Bootstrap Server 717 A bootstrap server MAY be used as a source of zero touch 718 bootstrapping data. A bootstrap server is defined as a RESTCONF 719 [RFC8040] server implementing the YANG module provided in Section 7. 721 Using a bootstrap server as a source of bootstrapping data is a 722 compelling option as it MAY use transport-level security, in lieu of 723 signed data, which may be easier to deploy in some situations. 724 Additionally, the bootstrap server is able to receive progress 725 updates from devices, which may be critical to some deployments 726 (e.g., the passing of the device's SSH host keys). 728 A bootstrap server may be a trusted or an untrusted source of 729 bootstrapping data, depending on if the device learned about the 730 bootstrap server's trust anchor from a trusted source. When a 731 bootstrap server is trusted, the information returned from it MAY be 732 signed. However, when the server is untrusted, in order for its 733 information to be of any use to the device, the bootstrap information 734 MUST either be signed or be information that can be processed 735 provisionally (e.g., unsigned redirect information). 737 From an artifact perspective, since a bootstrap server presents data 738 as a YANG-modeled data, the bootstrapping artifacts need to be mapped 739 to the YANG module. The three artifacts defined in Section 3 are 740 mapped to 'output' node of the 'get-bootstrapping-data' RPC defined 741 in Section 7.3 below. 743 Artifact to Bootstrap Server Mapping: 745 Zero Touch Information: Mapped to the 'zerotouch-information' 746 leaf in the output of the 'get-bootstrapping-data' RPC. 748 Owner Certificate: Mapped to the 'owner-certificate' leaf in the 749 output of the 'get-bootstrapping-data' RPC. 751 Ownership Voucher: Mapped to the 'ownership-voucher' leaf in the 752 output of the 'get-bootstrapping-data' RPC. 754 Unlike any other source of bootstrapping data described in this 755 document, a bootstrap server is not only a source of data, but it can 756 also receive data from devices using the YANG-defined 'report- 757 progress' RPC defined in the YANG module (Section 7.3). The 'report- 758 progress' RPC enables visibility into the bootstrapping process 759 (e.g., warnings and errors), and provides potentially useful 760 completion status information (e.g., the device's SSH host-keys). 762 While RESTCONF servers typically support a nested hierarchy of 763 resources, zero touch bootstrap servers only have the two RPCs 'get- 764 bootstrapping-data' and 'report-progress'. These RPCs use the 765 authenticated RESTCONF username to isolate the execution of the RPC 766 from other devices. 768 5. Device Details 770 Devices supporting the bootstrapping strategy described in this 771 document MUST have the preconfigured state and bootstrapping logic 772 described in the following sections. 774 5.1. Initial State 776 +-------------------------------------------------------------+ 777 | | 778 | | 779 | +---------------------------------------------------------+ | 780 | | | | 781 | | | | 782 | | 1. flag to enable zerotouch bootstrapping set to "true" | | 783 | +---------------------------------------------------------+ | 784 | | 785 | +---------------------------------------------------------+ | 786 | | | | 787 | | | | 788 | | 2. IDevID cert & associated intermediate certificate(s) | | 789 | | 3. list of trusted well-known bootstrap servers | | 790 | | 4. list of trust anchor certs for bootstrap servers | | 791 | | 5. trust anchor cert for verifying ownership vouchers | | 792 | +---------------------------------------------------------+ | 793 | | 794 | +----------------------+ | 795 | | | | 796 | | | | 797 | | 6. private key | | 798 | +----------------------+ | 799 | | 800 +-------------------------------------------------------------+ 802 Each numbered item below corresponds to a numbered item in the 803 diagram above. 805 1. Devices MUST have a configurable variable that is used to enable/ 806 disable the zerotouch bootstrapping. This variable MUST be 807 enabled by default in order for zerotouch bootstrapping to run 808 when the device first powers on. Because it is a goal that the 809 configuration installed by the bootstrapping process is able to 810 disable zerotouch bootstrapping, and because said configuration 811 may be merged into the existing configuration, using a 812 configuration node that relies on presence is NOT RECOMMENDED, as 813 it cannot be removed by the merging process. 815 2. Devices that support loading bootstrapping data from bootstrap 816 servers (see Section 4.4), whether preconfigured or learned 817 through the bootstrapping process, MUST possess an initial device 818 identifier (IDevID), as defined in [Std-802.1AR-2009]. The 819 IDevID is an X.509 certificate encoding, amongst other things, 820 the device's serial number and hardware manufacturer. The device 821 MUST also possess any intermediate certificates between the 822 IDevID certificate and the manufacturer's IDevID trust anchor 823 certificate provided to prospective owners separately (e.g., 824 Appendix A.1). 826 3. Devices that support loading bootstrapping data from well-known 827 bootstrap servers MUST possess a list of the well-known bootstrap 828 servers. Consistent with redirect information (Section 2.1, each 829 bootstrap server MAY be identified by its hostname or IP address, 830 and an optional port. 832 4. Devices that support loading bootstrapping data from well-known 833 bootstrap servers MUST also possess a list of trust anchor 834 certificates that can be used to secure the TLS connection to the 835 well-known bootstrap servers. 837 5. Devices that support loading signed data (see Section 1.2) MUST 838 possess the manufacturer's trust anchor certificate for 839 validating ownership vouchers. 841 6. Devices MUST possess a private key that corresponds to the public 842 key encoded in the device's IDevID certificate. This private key 843 SHOULD be securely stored, ideally in a cryptographic processor 844 (e.g., a TPM). 846 A YANG module representing this data is provided in Section 8. 848 5.2. Boot Sequence 850 A device claiming to support the bootstrapping strategy defined in 851 this document MUST support the boot sequence described in this 852 section. 854 Power On 855 | 856 v No 857 1. Zerotouch bootstrapping configured ------> Boot normally 858 | 859 | Yes 860 v 861 2. For each supported source of bootstrapping data, 862 try to load bootstrapping data from the source 863 | 864 | 865 v Yes 866 3. Able to bootstrap from any source? -----> Run with new config 867 | 868 | No 869 v 870 4. Loop and/or wait for manual provisioning. 872 Each numbered item below corresponds to a numbered item in the 873 diagram above. 875 1. When the device powers on, it first checks to see if zerotouch 876 bootstrapping is configured, as is expected to be the case for 877 the device's preconfigured state. If zerotouch bootstrapping is 878 not configured, then the device boots normally. 880 2. The device iterates over its list of sources for bootstrapping 881 data (Section 4). Details for how to processes a source of 882 bootstrapping data are provided in Section 5.3. 884 3. If the device is able to bootstrap itself from any of the sources 885 of bootstrapping data, it runs with the new bootstrapped 886 configuration. 888 4. Otherwise the device MAY loop back through the list of 889 bootstrapping sources again and/or wait for manual provisioning. 891 5.3. Processing a Source of Bootstrapping Data 893 This section describes a recursive algorithm that devices can use to, 894 ultimately, obtain onboarding information. The algorithm is 895 recursive because sources of bootstrapping data may return redirect 896 information, which causes the algorithm to run again, for the newly 897 discovered sources of bootstrapping information. An expression that 898 captures all possible successful sequences of bootstrapping 899 information is zero or more redirect information responses, followed 900 by one onboarding information response. 902 An important aspect of the algorithm is knowing when data needs to be 903 signed or not. The following figure provides a summary of options: 905 Untrusted Source Trusted Source 906 Kind of Bootstrapping Data Can Provide? Can Provide? 908 Unsigned Redirect Info : Yes+ Yes 909 Signed Redirect Info : Yes Yes* 910 Unsigned Onboarding Info : No Yes 911 Signed Onboarding Info : Yes Yes* 913 The '+' above denotes that the source redirected to MUST 914 return signed data, or more unsigned redirect information. 916 The '*' above denotes that, while possible, it is generally 917 unnecessary for a trusted source to return signed data. 919 The recursive algorithm uses a conceptual global-scoped variable 920 called "trust-state". The trust-state variable is initialized to 921 FALSE. The ultimate goal of this algorithm is for the device to 922 process onboarding information (Section 2.2) while the trust-state 923 variable is TRUE. 925 If the source of bootstrapping data (Section 4) is a bootstrap server 926 (Section 4.4), and the device is able to authenticate the bootstrap 927 server using X.509 certificate path validation ([RFC6125], Section 6) 928 to one of the device's preconfigured trust anchors, or to a trust 929 anchor that it learned from a previous step, then the device MUST set 930 trust-state to TRUE. 932 For any source of bootstrapping data (e.g., Section 4), if the 933 bootstrapping data returned is signed and the device is able to 934 validate the signed data using the algorithm described in 935 Section 5.4, then the device MUST set trust-state to TRUE, else the 936 device MUST set trust-state to FALSE. Note, this is worded to cover 937 the special case when signed data is returned even from a trusted 938 bootstrap server. 940 If the bootstrapping data is onboarding information, and trust-state 941 is FALSE, the device MUST exit the recursive algorithm (as this is 942 not allowed, see the figure above), returning to the state machine 943 described in Section 5.2. Otherwise, the device MUST attempt to 944 process the onboarding information as described in Section 5.6. In 945 either case, success or failure, the device MUST exit the recursive 946 algorithm, returning to the state machine described in Section 5.2, 947 the only difference being in how it responds to the "Able to 948 bootstrap from any source?" conditional described in the figure in 949 the section. 951 If the bootstrapping data is redirect information, the device MUST 952 process the redirect information as described in Section 5.5. This 953 is the recursion step, it will cause the device to reenter this 954 algorithm, but this time the data source will definitely be a 955 bootstrap server, as that is all redirect information is able to 956 redirect a device to. 958 5.4. Validating Signed Data 960 Whenever a device is presented signed data, it MUST validate the 961 signed data as described in this section. This includes the case 962 where the signed data is provided by a trusted source. 964 Whenever there is signed data, the device MUST also be provided an 965 ownership voucher and an owner certificate. How all the needed 966 artifacts are provided for each source of bootstrapping data is 967 defined in Section 4. 969 The device MUST first authenticate the ownership voucher by 970 validating its signature to one of its preconfigured trust anchors 971 (see Section 5.1), which may entail using additional intermediate 972 certificates attached to the ownership voucher. If the device has an 973 accurate clock, it MUST ensure that the ownership voucher was created 974 in the past (i.e., 'created-on' < now). If the 'expires-on' leaf is 975 present, the device MUST verify that the ownership voucher has not 976 yet expired (i.e., now < 'expires-on'), which requires an accurate 977 clock. The device MUST verify that the ownership voucher's 978 'assertion' value is acceptable (e.g., some devices may only accept 979 the assertion value 'verified'). The device MUST verify that the 980 ownership voucher specifies the device's serial number in the 981 'serial-number' leaf. If the 'idevid-issuer' leaf is present, the 982 device MUST verify that the value is set correctly. If the 983 authentication of the ownership voucher is successful, the device 984 extracts the 'pinned-domain-certificate' node, an X.509 certificate, 985 that is needed to verify the owner certificate in the next step. 987 The device MUST next authenticate the owner certificate by performing 988 X.509 certificate path verification to the trusted certificate 989 extracted from the ownership voucher's 'pinned-domain-cert' node. 990 This verification may entail using additional intermediate 991 certificates attached to the owner certificate artifact. If the 992 ownership voucher's 'domain-cert-revocation-checks' node's value is 993 set to "true", the device MUST verify the revocation status of the 994 certificate chain used to sign the owner certificate and, if the 995 revocation status is not attainable or if it is determined that a 996 certificate has been revoked, the device MUST not validate the owner 997 certificate. 999 Finally the device MUST verify the signature over the information 1000 artifact was generated by the private key matching the public key 1001 from the owner certificate. 1003 If any of these steps fail, then the device MUST invalidate the data 1004 and not perform any subsequent steps. 1006 5.5. Processing Redirect Information 1008 In order to process redirect information (Section 2.1), the device 1009 MUST follow the steps presented in this section. 1011 Processing redirect information is straightforward. The device 1012 sequentially steps through the list of provided bootstrap servers 1013 until it can find one it can bootstrap from. 1015 If a hostname is provided, and the hostname's DNS resolution is to 1016 more than one IP address, the device MUST attempt to connect to all 1017 of the DNS resolved addresses at least once, before moving on to the 1018 next bootstrap server. If the device is able to obtain bootstrapping 1019 data from any of the DNS resolved addresses, it MUST immediately 1020 process that data, without attempting to connect to any of the other 1021 DNS resolved addresses. 1023 If the redirect information is trusted (e.g., trust-state is TRUE), 1024 and the bootstrap server entry contains a trust anchor certificate, 1025 then the device MUST authenticate the specified bootstrap server 1026 RESTCONF TLS server certificate using X.509 certificate path 1027 validation ([RFC6125], Section 6) to the specified trust anchor. If 1028 the device is unable to authenticate the bootstrap server to the 1029 specified trust anchor, the device MAY attempt a provisional 1030 connection to the bootstrap server (i.e., by blindly accepting its 1031 server certificate) and setting trust-state to FALSE. 1033 If the redirect information is untrusted (e.g., trust-state is 1034 FALSE), the device MUST discard any trust anchors provided by the 1035 redirect information and establish a provisional connection to the 1036 bootstrap server (i.e., by blindly accepting its TLS server 1037 certificate). 1039 5.6. Processing Onboarding Information 1041 In order to process onboarding information (Section 2.2), the device 1042 MUST follow the steps presented in this section. 1044 When processing onboarding information, the device MUST first process 1045 the boot image information, then execute the pre-configuration script 1046 (if any), then commit the initial configuration, and then execute the 1047 post-configuration script (if any), in that order. If the device 1048 encounters an error at any step, it MUST NOT proceed to the next 1049 step. When the onboarding information was obtained from a trusted 1050 bootstrap server, the device SHOULD send progress reports throughout 1051 the bootstrapping process using the bootstrap server's 'report- 1052 progress' RPC. 1054 First the device MUST determine if the image it is running satisfies 1055 the specified boot image criteria (e.g., name and/or fingerprint 1056 match). If it does not, the device MUST download (using the supplied 1057 URI), verify, and install the specified boot image, and then reboot. 1058 To verify the downloaded boot image, the device MUST check that the 1059 boot image file matches the fingerprint (e.g., sha256) supplied by 1060 the onboarding information. Upon rebooting, the bootstrapping 1061 process runs again, which will eventually come to this very point, 1062 but this time the device's running image will satisfy the specified 1063 criteria, and thus the device will move to processing the next step. 1065 Next, for devices that support executing scripts, if a pre- 1066 configuration script has been specified, the device MUST execute the 1067 script and check its exit status code to determine if had any 1068 warnings or errors. In the case of errors, the device MUST reset 1069 itself in such a way that wipes out any bad state the script may have 1070 left behind. 1072 Next the device commits the provided initial configuration. Assuming 1073 no errors, the device moves to processing the next step. 1075 Again, for devices that support executing scripts, if a post- 1076 configuration script has been specified, the device MUST execute the 1077 script and check its exit status code to determine if it had any 1078 warnings or errors. In the case of errors, the device MUST reset 1079 itself in such a way that wipes out any bad state the script may have 1080 left behind. 1082 At this point, the device has completely processed the bootstrapping 1083 data and is ready to be managed. If the device obtained the 1084 onboarding information from a trusted bootstrap server, the device 1085 MUST post the 'bootstrap-complete' progress report now, using the 1086 bootstrap server's 'report-progress' RPC. 1088 At this point, the device is running its initial configuration. 1089 Notably, if NETCONF Call Home or RESTCONF Call Home [RFC8071] is 1090 configured, the device initiates trying to establish a call home 1091 connection at this time. 1093 6. The Zero Touch Information Data Model 1095 This section defines a YANG 1.1 [RFC7950] module that is used to 1096 define the data model for the zero touch information artifact 1097 described in Section 3.1. This data model uses the 'yang-data' 1098 extension statement defined in RFC 8040. Examples illustrating this 1099 data model are provided in Section 6.2. 1101 6.1. Data Model Overview 1103 The following tree diagram provides an overview of the data model for 1104 the zero touch information artifact. The syntax used for this tree 1105 diagram is described in Section 1.4. 1107 module: ietf-zerotouch-information 1109 yang-data zerotouch-information: 1110 +---- (information-type) 1111 +--:(redirect-information) 1112 | +---- redirect-information 1113 | +---- bootstrap-server* [address] 1114 | +---- address inet:host 1115 | +---- port? inet:port-number 1116 | +---- trust-anchor? binary 1117 +--:(onboarding-information) 1118 +---- onboarding-information 1119 +---- boot-image 1120 | +---- os-name string 1121 | +---- os-version string 1122 | +---- uri* inet:uri 1123 | +---- (hash-algorithm)? 1124 | +--:(sha256) 1125 | +---- sha256? yang:hex-string 1126 +---- configuration-handling? enumeration 1127 +---- pre-configuration-script? script 1128 +---- configuration? 1129 +---- post-configuration-script? script 1131 6.2. Example Usage 1133 The following example illustrates how redirect information 1134 (Section 2.1) can be encoded using JSON, as is needed by the zero 1135 touch information artifact. 1137 { 1138 "ietf-zerotouch-information:redirect-information" : { 1139 "bootstrap-server" : [ 1140 { 1141 "address" : "phs1.example.com", 1142 "port" : 8443, 1143 "trust-anchor" : "base64encodedvalue==" 1144 }, 1145 { 1146 "address" : "phs2.example.com", 1147 "port" : 8443, 1148 "trust-anchor" : "base64encodedvalue==" 1149 }, 1150 { 1151 "address" : "phs3.example.com", 1152 "port" : 8443, 1153 "trust-anchor" : "base64encodedvalue==" 1154 } 1155 ] 1156 } 1157 } 1159 The following example illustrates how onboarding information 1160 (Section 2.2) can be encoded using JSON, as is needed by the zero 1161 touch information artifact. 1163 Note: the sample configuration used in the below example configures 1164 an administrator account with an SSH public key, configures keystore 1165 with an authentication certificate, configures NETCONF Call Home and, 1166 lastly, disables the zerotouch bootstrapping service. This is 1167 acheived through use of YANG modules "ietf-system" from [RFC7317], 1168 "ietf-keystore" from [I-D.ietf-netconf-keystore], "ietf-netconf- 1169 server" from [I-D.ietf-netconf-netconf-client-server] and "ietf- 1170 zerotouch-device" from this document. 1172 [ note: '\' line wrapping for formatting only] 1174 { 1175 "ietf-zerotouch-information:onboarding-information" : { 1177 "boot-image" : { 1178 "os-name" : "VendorOS", 1179 "os-version" : "17.2R1.6", 1180 "uri" : [ "http://some/path/to/raw/file" ], 1181 "sha256" : "ba:ec:cf:a5:67:82:b4:10:77:c6:67:a6:22:ab:7d:50:04\ 1182 :a7:8b:8f:0e:db:02:8b:f4:75:55:fb:c1:13:b2:33" 1183 }, 1184 "configuration-handling" : "merge", 1186 "configuration" : { 1187 "ietf-system:system" : { 1188 "authentication" : { 1189 "user" : { 1190 "name" : "admin", 1191 "authorized-key" : { 1192 "name" : "admin's rsa ssh host-key", 1193 "algorithm" : "ssh-rsa", 1194 "key-data" : "base64encodedvalue==" 1195 } 1196 } 1197 } 1198 }, 1199 "ietf-keystore:keystore" : { 1200 "pinned-certificates" : { 1201 "name" : "deployment-specific-ca-certs", 1202 "description" : "Certs used to auth client connections.", 1203 "pinned-certificate" : { 1204 "name" : "ca.example.com", 1205 "data" : "base64encodedvalue==" 1206 } 1207 }, 1208 "pinned-certificates" : { 1209 "name" : "explicitly-trusted-client-certs", 1210 "description" : "Certs for explicitly-trusted clients.", 1211 "pinned-certificate" : { 1212 "name" : "Fred Flintstone", 1213 "data" : "base64encodedvalue==" 1214 } 1215 } 1216 }, 1217 "ietf-netconf-server:netconf-server" : { 1218 "call-home" : { 1219 "netconf-client" : { 1220 "name" : "config-mgr", 1221 "endpoints" : { 1222 "endpoint" : { 1223 "name" : "east-data-center", 1224 "ssh" : { 1225 "address" : "east.config-mgr.example.com", 1226 "host-keys" : { 1227 "host-key" : { 1228 "name" : "certificate", 1229 "certificate" : "builtin-idevid-cert" 1230 } 1231 }, 1232 "client-cert-auth" : { 1233 "trusted-ca-certs" : 1234 "deployment-specific-ca-certs", 1235 "trusted-client-certs" : 1236 "explicitly-trusted-client-certs" 1237 } 1238 } 1239 }, 1240 "endpoint" : { 1241 "name" : "west-data-center", 1242 "ssh" : { 1243 "address" : "west.config-mgr.example.com", 1244 "host-keys" : { 1245 "host-key" : { 1246 "name" : "certificate", 1247 "certificate" : "builtin-idevid-cert" 1248 } 1249 }, 1250 "client-cert-auth" : { 1251 "trusted-ca-certs" : 1252 "deployment-specific-ca-certs", 1253 "trusted-client-certs" : 1254 "explicitly-trusted-client-certs" 1255 } 1256 } 1257 } 1258 }, 1259 "connection-type" : { 1260 "periodic" : { 1261 "idle-timeout" : 300, 1262 "reconnect-timeout" : 60 1263 } 1264 }, 1265 "reconnect-strategy" : { 1266 "start-with" : "last-connected", 1267 "max-attempts" : 3 1268 } 1269 } 1270 } 1271 }, 1272 "ietf-device:zerotouch" : { 1273 "enabled" : false 1274 } 1275 } 1276 } 1277 } 1279 6.3. YANG Module 1281 The zero touch information data model is defined by the YANG module 1282 presented in this section. 1284 Note: the module defined herein uses data types defined in [RFC5280], 1285 [RFC6234], and [RFC6991], and an extension statement from [RFC8040], 1286 and an encoding defined in [ITU.X690.1994]. 1288 file "ietf-zerotouch-information@2017-10-18.yang" 1289 module ietf-zerotouch-information { 1290 yang-version 1.1; 1291 namespace "urn:ietf:params:xml:ns:yang:ietf-zerotouch-information"; 1292 prefix zti; 1294 import ietf-yang-types { 1295 prefix yang; 1296 reference "RFC 6991: Common YANG Data Types"; 1297 } 1298 import ietf-inet-types { 1299 prefix inet; 1300 reference "RFC 6991: Common YANG Data Types"; 1301 } 1302 import ietf-restconf { 1303 prefix rc; 1304 description 1305 "This import statement is only present to access 1306 the yang-data extension defined in RFC 8040."; 1307 reference "RFC 8040: RESTCONF Protocol"; 1308 } 1310 organization 1311 "IETF NETCONF (Network Configuration) Working Group"; 1313 contact 1314 "WG Web: http://tools.ietf.org/wg/netconf 1315 WG List: 1316 Author: Kent Watsen "; 1318 description 1319 "This module defines the data model for the Zero Touch Information 1320 artifact defined by RFC XXXX: Zero Touch Provisioning for NETCONF 1321 or RESTCONF based Management. 1323 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1324 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', 1325 and 'OPTIONAL' in the module text are to be interpreted as 1326 described in RFC 2119. 1328 Copyright (c) 2017 IETF Trust and the persons identified as 1329 authors of the code. All rights reserved. 1331 Redistribution and use in source and binary forms, with or 1332 without modification, is permitted pursuant to, and subject 1333 to the license terms contained in, the Simplified BSD License 1334 set forth in Section 4.c of the IETF Trust's Legal Provisions 1335 Relating to IETF Documents (http://trustee.ietf.org/license-info) 1337 This version of this YANG module is part of RFC XXXX; see the 1338 RFC itself for full legal notices."; 1340 revision 2017-10-18 { 1341 description 1342 "Initial version"; 1343 reference 1344 "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF based 1345 Management"; 1346 } 1348 rc:yang-data "zerotouch-information" { 1349 choice information-type { 1350 mandatory true; 1351 description 1352 "This choice statement ensures the response contains 1353 redirect-information or onboarding-information."; 1354 container redirect-information { 1355 description 1356 "Redirect information is described in Section 2.1 in 1357 RFC XXXX. Its purpose is to redirect a device to 1358 another bootstrap server."; 1359 reference 1360 "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF 1361 based Management"; 1362 list bootstrap-server { 1363 key "address"; 1364 min-elements 1; 1365 description 1366 "A bootstrap server entry."; 1367 leaf address { 1368 type inet:host; 1369 mandatory true; 1370 description 1371 "The IP address or hostname of the bootstrap server the 1372 device should redirect to."; 1373 } 1374 leaf port { 1375 type inet:port-number; 1376 default "443"; 1377 description 1378 "The port number the bootstrap server listens on. If no 1379 port is specified, the IANA-assigned port for 'https' 1380 (443) is used."; 1381 } 1382 leaf trust-anchor { 1383 type binary; 1384 description 1385 "An X.509 v3 certificate structure as specified by RFC 1386 5280, Section 4, encoded using ASN.1 distinguished 1387 encoding rules (DER), as specified in ITU-T X.690. A 1388 certificate that the device can use as the trust anchor 1389 to authenticate the bootstrap server the device is 1390 being redirected to. If not specified, the device may 1391 establish a provisional connection to the bootstrap 1392 server, as described in RFC XXXX."; 1393 reference 1394 "RFC 5280: 1395 Internet X.509 Public Key Infrastructure Certificate 1396 and Certificate Revocation List (CRL) Profile. 1397 ITU-T X.690: 1398 Information technology - ASN.1 encoding rules: 1399 Specification of Basic Encoding Rules (BER), 1400 Canonical Encoding Rules (CER) and Distinguished 1401 Encoding Rules (DER). 1402 RFC XXXX: 1403 Zero Touch Provisioning for NETCONF or RESTCONF 1404 based Management."; 1405 } 1406 } 1407 } 1408 container onboarding-information { 1409 description 1410 "Onboarding information is described in Section 2.2 in 1411 RFC XXXX. Its purpose is to provide the device everything 1412 it needs to bootstrap itself."; 1413 reference 1414 "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF 1415 based Management"; 1416 container boot-image { 1417 description 1418 "Specifies criteria for the boot image the device MUST 1419 be running."; 1420 leaf os-name { 1421 type string; 1422 mandatory true; 1423 description 1424 "The name of the operating system software the device 1425 MUST be running in order to not require a software 1426 image upgrade (ex. VendorOS)."; 1427 } 1428 leaf os-version { 1429 type string; 1430 mandatory true; 1431 description 1432 "The version of the operating system software the device 1433 MUST be running in order to not require a software 1434 image upgrade (ex. 17.3R2.1)."; 1435 } 1436 leaf-list uri { 1437 type inet:uri; 1438 must '../hash-algorithm' { 1439 description 1440 "A hash is needed in order to validate the downloaded 1441 image."; 1442 } 1443 ordered-by user; 1444 description 1445 "An ordered list of URIs to where the boot-image file 1446 MAY be obtained. Deployments MUST know in which URI 1447 schemes (http, ftp, etc.) a device supports. If a 1448 secure scheme (e.g., https) is provided, a device MAY 1449 establish a provisional connection to the server, by 1450 blindly accepting the server's credentials (e.g., its 1451 TLS certificate)"; 1452 } 1453 choice hash-algorithm { 1454 must '../uri' { 1455 description 1456 "A uri is needed in order to downloaded an image to 1457 validate."; 1458 } 1459 description 1460 "Identifies the hash algorithm used."; 1461 leaf sha256 { 1462 type yang:hex-string; 1463 description 1464 "The hex-encoded SHA-256 hash over the boot image 1465 file. This is used by the device to verify a 1466 downloaded boot image file."; 1467 reference "RFC 6234: US Secure Hash Algorithms."; 1468 } 1469 } 1470 } 1471 leaf configuration-handling { 1472 type enumeration { 1473 enum "merge" { 1474 description 1475 "Merge configuration into the running datastore."; 1476 } 1477 enum "replace" { 1478 description 1479 "Replace the existing running datastore with the 1480 passed configuration."; 1481 } 1482 } 1483 must '../configuration'; 1484 description 1485 "This enumeration indicates how the server should process 1486 the provided configuration."; 1487 } 1488 leaf pre-configuration-script { 1489 type script; 1490 description 1491 "A script that, when present, is executed before the 1492 configuration has been processed."; 1493 } 1494 anydata configuration { 1495 must '../configuration-handling'; 1496 description 1497 "Any configuration data model known to the device. It may 1498 contain manufacturer-specific and/or standards-based data 1499 models."; 1500 } 1501 leaf post-configuration-script { 1502 type script; 1503 description 1504 "A script that, when present, is executed after the 1505 configuration has been processed."; 1506 } 1507 } 1508 } 1509 } 1511 typedef script { 1512 type binary; 1513 description 1514 "A device specific script that enables the execution of 1515 commands to perform actions not possible thru configuration 1516 alone. 1518 No attempt is made to standardize the contents, running 1519 context, or programming language of the script, other than 1520 that it can emit an exit status code and stderr/sdtout. The 1521 contents of the script are considered specific to the vendor, 1522 product line, and/or model of the device. 1524 If a script is erroneously provided to a device that does not 1525 support the execution of scripts, the device SHOULD send a 1526 'script-warning' progress report, but otherwise continue 1527 processing the bootstrapping data as if the script had not 1528 been present. 1530 The script returns exit status code '0' on success and non-zero 1531 on error, with accompanying stderr/stdout for logging purposes. 1532 In the case of an error, the exit status code will specify what 1533 the device should do as follows. 1535 If the exit status code is greater than zero, then the device 1536 should assume that the script had a soft error, which the 1537 script believes does not affect manageability. If the device 1538 obtained the bootstrap information from a bootstrap server, 1539 it SHOULD send a 'script-warning' progress report. 1541 If the exit status code is less than zero, the device should 1542 assume the script had a hard error, which the script believes 1543 will affect manageability. In this case, the device SHOULD 1544 send a 'script-error' progress report followed by a reset that 1545 will wipe out anything the script may have done and restart 1546 the entire bootstrapping process again."; 1547 } 1548 } 1549 1551 7. The Zero Touch Bootstrap Server API 1553 This section defines the API for bootstrap servers. The API is 1554 defined as the API produced by a RESTCONF [RFC8040] server that 1555 supports the YANG 1.1 [RFC7950] module defined in this section. 1557 7.1. API Overview 1559 The following tree diagram provides an overview for the bootstrap 1560 server RESTCONF API. The syntax used for this tree diagram is 1561 described in Section 1.4. 1563 module: ietf-zerotouch-bootstrap-server 1565 rpcs: 1566 +---x get-bootstrapping-data 1567 | +---w input 1568 | | +---w untrusted-connection? empty 1569 | | +---w os-name? string 1570 | | +---w os-version? string 1571 | | +---w remote-id? string 1572 | | +---w circuit-id? string 1573 | | +---w nonce? string 1574 | +--ro output 1575 | +--ro bootstrapping-data 1576 | +--ro zerotouch-information pkcs7 1577 | +--ro owner-certificate? pkcs7 1578 | +--ro ownership-voucher? pkcs7 1579 +---x report-progress 1580 +---w input 1581 +---w progress-type enumeration 1582 +---w message? string 1583 +---w ssh-host-keys 1584 | +---w ssh-host-key* 1585 | +---w format enumeration 1586 | +---w key-data string 1587 +---w trust-anchors 1588 +---w trust-anchor* 1589 +---w certificate pkcs7 1591 7.2. Example Usage 1593 This section presents three examples illustrating the bootstrap 1594 server's API. Two examples are provided for the 'get-bootstrapping- 1595 data' RPC (once to an untrusted bootstrap server, and again to a 1596 trusted bootstrap server), and one example for the 'report-progress' 1597 RPC. 1599 The following example illustrates a device using the API to fetch its 1600 bootstrapping data from a untrusted bootstrap server. In this 1601 example, the device sends the 'untrusted-connection' input parameter 1602 and receives signed data in the response. 1604 REQUEST 1605 ------- 1606 ['\' line wrapping added for formatting only] 1608 POST /restconf/operations/ietf-zerotouch-bootstrap-server:get-boot\ 1609 strapping-data HTTP/1.1 1610 HOST: example.com 1611 Content-Type: application/yang.data+xml 1613 1615 1616 1618 RESPONSE 1619 -------- 1621 HTTP/1.1 200 OK 1622 Date: Sat, 31 Oct 2015 17:02:40 GMT 1623 Server: example-server 1624 Content-Type: application/yang.data+xml 1626 1628 base64encodedvalue== 1629 base64encodedvalue== 1630 base64encodedvalue== 1631 1633 The following example illustrates a device using the API to fetch its 1634 bootstrapping data from a trusted bootstrap server. In this example, 1635 the device sends addition input parameters that the bootstrap server 1636 can use when formulating its response to the device. 1638 REQUEST 1639 ------- 1640 ['\' line wrapping added for formatting only] 1642 POST /restconf/operations/ietf-zerotouch-bootstrap-server:get-boot\ 1643 strapping-data HTTP/1.1 1644 HOST: example.com 1645 Content-Type: application/yang.data+xml 1647 1649 VendorOS 1650 17.3R2.1 1651 32 1652 2 1653 base64encodedvalue== 1654 1656 RESPONSE 1657 -------- 1659 HTTP/1.1 200 OK 1660 Date: Sat, 31 Oct 2015 17:02:40 GMT 1661 Server: example-server 1662 Content-Type: application/yang.data+xml 1664 1666 base64encodedvalue== 1667 1669 The following example illustrates a device using the API to post a 1670 progress update to a bootstrap server. Illustrated below is the 1671 'bootstrap-complete' message, but the device may send other progress 1672 reports to the server while bootstrapping. In this example, the 1673 device is sending both its SSH host keys and a TLS server 1674 certificate, which the bootstrap server may, for example, pass to an 1675 NMS, as discussed in Appendix A.3. 1677 REQUEST 1678 ------- 1679 ['\' line wrapping added for formatting only] 1681 POST /restconf/operations/ietf-zerotouch-bootstrap-server:report-\ 1682 progress HTTP/1.1 1683 HOST: example.com 1684 Content-Type: application/yang.data+xml 1686 1688 bootstrap-complete 1689 example message 1690 1691 1692 ssh-rsa 1693 base64encodedvalue== 1694 1695 1696 ssh-dss 1697 base64encodedvalue== 1698 1699 1700 1701 1702 base64encodedvalue== 1703 1704 1705 1707 RESPONSE 1708 -------- 1710 HTTP/1.1 204 No Content 1711 Date: Sat, 31 Oct 2015 17:02:40 GMT 1712 Server: example-server 1714 7.3. YANG Module 1716 The bootstrap server's device-facing API is normatively defined by 1717 the YANG module defined in this section. 1719 Note: the module defined herein uses data types defined in [RFC2315], 1720 [RFC5280], [RFC6960], and [I-D.ietf-anima-voucher], and uses an 1721 encoding defined in [ITU.X690.1994]. 1723 file "ietf-zerotouch-bootstrap-server@2017-10-18.yang" 1724 module ietf-zerotouch-bootstrap-server { 1725 yang-version 1.1; 1726 namespace 1727 "urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server"; 1728 prefix ztbs; 1730 organization 1731 "IETF NETCONF (Network Configuration) Working Group"; 1733 contact 1734 "WG Web: 1735 WG List: 1736 Author: Kent Watsen "; 1738 description 1739 "This module defines an interface for bootstrap servers, as 1740 defined by RFC XXXX: Zero Touch Provisioning for NETCONF or 1741 RESTCONF based Management. 1743 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1744 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', 1745 and 'OPTIONAL' in the module text are to be interpreted as 1746 described in RFC 2119. 1748 Copyright (c) 2017 IETF Trust and the persons identified as 1749 authors of the code. All rights reserved. 1751 Redistribution and use in source and binary forms, with or 1752 without modification, is permitted pursuant to, and subject 1753 to the license terms contained in, the Simplified BSD License 1754 set forth in Section 4.c of the IETF Trust's Legal Provisions 1755 Relating to IETF Documents (http://trustee.ietf.org/license-info) 1757 This version of this YANG module is part of RFC XXXX; see the 1758 RFC itself for full legal notices."; 1760 revision 2017-10-18 { 1761 description 1762 "Initial version"; 1763 reference 1764 "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF based 1765 Management"; 1766 } 1768 // typedefs 1770 typedef pkcs7 { 1771 type binary; 1772 description 1773 "A PKCS #7 SignedData structure, as specified by Section 9.1 1774 in RFC 2315, encoded using ASN.1 distinguished encoding rules 1775 (DER), as specified in ITU-T X.690."; 1776 reference 1777 "RFC 2315: 1778 PKCS #7: Cryptographic Message Syntax Version 1.5. 1779 ITU-T X.690: 1780 Information technology - ASN.1 encoding rules: 1781 Specification of Basic Encoding Rules (BER), 1782 Canonical Encoding Rules (CER) and Distinguished 1783 Encoding Rules (DER)."; 1784 } 1786 // RPCs 1788 rpc get-bootstrapping-data { 1789 description 1790 "This RPC enables a device, as identified by its RESTCONF 1791 username, to obtain bootstrapping data that has been made 1792 available for it."; 1793 input { 1794 leaf untrusted-connection { 1795 type empty; 1796 description 1797 "This optional input parameter enables a device to 1798 communicate to the bootstrap server that it is unable 1799 to authenticate the bootstrap server's TLS certificate. 1800 In such circumstances, the device likely did not send 1801 any of the other input parameters. The bootstrap server 1802 needs to return either unsigned redirect information or 1803 signed data."; 1804 } 1805 leaf os-name { 1806 type string; 1807 description 1808 "This optional input parameter enables a device to 1809 communicate to the bootstrap server the name of its 1810 operating system. This parameter may be useful if 1811 the device, as identified by its IDevID certificate, 1812 to run more than one type of operating system (e.g., 1813 on a white-box system."; 1814 } 1815 leaf os-version { 1816 type string; 1817 description 1818 "This optional input parameter enables a device to 1819 communicate to the bootstrap server the version of 1820 its operating system. This parameter may be useful 1821 to a server that wants to return a response optimized 1822 for the device, negating, for instance, the need for 1823 a potentially expensive boot-image update."; 1824 } 1825 leaf remote-id { 1826 type string; 1827 must "../circuit-id"; 1828 description 1829 "This optional input parameter enables a device to 1830 communicate to the bootstrap server the 'remote-id' 1831 value it learned from a DHCP server via Option 82, 1832 as described in Section 2.0 or RFC 3046. 1834 This information, along with the circuit-id, enables 1835 the bootstrap server to return a deployment-specific 1836 response independent of the device's IDevID identity."; 1837 reference 1838 "RFC 3046: DHCP Relay Agent Information Option"; 1839 } 1840 leaf circuit-id { 1841 type string; 1842 must "../remote-id"; 1843 description 1844 "This optional input parameter enables a device to 1845 communicate to the bootstrap server the 'circuit-id' 1846 value it learned from a DHCP server via Option 82, 1847 as described in Section 2.0 or RFC 3046. 1849 This information, along with the remote-id, enables 1850 the bootstrap server to return a deployment-specific 1851 response independent of the device's IDevID identity."; 1852 reference 1853 "RFC 3046: DHCP Relay Agent Information Option"; 1854 } 1855 leaf nonce { 1856 type string; 1857 description 1858 "This optional input parameter enables a device to 1859 communicate to the bootstrap server a nonce value. 1860 This may be especially useful for devices lacking 1861 an accurate clock, as then the bootstrap server can 1862 then dynamically obtain from the manufacturer a 1863 voucher with the nonce value in it, as described 1864 in I-D.ietf-anima-voucher."; 1865 reference 1866 "RFC ZZZZ: Voucher Profile for Bootstrapping Protocols."; 1867 } 1868 } 1869 output { 1870 container bootstrapping-data { 1871 description 1872 "Top-level node for the bootstrapping data."; 1873 leaf zerotouch-information { 1874 type pkcs7; 1875 mandatory true; 1876 description 1877 "A 'zerotouch-information' artifact, as described in 1878 Section 4.1 of RFC XXXX. In order to be processed by a 1879 device, when conveyed over an untrusted transport, the 1880 PKCS#7 SignedData structure MUST contain a 'signerInfo' 1881 structure, described in Section 9.1 of RFC 2315, 1882 containing a signature generated using the private key 1883 associated with the 'owner-certificate'."; 1884 reference 1885 "RFC XXXX: Zero Touch Provisioning for NETCONF or 1886 RESTCONF based Management. 1887 RFC 2315: 1888 PKCS #7: Cryptographic Message Syntax Version 1.5"; 1889 } 1890 leaf owner-certificate { 1891 type pkcs7; 1892 must '../ownership-voucher' { 1893 description 1894 "An ownership voucher must be present whenever an owner 1895 certificate is presented."; 1896 } 1897 description 1898 "This PKCS#7 structure MUST contain the owner certificate 1899 and all intermediate certificates leading up to, and 1900 optionally including, the trust anchor certificate 1901 specified in the ownership voucher. Additionally, if 1902 needed by the device, this structure MAY also contain 1903 suitably fresh CRL and/or OCSP Responses with which to 1904 verify the revocation status of the certificates. 1906 X.509 certificates and CRLs are described in RFC 5280. 1907 OCSP Responses are described in RFC 6960."; 1908 reference 1909 "RFC 2315: 1910 PKCS #7: Cryptographic Message Syntax Version 1.5. 1911 RFC 5280: 1912 Internet X.509 Public Key Infrastructure Certificate 1913 and Certificate Revocation List (CRL) Profile. 1914 RFC 6960: 1915 X.509 Internet Public Key Infrastructure Online 1916 Certificate Status Protocol - OCSP. 1918 ITU-T X.690: 1919 Information technology - ASN.1 encoding rules: 1920 Specification of Basic Encoding Rules (BER), 1921 Canonical Encoding Rules (CER) and Distinguished 1922 Encoding Rules (DER)."; 1923 } 1924 leaf ownership-voucher { 1925 type pkcs7; 1926 must '../owner-certificate' { 1927 description 1928 "An owner certificate must be present whenever an 1929 ownership voucher is presented."; 1930 } 1931 description 1932 "A 'voucher' artifact, as described in Section 5 of 1933 I-D.ietf-anima-voucher. The voucher informs the device 1934 who its owner is. The voucher encodes the device's 1935 serial number, so that the device can ensure the 1936 voucher applies to it. The voucher is signed by the 1937 device's manufacturer."; 1938 reference 1939 "I-D.ietf-anima-voucher: 1940 Voucher and Voucher Revocation Profiles for 1941 Bootstrapping Protocols"; 1942 } 1943 } 1944 } 1945 } 1947 rpc report-progress { 1948 description 1949 "This RPC enables a device, as identified by its RESTCONF 1950 username, to report its bootstrapping progress to the 1951 bootstrap server."; 1952 input { 1953 leaf progress-type { 1954 type enumeration { 1955 enum "bootstrap-initiated" { 1956 description 1957 "Indicates that the device just used the 1958 'get-bootstrapping-data' RPC. The 'message' field 1959 below MAY contain any additional information that 1960 the manufacturer thinks might be useful."; 1961 } 1962 enum "parsing-warning" { 1963 description 1964 "Indicates that the device had a non-fatal error when 1965 parsing the response from the bootstrap server. The 1966 'message' field below SHOULD indicate the specific 1967 warning that occurred."; 1968 } 1969 enum "parsing-error" { 1970 description 1971 "Indicates that the device encountered a fatal error 1972 when parsing the response from the bootstrap server. 1973 For instance, this could be due to malformed 1974 encoding, the device expecting signed data when 1975 only unsigned data is provided, because the 1976 ownership voucher didn't include the device's 1977 unique identifier, or because the signature didn't 1978 match. The 'message' field below SHOULD indicate 1979 the specific error. This progress type also indicates 1980 that the device has abandoned trying to bootstrap 1981 off this bootstrap server."; 1982 } 1983 enum "boot-image-warning" { 1984 description 1985 "Indicates that the device encountered a non-fatal 1986 error condition when trying to install a boot-image. 1987 A possible reason might include a need to reformat a 1988 partition causing loss of data. The 'message' field 1989 below SHOULD indicate any warning messages that were 1990 generated."; 1991 } 1992 enum "boot-image-error" { 1993 description 1994 "Indicates that the device encountered an error when 1995 trying to install a boot-image, which could be for 1996 reasons such as a file server being unreachable, 1997 file not found, signature mismatch, etc. The 1998 'message' field SHOULD indicate the specific error 1999 that occurred. This progress type also indicates 2000 that the device has abandoned trying to bootstrap 2001 off this bootstrap server."; 2002 } 2003 enum "pre-script-warning" { 2004 description 2005 "Indicates that the device obtained a greater than 2006 zero exit status code from the script when it was 2007 executed. The 'message' field below SHOULD indicate 2008 both the resulting exit status code, as well as 2009 capture any stdout/stderr messages the script may 2010 have produced."; 2011 } 2012 enum "pre-script-error" { 2013 description 2014 "Indicates that the device obtained a less than 2015 zero exit status code from the script when it was 2016 executed. The 'message' field below SHOULD indicate 2017 both the resulting exit status code, as well as 2018 capture any stdout/stderr messages the script may 2019 have produced. This progress type also indicates 2020 that the device has abandoned trying to bootstrap 2021 off this bootstrap server."; 2022 } 2023 enum "config-warning" { 2024 description 2025 "Indicates that the device obtained warning messages 2026 when it committed the initial configuration. The 2027 'message' field below SHOULD indicate any warning 2028 messages that were generated."; 2029 } 2030 enum "config-error" { 2031 description 2032 "Indicates that the device obtained error messages 2033 when it committed the initial configuration. The 2034 'message' field below SHOULD indicate the error 2035 messages that were generated. This progress type 2036 also indicates that the device has abandoned trying 2037 to bootstrap off this bootstrap server."; 2038 } 2039 enum "post-script-warning" { 2040 description 2041 "Indicates that the device obtained a greater than 2042 zero exit status code from the script when it was 2043 executed. The 'message' field below SHOULD indicate 2044 both the resulting exit status code, as well as 2045 capture any stdout/stderr messages the script may 2046 have produced."; 2047 } 2048 enum "post-script-error" { 2049 description 2050 "Indicates that the device obtained a less than 2051 zero exit status code from the script when it was 2052 executed. The 'message' field below SHOULD indicate 2053 both the resulting exit status code, as well as 2054 capture any stdout/stderr messages the script may 2055 have produced. This progress type also indicates 2056 that the device has abandoned trying to bootstrap 2057 off this bootstrap server."; 2058 } 2059 enum "bootstrap-complete" { 2060 description 2061 "Indicates that the device successfully processed all 2062 'onboarding-information' provided, and that it is ready 2063 to be managed. The 'message' field below MAY contain 2064 any additional information that the manufacturer thinks 2065 might be useful. After sending this progress type, 2066 the device is not expected to access the bootstrap 2067 server again."; 2068 } 2069 enum "informational" { 2070 description 2071 "Indicates any additional information not captured 2072 by any of the other progress types. For instance, a 2073 message indicating that the device is about to 2074 reboot after having installed a boot-image could 2075 be provided. The 'message' field below SHOULD 2076 contain information that the manufacturer thinks 2077 might be useful."; 2078 } 2079 } 2080 mandatory true; 2081 description 2082 "The type of progress report provided."; 2083 } 2084 leaf message { 2085 type string; 2086 description 2087 "An optional arbitrary value."; 2088 } 2089 container ssh-host-keys { 2090 when "../progress-type = 'bootstrap-complete'" { 2091 description 2092 "SSH host keys are only sent when the progress type 2093 is 'bootstrap-complete'."; 2094 } 2095 description 2096 "A list of trust anchor certificates an NMS may use to 2097 authenticate subsequent SSH-based connections to this 2098 device (e.g., netconf-ssh, netconf-ch-ssh)."; 2099 list ssh-host-key { 2100 description 2101 "An SSH host-key."; 2102 leaf format { 2103 type enumeration { 2104 enum "ssh-dss" { 2105 description 2106 "ssh-dss"; 2107 } 2108 enum "ssh-rsa" { 2109 description 2110 "ssh-rsa"; 2111 } 2112 } 2113 mandatory true; 2114 description 2115 "The format of the SSH host key."; 2116 } 2117 leaf key-data { 2118 type string; 2119 mandatory true; 2120 description 2121 "The key data for the SSH host key"; 2122 } 2123 } 2124 } 2125 container trust-anchors { 2126 when "../progress-type = 'bootstrap-complete'" { 2127 description 2128 "Trust anchors are only sent when the progress type 2129 is 'bootstrap-complete'."; 2130 } 2131 description 2132 "A list of trust anchor certificates an NMS may use to 2133 authenticate subsequent certificate-based connections 2134 to this device (e.g., restconf-tls, netconf-tls, or 2135 even netconf-ssh with X.509 support from RFC 6187)."; 2136 reference 2137 "RFC 6187: 2138 X.509v3 Certificates for Secure Shell Authentication."; 2139 list trust-anchor { 2140 description 2141 "A trust anchor."; 2142 leaf certificate { 2143 type pkcs7; 2144 mandatory true; 2145 description 2146 "An X.509 v3 certificate structure, as specified 2147 by Section 4 in RFC 5280, encoded using ASN.1 2148 distinguished encoding rules (DER), as specified 2149 in ITU-T X.690."; 2150 reference 2151 "RFC 5280: 2152 Internet X.509 Public Key Infrastructure 2153 Certificate and Certificate Revocation List (CRL) 2154 Profile. 2155 ITU-T X.690: 2156 Information technology - ASN.1 encoding rules: 2157 Specification of Basic Encoding Rules (BER), 2158 Canonical Encoding Rules (CER) and Distinguished 2159 Encoding Rules (DER)."; 2160 } 2161 } 2162 } 2163 } 2164 } 2165 } 2166 2168 8. The Zero Touch Device Data Model 2170 This section defines a data model that devices can implement to 2171 enable the configuration of zerotouch bootstrapping and discovery of 2172 what parameters are used by its bootstrapping logic. 2174 8.1. Data Model Overview 2176 The following tree diagram provides an overview for the zerotouch 2177 device data model The syntax used for this tree diagram is described 2178 in Section 1.4. 2180 module: ietf-zerotouch-device 2181 +--rw zerotouch 2182 +--rw enabled? boolean 2183 +--ro devid-certificate? pkcs7 2184 | {bootstrap-servers}? 2185 +--ro bootstrap-servers {bootstrap-servers}? 2186 | +--ro bootstrap-server* [address] 2187 | +--ro address inet:host 2188 | +--ro port? inet:port-number 2189 +--ro bootstrap-server-ta-certificates? 2190 | -> /ks:keystore/pinned-certificates/name 2191 | {bootstrap-servers}? 2192 +--ro voucher-ta-certificates? 2193 -> /ks:keystore/pinned-certificates/name {signed-data}? 2195 In the above diagram, notice that there is only one configurable node 2196 'enabled'. The expectation is that this node would be set to 'true' 2197 in device's factory default configuration and that it would either be 2198 set to 'false' or deleted when the zerotouch bootstrapping is longer 2199 needed. 2201 8.2. Example Usage 2203 Following is an instance example for this data model. 2205 [ note: '\' line wrapping for formatting only] 2207 2209 true 2210 base64encodedvalue== 2211 2212 2213
phs1.example.com
2214 8443 2215 2216 2217
phs2.example.com
2218 8443 2219 2220 2221
phs3.example.com
2222 8443 2223 2224 2225 manufacturers-root-ca-certs 2227 manufacturers-root-ca-certs 2229 2231 8.3. YANG Module 2233 The device model is normatively defined by the YANG module defined in 2234 this section. 2236 Note: the module defined herein uses data types defined in [RFC2315] 2237 and [RFC6991], and uses an encoding defined in [ITU.X690.1994]. 2239 file "ietf-zerotouch-device@2017-10-18.yang" 2240 module ietf-zerotouch-device { 2241 yang-version 1.1; 2242 namespace 2243 "urn:ietf:params:xml:ns:yang:ietf-zerotouch-device"; 2244 prefix ztd; 2246 import ietf-inet-types { 2247 prefix inet; 2248 reference "RFC 6991: Common YANG Data Types"; 2249 } 2250 import ietf-keystore { 2251 prefix ks; 2252 reference 'RFC YYYY: YANG Data Model for a "Keystore" Mechanism'; 2254 } 2256 organization 2257 "IETF NETCONF (Network Configuration) Working Group"; 2259 contact 2260 "WG Web: 2261 WG List: 2262 Author: Kent Watsen "; 2264 description 2265 "This module defines a data model to enable zerotouch 2266 bootstrapping and discover what parameters are used. 2268 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 2269 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', 2270 and 'OPTIONAL' in the module text are to be interpreted as 2271 described in RFC 2119. 2273 Copyright (c) 2017 IETF Trust and the persons identified as 2274 authors of the code. All rights reserved. 2276 Redistribution and use in source and binary forms, with or 2277 without modification, is permitted pursuant to, and subject 2278 to the license terms contained in, the Simplified BSD License 2279 set forth in Section 4.c of the IETF Trust's Legal Provisions 2280 Relating to IETF Documents (http://trustee.ietf.org/license-info) 2282 This version of this YANG module is part of RFC XXXX; see the 2283 RFC itself for full legal notices."; 2285 revision 2017-10-18 { 2286 description 2287 "Initial version"; 2288 reference 2289 "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF based 2290 Management"; 2291 } 2293 // features 2295 feature bootstrap-servers { 2296 description 2297 "The device supports bootstrapping off bootstrap servers."; 2298 } 2300 feature signed-data { 2301 description 2302 "The device supports bootstrapping off signed data."; 2303 } 2305 // typedefs 2307 typedef pkcs7 { 2308 type binary; 2309 description 2310 "A PKCS #7 SignedData structure, as specified by Section 9.1 2311 in RFC 2315, encoded using ASN.1 distinguished encoding rules 2312 (DER), as specified in ITU-T X.690."; 2313 reference 2314 "RFC 2315: 2315 PKCS #7: Cryptographic Message Syntax Version 1.5. 2316 ITU-T X.690: 2317 Information technology - ASN.1 encoding rules: 2318 Specification of Basic Encoding Rules (BER), 2319 Canonical Encoding Rules (CER) and Distinguished 2320 Encoding Rules (DER)."; 2321 } 2323 // protocol accessible nodes 2325 container zerotouch { 2326 description 2327 "Top-level container for zerotouch data model."; 2328 leaf enabled { 2329 type boolean; 2330 default false; 2331 description 2332 "The 'enabled' leaf controls if zerotouch bootstrapping is 2333 enabled or disabled. The default is 'false' so that, when 2334 not enabled, which is most of the time, no configuration 2335 needs to be returned."; 2336 } 2337 leaf devid-certificate { 2338 if-feature bootstrap-servers; 2339 type pkcs7; 2340 config false; 2341 description 2342 "An unsigned PKCS #7 SignedData structure, as specified by 2343 Section 9.1 in RFC 2315, encoded using ASN.1 distinguished 2344 encoding rules (DER), as specified in ITU-T X.690. 2346 This structure contains the IDevID certificate and all 2347 intermediate certificates leading up to the manufacturer's 2348 well-known trust anchor certificate. IDevID certificates 2349 are described in IEEE 802.1AR-2009."; 2351 reference 2352 "RFC 2315: 2353 PKCS #7: Cryptographic Message Syntax Version 1.5. 2354 ITU-T X.690: 2355 Information technology - ASN.1 encoding rules: 2356 Specification of Basic Encoding Rules (BER), 2357 Canonical Encoding Rules (CER) and Distinguished 2358 Encoding Rules (DER). 2359 IEEE 802.1AR-2009: 2360 IEEE Standard for Local and metropolitan area 2361 networks - Secure Device Identity."; 2362 } 2363 container bootstrap-servers { 2364 if-feature bootstrap-servers; 2365 config false; 2366 description 2367 "Default list of bootstrap servers this device is 2368 configured to reach out to when bootstrapping."; 2369 list bootstrap-server { 2370 key "address"; 2371 description 2372 "A bootstrap server entry."; 2373 leaf address { 2374 type inet:host; 2375 mandatory true; 2376 description 2377 "The IP address or hostname of the bootstrap server the 2378 device should redirect to."; 2379 } 2380 leaf port { 2381 type inet:port-number; 2382 default "443"; 2383 description 2384 "The port number the bootstrap server listens on. If no 2385 port is specified, the IANA-assigned port for 'https' 2386 (443) is used."; 2387 } 2388 } 2389 } 2390 leaf bootstrap-server-ta-certificates { 2391 if-feature bootstrap-servers; 2392 type leafref { 2393 path "/ks:keystore/ks:pinned-certificates/ks:name"; 2394 } 2395 config false; 2396 description 2397 "A reference to a list of pinned certificate authority (CA) 2398 certificates that the device uses to validate bootstrap 2399 servers with."; 2400 } 2401 leaf voucher-ta-certificates { 2402 if-feature signed-data; 2403 type leafref { 2404 path "/ks:keystore/ks:pinned-certificates/ks:name"; 2405 } 2406 config false; 2407 description 2408 "A reference to a list of pinned certificate authority (CA) 2409 certificates that the device uses to validate ownership 2410 vouchers with."; 2411 } 2412 } 2413 } 2415 2417 9. DHCP Zero Touch Options 2419 This section defines two DHCP options, one for DHCPv4 and one for 2420 DHCPv6. These two options are semantically the same, though 2421 syntactically different. 2423 9.1. DHCPv4 Zero Touch Option 2425 The DHCPv4 Zero Touch Option is used to provision the client with one 2426 or more URIs for bootstrap servers that can be contacted to attempt 2427 further configuration. 2429 DHCPv4 Zero Touch Redirect Option 2431 0 1 2432 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 2433 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2434 | option-code (TBD) | option-length | 2435 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2436 . . 2437 . bootstrap-server-list (variable length) . 2438 . . 2439 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2441 o option-code: OPTION_V4_ZEROTOUCH_REDIRECT (TBD) 2442 o option-length: The option length in octets 2443 o bootstrap-server-list: A list of servers for the 2444 client to attempt contacting, in order to obtain 2445 further bootstrapping data, in the format shown 2446 in [common-field-encoding]. 2448 DHCPv4 Client Behavior 2450 Clients MAY request the OPTION_V4_ZEROTOUCH_REDIRECT by including its 2451 option code in the Parameter Request List (55) in DHCP request 2452 messages. 2454 On receipt of a DHCPv4 Reply message which contains the 2455 OPTION_V4_ZEROTOUCH_REDIRECT, the client performs the following 2456 steps: 2458 1. Check the contents of the DHCPv4 message for at least one valid 2459 URI. If there is more than one valid URI in the list, a candidate 2460 list of possible URIs is created. 2462 2. Attempt to connect to the one of the URIs in the candidate list. 2463 The order in which these are processed by the client is 2464 implementation specific and not defined here. 2466 3. If a successful connection to the zerotouch bootstrap server, 2467 then the client stops processing entries in the list and proceeds 2468 according to Appendix A.3, step(3). 2470 4. If the zerotouch bootstrap server does not respond, provides 2471 an invalid response, or the transaction otherwise fails, the 2472 client SHOULD attempt to contact another server from the 2473 candidate list. 2475 Any invalid URI entries received in the uri-data field are ignored by 2476 the client. If OPTION_V4_ZEROTOUCH_REDIRECT does not contain at 2477 least one valid URI entry in the uri-data field, then the client MUST 2478 discard the option. 2480 DHCPv4 Server Behavior 2482 The DHCPv4 server MAY include a single instance of Option 2483 OPTION_V4_ZEROTOUCH_REDIRECT in DHCP messages it sends. Servers MUST 2484 NOT send more than one instance of the OPTION_V4_ZEROTOUCH_REDIRECT 2485 option. 2487 9.2. DHCPv6 Zero Touch Option 2489 The DHCPv6 Zero Touch Option is used to provision the client with one 2490 or more URIs for bootstrap servers that can be contacted to attempt 2491 further configuration. 2493 DHCPv6 Zero Touch Redirect Option 2495 0 1 2 3 2496 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 2497 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2498 | option-code (TBD) | option-length | 2499 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2500 . bootstrap-server-list (variable length) . 2501 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2503 o option-code: OPTION_V6_ZEROTOUCH_REDIRECT (TBD) 2504 o option-length: The option length in octets 2505 o bootstrap-server-list: A list of servers for the client to 2506 attempt contacting, in order to obtain further bootstrapping 2507 data, in the format shown in [common-field-encoding]. 2509 DHCPv6 Client Behavior 2511 Clients MAY request the OPTION_V6_ZEROTOUCH_REDIRECT option, as 2512 defined in [RFC3315], Sections 17.1.1, 18.1.1, 18.1.3, 18.1.4, 2513 18.1.5, and 22.7. As a convenience to the reader, we mention here 2514 that the client includes requested option codes in the Option Request 2515 Option. 2517 On receipt of a DHCPv6 reply message which contains the 2518 OPTION_V6_ZEROTOUCH_REDIRECT, the client performs the following 2519 steps: 2521 1. Check the contents of the DHCPv6 message for at least one valid 2522 URI. If there is more than one valid URI in the list, a 2523 candidate list of possible URIs is created. 2525 2. Attempt to connect to the one of the URIs in the candidate list. 2526 The order in which these are processed by the client is 2527 implementation specific and not defined here. 2529 3. If a successful connection to the zerotouch bootstrap server, 2530 then the client stops processing entries in the list and proceeds 2531 according to Appendix A.3, step(3). 2533 4. If the zerotouch bootstrap server does not respond, provides 2534 and invalid response or the transaction otherwise fails, the 2535 client SHOULD attempt to contact another server from the 2536 candidate list. 2538 Any invalid URI entries received in the uri-data field are ignored by 2539 the client. If OPTION_V6_ZEROTOUCH_REDIRECT does not contain at 2540 least one valid URI entry in the uri-data field, then the client MUST 2541 discard the option. 2543 DHCPv6 Server Behavior 2545 Sections 17.2.2 and 18.2 of [RFC3315] govern server operation 2546 in regard to option assignment. As a convenience to the reader, 2547 we mention here that the server will send a particular option code 2548 only if configured with specific values for that option code and if 2549 the client requested it. 2551 Option OPTION_V6_ZEROTOUCH_REDIRECT is a singleton. Servers MUST NOT 2552 send more than one instance of the OPTION_V6_ZEROTOUCH_REDIRECT 2553 option. 2555 9.3. Common Field Encoding 2557 Both of the DHCPv4 and DHCPv6 options defined in this section encode 2558 a list of bootstrap server URIs. The "URI" structure is an option 2559 that can contain multiple URIs (see [RFC7227], Section 5.7). 2561 bootstrap-server-list: 2563 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 2564 | uri-length | URI | 2565 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 2567 o uri-length: variable, in octets. 2569 o URI: URI of zerotouch bootstrap server, using the HTTPS URI 2570 scheme defined in Section 2.7.2 of RFC7230. URI MUST be in 2571 form "https://[:]". 2573 10. Security Considerations 2575 10.1. Immutable storage for trust anchors 2577 Devices MUST ensure that all their trust anchor certificates, 2578 including those for connecting to bootstrap servers and verifying 2579 ownership vouchers, are protected from external modification. 2581 It may be necessary to update these certificates over time (e.g., the 2582 manufacturer wants to delegate trust to a new CA). It is therefore 2583 expected that devices MAY update these trust anchors when needed 2584 through a verifiable process, such as a software upgrade using signed 2585 software images. 2587 10.2. Clock Sensitivity 2589 The solution in this document relies on TLS certificates, owner 2590 certificates, and ownership vouchers, all of which require an 2591 accurate clock in order to be processed correctly (e.g., to test 2592 validity dates and revocation status). Implementations SHOULD ensure 2593 devices have an accurate clock when shipped from manufacturing 2594 facilities, and take steps to prevent clock tampering. 2596 If it is not possible to ensure clock accuracy, it is RECOMMENDED 2597 that implementations disable the aspects of the solution having clock 2598 sensitivity. In particular, such implementations should assume that 2599 TLS certificates, ownership vouchers, and owner certificates never 2600 expire and are not revokable. From an ownership voucher perspective, 2601 manufacturers SHOULD issue a single ownership voucher for the 2602 lifetime of such devices. 2604 Implementations SHOULD NOT rely on NTP for time, as NTP is not a 2605 secure protocol. 2607 10.3. Blindly authenticating a bootstrap server 2609 This document allows a device to blindly authenticate a bootstrap 2610 server's TLS certificate. It does so to allow for cases where the 2611 redirect information may be obtained in an unsecured manner, which is 2612 desirable to support in some cases. 2614 To compensate for this, this document requires that devices, when 2615 connected to an untrusted bootstrap server, assert that data 2616 downloaded from the server is signed. 2618 10.4. Entropy loss over time 2620 Section 7.2.7.2 of the IEEE Std 802.1AR-2009 standard says that 2621 IDevID certificate should never expire (i.e. having the notAfter 2622 value 99991231235959Z). Given the long-lived nature of these 2623 certificates, it is paramount to use a strong key length (e.g., 2624 512-bit ECC). 2626 10.5. Disclosing Information to Untrusted Servers 2628 This document enables devices to establish provisional connections to 2629 bootstrap servers, in order for the bootstrap server to provide 2630 either unsigned redirect information or signed data to the device. 2631 However, since the server is untrusted, it may be under the control 2632 of an adversary, and therefore devices should be cautious about the 2633 data they send in such cases. 2635 Already this document requires devices send their IDevID certificate 2636 to untrusted bootstrap servers, which means that the device's serial 2637 number and hardware manufacturer may be disclosed to an adversary. 2638 Serial numbers are ubiquitous and prominently contained in invoices 2639 and on labels affixed to devices and their packaging. That said, 2640 serial numbers many times encode revealing information, such as the 2641 device's model number, manufacture date, and/or manufacturing 2642 sequence number. Knowledge of this information may provide an 2643 adversary with details needed to launch an attack. 2645 In addition to the IDevID certificate, there are other potentially 2646 identifying values that may be disclosed to an untrusted server, 2647 including 'os-name', 'os-version', 'remote-id', 'circuit-id', and 2648 progress reports. In order to address this issue, it is RECOMMENDED 2649 that implementations first promote the untrusted connection to a 2650 trusted connection, as described in Appendix B. 2652 10.6. Sequencing Sources of Bootstrapping Data 2654 For devices supporting more than one source for bootstrapping data, 2655 no particular sequencing order has to be observed for security 2656 reasons, as the solution for each source is considered equally 2657 secure. However, from a privacy perspective, it is RECOMMENDED that 2658 devices access local sources before accessing remote sources. 2660 10.7. The "ietf-zerotouch-information" YANG Module 2662 The ietf-zerotouch-information module defined in this document 2663 defines a data structure that is always wrapped by a PKCS#7 2664 structure. When accessed by a secure mechanism (e.g., protected by 2665 TLS), then the PKCS#7 structure may be unsigned. However, when 2666 accessed by an insecure mechanism (e.g., removable storage device), 2667 then the PKCS#7 structure must be signed, in order for the device to 2668 trust it. 2670 Implementations should be aware that signed bootstrapping data only 2671 protects the data from modification, the contents are still visible 2672 to others. This doesn't affect Security so much as Privacy. That 2673 the contents may be read by unintended parties when accessed by 2674 insecure mechanisms is considered next. 2676 The ietf-zerotouch-information module defines a top-level 'choice' 2677 statement that declares the contents are either "redirect- 2678 information" or "onboarding-information". Each of these two cases 2679 are now considered. 2681 When the contents of the PKCS#7 structure are redirect-information, 2682 an observer can learn about the bootstrap servers the device is being 2683 directed, their IP addresses or hostnames, ports, and trust anchor 2684 certificates. Knowledge of this information could provide an 2685 observer some insight into a network's inner structure. 2687 When the contents of the PKCS#7 structure are onboarding-information, 2688 as observer could learn considerable information about how the device 2689 is to be provisioned. This information includes the specific 2690 operating system version, the initial configuration, and the specific 2691 scripts that the device is to run. All of this information should be 2692 considered highly sensitive and precautions should be taken to 2693 protect it from falling into the wrong hands. 2695 10.8. The "ietf-zerotouch-bootstrap-server" YANG Module 2697 The ietf-zerotouch-bootstrap-server module defined in this document 2698 is specifies an API for a RESTCONF [RFC8040]. The lowest RESTCONF 2699 layer is HTTPS, and the mandatory-to-implement secure transport is 2700 TLS [RFC5246]. 2702 The NETCONF Access Control Model (NACM) [RFC6536] provides the means 2703 to restrict access for particular users to a preconfigured subset of 2704 all available protocol operations and content. 2706 This module presents no data nodes (only RPCs). There is no need to 2707 discuss the sensitivity of data nodes. 2709 This module defines two RPC operations that may be considered 2710 sensitive in some network environments. These are the operations and 2711 their sensitivity/vulnerability: 2713 get-bootstrapping-data: This RPC is used by devices to obtain their 2714 bootstrapping data. By design, each device, as identified by its 2715 IDevID certificate, can only obtain its own data. NACM is not 2716 needed to further constrain access to this RPC. 2718 report-bootstrapping-progress: This RPC is used by devices to report 2719 their bootstrapping progress. By design, each device, as 2720 identified by its IDevID certificate, can only report data for 2721 itself. NACM is not needed to further constrain access to this 2722 RPC. 2724 10.9. The "ietf-zerotouch-device" YANG Module 2726 The ietf-zerotouch-device module defined in this document is designed 2727 to be accessed via network management protocols such as NETCONF 2728 [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the 2729 secure transport layer, and the mandatory-to-implement secure 2730 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 2731 is HTTPS, and the mandatory-to-implement secure transport is TLS 2732 [RFC5246]. 2734 The NETCONF access control model [RFC6536] provides the means to 2735 restrict access for particular NETCONF or RESTCONF users to a 2736 preconfigured subset of all available NETCONF or RESTCONF protocol 2737 operations and content. 2739 There is a data node defined in this YANG module that is 2740 writable/creatable/deletable (i.e., config true, which is the 2741 default). This data node may be considered sensitive or vulnerable 2742 in some network environments. Write operations (e.g., edit-config) 2743 to this data node without proper protection can have a negative 2744 effect on network operations. This is the data node and its 2745 sensitivity/vulnerability: 2747 /enabled: This data node is used to enable/disable the zerotouch 2748 bootstrapping mechanism on a device. NACM rules or equivalent 2749 should be used to restrict write-access to this node to 2750 authenticated clients. 2752 11. IANA Considerations 2754 11.1. The BOOTP Manufacturer Extensions and DHCP Options Registry 2756 IANA is kindly requested to allocate a new option code from the 2757 "BOOTP Manufacturer Extensions and DHCP Options" registry maintained 2758 at http://www.iana.org/assignments/bootp-dhcp-parameters: 2760 TBD for OPTION_V4_ZEROTOUCH_REDIRECT 2762 And a new option code from the "Dynamic Host Configuration Protocol 2763 for IPv6 (DHCPv6)" registry maintained at 2764 http://www.iana.org/assignments/dhcpv6-parameters: 2766 TBD for OPTION_V6_ZEROTOUCH_REDIRECT 2768 11.2. The IETF XML Registry 2770 This document registers three URIs in the IETF XML registry 2771 [RFC3688]. Following the format in [RFC3688], the following 2772 registrations are requested: 2774 URI: urn:ietf:params:xml:ns:yang:ietf-zerotouch-information 2775 Registrant Contact: The NETCONF WG of the IETF. 2776 XML: N/A, the requested URI is an XML namespace. 2778 URI: urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server 2779 Registrant Contact: The NETCONF WG of the IETF. 2780 XML: N/A, the requested URI is an XML namespace. 2782 URI: urn:ietf:params:xml:ns:yang:ietf-zerotouch-device 2783 Registrant Contact: The NETCONF WG of the IETF. 2784 XML: N/A, the requested URI is an XML namespace. 2786 11.3. The YANG Module Names Registry 2788 This document registers three YANG modules in the YANG Module Names 2789 registry [RFC6020]. Following the format defined in [RFC6020], the 2790 the following registrations are requested: 2792 name: ietf-zerotouch-information 2793 namespace: urn:ietf:params:xml:ns:yang:ietf-zerotouch-information 2794 prefix: zti 2795 reference: RFC XXXX 2797 name: ietf-zerotouch-bootstrap-server 2798 namespace: urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-\ 2799 server (note: '\' used for formatting reasons only) 2800 prefix: ztbs 2801 reference: RFC XXXX 2803 name: ietf-zerotouch-device 2804 namespace: urn:ietf:params:xml:ns:yang:ietf-zerotouch-device 2805 prefix: ztd 2806 reference: RFC XXXX 2808 12. Acknowledgements 2810 The authors would like to thank for following for lively discussions 2811 on list and in the halls (ordered by last name): David Harrington, 2812 Michael Behringer, Dean Bogdanovic, Martin Bjorklund, Joe Clarke, 2813 Toerless Eckert, Stephen Farrell, Stephen Hanna, Wes Hardaker, Radek 2814 Krejci, Russ Mundy, Reinaldo Penno, Randy Presuhn, Max Pritikin, 2815 Michael Richardson, Phil Shafer, Juergen Schoenwaelder. 2817 Special thanks goes to Steve Hanna, Russ Mundy, and Wes Hardaker for 2818 brainstorming the original I-D's solution during the IETF 87 meeting 2819 in Berlin. 2821 13. References 2823 13.1. Normative References 2825 [I-D.ietf-anima-voucher] 2826 Watsen, K., Richardson, M., Pritikin, M., and T. Eckert, 2827 "Voucher Profile for Bootstrapping Protocols", draft-ietf- 2828 anima-voucher-05 (work in progress), August 2017. 2830 [ITU.X690.1994] 2831 International Telecommunications Union, "Information 2832 Technology - ASN.1 encoding rules: Specification of Basic 2833 Encoding Rules (BER), Canonical Encoding Rules (CER) and 2834 Distinguished Encoding Rules (DER)", ITU-T Recommendation 2835 X.690, 1994. 2837 [RFC1035] Mockapetris, P., "Domain names - implementation and 2838 specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, 2839 November 1987, . 2841 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2842 Requirement Levels", BCP 14, RFC 2119, 2843 DOI 10.17487/RFC2119, March 1997, 2844 . 2846 [RFC2315] Kaliski, B., "PKCS #7: Cryptographic Message Syntax 2847 Version 1.5", RFC 2315, DOI 10.17487/RFC2315, March 1998, 2848 . 2850 [RFC3315] Droms, R., Ed., Bound, J., Volz, B., Lemon, T., Perkins, 2851 C., and M. Carney, "Dynamic Host Configuration Protocol 2852 for IPv6 (DHCPv6)", RFC 3315, DOI 10.17487/RFC3315, July 2853 2003, . 2855 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2856 Housley, R., and W. Polk, "Internet X.509 Public Key 2857 Infrastructure Certificate and Certificate Revocation List 2858 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 2859 . 2861 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2862 the Network Configuration Protocol (NETCONF)", RFC 6020, 2863 DOI 10.17487/RFC6020, October 2010, 2864 . 2866 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2867 Verification of Domain-Based Application Service Identity 2868 within Internet Public Key Infrastructure Using X.509 2869 (PKIX) Certificates in the Context of Transport Layer 2870 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2871 2011, . 2873 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 2874 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 2875 DOI 10.17487/RFC6234, May 2011, 2876 . 2878 [RFC6762] Cheshire, S. and M. Krochmal, "Multicast DNS", RFC 6762, 2879 DOI 10.17487/RFC6762, February 2013, 2880 . 2882 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 2883 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, 2884 . 2886 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2887 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2888 . 2890 [RFC7227] Hankins, D., Mrugalski, T., Siodelski, M., Jiang, S., and 2891 S. Krishnan, "Guidelines for Creating New DHCPv6 Options", 2892 BCP 187, RFC 7227, DOI 10.17487/RFC7227, May 2014, 2893 . 2895 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2896 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2897 . 2899 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2900 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2901 . 2903 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2904 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2905 May 2017, . 2907 [Std-802.1AR-2009] 2908 IEEE SA-Standards Board, "IEEE Standard for Local and 2909 metropolitan area networks - Secure Device Identity", 2910 December 2009, . 2913 13.2. Informative References 2915 [I-D.ietf-netconf-keystore] 2916 Watsen, K., "Keystore Model", draft-ietf-netconf- 2917 keystore-02 (work in progress), June 2017. 2919 [I-D.ietf-netconf-netconf-client-server] 2920 Watsen, K., Wu, G., and J. Schoenwaelder, "NETCONF Client 2921 and Server Models", draft-ietf-netconf-netconf-client- 2922 server-04 (work in progress), July 2017. 2924 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2925 DOI 10.17487/RFC3688, January 2004, 2926 . 2928 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2929 (TLS) Protocol Version 1.2", RFC 5246, 2930 DOI 10.17487/RFC5246, August 2008, 2931 . 2933 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2934 and A. Bierman, Ed., "Network Configuration Protocol 2935 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2936 . 2938 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2939 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2940 . 2942 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2943 Protocol (NETCONF) Access Control Model", RFC 6536, 2944 DOI 10.17487/RFC6536, March 2012, 2945 . 2947 [RFC6698] Hoffman, P. and J. Schlyter, "The DNS-Based Authentication 2948 of Named Entities (DANE) Transport Layer Security (TLS) 2949 Protocol: TLSA", RFC 6698, DOI 10.17487/RFC6698, August 2950 2012, . 2952 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 2953 Galperin, S., and C. Adams, "X.509 Internet Public Key 2954 Infrastructure Online Certificate Status Protocol - OCSP", 2955 RFC 6960, DOI 10.17487/RFC6960, June 2013, 2956 . 2958 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 2959 System Management", RFC 7317, DOI 10.17487/RFC7317, August 2960 2014, . 2962 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 2963 RFC 8071, DOI 10.17487/RFC8071, February 2017, 2964 . 2966 Appendix A. Workflow Overview 2968 The zero touch solution presented in this document is conceptualized 2969 to be composed of the non-normative workflows described in this 2970 section. Implementation details are expected to vary. Each diagram 2971 is followed by a detailed description of the steps presented in the 2972 diagram, with further explanation on how implementations may vary. 2974 A.1. Enrollment and Ordering Devices 2976 The following diagram illustrates key interactions that may occur 2977 from when a prospective owner enrolls in a manufacturer's zero touch 2978 program to when the manufacturer ships devices for an order placed by 2979 the prospective owner. 2981 +-----------+ 2982 +------------+ |Prospective| +---+ 2983 |Manufacturer| | Owner | |NMS| 2984 +------------+ +-----------+ +---+ 2985 | | | 2986 | | | 2987 | 1. initiate enrollment | | 2988 #<-----------------------------| | 2989 # | | 2990 # | | 2991 # IDevID trust anchor | | 2992 #-----------------------------># set IDevID trust anchor | 2993 # #--------------------------->| 2994 # | | 2995 # bootstrap server | | 2996 # account credentials | | 2997 #-----------------------------># set credentials | 2998 | #--------------------------->| 2999 | | | 3000 | | | 3001 | 2. set owner certificate trust anchor | 3002 |<----------------------------------------------------------| 3003 | | | 3004 | | | 3005 | 3. place device order | | 3006 |<-----------------------------# model devices | 3007 | #--------------------------->| 3008 | | | 3009 | 4. ship devices and send | | 3010 | device identifiers and | | 3011 | ownership vouchers | | 3012 |-----------------------------># set device identifiers | 3013 | # and ownership vouchers | 3014 | #--------------------------->| 3015 | | | 3017 Each numbered item below corresponds to a numbered item in the 3018 diagram above. 3020 1. A prospective owner of a manufacturer's devices initiates an 3021 enrollment process with the manufacturer. This process includes 3022 the following: 3024 * Regardless how the prospective owner intends to bootstrap 3025 their devices, they will always obtain from the manufacturer 3026 the trust anchor certificate for the IDevID certificates. 3027 This certificate will is installed on the prospective owner's 3028 NMS so that the NMS can authenticate the IDevID certificates 3029 when they're presented to subsequent steps. 3031 * If the manufacturer hosts an Internet based bootstrap server 3032 (e.g., a redirect server) such as described in Section 4.4, 3033 then credentials necessary to configure the bootstrap server 3034 would be provided to the prospective owner. If the bootstrap 3035 server is configurable through an API (outside the scope of 3036 this document), then the credentials might be installed on the 3037 prospective owner's NMS so that the NMS can subsequently 3038 configure the manufacturer-hosted bootstrap server directly. 3040 2. If the manufacturer's devices are able to validate signed data 3041 (Section 5.4), and assuming that the prospective owner's NMS is 3042 able to prepare and sign the bootstrapping data itself, the 3043 prospective owner's NMS might set a trust anchor certificate onto 3044 the manufacturer's bootstrap server, using the credentials 3045 provided in the previous step. This certificate is the trust 3046 anchor certificate that the prospective owner would like the 3047 manufacturer to place into the ownership vouchers it generates, 3048 thereby enabling devices to trust the owner's owner certificate. 3049 How this trust anchor certificate is used to enable devices to 3050 validate signed bootstrapping data is described in Section 5.4. 3052 3. Some time later, the prospective owner places an order with the 3053 manufacturer, perhaps with a special flag checked for zero touch 3054 handling. At this time, or perhaps before placing the order, the 3055 owner may model the devices in their NMS, creating virtual 3056 objects for the devices with no real-world device associations. 3057 For instance the model can be used to simulate the device's 3058 location in the network and the configuration it should have when 3059 fully operational. 3061 4. When the manufacturer fulfills the order, shipping the devices to 3062 their intended locations, they may notify the owner of the 3063 devices's serial numbers and shipping destinations, which the 3064 owner may use to stage the network for when the devices power on. 3065 Additionally, the manufacturer may send one or more ownership 3066 vouchers, cryptographically assigning ownership of those devices 3067 to the owner. The owner may set this information on their NMS, 3068 perhaps binding specific modeled devices to the serial numbers 3069 and ownership vouchers. 3071 A.2. Owner Stages the Network for Bootstrap 3073 The following diagram illustrates how an owner might stage the 3074 network for bootstrapping devices. 3076 +----------+ +------------+ 3077 |Deployment| |Manufacturer| +------+ +------+ 3078 | Specific | | Hosted | | Local| | Local| +---------+ 3079 +---+ |Bootstrap | | Bootstrap | | DNS | | DHCP | |Removable| 3080 |NMS| | Server | | Server | |Server| |Server| | Storage | 3081 +---+ +----------+ +------------+ +------+ +------+ +---------+ 3082 | | | | | | 3083 1. | | | | | | 3084 activate | | | | | | 3085 modeled | | | | | | 3086 device | | | | | | 3087 -------->| | | | | | 3088 | 2. (optional) | | | | 3089 | configure | | | | 3090 | bootstrap | | | | 3091 | server | | | | 3092 |------->| | | | | 3093 | | | | | | 3094 | 3. (optional) configure | | | 3095 | bootstrap server | | | | 3096 |--------------------->| | | | 3097 | | | | | | 3098 | | | | | | 3099 | 4. (optional) configure DNS server| | | 3100 |---------------------------------->| | | 3101 | | | | | | 3102 | | | | | | 3103 | 5. (optional) configure DHCP server | | 3104 |------------------------------------------->| | 3105 | | | | | | 3106 | | | | | | 3107 | 6. (optional) store bootstrapping artifacts on media | 3108 |----------------------------------------------------->| 3109 | | | | | | 3110 | | | | | | 3112 Each numbered item below corresponds to a numbered item in the 3113 diagram above. 3115 1. Having previously modeled the devices, including setting their 3116 fully operational configurations and associating device serial 3117 numbers and (optionally) ownership vouchers, the owner might 3118 "activate" one or more modeled devices. That is, the owner tells 3119 the NMS to perform the steps necessary to prepare for when the 3120 real-world devices power up and initiate the bootstrapping 3121 process. Note that, in some deployments, this step might be 3122 combined with the last step from the previous workflow. Here it 3123 is depicted that an NMS performs the steps, but they may be 3124 performed manually or through some other mechanism. 3126 2. If it is desired to use a deployment specific bootstrap server, 3127 it must be configured to provide the bootstrapping information 3128 for the specific devices. Configuring the bootstrap server may 3129 occur via a programmatic API not defined by this document. 3130 Illustrated here as an external component, the bootstrap server 3131 may be implemented as an internal component of the NMS itself. 3133 3. If it is desired to use a manufacturer hosted bootstrap server, 3134 it must be configured to provide the bootstrapping information 3135 for the specific devices. The configuration must be either 3136 redirect or onboarding information. That is, either the 3137 manufacturer hosted bootstrap server will redirect the device to 3138 another bootstrap server, or provide the device with the 3139 onboarding information itself. The types of bootstrapping 3140 information the manufacturer hosted bootstrap server supports may 3141 vary by implementation; some implementations may only support 3142 redirect information, or only support onboarding information, or 3143 support both redirect and onboarding information. Configuring 3144 the bootstrap server may occur via a programmatic API not defined 3145 by this document. 3147 4. If it is desired to use a DNS server to supply bootstrapping 3148 information, a DNS server needs to be configured. If multicast 3149 DNS-SD is desired, then the server must reside on the local 3150 network, otherwise the DNS server may reside on a remote network. 3151 Please see Section 4.2 for more information about how to 3152 configure DNS servers. Configuring the DNS server may occur via 3153 a programmatic API not defined by this document. 3155 5. If it is desired to use a DHCP server to supply bootstrapping 3156 data, a DHCP server needs to be configured. The DHCP server may 3157 be accessed directly or via a DHCP relay. Please see Section 4.3 3158 for more information about how to configure DHCP servers. 3159 Configuring the DHCP server may occur via a programmatic API not 3160 defined by this document. 3162 6. If it is desired to use a removable storage device (e.g., USB 3163 flash drive) to supply bootstrapping information, the information 3164 would need to be placed onto it. Please see Section 4.1 for more 3165 information about how to configure a removable storage device. 3167 A.3. Device Powers On 3169 The following diagram illustrates the sequence of activities that 3170 occur when a device powers on. 3172 +----------+ 3173 +-----------+ |Deployment| 3174 | Source of | | Specific | 3175 +------+ | Bootstrap | |Bootstrap | +---+ 3176 |Device| | Data | | Server | |NMS| 3177 +------+ +-----------+ +----------+ +---+ 3178 | | | | 3179 | | | | 3180 | 1. if zerotouch bootstrap service | | | 3181 | is not enabled, then exit. | | | 3182 | | | | 3183 | 2. for each source supported, check | | | 3184 | for bootstrapping data. | | | 3185 |------------------------------------->| | | 3186 | | | | 3187 | 3. if onboarding information found, | | | 3188 | initialize self and, only if | | | 3189 | source is a bootstrap server, | | | 3190 | send progress updates. | | | 3191 |-------------------------------------># | | 3192 | # webhook | | 3193 | #----------------------->| 3194 | | | 3195 | 4. else if redirect-information found, for each | | 3196 | bootstrap server specified, check for data. | | 3197 |-+-------------------------------------------------->| | 3198 | | | | 3199 | | if more redirect-information is found, recurse | | 3200 | | (not depicted), else if onboarding-information | | 3201 | | found, initialize self and post progress reports | | 3202 | +--------------------------------------------------># | 3203 | # webhook | 3204 | #-------->| 3205 | 3206 | 5. retry sources and/or wait for manual provisioning. 3207 | 3209 The interactions in the above diagram are described below. 3211 1. Upon power being applied, the device checks to see if zerotouch 3212 bootstrapping is configured, such as must be the case when 3213 running its "factory default" configuration. If zerotouch 3214 bootstrapping is not configured, then the bootstrapping logic 3215 exits and none of the following interactions occur. 3217 2. For each source of bootstrapping data the device supports, 3218 preferably in order of closeness to the device (e.g., removable 3219 storage before Internet based servers), the device checks to see 3220 if there is any bootstrapping data for it there. 3222 3. If onboarding information is found, the device initializes itself 3223 accordingly (e.g., installing a boot-image and committing an 3224 initial configuration). If the source is a bootstrap server, and 3225 the bootstrap server can be trusted (i.e., TLS-level 3226 authentication), the device also sends progress reports to the 3227 bootstrap server. 3229 * The contents of the initial configuration should configure an 3230 administrator account on the device (e.g., username, ssh-rsa 3231 key, etc.), and should configure the device either to listen 3232 for NETCONF or RESTCONF connections or to initiate call home 3233 connections [RFC8071], and should disable the zerotouch 3234 bootstrapping service. 3236 * If the bootstrap server supports forwarding device progress 3237 updates to external systems (e.g., via a webhook), a 3238 "bootstrap-complete" progress report (Section 7.3) informs the 3239 external system to know when it can, for instance, initiate a 3240 connection to the device. To support this scenario further, 3241 the 'bootstrap-complete' progress update may also relay the 3242 device's SSH host keys and/or TLS certificates, with which the 3243 external system can use to authenticate subsequent connections 3244 to the device. IDevID certificates do not need to be sent as 3245 they do not need to be pinned by an NMS in order for the NMS 3246 to trust the IDevID certificate. 3248 If the device successfully completes the bootstrapping process, 3249 it exits the bootstrapping logic without considering any 3250 additional sources of bootstrapping data. 3252 4. Otherwise, if redirect information is found, the device iterates 3253 through the list of specified bootstrap servers, checking to see 3254 if it has bootstrapping data for the device. If the bootstrap 3255 server returns more redirect information, then the device 3256 processes it recursively. Otherwise, if the bootstrap server 3257 returns onboarding information, the device processes it following 3258 the description provided in (3) above. 3260 5. After having tried all supported sources of bootstrapping data, 3261 the device may retry again all the sources and/or provide 3262 manageability interfaces for manual configuration (e.g., CLI, 3263 HTTP, NETCONF, etc.). If manual configuration is allowed, and 3264 such configuration is provided, the configuration should also 3265 disable the zerotouch bootstrapping service, as the need for 3266 bootstrapping would no longer be present. 3268 Appendix B. Promoting a Connection from Untrusted to Trusted 3270 The following diagram illustrates a sequence of bootstrapping 3271 activities that promote an untrusted connection to a bootstrap server 3272 to a trusted connection to the same bootstrap server. This enables a 3273 device to limit the amount of information it might disclose to an 3274 adversary hosting an untrusted bootstrap server. 3276 +----------+ 3277 |Deployment| 3278 | Specific | 3279 +------+ |Bootstrap | 3280 |Device| | Server | 3281 +------+ +----------+ 3282 | | 3283 | 1. "HTTPS" Request ('untrusted-connection') | 3284 |------------------------------------------------------->| 3285 | 2. "HTTPS" Response (signed redirect information) | 3286 |<-------------------------------------------------------| 3287 | | 3288 | | 3289 | 3. HTTPS Request (os-name=xyz, os-version=123, etc.) | 3290 |------------------------------------------------------->| 3291 | 4. HTTPS Response (unsigned onboarding information | 3292 |<-------------------------------------------------------| 3293 | | 3295 The interactions in the above diagram are described below. 3297 1. The device initiates an untrusted connection to a bootstrap 3298 server, as is indicated by putting "HTTPS" in double quotes 3299 above. It is still an HTTPS connection, but the device is unable 3300 to authenticate the bootstrap server's TLS certificate. Because 3301 the device is unable to trust the bootstrap server, it purposely 3302 only sends the 'untrusted-connection' input parameter to the 3303 'get-bootstrapping-data' RPC, informing the bootstrap server that 3304 it doesn't trust it and may be holding back some information from 3305 the server (e.g., other input parameters, progress reports, 3306 etc.). 3308 2. The bootstrap server, seeing the 'untrusted-connection' input 3309 parameters, knows that it can either send unsigned redirect 3310 information or signed data of any type. But, in this case, the 3311 bootstrap server has the ability to sign data and chooses to 3312 respond with signed redirect information, not signed onboarding 3313 information as might be expected, securely redirecting the device 3314 back to it again. 3316 3. Upon validating the signed redirect information, the device 3317 establishes a secure connection to the bootstrap server. 3318 Unbeknownst to the device, it is the same bootstrap server it was 3319 connected to previously but, because the device is able to 3320 authenticate the bootstrap server tis time, it sends its normal 3321 'get-bootstrapping-data' request (i.e., with additional input 3322 parameters) as well as its progress reports (not depicted). 3324 4. This time, because the 'untrusted-connection' parameter was not 3325 passed, having access to all of the device's input parameters, 3326 the bootstrap server returns unsigned onboarding information to 3327 the device. 3329 Appendix C. Change Log 3331 C.1. ID to 00 3333 o Major structural update; the essence is the same. Most every 3334 section was rewritten to some degree. 3336 o Added a Use Cases section 3338 o Added diagrams for "Actors and Roles" and "NMS Precondition" 3339 sections, and greatly improved the "Device Boot Sequence" diagram 3341 o Removed support for physical presence or any ability for 3342 configlets to not be signed. 3344 o Defined the Zero Touch Information DHCP option 3346 o Added an ability for devices to also download images from 3347 configuration servers 3349 o Added an ability for configlets to be encrypted 3351 o Now configuration servers only have to support HTTP/S - no other 3352 schemes possible 3354 C.2. 00 to 01 3356 o Added boot-image and validate-owner annotations to the "Actors and 3357 Roles" diagram. 3359 o Fixed 2nd paragraph in section 7.1 to reflect current use of 3360 anyxml. 3362 o Added encrypted and signed-encrypted examples 3364 o Replaced YANG module with XSD schema 3366 o Added IANA request for the Zero Touch Information DHCP Option 3368 o Added IANA request for media types for boot-image and 3369 configuration 3371 C.3. 01 to 02 3373 o Replaced the need for a configuration signer with the ability for 3374 each NMS to be able to sign its own configurations, using 3375 manufacturer signed ownership vouchers and owner certificates. 3377 o Renamed configuration server to bootstrap server, a more 3378 representative name given the information devices download from 3379 it. 3381 o Replaced the concept of a configlet by defining a southbound 3382 interface for the bootstrap server using YANG. 3384 o Removed the IANA request for the boot-image and configuration 3385 media types 3387 C.4. 02 to 03 3389 o Minor update, mostly just to add an Editor's Note to show how this 3390 draft might integrate with the draft-pritikin-anima-bootstrapping- 3391 keyinfra. 3393 C.5. 03 to 04 3395 o Major update formally introducing unsigned data and support for 3396 Internet-based redirect servers. 3398 o Added many terms to Terminology section. 3400 o Added all new "Guiding Principles" section. 3402 o Added all new "Sources for Bootstrapping Data" section. 3404 o Rewrote the "Interactions" section and renamed it "Workflow 3405 Overview". 3407 C.6. 04 to 05 3409 o Semi-major update, refactoring the document into more logical 3410 parts 3412 o Created new section for information types 3414 o Added support for DNS servers 3416 o Now allows provisional TLS connections 3418 o Bootstrapping data now supports scripts 3420 o Device Details section overhauled 3422 o Security Considerations expanded 3424 o Filled in enumerations for notification types 3426 C.7. 05 to 06 3428 o Minor update 3430 o Added many Normative and Informative references. 3432 o Added new section Other Considerations. 3434 C.8. 06 to 07 3436 o Minor update 3438 o Added an Editorial Note section for RFC Editor. 3440 o Updated the IANA Considerations section. 3442 C.9. 07 to 08 3444 o Minor update 3446 o Updated to reflect review from Michael Richardson. 3448 C.10. 08 to 09 3450 o Added in missing "Signature" artifact example. 3452 o Added recommendation for manufacturers to use interoperable 3453 formats and file naming conventions for removable storage devices. 3455 o Added configuration-handling leaf to guide if config should be 3456 merged, replaced, or processed like an edit-config/yang-patch 3457 document. 3459 o Added a pre-configuration script, in addition to the post- 3460 configuration script from -05 (issue #15). 3462 C.11. 09 to 10 3464 o Factored ownership voucher and voucher revocation to a separate 3465 document: draft-kwatsen-netconf-voucher. (issue #11) 3467 o Removed options 'edit-config' and 'yang- 3468 patch'. (issue #12) 3470 o Defined how a signature over signed-data returned from a bootstrap 3471 server is processed. (issue #13) 3473 o Added recommendation for removable storage devices to use open/ 3474 standard file systems when possible. (issue #14) 3476 o Replaced notifications "script-[warning/error]" with "[pre/post]- 3477 script-[warning/error]". (goes with issue #15) 3479 o switched owner-certificate to be encoded using the pkcs#7 format. 3480 (issue #16) 3482 o Replaced md5/sha1 with sha256 inside a choice statement, for 3483 future extensibility. (issue #17) 3485 o A ton of editorial changes, as I went thru the entire draft with a 3486 fine-toothed comb. 3488 C.12. 10 to 11 3490 o fixed yang validation issues found by IETFYANGPageCompilation. 3491 note: these issues were NOT found by pyang --ietf or by the 3492 submission-time validator... 3494 o fixed a typo in the yang module, someone the config false 3495 statement was removed. 3497 C.13. 11 to 12 3499 o fixed typo that prevented Appendix B from loading the examples 3500 correctly. 3502 o fixed more yang validation issues found by 3503 IETFYANGPageCompilation. note: again, these issues were NOT found 3504 by pyang --ietf or by the submission-time validator... 3506 o updated a few of the notification enumerations to be more 3507 consistent with the other enumerations (following the warning/ 3508 error pattern). 3510 o updated the information-type artifact to state how it's encoded, 3511 matching the language that was in Appendix B. 3513 C.14. 12 to 13 3515 o defined a standalone artifact to encode the old information-type 3516 into a PKCS#7 structure. 3518 o standalone information artifact hardcodes JSON encoding (to match 3519 the voucher draft). 3521 o combined the information and signature PKCS#7 structures into a 3522 single PKCS#7 structure. 3524 o moved the certificate-revocations into the owner-certificate's 3525 PKCS#7 structure. 3527 o eliminated support for voucher-revocations, to reflect the 3528 voucher-draft's switch from revocations to renewals. 3530 C.15. 13 to 14 3532 o Renamed "bootstrap information" to "onboarding information". 3534 o Rewrote DHCP sections to address the packet-size limitation issue, 3535 as discussed in Chicago. 3537 o Added Ian as an author for his text-contributions to the DHCP 3538 sections. 3540 o Removed the Guiding Principles section. 3542 C.16. 14 to 15 3544 o Renamed action 'notification' to 'update-progress' and, likewise 3545 'notification-type' to 'update-type'. 3547 o Updated examples to use "base64encodedvalue==" for binary values. 3549 o Greatly simplified the "Artifact Groupings" section, and moved it 3550 as a subsection to the "Artifacts" section. 3552 o Moved the "Workflow Overview" section to the Appendix. 3554 o Renamed "bootstrap information" to "update information". 3556 o Removed "Other Considerations" section. 3558 o Tons of editorial updates. 3560 C.17. 15 to 16 3562 o tweaked language to refer to "initial state" rather than "factory 3563 default configuration", so as accommodate white-box scenarios. 3565 o added a paragraph to Intro regarding how the solution primarily 3566 regards physical machines, but could be extended to VMs by a 3567 future document. 3569 o added a pointer to the Workflow Overview section (recently moved 3570 to the Appendix) to the Intro. 3572 o added a note that, in order to simplify the verification process, 3573 the "Zerotouch Information" PKCS#7 structure MUST also contain the 3574 signing X.509 certificate. 3576 o noted that the owner certificate's must either have no Key Usage 3577 or the Key Usage must set the "digitalSignature" bit. 3579 o noted that the owner certificate's subject and subjectAltName 3580 values are not constrained. 3582 o moved/consolidated some text from the Artifacts section down to 3583 the Device Details section. 3585 o tightened up some ambiguous language, for instance, by referring 3586 to specific leaf names in the Voucher artifact. 3588 o reverted a previously overzealous s/unique-id/serial-number/ 3589 change. 3591 o modified language for when ZTP runs from when factory-default 3592 config is running to when ZTP is configured, which the factory- 3593 defaults should set . 3595 C.18. 16 to 17 3597 o Added an example for how to promote an untrusted connection to a 3598 trusted connection. 3600 o Added a "query parameters" section defining some parameters 3601 enabling scenarios raised in last call. 3603 o Added a "Disclosing Information to Untrusted Servers" section to 3604 the Security Considerations. 3606 C.19. 17 to 18 3608 o Added Security Considerations for each YANG module. 3610 o Reverted back to the device always sending its DevID cert. 3612 o Moved data tree to ac'get-bootstrapping-data' RPC. 3614 o Moved the 'update-progress' action to a 'report-progress' RPC. 3616 o Added an 'untrusted-connection' parameter to 'get-bootstrapping- 3617 data' RPC. 3619 o Added the "ietf-zerotouch-device" module. 3621 o Lots of small updates. 3623 Authors' Addresses 3625 Kent Watsen 3626 Juniper Networks 3628 EMail: kwatsen@juniper.net 3630 Mikael Abrahamsson 3631 T-Systems 3633 EMail: mikael.abrahamsson@t-systems.se 3634 Ian Farrer 3635 Deutsche Telekom AG 3637 EMail: ian.farrer@telekom.de