idnits 2.17.1 draft-ietf-netconf-zerotouch-17.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 5 instances of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1329 has weird spacing: '...te that devic...' == Line 1495 has weird spacing: '...rmation pkc...' == Line 1505 has weird spacing: '...ey-data str...' == Line 1509 has weird spacing: '...ificate pkc...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The device MUST next authenticate the owner certificate by performing X.509 certificate path verification to the trusted certificate extracted from the voucher's 'pinned-domain-cert' node. 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 (September 11, 2017) is 2420 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC7468' is defined on line 2480, but no explicit reference was found in the text == Unused Reference: 'RFC2939' is defined on line 2509, but no explicit reference was found in the text == Outdated reference: A later version (-07) exists of draft-ietf-anima-voucher-05 ** Downref: Normative reference to an Informational RFC: RFC 2315 ** Obsolete normative reference: RFC 3315 (Obsoleted by RFC 8415) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Downref: Normative reference to an Informational RFC: RFC 6234 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-04 Summary: 5 errors (**), 0 flaws (~~), 10 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Juniper Networks 4 Intended status: Standards Track M. Abrahamsson 5 Expires: March 15, 2018 T-Systems 6 I. Farrer 7 Deutsche Telekom AG 8 September 11, 2017 10 Zero Touch Provisioning for NETCONF or RESTCONF based Management 11 draft-ietf-netconf-zerotouch-17 13 Abstract 15 This draft presents a secure technique for establishing a NETCONF or 16 RESTCONF connection between a newly deployed device, configured with 17 just its preconfigured initial state (e.g., factory default 18 settings), and its deployment specific network management system 19 (NMS). 21 Editorial Note (To be removed by RFC Editor) 23 This draft contains many placeholder values that need to be replaced 24 with finalized values at the time of publication. This note 25 summarizes all of the substitutions that are needed. Please note 26 that no other RFC Editor instructions are specified anywhere else in 27 this document. 29 Artwork in the IANA Considerations section contains placeholder 30 values for DHCP options pending IANA assignment. Please apply the 31 following replacements: 33 o "OPTION_V4_ZEROTOUCH_REDIRECT" --> the option code assigned for 34 the "DHCPv4 Zero Touch Option" option 36 o "OPTION_V6_ZEROTOUCH_REDIRECT" --> the option code assigned for 37 the "DHCPv6 Zero Touch Option" option 39 Artwork in this document contains shorthand references to drafts in 40 progress. Please apply the following replacements: 42 o "XXXX" --> the assigned RFC value for this draft 44 Artwork in this document contains placeholder values for the date of 45 publication of this draft. Please apply the following replacement: 47 o "2017-09-11" --> the publication date of this draft 48 Please update the following references to reflect their final RFC 49 assignments: 51 o I-D.ieft-netconf-netconf-client-server 53 The following one Appendix section is to be removed prior to 54 publication: 56 o Appendix A. Change Log 58 Status of This Memo 60 This Internet-Draft is submitted in full conformance with the 61 provisions of BCP 78 and BCP 79. 63 Internet-Drafts are working documents of the Internet Engineering 64 Task Force (IETF). Note that other groups may also distribute 65 working documents as Internet-Drafts. The list of current Internet- 66 Drafts is at https://datatracker.ietf.org/drafts/current/. 68 Internet-Drafts are draft documents valid for a maximum of six months 69 and may be updated, replaced, or obsoleted by other documents at any 70 time. It is inappropriate to use Internet-Drafts as reference 71 material or to cite them other than as "work in progress." 73 This Internet-Draft will expire on March 15, 2018. 75 Copyright Notice 77 Copyright (c) 2017 IETF Trust and the persons identified as the 78 document authors. All rights reserved. 80 This document is subject to BCP 78 and the IETF Trust's Legal 81 Provisions Relating to IETF Documents 82 (https://trustee.ietf.org/license-info) in effect on the date of 83 publication of this document. Please review these documents 84 carefully, as they describe your rights and restrictions with respect 85 to this document. Code Components extracted from this document must 86 include Simplified BSD License text as described in Section 4.e of 87 the Trust Legal Provisions and are provided without warranty as 88 described in the Simplified BSD License. 90 Table of Contents 92 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 93 1.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 5 94 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 95 1.3. Requirements Language . . . . . . . . . . . . . . . . . . 7 96 1.4. Tree Diagram Notation . . . . . . . . . . . . . . . . . . 7 97 2. Types of Bootstrapping Information . . . . . . . . . . . . . 8 98 2.1. Redirect Information . . . . . . . . . . . . . . . . . . 8 99 2.2. Onboarding Information . . . . . . . . . . . . . . . . . 9 100 3. Artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . 10 101 3.1. Zero Touch Information . . . . . . . . . . . . . . . . . 10 102 3.2. Owner Certificate . . . . . . . . . . . . . . . . . . . . 10 103 3.3. Ownership Voucher . . . . . . . . . . . . . . . . . . . . 11 104 3.4. Artifact Groupings . . . . . . . . . . . . . . . . . . . 11 105 4. Sources of Bootstrapping Data . . . . . . . . . . . . . . . . 12 106 4.1. Removable Storage . . . . . . . . . . . . . . . . . . . . 12 107 4.2. DNS Server . . . . . . . . . . . . . . . . . . . . . . . 13 108 4.3. DHCP Server . . . . . . . . . . . . . . . . . . . . . . . 15 109 4.4. Bootstrap Server . . . . . . . . . . . . . . . . . . . . 15 110 5. Device Details . . . . . . . . . . . . . . . . . . . . . . . 17 111 5.1. Initial State . . . . . . . . . . . . . . . . . . . . . . 17 112 5.2. Boot Sequence . . . . . . . . . . . . . . . . . . . . . . 18 113 5.3. Processing a Source of Bootstrapping Data . . . . . . . . 19 114 5.4. Validating Signed Data . . . . . . . . . . . . . . . . . 21 115 5.5. Processing Redirect Information . . . . . . . . . . . . . 22 116 5.6. Processing Onboarding Information . . . . . . . . . . . . 22 117 6. The Zero Touch Information Artifact . . . . . . . . . . . . . 23 118 6.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 23 119 6.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 24 120 6.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 27 121 7. The Zero Touch Bootstrap Server API . . . . . . . . . . . . . 32 122 7.1. API Overview . . . . . . . . . . . . . . . . . . . . . . 32 123 7.2. Query Parameters . . . . . . . . . . . . . . . . . . . . 33 124 7.3. Example Usage . . . . . . . . . . . . . . . . . . . . . . 34 125 7.4. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 37 126 8. DHCP Zero Touch Options . . . . . . . . . . . . . . . . . . . 44 127 8.1. DHCPv4 Zero Touch Option . . . . . . . . . . . . . . . . 45 128 8.2. DHCPv6 Zero Touch Option . . . . . . . . . . . . . . . . 46 129 8.3. Common Field Encoding . . . . . . . . . . . . . . . . . . 47 130 9. Security Considerations . . . . . . . . . . . . . . . . . . . 48 131 9.1. Immutable storage for trust anchors . . . . . . . . . . . 48 132 9.2. Clock Sensitivity . . . . . . . . . . . . . . . . . . . . 48 133 9.3. Blindly authenticating a bootstrap server . . . . . . . . 49 134 9.4. Entropy loss over time . . . . . . . . . . . . . . . . . 49 135 9.5. Serial Numbers . . . . . . . . . . . . . . . . . . . . . 49 136 9.6. Disclosing Information to Untrusted Servers . . . . . . . 49 137 9.7. Sequencing Sources of Bootstrapping Data . . . . . . . . 50 139 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 50 140 10.1. The BOOTP Manufacturer Extensions and DHCP Options 141 Registry . . . . . . . . . . . . . . . . . . . . . . . . 50 142 10.2. The IETF XML Registry . . . . . . . . . . . . . . . . . 50 143 10.3. The YANG Module Names Registry . . . . . . . . . . . . . 51 144 10.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 51 145 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 51 146 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 52 147 12.1. Normative References . . . . . . . . . . . . . . . . . . 52 148 12.2. Informative References . . . . . . . . . . . . . . . . . 54 149 Appendix A. Workflow Overview . . . . . . . . . . . . . . . . . 55 150 A.1. Enrollment and Ordering Devices . . . . . . . . . . . . . 55 151 A.2. Owner Stages the Network for Bootstrap . . . . . . . . . 57 152 A.3. Device Powers On . . . . . . . . . . . . . . . . . . . . 59 153 Appendix B. Promoting a Connection from Untrusted to Trusted . . 62 154 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 63 155 C.1. ID to 00 . . . . . . . . . . . . . . . . . . . . . . . . 63 156 C.2. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 63 157 C.3. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 64 158 C.4. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 64 159 C.5. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 64 160 C.6. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 64 161 C.7. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 65 162 C.8. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 65 163 C.9. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 65 164 C.10. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 65 165 C.11. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 65 166 C.12. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 66 167 C.13. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 66 168 C.14. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 67 169 C.15. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 67 170 C.16. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 67 171 C.17. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 68 172 C.18. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 68 173 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 69 175 1. Introduction 177 A fundamental business requirement for any network operator is to 178 reduce costs where possible. For network operators, deploying 179 devices to many locations can be a significant cost, as sending 180 trained specialists to each site for installations is both cost 181 prohibitive and does not scale. 183 This document defines a bootstrapping strategy enabling devices to 184 securely obtain bootstrapping data with no installer action beyond 185 physical placement and connecting network and power cables. The 186 ultimate goal of this document is to enable a secure NETCONF 188 [RFC6241] or RESTCONF [RFC8040] connection to a deployment specific 189 network management system (NMS). 191 This document primarily regards physical devices, where the setting 192 of the device's initial state, described in Section 5.1, occurs 193 during the device's manufacturing process. However, the zerotouch 194 solution may be extensible to virtual machines whereby, for instance, 195 the host-system has an IDevID certificate and some ability to verify 196 the virtual machine's image before loading it and also provision a 197 just-in-time IDevID certificate. Details for how this may be 198 accomplished can be defined in future work. 200 1.1. Use Cases 202 o Device connecting to a remotely administered network 204 This use-case involves scenarios, such as a remote branch 205 office or convenience store, whereby a device connects as an 206 access gateway to an ISP's network. Assuming it is not 207 possible to customize the ISP's network to provide any 208 bootstrapping support, and with no other nearby device to 209 leverage, the device has no recourse but to reach out to an 210 Internet-based bootstrap server to bootstrap from. 212 o Device connecting to a locally administered network 214 This use-case covers all other scenarios and differs only in 215 that the device may additionally leverage nearby devices, which 216 may direct it to use a local service to bootstrap from. If no 217 such information is available, or the device is unable to use 218 the information provided, it can then reach out to the network 219 just as it would for the remotely administered network use- 220 case. 222 Conceptual workflows for how zerotouch might be deployed are provided 223 in Appendix A. 225 1.2. Terminology 227 This document uses the following terms (sorted by name): 229 Artifact: The term "artifact" is used throughout to represent any of 230 the three artifacts defined in Section 3 (Zero Touch Information, 231 Ownership Voucher, and Owner Certificate). These artifacts 232 collectively provide all the bootstrapping data a device may use. 234 Bootstrapping Data: The term "bootstrapping data" is used throughout 235 this document to refer to the collection of data that a device 236 may obtain during the bootstrapping process. Specifically, it 237 refers to the three artifacts defined in Section 3. 239 Bootstrap Server: The term "bootstrap server" is used within this 240 document to mean any RESTCONF server implementing the YANG module 241 defined in Section 7.4. 243 Device: The term "device" is used throughout this document to refer 244 to the network element that needs to be bootstrapped. See 245 Section 5 for more information about devices. 247 Initial Secure Device Identifier (IDevID): The term "IDevID" is 248 defined in [Std-802.1AR-2009] as the globally unique secure 249 device identifier (DevID) installed on the device by the 250 manufacturer. This identifier is used in this document to enable 251 a Bootstrap Server to securely identify and authenticate a 252 device. 254 Manufacturer: The term "manufacturer" is used herein to refer to the 255 manufacturer of a device or a delegate of the manufacturer. 257 Network Management System (NMS): The acronym "NMS" is used 258 throughout this document to refer to the deployment specific 259 management system that the bootstrapping process is responsible 260 for introducing devices to. From a device's perspective, when 261 the bootstrapping process has completed, the NMS is a NETCONF or 262 RESTCONF client. 264 Onboarding Information: The term "onboarding information" is used 265 herein to refer to one of the two types of 'zero touch 266 information' (see term) defined in this document, the other being 267 'redirect information'. Specifically, onboarding information is 268 defined by the 'onboarding-information' YANG-data structure in 269 Section 6.3. 271 Owner: The term "owner" is used throughout this document to refer to 272 the person or organization that purchased or otherwise owns a 273 device. 275 Owner Certificate: The term "owner certificate" is used in this 276 document to represent an X.509 certificate that binds an owner 277 identity to a public key, which a device can use to validate a 278 signature over the zero touch information artifacts. The owner 279 certificate is one of the three bootstrapping artifacts described 280 in Section 3. 282 Ownership Voucher: The term "ownership voucher" is used in this 283 document to represent the voucher artifact defined in 285 [I-D.ietf-anima-voucher]. The ownership voucher is used to 286 assign a device to an owner. The ownership voucher is one of the 287 three bootstrapping artifacts described in Section 3. 289 Redirect Information: The term "redirect information" is used herein 290 to refer to one of the two types of 'zero touch information' (see 291 term) defined in this document, the other being 'onboarding 292 information'. Specifically, redirect information is defined by 293 the 'redirect-information' YANG-data structure in Section 6.3. 295 Redirect Server: The term "redirect server" is used to refer to a 296 bootstrap server that only returns redirect information. A 297 redirect server is particularly useful when hosted by a 298 manufacturer, as an Internet-based resource to redirect devices 299 to deployment-specific bootstrap servers. 301 Signed Data: The term "signed data" is used throughout to mean 302 either redirect information or onboarding information that has 303 been signed, specifically by a private key possessed by a 304 device's owner. 306 Unsigned Data: The term "unsigned data" is used throughout to mean 307 either redirect information or onboarding information that has 308 not been signed. 310 Zero Touch Information: The term "zero touch information" is used 311 generally herein to refer either redirect information or 312 onboarding information. Zero touch information is one of the 313 three bootstrapping artifacts described in Section 3. 315 1.3. Requirements Language 317 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 318 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 319 "OPTIONAL" in this document are to be interpreted as described in BCP 320 14 [RFC2119] [RFC8174] when, and only when, they appear in all 321 capitals, as shown here. 323 1.4. Tree Diagram Notation 325 A simplified graphical representation of the data models is used in 326 this document. The meaning of the symbols in these diagrams is as 327 follows: 329 o Brackets "[" and "]" enclose list keys. 331 o Braces "{" and "}" enclose feature names, and indicate that the 332 named feature must be present for the subtree to be present. 334 o Abbreviations before data node names: "rw" (read-write) represents 335 configuration data and "ro" (read-only) represents state data. 337 o Symbols after data node names: "?" means an optional node, "!" 338 means a presence container, and "*" denotes a list and leaf-list. 340 o Parentheses enclose choice and case nodes, and case nodes are also 341 marked with a colon (":"). 343 o Ellipsis ("...") stands for contents of subtrees that are not 344 shown. 346 2. Types of Bootstrapping Information 348 This document defines two types of information that devices access 349 during the bootstrapping process. These information types are 350 described in this section. Examples are provided in Section 6.2 352 2.1. Redirect Information 354 Redirect information redirects a device to another bootstrap server. 355 Redirect information encodes a list of bootstrap servers, each 356 defined by its hostname or IP address, an optional port, and an 357 optional trust anchor certificate. 359 Redirect information is YANG modeled data formally defined by the 360 "redirect-information" container in the YANG module presented in 361 Section 6.3. This container has the tree diagram shown below. 362 Please see Section 1.4 for tree diagram notation. 364 +--:(redirect-information) 365 +--ro redirect-information 366 +--ro bootstrap-server* [address] 367 +--ro address inet:host 368 +--ro port? inet:port-number 369 +--ro trust-anchor? binary 371 Redirect information MAY be trusted or untrusted. The redirect 372 information is trusted whenever it is obtained via a secure 373 connection to a trusted bootstrap server, or whenever it is signed by 374 the device's owner. In all other cases, the redirect information is 375 untrusted. 377 Trusted redirect information is useful for enabling a device to 378 establish a secure connection to a bootstrap server, which is 379 possible when the redirect information includes the bootstrap 380 server's trust anchor certificate. When a device is able to 381 establish a secure connection to a bootstrap server, the data is 382 implicitly trusted, and does not need to be signed. 384 Untrusted redirect information is useful for directing a device to a 385 bootstrap server where signed data has been staged for it to obtain. 386 When the redirect information is untrusted, the device MUST discard 387 any potentially included trust anchor certificates and SHOULD 388 establish a provisional connection (by blindly accepting the TLS 389 certificate) to any of the specified bootstrap servers. In this 390 case, the device MUST NOT trust the bootstrap server, and data 391 provided by the bootstrap server MUST be signed for it to be of any 392 use to the device. 394 How devices process redirect information is described more formally 395 in Section 5.5. 397 2.2. Onboarding Information 399 Bootstrap information provides all the data necessary for a device to 400 bootstrap itself, in order to be considered ready to be managed 401 (e.g., by an NMS). As defined in this document, this data includes 402 information about a boot image the device MUST be running, an initial 403 configuration the device MUST commit, and optional scripts that, if 404 specified, the device MUST successfully execute. 406 Bootstrap information is YANG modeled data formally defined by the 407 "onboarding-information" container in the YANG module presented in 408 Section 6.3. This container has the tree diagram shown below. 409 Please see Section 1.4 for tree diagram notation. 411 +--:(onboarding-information) 412 +--ro onboarding-information 413 +--ro boot-image 414 | +--ro name string 415 | +--ro (hash-algorithm) 416 | | +--:(sha256) 417 | | +--ro sha256? string 418 | +--ro uri* inet:uri 419 +--ro configuration-handling enumeration 420 +--ro pre-configuration-script? script 421 +--ro configuration? 422 +--ro post-configuration-script? script 424 Bootstrap information MUST be trusted for it to be of any use to a 425 device. There is no option for a device to process untrusted 426 onboarding information. 428 Bootstrap information is trusted whenever it is obtained via a secure 429 connection to a trusted bootstrap server, or whenever it is signed by 430 the device's owner. In all other cases, the onboarding information 431 is untrusted. 433 How devices process onboarding information is described more formally 434 in Section 5.6. 436 3. Artifacts 438 This document defines three artifacts that can be made available to 439 devices while they are bootstrapping. Each source of bootstrapping 440 information specifies a means for providing each of the artifacts 441 defined in this section (see Section 4). 443 3.1. Zero Touch Information 445 The zero touch information artifact encodes the essential 446 bootstrapping data for the device. This artifact is used to encode 447 the redirect information and onboarding information types discussed 448 in Section 2. 450 The zero touch information artifact is a PKCS#7 SignedData structure, 451 as specified by Section 9.1 of [RFC2315], encoded using ASN.1 452 distinguished encoding rules (DER), as specified in ITU-T X.690. The 453 PKCS#7 structure MUST contain JSON-encoded content conforming to the 454 YANG module specified in Section 6.3. 456 In order for the zero touch information artifact to be trusted when 457 conveyed over an untrusted transport, the PKCS#7 structure MUST also 458 contain a 'signerInfo' structure, as described in Section 9.1 of 459 [RFC2315], containing a signature generated over the content using 460 the private key associated with the owner certificate (Section 3.2). 461 In order to simplify the verification process, the PKCS#7 structure 462 MUST also contain the signing X.509 certificate. 464 3.2. Owner Certificate 466 The owner certificate artifact is a certificate that is used to 467 identify an 'owner' (e.g., an organization). The owner certificate 468 can be signed by any certificate authority (CA). The owner 469 certificate MUST either have no Key Usage specified, or the Key Usage 470 MUST set the "digitalSignature" bit. The values for the owner 471 certificate's "subject" and/or "subjectAltName" are not constrained 472 by this document. 474 The owner certificate is used by a device to verify the signature for 475 the zero touch information artifact (Section 3.1), the device SHOULD 476 also have received, as described in Section 3.4. In particular, the 477 device verifies signature using the public key in the owner 478 certificate over the content contained within the zero touch 479 information artifact. 481 The owner certificate artifact is formally an unsigned PKCS #7 482 SignedData structure as specified by Section 9.1 in [RFC2315], 483 encoded using ASN.1 distinguished encoding rules (DER), as specified 484 in ITU-T X.690. 486 The owner certificate PKCS#7 structure MUST contain the owner 487 certificate itself, as well as all intermediate certificates leading 488 up to the 'pinned-domain-cert' certificate specified in the ownership 489 voucher. The owner certificate artifact MAY optionally include the 490 trust anchor certificate. 492 Additionally, in order to support devices deployed on private 493 networks, the owner certificate PKCS#7 structure MAY also contain 494 suitably fresh CRLs [RFC5280] and/or OCSP Responses [RFC6960]. 495 Having these revocation objects stapled to the owner certificate 496 precludes the need for the device to have to download them 497 dynamically using the CRL distribution point or an OCSP responder 498 specified in the associated certificates. 500 3.3. Ownership Voucher 502 The ownership voucher artifact is used to securely identify a 503 device's owner, as it is known to the manufacturer. The ownership 504 voucher is signed by the device's manufacturer or delegate. 506 More specifically, the ownership voucher is used to verify the owner 507 certificate (Section 3.2) that the device SHOULD have also received, 508 as described in Section 3.4. In particular, the device verifies that 509 the owner certificate has a chain of trust leading to the trusted 510 certificate included in the ownership voucher, even if it is itself 511 (e.g., self-signed certificate). 513 The ownership voucher artifact, including its encoding, is formally 514 defined in [I-D.ietf-anima-voucher]. 516 3.4. Artifact Groupings 518 This section lists all the possible bootstrapping artifacts, but only 519 certain groupings of these artifacts make sense to return in the 520 various bootstrapping situations described in this document. These 521 groupings are: 523 Unsigned Information: This grouping is useful for cases when 524 transport level security can be used to convey trust (e.g., 525 HTTPS), or when the information can be processed in a 526 provisional manner (i.e. unsigned redirect information). 528 Signed Information, without revocations: The grouping is useful 529 when signed information is needed, because it's obtained from 530 an untrusted source, and it cannot be processed provisionally, 531 and yet either revocations are not needed or they can be 532 obtained dynamically. 534 Signed Information, with revocations: The grouping is useful when 535 signed information is needed, because it's obtained from an 536 untrusted source, and it cannot be processed provisionally, and 537 revocations are needed and cannot be obtained dynamically. 539 The artifacts associated with these groupings are described below: 541 Zero Touch Ownership Owner 542 Grouping Information Voucher Certificate 543 -------------------- ------------- ------------ ----------- 544 Unsigned Information Yes, no sig No No 546 Signed Information, Yes, with sig Yes, without Yes, without 547 without revocations revocations revocations 549 Signed Information, Yes, with sig Yes, with Yes, with 550 with revocations revocations revocations 552 4. Sources of Bootstrapping Data 554 This section defines some sources for zero touch bootstrapping data 555 that a device can access. The list of sources defined here is not 556 meant to be exhaustive. It is left to future documents to define 557 additional sources for obtaining zero touch bootstrapping data. 559 For each source defined in this section, details are given for how 560 each of the three artifacts listed in Section 3 is provided. 562 4.1. Removable Storage 564 A directly attached removable storage device (e.g., a USB flash 565 drive) MAY be used as a source of zero touch bootstrapping data. 567 To use a removable storage device as a source of bootstrapping data, 568 a device need only detect if the removable storage device is plugged 569 in and mount its filesystem. 571 Use of a removable storage device is compelling, as it doesn't 572 require any external infrastructure to work. It is notable that the 573 raw boot image file can be located on the removable storage device, 574 enabling a removable storage device to be a fully self-standing 575 bootstrapping solution. 577 A removable storage device is an untrusted source of bootstrapping 578 data. This means that the information stored on the removable 579 storage device either MUST be signed, or it MUST be information that 580 can be processed provisionally (e.g., unsigned redirect information). 582 From an artifact perspective, since a removable storage device 583 presents itself as a filesystem, the bootstrapping artifacts need to 584 be presented as files. The three artifacts defined in Section 3 are 585 mapped to files below. 587 Artifact to File Mapping: 589 Zero Touch Information: Mapped to a file containing the binary 590 artifact described in Section 3.1 (e.g., zerotouch- 591 information.pk7). 593 Owner Certificate: Mapped to a file containing the binary 594 artifact described in Section 3.2 (e.g., owner- 595 certificate.pk7). 597 Ownership Voucher: Mapped to a file containing the binary 598 artifact described in Section 3.3 (e.g., ownership- 599 voucher.pk7). 601 The format of the removable storage device's filesystem and the 602 naming of the files are outside the scope of this document. However, 603 in order to facilitate interoperability, it is RECOMMENDED devices 604 support open and/or standards based filesystems. It is also 605 RECOMMENDED that devices assume a file naming convention that enables 606 more than one instance of bootstrapping data to exist on a removable 607 storage device. The file naming convention SHOULD be unique to the 608 manufacturer, in order to enable bootstrapping data from multiple 609 manufacturers to exist on a removable storage device. 611 4.2. DNS Server 613 A DNS server MAY be used as a source of zero touch bootstrapping 614 data. 616 Using a DNS server may be a compelling option for deployments having 617 existing DNS infrastructure, as it enables a touchless bootstrapping 618 option that does not entail utilizing an Internet based resource 619 hosted by a 3rd-party. 621 To use a DNS server as a source of bootstrapping data, a device MAY 622 perform a multicast DNS [RFC6762] query searching for the service 623 "_zerotouch._tcp.local.". Alternatively the device MAY perform DNS- 624 SD [RFC6763] via normal DNS operation, using the domain returned to 625 it from the DHCP server; for example, searching for the service 626 "_zerotouch._tcp.example.com". 628 Unsigned DNS records (e.g., not using DNSSEC as described in 629 [RFC6698]) are an untrusted source of bootstrapping data. This means 630 that the information stored in the DNS records either MUST be signed, 631 or it MUST be information that can be processed provisionally (e.g., 632 unsigned redirect information). 634 From an artifact perspective, since a DNS server presents resource 635 records (Section 3.2.1 of [RFC1035]), the bootstrapping artifacts 636 need to be presented as resource records. The three artifacts 637 defined in Section 3 are mapped to resource records below. 639 Artifact to Resource Record Mapping: 641 Zero Touch Information: Mapped to a TXT record called "zt-info" 642 containing the base64-encoding of the binary artifact described 643 in Section 3.1. 645 Owner Certificate: Mapped to a TXT record called "zt-cert" 646 containing the base64-encoding of the binary artifact described 647 in Section 3.2. 649 Ownership Voucher: Mapped to a TXT record called "zt-voucher" 650 containing the base64-encoding of the binary artifact described 651 in Section 3.3. 653 TXT records have an upper size limit of 65535 bytes (Section 3.2.1 in 654 RFC1035), since 'RDLENGTH' is a 16-bit field. Please see 655 Section 3.1.3 in RFC4408 for how a TXT record can achieve this size. 656 Due to this size limitation, some zero touch information artifacts 657 may not fit. In particular, onboarding information could hit this 658 upper bound, depending on the size of the included configuration and 659 scripts. 661 When onboarding information (not redirect information) is provided, 662 it is notable that the URL for the boot-image the device can download 663 would have to point to another server (e.g., http://, ftp://, etc.), 664 as DNS servers do not themselves distribute files. 666 4.3. DHCP Server 668 A DHCP server MAY be used as a source of zero touch bootstrapping 669 data. 671 Using a DHCP server may be a compelling option for deployments having 672 existing DHCP infrastructure, as it enables a touchless bootstrapping 673 option that does not entail utilizing an Internet based resource 674 hosted by a 3rd-party. 676 A DHCP server is an untrusted source of bootstrapping data. Thus the 677 information stored on the DHCP server either MUST be signed, or it 678 MUST be information that can be processed provisionally (e.g., 679 unsigned redirect information). 681 However, unlike other sources of bootstrapping data described in this 682 document, the DHCP protocol (especially DHCP for IPv4) is limited in 683 the amount of data that can be conveyed, to the extent that signed 684 data cannot be communicated. This means only unsigned redirect 685 information can be conveyed. Since the redirect information is 686 unsigned, it SHOULD NOT include the optional trust anchor 687 certificate, as the device would have to discard it anyway. 689 From an artifact perspective, the three artifacts defined in 690 Section 3 are mapped to the DHCP fields specified in Section 8 as 691 follows: 693 Zero Touch Information: This artifact is not supported directly. 694 Instead, the essence of redirect information (not onboarding 695 information) is mapped to the DHCP fields described in 696 Section 8. 698 Owner Certificate: Not supported. There is not enough space in 699 the DHCP packet to hold an owner certificate artifact. 701 Ownership Voucher: Not supported. There is not enough space in 702 the DHCP packet to hold an ownership voucher artifact. 704 4.4. Bootstrap Server 706 A bootstrap server MAY be used as a source of zero touch 707 bootstrapping data. A bootstrap server is defined as a RESTCONF 708 [RFC8040] server implementing the YANG module provided in Section 7. 710 Unlike any other source of bootstrap data described in this document, 711 a bootstrap server is not only a source of data, but it can also 712 receive data from devices using the YANG-defined 'update-progress' 713 action defined in the YANG module (Section 7.4). The data sent from 714 devices both enables visibility into the bootstrapping process (e.g., 715 warnings and errors) as well as provides potentially useful 716 completion status information (e.g., the device's SSH host-keys). 718 To use a bootstrap server as a source of bootstrapping data, a device 719 MUST use the RESTCONF protocol to access the YANG container node 720 /device, passing its unique identifier in the URL as the key to the 721 'device' list. 723 Using a bootstrap server as a source of bootstrapping data is a 724 compelling option as it MAY use transport-level security, in lieu of 725 signed data, which may be easier to deploy in some situations. 726 Additionally, the bootstrap server is able to receive progress 727 updates from devices, which may be critical to some deployments 728 (e.g., the passing of the device's SSH host keys). 730 A bootstrap server may be trusted or an untrusted source of 731 bootstrapping data, depending on how the device learned about the 732 bootstrap server's trust anchor from a trusted source. When a 733 bootstrap server is trusted, the information returned from it MAY be 734 signed. However, when the server is untrusted, in order for its 735 information to be of any use to the device, the bootstrap information 736 MUST either be signed or be information that can be processed 737 provisionally (e.g., unsigned redirect information). 739 When a device is able to trust a bootstrap server, it MUST send its 740 IDevID certificate in the form of a TLS client certificate, and it 741 MUST send progress updates to the bootstrap server. When a device is 742 not able to trust a bootstrap server, it MUST NOT send its IDevID 743 certificate in the form of a TLS client certificate, and it MUST NOT 744 send any progress updates to the bootstrap server. 746 From an artifact perspective, since a bootstrap server presents data 747 as a YANG-modeled data, the bootstrapping artifacts need to be mapped 748 to nodes in the YANG module. The three artifacts defined in 749 Section 3 are mapped to bootstrap server nodes defined in Section 7.4 750 below. 752 Artifact to Bootstrap Server Node Mapping: 754 Zero Touch Information: Mapped to the leaf node /device/ 755 zerotouch-information. 757 Owner Certificate: Mapped to the leaf node /device/owner- 758 certificate. 760 Ownership Voucher: Mapped to the leaf node /device/ownership- 761 voucher. 763 While RESTCONF servers typically support a nested hierarchy of 764 resources, zero touch bootstrap servers only need to support the 765 paths /device and /device/update-progress. The device processing 766 instructions provided in Section 5.3 only uses these two URLs. 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. IDevID cert & associated intermediate certificate(s) | | 783 | | 2. list of trusted Internet based bootstrap servers | | 784 | | 3. list of trust anchor certs for bootstrap servers | | 785 | | 4. trust anchor cert for verifying ownership vouchers | | 786 | +----------------------------------------------------------+ | 787 | | 788 | +----------------------+ | 789 | | | | 790 | | | | 791 | | 5. private key | | 792 | +----------------------+ | 793 | | 794 +--------------------------------------------------------------+ 796 Each numbered item below corresponds to a numbered item in the 797 diagram above. 799 1. Devices MUST possess an initial device identifier (IDevID), as 800 defined in [Std-802.1AR-2009]. The IDevID is an X.509 801 certificate, encoding e.g., the device's serial number and 802 hardware manufacturer. The device MUST also possess any 803 intermediate certificates between the IDevID certificate and the 804 IDevID trust anchor certificate, which is provided to prospective 805 owners separately (e.g., Appendix A.1). 807 2. Devices that support loading bootstrapping data from an Internet- 808 based bootstrap server (see Section 4.4) MUST possess: 810 * A configured list of trusted bootstrap servers. Consistent 811 with redirect information (Section 2.1, each bootstrap server 812 MAY be identified by its hostname or IP address, and an 813 optional port. 815 * A configured list of trust anchor certificates that can be 816 used for X.509 certificate path validation ([RFC6125], 817 Section 6) on the bootstrap server's TLS server certificate. 819 3. Devices that support loading signed data (see Section 1.2) MUST 820 possess the manufacturer's trust anchor certificate for 821 validating ownership vouchers. 823 4. Devices MUST possess a private key that corresponds to the public 824 key encoded in the device's IDevID certificate. This private key 825 SHOULD be securely stored, ideally by a cryptographic processor 826 (e.g., a TPM). 828 5.2. Boot Sequence 830 A device claiming to support the bootstrapping strategy defined in 831 this document MUST support the boot sequence described in this 832 section. 834 Power On 835 | 836 v No 837 1. Zerotouch bootstrapping configured --------> Boot normally 838 | 839 | Yes 840 v 841 2. For each supported source of bootstrapping data, 842 try to load bootstrapping data from the source 843 | 844 | 845 v Yes 846 3. Able to bootstrap from any source? ----> Run with new configuration 847 | 848 | No 849 v 850 4. Loop and/or wait for manual provisioning. 852 Each numbered item below corresponds to a numbered item in the 853 diagram above. 855 1. When the device powers on, it first checks to see if zerotouch 856 bootstrapping is configured, as is expected to be the case for 857 the device's preconfigured state. If zerotouch bootstrapping is 858 not configured, then the device boots normally. 860 2. The device iterates over its list of sources for bootstrapping 861 data (Section 4). Details for how to processes a source of 862 bootstrapping data are provided in Section 5.3. 864 3. If the device is able to bootstrap itself from any of the sources 865 of bootstrapping data, it runs with the new bootstrapped 866 configuration. 868 4. Otherwise the device MAY loop back through the list of 869 bootstrapping sources again and/or wait for manual provisioning. 871 5.3. Processing a Source of Bootstrapping Data 873 This section describes a recursive algorithm that devices can use to, 874 ultimately, obtain onboarding information. The algorithm is 875 recursive because sources of bootstrapping data MAY return redirect 876 information, which causes the algorithm to run again, for the newly 877 discovered sources of bootstrapping information. An ANBF-like 878 expression that captures all possible sequences of bootstrapping 879 information is "(redirect information)* onboarding information". 880 That is, zero or more redirect information responses, followed by one 881 bootstrap information response. 883 An important aspect of the algorithm is knowing when data needs to be 884 signed or not. The following figure provides a summary of options: 886 Untrusted Source Trusted Source 887 Kind of Bootstrapping Data Can Provide? Can Provide? 889 Unsigned Redirect Info : Yes+ Yes 890 Signed Redirect Info : Yes Yes* 891 Unsigned Onboarding Info : No Yes 892 Signed Onboarding Info : Yes Yes* 894 The '+' above denotes that the source redirected to MUST 895 return signed data, or more unsigned redirect information. 897 The '*' above denotes that, while possible, it is generally 898 unnecessary for a trusted source to return signed data. In 899 fact, it's only needed when the '+' case occurs. 901 The recursive algorithm uses a conceptual global-scoped variable 902 called "trust-state". The trust-state variable is initialized to 903 FALSE. The ultimate goal of this algorithm is for the device to 904 process onboarding information (Section 2.2) while the trust-state 905 variable is TRUE. 907 If the data source is a bootstrap server, and the device is able to 908 authenticate the bootstrap server using X.509 certificate path 909 validation ([RFC6125], Section 6) to one of the device's 910 preconfigured trust anchors, or to a trust anchor that it learned 911 from a previous step, then the device MUST set trust-state to TRUE. 913 If trust-state is TRUE, when connecting to the bootstrap server, the 914 device MUST use its IDevID certificate for client certificate based 915 authentication and MUST post progress updates using the bootstrap 916 server's "update-progress" action. Otherwise, if trust-state is 917 FALSE, when connecting to the bootstrap server, the device MUST NOT 918 use its IDevID certificate for a client certificate based 919 authentication and MUST NOT post progress updates using the bootstrap 920 server's "update-progress" action. 922 When accessing a bootstrap server, the device SHOULD only access its 923 top-level resource, to obtain all the data staged for it in a single 924 GET request. 926 For any source of bootstrapping data (e.g., Section 4), if the data 927 is signed and the device is able to validate the signed data using 928 the algorithm described in Section 5.4, then the device MUST set 929 trust-state to TRUE, else the device MUST set trust-state to FALSE. 930 Note, this is worded to cover the special case when signed data is 931 returned even from a trusted bootstrap server. 933 If the data is onboarding information (not redirect information), and 934 trust-state is FALSE, the device MUST exit the recursive algorithm 935 (as this is not allowed, per the figure above), returning to the 936 state machine described in Section 5.2. Otherwise, the device MUST 937 attempt to process the onboarding information as described in 938 Section 5.6. In either case, success or failure, the device MUST 939 exit the recursive algorithm, returning to the state machine 940 described in Section 5.2, the only difference being in how it 941 responds to the "Able to bootstrap from any source?" conditional 942 described in the figure in the section. 944 If the data is redirect information, the device MUST process the 945 redirect information as described in Section 5.5. This is the 946 recursion step, it will cause to device to reenter this algorithm, 947 but this time the data source will most definitely be a bootstrap 948 server, as that is all redirect information is able to redirect a 949 device to. 951 5.4. Validating Signed Data 953 Whenever a device is presented signed data, it MUST validate the 954 signed data as described in this section. This includes the case 955 where the signed data is provided by a trusted source. 957 Whenever there is signed data, the device MUST also be provided an 958 ownership voucher and an owner certificate. How all the needed 959 artifacts are provided for each source of bootstrapping data is 960 defined in Section 4. 962 The device MUST first authenticate the ownership voucher by 963 validating the signature on it to one of its preconfigured trust 964 anchors (see Section 5.1), which may entail using additional 965 intermediate certificates attached to the ownership voucher. If the 966 device has an accurate clock, it MUST ensure that the ownership 967 voucher was created in the past (i.e., 'created-on' < now). If the 968 'expires-on' leaf is present, the device MUST verify that the 969 ownership voucher has not yet expired (i.e., now < 'expires-on'), 970 which requires an accurate clock. The device MUST verify that the 971 ownership voucher's 'assertion' value is acceptable (e.g., some 972 devices may only accept the assertion value 'verified'). The device 973 MUST verify that the ownership voucher specifies the device's serial 974 number in the 'serial-number' leaf. If the 'idevid-issuer' leaf is 975 present, the device MUST verify that the value is set correctly. If 976 the authentication of the ownership voucher is successful, the device 977 extracts the 'pinned-domain-certificate' node, an X.509 certificate, 978 that is needed to verify the owner certificate in the next step. 980 The device MUST next authenticate the owner certificate by performing 981 X.509 certificate path verification to the trusted certificate 982 extracted from the voucher's 'pinned-domain-cert' node. This 983 verification may entail using additional intermediate certificates 984 attached to the owner certificate artifact. If the ownership 985 voucher's 'domain-cert-revocation-checks' node's value is set to 986 "true", the device MUST verify the revocation status of the 987 certificate chain used to sign the owner certificate and, if the 988 revocation status is not attainable or if it is determined that a 989 certificate has been revoked, the device MUST not validate the owner 990 certificate. 992 Finally the device MUST verify the signature over information 993 artifact was generated by the private key matching the public key 994 from the owner certificate. 996 If any of these steps fail, then the device MUST mark the data as 997 invalid and not perform any subsequent processing step. 999 5.5. Processing Redirect Information 1001 In order to process redirect information (Section 2.1), the device 1002 MUST follow the steps presented in this section. 1004 Processing redirect information is straightforward. The device 1005 sequentially steps through the list of provided bootstrap servers 1006 until it can find one it can bootstrap from. 1008 If a hostname is provided, and the hostname's DNS resolution is to 1009 more than one IP address, the device MUST attempt to connect to all 1010 of the DNS resolved addresses at least once, before moving on to the 1011 next bootstrap server. If the device is able to obtain bootstrapping 1012 data from any of the DNS resolved addresses, it MUST immediately 1013 process that data, without attempting to connect to any of the other 1014 DNS resolved addresses. 1016 If the redirect information is trusted (e.g., trust-state is TRUE), 1017 and the bootstrap server entry contains a trust anchor certificate, 1018 then the device MUST authenticate the bootstrap server using X.509 1019 certificate path validation ([RFC6125], Section 6) to the specified 1020 trust anchor. If the device is unable to authenticate the bootstrap 1021 server to the specified trust anchor, the device MUST NOT attempt a 1022 provisional connection to the bootstrap server (i.e., by blindly 1023 accepting its server certificate). 1025 If the redirect information is untrusted (e.g., trust-state is 1026 FALSE), the device MUST discard any trust anchors provided by the 1027 redirect information and establish a provisional connection to the 1028 bootstrap server (i.e., by blindly accepting its TLS server 1029 certificate). 1031 5.6. Processing Onboarding Information 1033 In order to process onboarding information (Section 2.2), the device 1034 MUST follow the steps presented in this section. 1036 When processing onboarding information, the device MUST first process 1037 the boot image information, then execute the pre-configuration script 1038 (if any), then commit the initial configuration, and then execute the 1039 post-configuration script (if any), in that order. If the device 1040 encounters an error at any step, it MUST NOT proceed to the next 1041 step. 1043 First the device MUST determine if the image it is running satisfies 1044 the specified boot image criteria (e.g., name and/or fingerprint 1045 match). If it does not, the device MUST download (using the supplied 1046 URI), verify, and install the specified boot image, and then reboot. 1048 To verify the boot image, the device MUST check that the boot image 1049 file matches the fingerprint (e.g., sha256) supplied by the 1050 bootstrapping information. Upon rebooting, the device MUST still be 1051 in its initial state, causing the bootstrapping process to run again, 1052 which will eventually come to this very point, but this time the 1053 device's running image will satisfy the specified criteria, and thus 1054 the device will move to processing the next step. 1056 Next, for devices that support executing scripts, if a pre- 1057 configuration script has been specified, the device MUST execute the 1058 script and check its exit status code to determine if had any 1059 warnings or errors. In the case of errors, the device MUST reset 1060 itself in such a way that forces a reinstallation of the boot image, 1061 thereby wiping out any bad state the script may have left behind. 1063 Next the device commits the provided initial configuration. Assuming 1064 no errors, the device moves to processing the next step. 1066 Again, for devices that support executing scripts, if a post- 1067 configuration script has been specified, the device MUST execute the 1068 script and check its exit status code to determine if it had any 1069 warnings or errors. In the case of errors, the device MUST reset 1070 itself in such a way that forces a reinstallation of the boot image, 1071 thereby wiping out any bad state the script may have left behind. 1073 At this point, the device has completely processed the bootstrapping 1074 data and is ready to be managed. If the device obtained the 1075 bootstrap information from a trusted bootstrap server, the device 1076 MUST post the 'bootstrap-complete' progress update now, using the 1077 bootstrap server's 'update-progress' action. 1079 At this point the device is running its initial configuration. 1080 Notably, if NETCONF Call Home or RESTCONF Call Home [RFC8071] is 1081 configured, the device initiates trying to establish a call home 1082 connection at this time. 1084 6. The Zero Touch Information Artifact 1086 This section defines a YANG 1.1 [RFC7950] module that is used to 1087 define the data model for the zero touch information artifact 1088 described in Section 3.1. Examples illustrating this artifact in use 1089 are provided in Section 6.2. 1091 6.1. Data Model Overview 1093 The following tree diagram provides an overview of the data model for 1094 the zero touch information artifact. The syntax used for this tree 1095 diagram is described in Section 1.4. 1097 module: ietf-zerotouch-information 1098 yang-data: 1099 zerotouch-information 1100 +---- (information-type) 1101 +--:(redirect-information) 1102 | +---- redirect-information 1103 | +---- bootstrap-server* [address] 1104 | +---- address inet:host 1105 | +---- port? inet:port-number 1106 | +---- trust-anchor? binary 1107 +--:(onboarding-information) 1108 +---- onboarding-information 1109 +---- boot-image 1110 | +---- name string 1111 | +---- (hash-algorithm) 1112 | | +--:(sha256) 1113 | | +---- sha256? string 1114 | +---- uri* inet:uri 1115 +---- configuration-handling? enumeration 1116 +---- pre-configuration-script? script 1117 +---- configuration? 1118 +---- post-configuration-script? script 1120 6.2. Example Usage 1122 This section presents examples for how the zero touch information 1123 artifact (Section 3.1) can be encoded into a document that can be 1124 distributed outside the bootstrap server's RESTCONF API. 1126 The following example illustrates how redirect information can be 1127 encoded into an artifact. 1129 1131 1132
phs1.example.com
1133 8443 1134 base64encodedvalue== 1135 1136 1137
phs2.example.com
1138 8443 1139 base64encodedvalue== 1140 1141 1142
phs3.example.com
1143 8443 1144 base64encodedvalue== 1145 1146 1148 The following example illustrates how onboarding information can be 1149 encoded into an artifact. This example uses data models from 1150 [RFC7317] and [I-D.ietf-netconf-netconf-client-server]. 1152 1154 1155 boot-image-v3.2R1.6.img 1156 base64encodedvalue== 1157 file:///some/path/to/raw/file 1158 1159 merge 1160 1161 1162 1163 1164 1165 admin 1166 1167 admin's rsa ssh host-key 1168 ssh-rsa 1169 base64encodedvalue== 1170 1171 1172 1173 1174 1175 1177 1178 1179 config-mgr 1180 1181 1182 1183 east-data-center 1184
east.config-mgr.example.com
1185 1186 1187 west-data-center 1188
west.config-mgr.example.com
1189 1190 1191 1192 1193 certificate 1194 builtin-idevid-cert 1195 1196 1197 1198 1199 deployment-specific-ca-certs 1200 1201 1202 explicitly-trusted-client-certs 1203 1204 1205 1206 1207 1208 300 1209 60 1210 1211 1212 1213 last-connected 1214 3 1215 1216 1217 1218 1219 1220 1222 6.3. YANG Module 1224 The zero touch information artifact is normatively defined by the 1225 YANG module defined in this section. 1227 Note: the module defined herein uses data types defined in [RFC5280], 1228 [RFC6234], and [RFC6991]. 1230 file "ietf-zerotouch-information@2017-09-11.yang" 1231 module ietf-zerotouch-information { 1232 yang-version "1.1"; 1234 namespace "urn:ietf:params:xml:ns:yang:ietf-zerotouch-information"; 1235 prefix "zti"; 1237 import ietf-inet-types { 1238 prefix inet; 1239 reference "RFC 6991: Common YANG Data Types"; 1240 } 1242 import ietf-restconf { 1243 prefix rc; 1244 description 1245 "This import statement is only present to access 1246 the yang-data extension defined in RFC 8040."; 1247 reference "RFC 8040: RESTCONF Protocol"; 1248 } 1250 organization 1251 "IETF NETCONF (Network Configuration) Working Group"; 1253 contact 1254 "WG Web: http://tools.ietf.org/wg/netconf 1255 WG List: 1256 Author: Kent Watsen "; 1258 description 1259 "This module defines the data model for the Zero Touch Information 1260 artifact defined by RFC XXXX: Zero Touch Provisioning for NETCONF 1261 or RESTCONF based Management. 1263 Copyright (c) 2017 IETF Trust and the persons identified as 1264 authors of the code. All rights reserved. 1266 Redistribution and use in source and binary forms, with or without 1267 modification, is permitted pursuant to, and subject to the license 1268 terms contained in, the Simplified BSD License set forth in Section 1269 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents 1270 (http://trustee.ietf.org/license-info). 1272 This version of this YANG module is part of RFC XXXX; see the RFC 1273 itself for full legal notices."; 1275 revision "2017-09-11" { 1276 description 1277 "Initial version"; 1278 reference 1279 "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF based 1280 Management"; 1281 } 1283 rc:yang-data zerotouch-information { 1285 choice information-type { 1286 mandatory true; 1287 description 1288 "This choice statement ensures the response only contains 1289 redirect-information or onboarding-information. Note that 1290 this is the only mandatory true node, as the other nodes 1291 are not needed when the device trusts the bootstrap server, 1292 in which case the data does not need to be signed."; 1294 container redirect-information { 1295 description 1296 "Redirect information is described in Section 2.1 in 1297 RFC XXXX. Its purpose is to redirect a device to 1298 another bootstrap server."; 1299 reference 1300 "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF 1301 based Management"; 1303 list bootstrap-server { 1304 key address; 1305 description 1306 "A bootstrap server entry."; 1308 leaf address { 1309 type inet:host; 1310 mandatory true; 1311 description 1312 "The IP address or hostname of the bootstrap server the 1313 device should redirect to."; 1314 } 1315 leaf port { 1316 type inet:port-number; 1317 default 443; 1318 description 1319 "The port number the bootstrap server listens on. If no 1320 port is specified, the IANA-assigned port for 'https' 1321 (443) is used."; 1322 } 1323 leaf trust-anchor { 1324 type binary; 1325 description 1326 "An X.509 v3 certificate structure as specified by RFC 1327 5280, Section 4, encoded using ASN.1 distinguished 1328 encoding rules (DER), as specified in ITU-T X.690. A 1329 certificate that device can use as the trust anchor 1330 to authenticate the bootstrap server the device is 1331 being redirected to."; 1332 reference 1333 "RFC 5280: 1334 Internet X.509 Public Key Infrastructure Certificate 1335 and Certificate Revocation List (CRL) Profile. 1336 ITU-T X.690: 1337 Information technology - ASN.1 encoding rules: 1338 Specification of Basic Encoding Rules (BER), 1339 Canonical Encoding Rules (CER) and Distinguished 1340 Encoding Rules (DER)."; 1341 } 1342 } 1343 } 1345 container onboarding-information { 1346 description 1347 "Bootstrap information is described in Section 2.2 in 1348 RFC XXXX. Its purpose is to provide the device 1349 everything it needs to bootstrap itself."; 1350 reference 1351 "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF 1352 based Management"; 1354 container boot-image { 1355 description 1356 "Specifies criteria for the boot image the device MUST 1357 be running."; 1359 leaf name { 1360 type string; 1361 mandatory true; 1362 description 1363 "The name of a software image that the device MUST 1364 be running in order to process the remaining nodes."; 1365 } 1366 choice hash-algorithm { 1367 mandatory true; 1368 description 1369 "Identifies the hash algorithm used."; 1370 leaf sha256 { 1371 type string; 1372 description 1373 "The hex-encoded SHA-256 hash over the boot 1374 image file. This is used by the device to 1375 verify a downloaded boot image file."; 1376 reference 1377 "RFC 6234: US Secure Hash Algorithms."; 1378 } 1379 } 1380 leaf-list uri { 1381 type inet:uri; 1382 min-elements 1; 1383 description 1384 "An ordered list of URIs to where the boot-image file MAY 1385 be obtained. Deployments MUST know in which URI schemes 1386 (http, ftp, etc.) a device supports. If a secure scheme 1387 (e.g., https) is provided, a device MAY establish a 1388 provisional connection to the server, by blindly 1389 accepting the server's credentials (e.g., its TLS 1390 certificate)"; 1391 } 1392 } 1394 leaf configuration-handling { 1395 type enumeration { 1396 enum merge { 1397 description 1398 "Merge configuration into the running datastore."; 1399 } 1400 enum replace { 1401 description 1402 "Replace the existing running datastore with the 1403 passed configuration."; 1404 } 1405 } 1406 description 1407 "This enumeration indicates how the server should process 1408 the provided configuration. When not specified, the device 1409 MAY determine how to process the configuration using other 1410 means (e.g., vendor-specific metadata)."; 1411 } 1413 leaf pre-configuration-script { 1414 type script; 1415 description 1416 "A script that, when present, is executed before the 1417 configuration has been processed."; 1418 } 1420 anydata configuration { 1421 must "../configuration-handling"; 1422 description 1423 "Any configuration data model known to the device. It may 1424 contain manufacturer-specific and/or standards-based data 1425 models."; 1426 } 1428 leaf post-configuration-script { 1429 type script; 1430 description 1431 "A script that, when present, is executed after the 1432 configuration has been processed."; 1433 } 1434 } 1435 } 1436 } 1438 typedef script { 1439 type binary; 1440 description 1441 "A device specific script that enables the execution of commands 1442 to perform actions not possible thru configuration alone. 1444 No attempt is made to standardize the contents, running context, 1445 or programming language of the script. The contents of the 1446 script are considered specific to the vendor, product line, 1447 and/or model of the device. 1449 If a script is erroneously provided to a device that does not 1450 support the execution of scripts, the device SHOULD send a 1451 'script-warning' notification message, but otherwise continue 1452 processing the bootstrapping data as if the script had not 1453 been present. 1455 The script returns exit status code '0' on success and non-zero 1456 on error, with accompanying stderr/stdout for logging purposes. 1457 In the case of an error, the exit status code will specify what 1458 the device should do. 1460 If the exit status code is greater than zero, then the device 1461 should assume that the script had a soft error, which the 1462 script believes does not affect manageability. If the device 1463 obtained the bootstrap information from a bootstrap server, 1464 it SHOULD send a 'script-warning' notification message. 1466 If the exit status code is less than zero, the device should 1467 assume the script had a hard error, which the script believes 1468 will affect manageability. In this case, the device SHOULD 1469 send a 'script-error' notification message followed by a 1470 reset that will force a new boot-image install (wiping out 1471 anything the script may have done) and restart the entire 1472 bootstrapping process again."; 1473 } 1475 } 1476 1478 7. The Zero Touch Bootstrap Server API 1480 This section defines the API for bootstrap servers. The API is 1481 defined as the API produced by a RESTCONF [RFC8040] server that 1482 supports the YANG 1.1 [RFC7950] module defined in this section. The 1483 bootstrap server MAY also support the query parameters defined in 1484 this section. 1486 7.1. API Overview 1488 The following tree diagram provides an overview for the bootstrap 1489 server RESTCONF API. The syntax used for this tree diagram is 1490 described in Section 1.4. 1492 module: ietf-zerotouch-bootstrap-server 1493 +--ro device* [unique-id] 1494 +--ro unique-id string 1495 +--ro zerotouch-information pkcs7 1496 +--ro owner-certificate? pkcs7 1497 +--ro ownership-voucher? pkcs7 1498 +---x update-progress 1499 +---w input 1500 +---w update-type enumeration 1501 +---w message? string 1502 +---w ssh-host-keys 1503 | +---w ssh-host-key* 1504 | +---w format enumeration 1505 | +---w key-data string 1506 +---w trust-anchors 1507 +---w trust-anchor* 1508 +---w protocol* enumeration 1509 +---w certificate pkcs7 1511 In the above diagram, notice that all of the protocol accessible 1512 nodes are read-only, to assert that devices can only pull data from 1513 the bootstrap server. 1515 Also notice that the module defines an action statement, which 1516 devices use to provide progress updates to the bootstrap server. 1518 7.2. Query Parameters 1520 Bootstrap servers may optionally support the query parameters defined 1521 in this section. 1523 o The "os-name" Query Parameter 1525 The "os-name" query parameter indicates the name of the 1526 operating system the device is running. This parameter is only 1527 needed if it is possible for the device, as identified by its 1528 to run more than one type of operating system. 1529 This query parameter MUST be supported by servers needing to 1530 support such devices. 1532 HTTP Methods: GET, HEAD 1534 Capability URI: urn:ietf:params:restconf:capability:os-name:1.0 1536 o The "os-version" Query Parameter 1538 The "os-version" query parameter indicates the version of the 1539 operating system the device is running. This parameter enables 1540 the server to dynamically generate an optimal response for the 1541 device negating, for instance, the need for a potentially 1542 expensive boot-image update. This query parameter MUST be 1543 supported by servers wanting to support such use-cases. 1545 HTTP Methods: GET, HEAD 1547 Capability URI: urn:ietf:params:restconf:capability:os- 1548 version:1.0 1550 o The "circuit-id" Query Parameter 1552 The "circuit-id" query parameter, along with the "remote-id" 1553 query parameter, enables a device to propagate information 1554 collected (e.g., via DHCP Option 82) to the bootstrap server. 1555 This information enables the bootstrap server to return a 1556 customized response independent of the device's unique 1557 identifier. 1559 HTTP Methods: GET, HEAD 1561 Capability URI: urn:ietf:params:restconf:capability:circuit- 1562 id:1.0 1564 o The "remote-id" Query Parameter 1566 The "remote-id" query parameter, along with the "circuit-id" 1567 query parameter, enables a device to propogate information 1568 collected (e.g., via DHCP Option 82) to the bootstrap server. 1569 This information enables the bootstrap server to return a 1570 customized response independent of the device's unique 1571 identifier. 1573 HTTP Methods: GET, HEAD 1575 Capability URI: urn:ietf:params:restconf:capability:remote- 1576 id:1.0 1578 o The "nonce" Query Parameter 1580 The "nonce" query parameter enables a device without an 1581 accurate clock to obtain a one-time use voucher, as opposed to 1582 a never-expiring voucher that it would otherwise receive. This 1583 query parameter is only useful for cases where the device is 1584 connected to an untrusted bootstrap server, when signed data 1585 must be returned. The bootstrap server uses backend APIs not 1586 described in this document to dynamically obtain the one-time 1587 use voucher from the device's manufacturer. 1589 HTTP Methods: GET, HEAD 1591 Capability URI: urn:ietf:params:restconf:capability:nonce:1.0 1593 7.3. Example Usage 1595 This section presents some examples illustrating the bootstrap 1596 server's API. Two examples are provided, one illustrating a device 1597 fetching bootstrapping data from the server, and the other 1598 illustrating a data posting a progress updates to the server. 1600 The following example illustrates a device using the API to fetch its 1601 bootstrapping data from the bootstrap server. In this example, the 1602 device receives a signed response; an unsigned response would look 1603 similar except the last two fields (owner-certificate and ownership- 1604 voucher) would be absent in the response. 1606 REQUEST 1607 ------- 1608 ['\' line wrapping added for formatting only] 1610 GET https://example.com/restconf/data/ietf-zerotouch-bootstrap-server:\ 1611 device=123456 HTTP/1.1 1612 HOST: example.com 1613 Accept: application/yang.data+xml 1615 RESPONSE 1616 -------- 1618 HTTP/1.1 200 OK 1619 Date: Sat, 31 Oct 2015 17:02:40 GMT 1620 Server: example-server 1621 Content-Type: application/yang.data+xml 1623 1625 123456789 1626 base64encodedvalue== 1627 base64encodedvalue== 1628 base64encodedvalue== 1629 1631 The following example illustrates a device using the API to post a 1632 progress update to a bootstrap server. Illustrated below is the 1633 'bootstrap-complete' message, but the device may send other progress 1634 updates to the server while bootstrapping (e.g., to provide status 1635 updates). In this message, the device is sending both its SSH host 1636 keys and TLS server certificate, which the bootstrap server may, for 1637 example, pass to an NMS, as discussed in Appendix A.3. 1639 Note that devices that are able to present an IDevID certificate 1640 [Std-802.1AR-2009] when establishing SSH or TLS connections do not 1641 need to include its DevID certificate in the bootstrap-complete 1642 message. It is unnecessary to send the DevID certificate in this 1643 case because the IDevID certificate does not need to be pinned by an 1644 NMS in order to be trusted. 1646 Note that the bootstrap server MUST NOT process a progress update 1647 from a device without first authenticating the device. This is in 1648 contrast to when a device is fetching data from the server, a read- 1649 only operation, in which case device authentication is not strictly 1650 required (e.g., when sending signed information). 1652 REQUEST 1653 ------- 1654 ['\' line wrapping added for formatting only] 1656 POST https://example.com/restconf/data/ietf-zerotouch:\ 1657 device=123456/update-progress HTTP/1.1 1658 HOST: example.com 1659 Content-Type: application/yang.data+xml 1661 1662 1663 1665 123456789 1666 1667 bootstrap-complete 1668 example message 1669 1670 1671 ssh-rsa 1672 base64encodedvalue== 1673 1674 1675 ssh-dss 1676 base64encodedvalue== 1677 1678 1679 1680 1681 netconf-ssh 1682 netconf-tls 1683 restconf-tls 1684 netconf-ch-ssh 1685 netconf-ch-tls 1686 restconf-ch-tls 1687 base64encodedvalue== 1688 1689 1690 1691 1692 1693 1695 RESPONSE 1696 -------- 1698 HTTP/1.1 204 No Content 1699 Date: Sat, 31 Oct 2015 17:02:40 GMT 1700 Server: example-server 1702 7.4. YANG Module 1704 The bootstrap server's device-facing API is normatively defined by 1705 the YANG module defined in this section. 1707 Note: the module defined herein uses data types defined in [RFC2315], 1708 [RFC5280], and [I-D.ietf-anima-voucher]. 1710 file "ietf-zerotouch-bootstrap-server@2017-09-11.yang" 1711 module ietf-zerotouch-bootstrap-server { 1712 yang-version "1.1"; 1714 namespace 1715 "urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server"; 1716 prefix "ztbs"; 1718 organization 1719 "IETF NETCONF (Network Configuration) Working Group"; 1721 contact 1722 "WG Web: 1723 WG List: 1724 Author: Kent Watsen 1725 "; 1727 description 1728 "This module defines an interface for bootstrap servers, as defined 1729 by RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF based 1730 Management. 1732 Copyright (c) 2017 IETF Trust and the persons identified as 1733 authors of the code. All rights reserved. 1735 Redistribution and use in source and binary forms, with or without 1736 modification, is permitted pursuant to, and subject to the license 1737 terms contained in, the Simplified BSD License set forth in Section 1738 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents 1739 (http://trustee.ietf.org/license-info). 1741 This version of this YANG module is part of RFC XXXX; see the RFC 1742 itself for full legal notices."; 1744 revision "2017-09-11" { 1745 description 1746 "Initial version"; 1747 reference 1748 "RFC XXXX: Zero Touch Provisioning for NETCONF or RESTCONF based 1749 Management"; 1750 } 1752 // typedefs 1754 typedef pkcs7 { 1755 type binary; 1756 description 1757 "A PKCS #7 SignedData structure, as specified by Section 9.1 1758 in RFC 2315, encoded using ASN.1 distinguished encoding rules 1759 (DER), as specified in ITU-T X.690."; 1760 reference 1761 "RFC 2315: 1762 PKCS #7: Cryptographic Message Syntax Version 1.5. 1763 ITU-T X.690: 1764 Information technology - ASN.1 encoding rules: 1765 Specification of Basic Encoding Rules (BER), 1766 Canonical Encoding Rules (CER) and Distinguished 1767 Encoding Rules (DER)."; 1768 } 1770 // protocol accessible nodes 1772 list device { 1773 key unique-id; 1774 config false; 1775 description 1776 "A device record containing bootstrapping data for the device 1777 with the specified identifier. This top-level node provides 1778 a device with all the data it needs in a single request."; 1779 reference 1780 "RFC XXXX: Zero Touch Provisioning for NETCONF or 1781 RESTCONF based Management"; 1783 leaf unique-id { 1784 type string; 1785 description 1786 "A unique identifier for the device (e.g., serial number). 1787 Each device accesses its bootstrapping record by its unique 1788 identifier."; 1789 } 1791 leaf zerotouch-information { 1792 type pkcs7; 1793 mandatory true; 1794 description 1795 "A 'zerotouch-information' artifact, as described in Section 1796 4.1 of RFC XXXX. When conveyed over an untrusted transport, in 1797 order to be processed by a device, this PKCS#7 SignedData 1798 structure MUST contain a 'signerInfo' structure, described 1799 in Section 9.1 of RFC 2315, containing a signature generated 1800 using the owner's private key."; 1801 reference 1802 "RFC XXXX: Zero Touch Provisioning for NETCONF or 1803 RESTCONF based Management. 1804 RFC 2315: 1805 PKCS #7: Cryptographic Message Syntax Version 1.5"; 1806 } 1808 leaf owner-certificate { 1809 type pkcs7; 1810 description 1811 "An unsigned PKCS #7 SignedData structure, as specified by 1812 Section 9.1 in RFC 2315, encoded using ASN.1 distinguished 1813 encoding rules (DER), as specified in ITU-T X.690. 1815 This structure MUST contain the owner certificate and all 1816 intermediate certificates leading up to at least the trust 1817 anchor certificate specified in the ownership voucher. 1818 Additionally, if needed by the device, this structure MAY 1819 also contain suitably fresh CRL and or OCSP Responses. 1821 X.509 certificates and CRLs are described in RFC 5280. 1822 OCSP Responses are described in RFC 6960."; 1823 reference 1824 "RFC 2315: 1825 PKCS #7: Cryptographic Message Syntax Version 1.5. 1826 RFC 5280: 1827 Internet X.509 Public Key Infrastructure Certificate 1828 and Certificate Revocation List (CRL) Profile. 1829 RFC 6960: 1830 X.509 Internet Public Key Infrastructure Online 1831 Certificate Status Protocol - OCSP. 1832 ITU-T X.690: 1833 Information technology - ASN.1 encoding rules: 1834 Specification of Basic Encoding Rules (BER), 1835 Canonical Encoding Rules (CER) and Distinguished 1836 Encoding Rules (DER)."; 1837 } 1839 leaf ownership-voucher { 1840 type pkcs7; 1841 must "../owner-certificate" { 1842 description 1843 "An owner certificate must be present whenever an ownership 1844 voucher is presented."; 1845 } 1846 description 1847 "A 'voucher' artifact, as described in Section 5 of 1848 I-D.ietf-anima-voucher. The voucher informs the device 1849 who it's 'owner' is. The voucher encodes the device's 1850 serial number, so that the device can be ensured that 1851 the voucher applies to it. The voucher is signed by 1852 the device's manufacturer or delegate."; 1853 reference 1854 "I-D.etf-anima-voucher: 1855 Voucher and Voucher Revocation Profiles for Bootstrapping 1856 Protocols"; 1857 } 1859 action update-progress { 1860 input { 1861 leaf update-type { 1862 type enumeration { 1863 enum bootstrap-initiated { 1864 description 1865 "Indicates that the device has just accessed the 1866 bootstrap server. The 'message' field below MAY 1867 contain any additional information that the 1868 manufacturer thinks might be useful."; 1869 } 1870 enum parsing-warning { 1871 description 1872 "Indicates that the device had a non-fatal error when 1873 parsing the response from the bootstrap server. The 1874 'message' field below SHOULD indicate the specific 1875 warning that occurred."; 1876 } 1877 enum parsing-error { 1878 description 1879 "Indicates that the device encountered a fatal error 1880 when parsing the response from the bootstrap server. 1881 For instance, this could be due to malformed encoding, 1882 the device expecting signed data when only unsigned 1883 data is provided, because the ownership voucher didn't 1884 include the device's unique identifier, or because the 1885 signature didn't match. The 'message' field below 1886 SHOULD indicate the specific error. This update type 1887 also indicates that the device has abandoned trying to 1888 bootstrap off this bootstrap server."; 1889 } 1890 enum boot-image-warning { 1891 description 1892 "Indicates that the device encountered a non-fatal 1893 error condition when trying to install a boot-image. 1894 A possible reason might include a need to reformat a 1895 partition causing loss of data. The 'message' field 1896 below SHOULD indicate any warning messages that were 1897 generated."; 1898 } 1899 enum boot-image-error { 1900 description 1901 "Indicates that the device encountered an error when 1902 trying to install a boot-image, which could be for 1903 reasons such as a file server being unreachable, 1904 file not found, signature mismatch, etc. The 1905 'message' field SHOULD indicate the specific error 1906 that occurred. This update type also indicates 1907 that the device has abandoned trying to bootstrap 1908 off this bootstrap server."; 1909 } 1910 enum pre-script-warning { 1911 description 1912 "Indicates that the device obtained a greater than 1913 zero exit status code from the script when it was 1914 executed. The 'message' field below SHOULD indicate 1915 both the resulting exit status code, as well as 1916 capture any stdout/stderr messages the script may 1917 have produced."; 1918 } 1919 enum pre-script-error { 1920 description 1921 "Indicates that the device obtained a less than zero 1922 exit status code from the script when it was executed. 1923 The 'message' field below SHOULD indicate both the 1924 resulting exit status code, as well as capture any 1925 stdout/stderr messages the script may have produced. 1926 This update type also indicates that the device has 1927 abandoned trying to bootstrap off this bootstrap 1928 server."; 1929 } 1930 enum config-warning { 1931 description 1932 "Indicates that the device obtained warning messages 1933 when it committed the initial configuration. The 1934 'message' field below SHOULD indicate any warning 1935 messages that were generated."; 1936 } 1937 enum config-error { 1938 description 1939 "Indicates that the device obtained error messages 1940 when it committed the initial configuration. The 1941 'message' field below SHOULD indicate the error 1942 messages that were generated. This update type 1943 also indicates that the device has abandoned trying 1944 to bootstrap off this bootstrap server."; 1945 } 1946 enum post-script-warning { 1947 description 1948 "Indicates that the device obtained a greater than 1949 zero exit status code from the script when it was 1950 executed. The 'message' field below SHOULD indicate 1951 both the resulting exit status code, as well as 1952 capture any stdout/stderr messages the script may 1953 have produced."; 1954 } 1955 enum post-script-error { 1956 description 1957 "Indicates that the device obtained a less than zero 1958 exit status code from the script when it was executed. 1959 The 'message' field below SHOULD indicate both the 1960 resulting exit status code, as well as capture any 1961 stdout/stderr messages the script may have produced. 1962 This update type also indicates that the device has 1963 abandoned trying to bootstrap off this bootstrap 1964 server."; 1965 } 1966 enum bootstrap-complete { 1967 description 1968 "Indicates that the device successfully processed the 1969 all the bootstrapping data and that it is ready to be 1970 managed. The 'message' field below MAY contain any 1971 additional information that the manufacturer thinks 1972 might be useful. After sending this update type, 1973 the device is not expected to access the bootstrap 1974 server again."; 1975 } 1976 enum informational { 1977 description 1978 "Indicates any additional information not captured by 1979 any of the other update type. For instance, a 1980 message indicating that the device is about to reboot 1981 after having installed a boot-image could be provided. 1982 The 'message' field below SHOULD contain information 1983 that the manufacturer thinks might be useful."; 1984 } 1985 } 1986 mandatory true; 1987 description 1988 "The type of update provided."; 1989 } 1990 leaf message { 1991 type string; 1992 description 1993 "An optional human-readable value."; 1994 } 1995 container ssh-host-keys { 1996 when "../update-type = 'bootstrap-complete'" { 1997 description 1998 "SSH host keys are only sent when the update type 1999 is 'bootstrap-complete'."; 2000 } 2001 description 2002 "A list of SSH host keys an NMS may use to authenticate 2003 a NETCONF connection to the device with."; 2004 list ssh-host-key { 2005 description 2006 "An SSH host-key"; 2007 leaf format { 2008 type enumeration { 2009 enum ssh-dss { description "ssh-dss"; } 2010 enum ssh-rsa { description "ssh-rsa"; } 2011 } 2012 mandatory true; 2013 description 2014 "The format of the SSH host key."; 2015 } 2016 leaf key-data { 2017 type string; 2018 mandatory true; 2019 description 2020 "The key data for the SSH host key"; 2021 } 2022 } 2023 } 2024 container trust-anchors { 2025 when "../update-type = 'bootstrap-complete'" { 2026 description 2027 "Trust anchors are only sent when the update type 2028 is 'bootstrap-complete'."; 2029 } 2030 description 2031 "A list of trust anchor certificates an NMS may use to 2032 authenticate a NETCONF or RESTCONF connection to the 2033 device with."; 2034 list trust-anchor { 2035 description 2036 "A list of trust anchor certificates an NMS may use to 2037 authenticate a NETCONF or RESTCONF connection to the 2038 device with."; 2039 leaf-list protocol { 2040 type enumeration { 2041 enum netconf-ssh { description "netconf-ssh"; } 2042 enum netconf-tls { description "netconf-tls"; } 2043 enum restconf-tls { description "restconf-tls"; } 2044 enum netconf-ch-ssh { description "netconf-ch-ssh"; } 2045 enum netconf-ch-tls { description "netconf-ch-tls"; } 2046 enum restconf-ch-tls { description "restconf-ch-tls"; } 2047 } 2048 min-elements 1; 2049 description 2050 "The protocols that this trust anchor secures."; 2051 } 2052 leaf certificate { 2053 type pkcs7; 2054 mandatory true; 2055 description 2056 "An X.509 v3 certificate structure, as specified by 2057 Section 4 in RFC5280, encoded using ASN.1 distinguished 2058 encoding rules (DER), as specified in ITU-T X.690."; 2059 reference 2060 "RFC 5280: 2061 Internet X.509 Public Key Infrastructure Certificate 2062 and Certificate Revocation List (CRL) Profile. 2063 ITU-T X.690: 2064 Information technology - ASN.1 encoding rules: 2065 Specification of Basic Encoding Rules (BER), 2066 Canonical Encoding Rules (CER) and Distinguished 2067 Encoding Rules (DER)."; 2068 } 2069 } 2070 } 2071 } 2072 } // end action 2074 } // end device 2076 } 2077 2079 8. DHCP Zero Touch Options 2081 This section defines two DHCP options, one for DHCPv4 and one for 2082 DHCPv6. These two options are semantically the same, though 2083 syntactically different. 2085 8.1. DHCPv4 Zero Touch Option 2087 The DHCPv4 Zero Touch Option is used to provision the client with one 2088 or more URIs for bootstrap servers that can be contacted to attempt 2089 further configuration. 2091 DHCPv4 Zero Touch Redirect Option 2093 0 1 2094 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 2095 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2096 | option-code (TBD) | option-length | 2097 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2098 . . 2099 . bootstrap-server-list (variable length) . 2100 . . 2101 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2103 o option-code: OPTION_V4_ZEROTOUCH_REDIRECT (TBD) 2104 o option-length: The option length in octets 2105 o bootstrap-server-list: A list of servers for the 2106 client to attempt contacting, in order to obtain 2107 further bootstrapping data, in the format shown 2108 in [common-field-encoding]. 2110 DHCPv4 Client Behavior 2112 Clients MAY request the OPTION_V4_ZEROTOUCH_REDIRECT by including its 2113 option code in the Parameter Request List (55) in DHCP request 2114 messages. 2116 On receipt of a DHCPv4 Reply message which contains the 2117 OPTION_V4_ZEROTOUCH_REDIRECT, the client performs the following 2118 steps: 2120 1. Check the contents of the DHCPv4 message for at least one valid 2121 URI. If there is more than one valid URI in the list, a candidate 2122 list of possible URIs is created. 2124 2. Attempt to connect to the one of the URIs in the candidate list. 2125 The order in which these are processed by the client is 2126 implementation specific and not defined here. 2128 3. If a successful connection to the Zero Touch bootstrap server, 2129 then the client stops processing entries in the list and proceeds 2130 according to Appendix A.3, step(3). 2132 4. If the Zero Touch bootstrap server does not respond, provides 2133 an invalid response, or the transaction otherwise fails, the 2134 client SHOULD attempt to contact another server from the 2135 candidate list. 2137 Any invalid URI entries received in the uri-data field are ignored by 2138 the client. If OPTION_V4_ZEROTOUCH_REDIRECT does not contain at 2139 least one valid URI entry in the uri-data field, then the client MUST 2140 discard the option. 2142 DHCPv4 Server Behavior 2144 The DHCPv4 server MAY include a single instance of Option 2145 OPTION_V4_ZEROTOUCH_REDIRECT in DHCP messages it sends. Servers MUST 2146 NOT send more than one instance of the OPTION_V4_ZEROTOUCH_REDIRECT 2147 option. 2149 8.2. DHCPv6 Zero Touch Option 2151 The DHCPv6 Zero Touch Option is used to provision the client with one 2152 or more URIs for bootstrap servers that can be contacted to attempt 2153 further configuration. 2155 DHCPv6 Zero Touch Redirect Option 2157 0 1 2 3 2158 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 2159 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2160 | option-code (TBD) | option-length | 2161 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2162 . bootstrap-server-list (variable length) . 2163 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2165 o option-code: OPTION_V6_ZEROTOUCH_REDIRECT (TBD) 2166 o option-length: The option length in octets 2167 o bootstrap-server-list: A list of servers for the client to 2168 attempt contacting, in order to obtain further bootstrapping 2169 data, in the format shown in [common-field-encoding]. 2171 DHCPv6 Client Behavior 2173 Clients MAY request the OPTION_V6_ZEROTOUCH_REDIRECT option, as 2174 defined in [RFC3315], Sections 17.1.1, 18.1.1, 18.1.3, 18.1.4, 2175 18.1.5, and 22.7. As a convenience to the reader, we mention here 2176 that the client includes requested option codes in the Option Request 2177 Option. 2179 On receipt of a DHCPv6 reply message which contains the 2180 OPTION_V6_ZEROTOUCH_REDIRECT, the client performs the following 2181 steps: 2183 1. Check the contents of the DHCPv6 message for at least one valid 2184 URI. If there is more than one valid URI in the list, a 2185 candidate list of possible URIs is created. 2187 2. Attempt to connect to the one of the URIs in the candidate list. 2188 The order in which these are processed by the client is 2189 implementation specific and not defined here. 2191 3. If a successful connection to the Netconf Zero Touch Bootstrap 2192 server, then the client stops processing entries in the list and 2193 proceeds according to Appendix A.3, step(3). 2195 4. If the Zero Touch bootstrap server does not respond, provides 2196 and invalid response or the transaction otherwise fails, the 2197 client SHOULD attempt to contact another server from the 2198 candidate list. 2200 Any invalid URI entries received in the uri-data field are ignored by 2201 the client. If OPTION_V6_ZEROTOUCH_REDIRECT does not contain at 2202 least one valid URI entry in the uri-data field, then the client MUST 2203 discard the option. 2205 DHCPv6 Server Behavior 2207 Sections 17.2.2 and 18.2 of [RFC3315] govern server operation 2208 in regard to option assignment. As a convenience to the reader, 2209 we mention here that the server will send a particular option code 2210 only if configured with specific values for that option code and if 2211 the client requested it. 2213 Option OPTION_V6_ZEROTOUCH_REDIRECT is a singleton. Servers MUST NOT 2214 send more than one instance of the OPTION_V6_ZEROTOUCH_REDIRECT 2215 option. 2217 8.3. Common Field Encoding 2219 Both of the DHCPv4 and DHCPv6 options defined in this section encode 2220 a list of bootstrap server URIs. The 'URI' structure is an option 2221 that can contain multiple URIs (see [RFC7227], Section 5.7). 2223 bootstrap-server-list: 2225 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 2226 | uri-length | URI | 2227 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 2229 o uri-length: variable, in octets. 2231 o URI: URI of zerotouch bootstrap server, using the HTTPS URI 2232 scheme defined in Section 2.7.2 of RFC7230. 2234 9. Security Considerations 2236 9.1. Immutable storage for trust anchors 2238 Devices MUST ensure that all their trust anchor certificates, 2239 including those for connecting to bootstrap servers and verifying 2240 ownership vouchers, are protected from external modification. 2242 It may be necessary to update these certificates over time (e.g., the 2243 manufacturer wants to delegate trust to a new CA). It is therefore 2244 expected that devices MAY update these trust anchors when needed 2245 through a verifiable process, such as a software upgrade using signed 2246 software images. 2248 9.2. Clock Sensitivity 2250 The solution in this document relies on TLS certificates, owner 2251 certificates, and ownership vouchers, all of which require an 2252 accurate clock in order to be processed correctly (e.g., to test 2253 validity dates and revocation status). Implementations MUST ensure 2254 devices have an accurate clock when shipped from manufacturing 2255 facilities, and take steps to prevent clock tampering. 2257 If it is not possible to ensure clock accuracy, it is RECOMMENDED 2258 that implementations disable the aspects of the solution having clock 2259 sensitivity. In particular, such implementations should assume that 2260 TLS certificates, ownership vouchers, and owner certificates never 2261 expire and are not revokable. In real-world terms, this means that 2262 manufacturers SHOULD only issue a single ownership voucher for the 2263 lifetime of such devices. 2265 Implementations SHOULD NOT rely on NTP for time, as NTP is not a 2266 secure protocol. 2268 9.3. Blindly authenticating a bootstrap server 2270 This document allows a device to blindly authenticate a bootstrap 2271 server's TLS certificate. It does so to allow for cases where the 2272 redirect information may be obtained in an unsecured manner, which is 2273 desirable to support in some cases. 2275 To compensate for this, this document requires that devices, when 2276 connected to an untrusted bootstrap server, do not send their IDevID 2277 certificate for client authentication, and they do not POST any 2278 progress updates, and they assert that data downloaded from the 2279 server is signed. 2281 9.4. Entropy loss over time 2283 Section 7.2.7.2 of the IEEE Std 802.1AR-2009 standard says that 2284 IDevID certificate should never expire (i.e. having the notAfter 2285 value 99991231235959Z). Given the long-lived nature of these 2286 certificates, it is paramount to use a strong key length (e.g., 2287 512-bit ECC). 2289 9.5. Serial Numbers 2291 This draft uses the device's serial number both in the IDevID 2292 certificate as well as in the bootstrap server API. Serial numbers 2293 are ubiquitous and prominently contained in invoices and on labels 2294 affixed to devices and their packaging. That said, serial numbers 2295 many times encode revealing information, such as the device's model 2296 number, manufacture date, and/or sequence number. Knowledge of this 2297 information may provide an adversary with details needed to launch an 2298 attack. 2300 9.6. Disclosing Information to Untrusted Servers 2302 This document enables devices to establish provisional connections to 2303 untrusted bootstrap servers, in order for the server to provide 2304 signed data to the device. However, since the server is untrusted, 2305 it may be under the control of an adversary, and therefore devices 2306 should be cautious about the data they send in such cases. 2308 Already this document prevents devices from sending either their 2309 IDevID certificate or their progress updates to untrusted servers, 2310 however potentially identifying values (e.g., unique-id, os-name, os- 2311 version) are still potentially encoded in the HTTP request sent to 2312 the servers. This information could be used by an adversary to mount 2313 an attack against the device. 2315 Devices concerned about such disclosures, when connecting to an 2316 untrusted server, should 1) use a 'unique-id' value that is not 2317 easily associated to the type of device it is (e.g., use a key 2318 derivation function over the unique-id value) and 2) be very 2319 selective about which HTTP query parameters are sent (ideally none). 2321 Building on top of the recursive nature of the solution presented in 2322 this document, a server, seeing that a device is following the 2323 recommendation from the previous paragraph, should return signed 2324 redirect information, not signed onboarding information, as would 2325 normally be expected. The redirect information should point the 2326 device back to the same server but, because the signed redirect 2327 information contained the trust anchor certificate for the server, 2328 the device would then establish a trusted connection to the server, 2329 and thereby be able to freely send data to the server, including its 2330 IDevID certificate, unique-id, query parameters, and various progress 2331 updates. Please see Appendix B for more information on this. 2333 9.7. Sequencing Sources of Bootstrapping Data 2335 For devices supporting more than one source for bootstrapping data, 2336 no particular sequencing order has to be observed for security 2337 reasons, as the solution for each source is considered equally 2338 secure. However, from a privacy perspective, it is RECOMMENDED that 2339 devices access local sources before accessing remote sources. 2341 10. IANA Considerations 2343 10.1. The BOOTP Manufacturer Extensions and DHCP Options Registry 2345 IANA is kindly requested to allocate a new option code from the 2346 "BOOTP Manufacturer Extensions and DHCP Options" registry maintained 2347 at http://www.iana.org/assignments/bootp-dhcp-parameters: 2349 TBD for OPTION_V4_ZEROTOUCH_REDIRECT 2351 And a new option code from the "Dynamic Host Configuration Protocol 2352 for IPv6 (DHCPv6)" registry maintained at 2353 http://www.iana.org/assignments/dhcpv6-parameters: 2355 TBD for OPTION_V6_ZEROTOUCH_REDIRECT 2357 10.2. The IETF XML Registry 2359 This document registers two URIs in the IETF XML registry [RFC3688]. 2360 Following the format in [RFC3688], the following registrations are 2361 requested: 2363 URI: urn:ietf:params:xml:ns:yang:ietf-zerotouch-information 2364 Registrant Contact: The NETCONF WG of the IETF. 2365 XML: N/A, the requested URI is an XML namespace. 2367 URI: urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server 2368 Registrant Contact: The NETCONF WG of the IETF. 2369 XML: N/A, the requested URI is an XML namespace. 2371 10.3. The YANG Module Names Registry 2373 This document registers two YANG modules in the YANG Module Names 2374 registry [RFC6020]. Following the format defined in [RFC6020], the 2375 the following registrations are requested: 2377 name: ietf-zerotouch-information 2378 namespace: urn:ietf:params:xml:ns:yang:ietf-zerotouch-information 2379 prefix: zti 2380 reference: RFC XXXX 2382 name: ietf-zerotouch-bootstrap-server 2383 namespace: urn:ietf:params:xml:ns:yang:ietf-zerotouch-bootstrap-server 2384 prefix: ztbs 2385 reference: RFC XXXX 2387 10.4. RESTCONF Capability URNs 2389 This document registers several capability identifiers in the 2390 "RESTCONF Capability URNs" registry per [RFC8040]: 2392 Index Capability Identifier 2393 --------------------------------------------------------------------- 2394 :os-name urn:ietf:params:restconf:capability:os-name:1.0 2395 :os-version urn:ietf:params:restconf:capability:os-version:1.0 2396 :circuit-id urn:ietf:params:restconf:capability:circuit-id:1.0 2397 :remote-id urn:ietf:params:restconf:capability:remote-id:1.0 2398 :nonce urn:ietf:params:restconf:capability:nonce:1.0 2400 11. Acknowledgements 2402 The authors would like to thank for following for lively discussions 2403 on list and in the halls (ordered by last name): David Harrington, 2404 Michael Behringer, Dean Bogdanovic, Martin Bjorklund, Joe Clarke, 2405 Toerless Eckert, Stephen Farrell, Stephen Hanna, Wes Hardaker, Russ 2406 Mundy, Reinaldo Penno, Randy Presuhn, Max Pritikin, Michael 2407 Richardson, Phil Shafer, Juergen Schoenwaelder. 2409 Special thanks goes to Steve Hanna, Russ Mundy, and Wes Hardaker for 2410 brainstorming the original I-D's solution during the IETF 87 meeting 2411 in Berlin. 2413 12. References 2415 12.1. Normative References 2417 [I-D.ietf-anima-voucher] 2418 Watsen, K., Richardson, M., Pritikin, M., and T. Eckert, 2419 "Voucher Profile for Bootstrapping Protocols", draft-ietf- 2420 anima-voucher-05 (work in progress), August 2017. 2422 [RFC1035] Mockapetris, P., "Domain names - implementation and 2423 specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, 2424 November 1987, . 2426 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2427 Requirement Levels", BCP 14, RFC 2119, 2428 DOI 10.17487/RFC2119, March 1997, 2429 . 2431 [RFC2315] Kaliski, B., "PKCS #7: Cryptographic Message Syntax 2432 Version 1.5", RFC 2315, DOI 10.17487/RFC2315, March 1998, 2433 . 2435 [RFC3315] Droms, R., Ed., Bound, J., Volz, B., Lemon, T., Perkins, 2436 C., and M. Carney, "Dynamic Host Configuration Protocol 2437 for IPv6 (DHCPv6)", RFC 3315, DOI 10.17487/RFC3315, July 2438 2003, . 2440 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2441 Housley, R., and W. Polk, "Internet X.509 Public Key 2442 Infrastructure Certificate and Certificate Revocation List 2443 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 2444 . 2446 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2447 the Network Configuration Protocol (NETCONF)", RFC 6020, 2448 DOI 10.17487/RFC6020, October 2010, 2449 . 2451 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2452 Verification of Domain-Based Application Service Identity 2453 within Internet Public Key Infrastructure Using X.509 2454 (PKIX) Certificates in the Context of Transport Layer 2455 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2456 2011, . 2458 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 2459 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 2460 DOI 10.17487/RFC6234, May 2011, 2461 . 2463 [RFC6762] Cheshire, S. and M. Krochmal, "Multicast DNS", RFC 6762, 2464 DOI 10.17487/RFC6762, February 2013, 2465 . 2467 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 2468 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, 2469 . 2471 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2472 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2473 . 2475 [RFC7227] Hankins, D., Mrugalski, T., Siodelski, M., Jiang, S., and 2476 S. Krishnan, "Guidelines for Creating New DHCPv6 Options", 2477 BCP 187, RFC 7227, DOI 10.17487/RFC7227, May 2014, 2478 . 2480 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 2481 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 2482 April 2015, . 2484 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2485 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2486 . 2488 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2489 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2490 . 2492 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2493 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2494 May 2017, . 2496 [Std-802.1AR-2009] 2497 IEEE SA-Standards Board, "IEEE Standard for Local and 2498 metropolitan area networks - Secure Device Identity", 2499 December 2009, . 2502 12.2. Informative References 2504 [I-D.ietf-netconf-netconf-client-server] 2505 Watsen, K., Wu, G., and J. Schoenwaelder, "NETCONF Client 2506 and Server Models", draft-ietf-netconf-netconf-client- 2507 server-04 (work in progress), July 2017. 2509 [RFC2939] Droms, R., "Procedures and IANA Guidelines for Definition 2510 of New DHCP Options and Message Types", BCP 43, RFC 2939, 2511 DOI 10.17487/RFC2939, September 2000, 2512 . 2514 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2515 DOI 10.17487/RFC3688, January 2004, 2516 . 2518 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2519 and A. Bierman, Ed., "Network Configuration Protocol 2520 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2521 . 2523 [RFC6698] Hoffman, P. and J. Schlyter, "The DNS-Based Authentication 2524 of Named Entities (DANE) Transport Layer Security (TLS) 2525 Protocol: TLSA", RFC 6698, DOI 10.17487/RFC6698, August 2526 2012, . 2528 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 2529 Galperin, S., and C. Adams, "X.509 Internet Public Key 2530 Infrastructure Online Certificate Status Protocol - OCSP", 2531 RFC 6960, DOI 10.17487/RFC6960, June 2013, 2532 . 2534 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 2535 System Management", RFC 7317, DOI 10.17487/RFC7317, August 2536 2014, . 2538 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 2539 RFC 8071, DOI 10.17487/RFC8071, February 2017, 2540 . 2542 Appendix A. Workflow Overview 2544 The zero touch solution presented in this document is conceptualized 2545 to be composed of the non-normative workflows described in this 2546 section. Implementations details are expected to vary. Each diagram 2547 is followed by a detailed description of the steps presented in the 2548 diagram, with further explanation on how implementations may vary. 2550 A.1. Enrollment and Ordering Devices 2552 The following diagram illustrates key interactions that may occur 2553 from when a prospective owner enrolls in a manufacturer's zero touch 2554 program to when the manufacturer ships devices for an order placed by 2555 the prospective owner. 2557 +-----------+ 2558 +------------+ |Prospective| +---+ 2559 |Manufacturer| | Owner | |NMS| 2560 +------------+ +-----------+ +---+ 2561 | | | 2562 | | | 2563 | 1. initiate enrollment | | 2564 #<-----------------------------| | 2565 # | | 2566 # | | 2567 # IDevID trust anchor | | 2568 #-----------------------------># set IDevID trust anchor | 2569 # #--------------------------->| 2570 # | | 2571 # bootstrap server | | 2572 # account credentials | | 2573 #-----------------------------># set credentials | 2574 | #--------------------------->| 2575 | | | 2576 | | | 2577 | 2. set owner certificate trust anchor | 2578 |<----------------------------------------------------------| 2579 | | | 2580 | | | 2581 | 3. place device order | | 2582 |<-----------------------------# model devices | 2583 | #--------------------------->| 2584 | | | 2585 | 4. ship devices and send | | 2586 | device identifiers and | | 2587 | ownership vouchers | | 2588 |-----------------------------># set device identifiers | 2589 | # and ownership vouchers | 2590 | #--------------------------->| 2591 | | | 2593 Each numbered item below corresponds to a numbered item in the 2594 diagram above. 2596 1. A prospective owner of a manufacturer's devices, or an existing 2597 owner that wishes to start using zero touch for future device 2598 orders, initiates an enrollment process with the manufacturer or 2599 delegate. This process includes the following: 2601 * Regardless how the prospective owner intends to bootstrap 2602 their devices, they will always obtain from the manufacturer 2603 or delegate the trust anchor certificate for its device's 2604 IDevID certificates. This certificate will need to be 2605 installed on the prospective owner's NMS so that the NMS can 2606 subsequently authenticate the devices' IDevID certificates. 2608 * If the manufacturer hosts an Internet based bootstrap server 2609 (e.g., a redirect server) such as described in Section 4.4, 2610 then credentials necessary to configure the bootstrap server 2611 would be provided to the prospective owner. If the bootstrap 2612 server is configurable through an API (outside the scope of 2613 this document), then the credentials might be installed on the 2614 prospective owner's NMS so that the NMS can subsequently 2615 configure the manufacturer-hosted bootstrap server directly. 2617 2. If the manufacturer's devices are able to validate signed data 2618 (Section 5.4), and assuming that the prospective owner's NMS is 2619 able to prepare and sign the bootstrapping data itself, the 2620 prospective owner's NMS might set a trust anchor certificate onto 2621 the manufacturer's bootstrap server, using the credentials 2622 provided in the previous step. This certificate is the trust 2623 anchor certificate that the prospective owner would like the 2624 manufacturer to place into the ownership vouchers it generates, 2625 thereby enabling devices to trust the owner's owner certificate. 2626 How this trust anchor certificate is used to enable devices to 2627 validate signed bootstrapping data is described in Section 5.4. 2629 3. Some time later, the prospective owner places an order with the 2630 manufacturer or delegate, perhaps with a special flag checked for 2631 zero touch handling. At this time, or perhaps before placing the 2632 order, the owner may model the devices in their NMS, creating 2633 virtual objects for the devices with no real-world device 2634 associations. For instance the model can be used to simulate the 2635 device's location in the network and the configuration it should 2636 have when fully operational. 2638 4. When the manufacturer or delegate fulfills the order, shipping 2639 the devices to their intended locations, they may notify the 2640 owner of the devices's serial numbers and shipping destinations, 2641 which the owner may use to stage the network for when the devices 2642 power on. Additionally, the manufacturer may send one or more 2643 ownership vouchers, cryptographically assigning ownership of 2644 those devices to the owner. The owner may set this information 2645 on their NMS, perhaps binding specific modeled devices to the 2646 serial numbers and ownership vouchers. 2648 A.2. Owner Stages the Network for Bootstrap 2650 The following diagram illustrates how an owner might stage the 2651 network for bootstrapping devices. 2653 +----------+ +------------+ 2654 |Deployment| |Manufacturer| +------+ +------+ 2655 | Specific | | Hosted | | Local| | Local| +---------+ 2656 +---+ |Bootstrap | | Bootstrap | | DNS | | DHCP | |Removable| 2657 |NMS| | Server | | Server | |Server| |Server| | Storage | 2658 +---+ +----------+ +------------+ +------+ +------+ +---------+ 2659 | | | | | | 2660 activate | | | | | | 2661 modeled | | | | | | 2662 1. device | | | | | | 2663 ----------->| | | | | | 2664 | 2. (optional) | | | | 2665 | configure | | | | 2666 | bootstrap | | | | 2667 | server | | | | 2668 |------->| | | | | 2669 | | | | | | 2670 | 3. (optional) configure | | | 2671 | bootstrap server | | | | 2672 |--------------------->| | | | 2673 | | | | | | 2674 | | | | | | 2675 | 4. (optional) configure DNS server| | | 2676 |---------------------------------->| | | 2677 | | | | | | 2678 | | | | | | 2679 | 5. (optional) configure DHCP server | | 2680 |------------------------------------------->| | 2681 | | | | | | 2682 | | | | | | 2683 | 6. (optional) store bootstrapping artifacts on media | 2684 |----------------------------------------------------->| 2685 | | | | | | 2686 | | | | | | 2688 Each numbered item below corresponds to a numbered item in the 2689 diagram above. 2691 1. Having previously modeled the devices, including setting their 2692 fully operational configurations and associating both device 2693 serial numbers and ownership vouchers, the owner might "activate" 2694 one or more modeled devices. That is, the owner tells the NMS to 2695 perform the steps necessary to prepare for when the real-world 2696 devices power up and initiate the bootstrapping process. Note 2697 that, in some deployments, this step might be combined with the 2698 last step from the previous workflow. Here it is depicted that 2699 an NMS performs the steps, but they may be performed manually or 2700 through some other mechanism. 2702 2. If it is desired to use a deployment specific bootstrap server, 2703 it must be configured to provide the bootstrapping information 2704 for the specific devices. Configuring the bootstrap server may 2705 occur via a programmatic API not defined by this document. 2706 Illustrated here as an external component, the bootstrap server 2707 may be implemented as an internal component of the NMS itself. 2709 3. If it is desired to use a manufacturer (or delegate) hosted 2710 bootstrap server, it must be configured to provide the 2711 bootstrapping information for the specific devices. The 2712 configuration must be either redirect or onboarding information. 2713 That is, either the manufacturer hosted bootstrap server will 2714 redirect the device to another bootstrap server, or provide the 2715 device with its bootstrapping information itself. The types of 2716 bootstrapping information the manufacturer hosted bootstrap 2717 server supports may vary by implementation; some implementations 2718 may only support redirect information, or only support onboarding 2719 information, or support both redirect and onboarding information. 2720 Configuring the bootstrap server may occur via a programmatic API 2721 not defined by this document. 2723 4. If it is desired to use a DNS server to supply bootstrapping 2724 information, a DNS server needs to be configured. If multicast 2725 DNS-SD is desired, then the server must reside on the local 2726 network, otherwise the DNS server may reside on a remote network. 2727 Please see Section 4.2 for more information about how to 2728 configure DNS servers. Configuring the DNS server may occur via 2729 a programmatic API not defined by this document. 2731 5. If it is desired to use a DHCP server to supply bootstrapping 2732 data, a DHCP server needs to be configured. The DHCP server may 2733 be accessed directly or via a DHCP relay. Please see Section 4.3 2734 for more information about how to configure DHCP servers. 2735 Configuring the DHCP server may occur via a programmatic API not 2736 defined by this document. 2738 6. If it is desired to use a removable storage device (e.g., USB 2739 flash drive) to supply bootstrapping information, the information 2740 would need to be placed onto it. Please see Section 4.1 for more 2741 information about how to configure a removable storage device. 2743 A.3. Device Powers On 2745 The following diagram illustrates the sequence of activities that 2746 occur when a device powers on. 2748 +----------+ 2749 +-----------+ |Deployment| 2750 | Source of | | Specific | 2751 +------+ | Bootstrap | |Bootstrap | +---+ 2752 |Device| | Data | | Server | |NMS| 2753 +------+ +-----------+ +----------+ +---+ 2754 | | | | 2755 | | | | 2756 | 1. if zerotouch bootstrap is not | | | 2757 | configured, then exit. | | | 2758 | | | | 2759 | 2. for each source supported, check | | | 2760 |------------------------------------->| | | 2761 | | | | 2762 | 3. if onboarding-information found, | | | 2763 | initialize self and, only if | | | 2764 | source is a bootstrap server, | | | 2765 | send progress updates | | | 2766 |-------------------------------------># | | 2767 | # webhook | | 2768 | #----------------------->| 2769 | | | 2770 | 4. else if redirect-information found, for | | 2771 | each bootstrap server specified, check | | 2772 |-+-------------------------------------------------->| | 2773 | | | | 2774 | | if more redirect-information is found, recurse | | 2775 | | (not depicted), else if onboarding-information | | 2776 | | found, initialize self and post progress updates | | 2777 | +--------------------------------------------------># | 2778 | # webhook | 2779 | #-------->| 2780 | 2781 | 5. retry sources and/or wait for manual provisioning. 2782 | 2784 The interactions in the above diagram are described below. 2786 1. Upon power being applied, the device checks to see if zerotouch 2787 bootstrapping is configured, such as is the case when running its 2788 "factory default" configuration. If zerotouch bootstrapping is 2789 not configured, then the bootstrapping logic exits and none of 2790 the following interactions occur. 2792 2. For each source of bootstrapping data the device supports, 2793 preferably in order of closeness to the device (e.g., removable 2794 storage before Internet based servers), the device checks to see 2795 if there is any bootstrapping data for it there. 2797 3. If onboarding information is found, the device initializes itself 2798 accordingly (e.g., installing a boot-image and committing an 2799 initial configuration). If the source is a bootstrap server, and 2800 the bootstrap server can be trusted (i.e., TLS-level 2801 authentication), the device also sends progress updates to the 2802 bootstrap server. 2804 * The contents of the initial configuration should configure an 2805 administrator account on the device (e.g., username, ssh-rsa 2806 key, etc.) and should configure the device either to listen 2807 for NETCONF or RESTCONF connections or to initiate call home 2808 connections [RFC8071]. 2810 * If the bootstrap server supports forwarding device progress 2811 updates to external systems (e.g., via a webhook), a 2812 "bootstrap-complete" progress update (Section 7.4) informs the 2813 external system to know when it can, for instance, initiate a 2814 connection to the device (assuming it knows the device's 2815 address and the device was configured to listen for 2816 connections). To support this further, the bootstrap-complete 2817 progress update may also relay the device's SSH host keys and/ 2818 or TLS certificates, with which the external system can use to 2819 authenticate subsequent connections to the device. 2821 If the device successfully completes the bootstrapping process 2822 (i.e., zerotouch bootstrapping is no longer configured), it exits 2823 the bootstrapping logic without considering any additional 2824 sources of bootstrapping data. 2826 4. Otherwise, if redirect information is found, the device iterates 2827 through the list of specified bootstrap servers, checking to see 2828 if there is any bootstrapping data for it on them. If the 2829 bootstrap server returns more redirect information, then the 2830 device processes it recursively. Otherwise, if the bootstrap 2831 server returns onboarding information, the device processes it 2832 following the description provided in (3) above. 2834 5. After having tried all supported sources of bootstrapping data, 2835 the device may retry again all the sources and/or provide 2836 manageability interfaces for manual configuration (e.g., CLI, 2837 HTTP, NETCONF, etc.). If manual configuration is allowed, and 2838 such configuration is provided, the device should cease trying to 2839 obtain bootstrapping data, as the need to do so would no longer 2840 be present. 2842 Appendix B. Promoting a Connection from Untrusted to Trusted 2844 The following diagram illustrates a sequence of bootstrapping 2845 activities that promote an untrusted connection to a bootstrap server 2846 to a trusted connection to the same bootstrap server. 2848 +----------+ 2849 |Deployment| 2850 | Specific | 2851 +------+ |Bootstrap | 2852 |Device| | Server | 2853 +------+ +----------+ 2854 | | 2855 | 1. "HTTPS" Request (GET /device=) | 2856 |------------------------------------------------------->| 2857 | 2. "HTTPS" Response (signed redirect information) | 2858 |<-------------------------------------------------------| 2859 | | 2860 | | 2861 | 3. HTTPS Request (GET /device=unique-id?os-name=xyz) | 2862 |------------------------------------------------------->| 2863 | 4. HTTPS Response (unsigned onboarding information | 2864 |<-------------------------------------------------------| 2865 | | 2867 The interactions in the above diagram are described below. 2869 1. The device initiates an untrusted connection to a bootstrap 2870 server, as is indicated by putting "HTTPS" in doublequotes above. 2871 Because the device is unable to trust the server, it does not 2872 send its IDevID certificate, or its raw unique id, or any HTTP 2873 query parameters it may have. The diagram above uses 2874 to indicate that the device used a key 2875 derivation function, KDF, over its unique-id to protect the 2876 device's identity in case the server is owned by an adversary. 2878 2. The bootstrap server iterates over some internal database of 2879 devices until finding one for which the key derivation function 2880 over its unique-id generates a match. In this example, the 2881 bootstrap server wants the device to have a secure connection to 2882 it so, rather than sending the device signed onboarding 2883 information, it sends signed redirect information instead, 2884 redirecting the device back to it again. 2886 3. Upon validating the signed redirect information, the device 2887 establishes a secure connection to the bootstrap server. 2888 Unbeknownst to the device, it is the same bootstrap server it was 2889 connected to previously. Because the device is able to 2890 authenticate the bootstrap server, it sends its IDevID 2891 certificate, raw unique-id, and any additional query parameters 2892 it has ("os-name" shown above) to the bootstrap server. 2894 4. This time the bootstrap server returns unsigned onboarding 2895 information to the device. 2897 Appendix C. Change Log 2899 C.1. ID to 00 2901 o Major structural update; the essence is the same. Most every 2902 section was rewritten to some degree. 2904 o Added a Use Cases section 2906 o Added diagrams for "Actors and Roles" and "NMS Precondition" 2907 sections, and greatly improved the "Device Boot Sequence" diagram 2909 o Removed support for physical presence or any ability for 2910 configlets to not be signed. 2912 o Defined the Zero Touch Information DHCP option 2914 o Added an ability for devices to also download images from 2915 configuration servers 2917 o Added an ability for configlets to be encrypted 2919 o Now configuration servers only have to support HTTP/S - no other 2920 schemes possible 2922 C.2. 00 to 01 2924 o Added boot-image and validate-owner annotations to the "Actors and 2925 Roles" diagram. 2927 o Fixed 2nd paragraph in section 7.1 to reflect current use of 2928 anyxml. 2930 o Added encrypted and signed-encrypted examples 2932 o Replaced YANG module with XSD schema 2934 o Added IANA request for the Zero Touch Information DHCP Option 2936 o Added IANA request for media types for boot-image and 2937 configuration 2939 C.3. 01 to 02 2941 o Replaced the need for a configuration signer with the ability for 2942 each NMS to be able to sign its own configurations, using 2943 manufacturer signed ownership vouchers and owner certificates. 2945 o Renamed configuration server to bootstrap server, a more 2946 representative name given the information devices download from 2947 it. 2949 o Replaced the concept of a configlet by defining a southbound 2950 interface for the bootstrap server using YANG. 2952 o Removed the IANA request for the boot-image and configuration 2953 media types 2955 C.4. 02 to 03 2957 o Minor update, mostly just to add an Editor's Note to show how this 2958 draft might integrate with the draft-pritikin-anima-bootstrapping- 2959 keyinfra. 2961 C.5. 03 to 04 2963 o Major update formally introducing unsigned data and support for 2964 Internet-based redirect servers. 2966 o Added many terms to Terminology section. 2968 o Added all new "Guiding Principles" section. 2970 o Added all new "Sources for Bootstrapping Data" section. 2972 o Rewrote the "Interactions" section and renamed it "Workflow 2973 Overview". 2975 C.6. 04 to 05 2977 o Semi-major update, refactoring the document into more logical 2978 parts 2980 o Created new section for information types 2982 o Added support for DNS servers 2984 o Now allows provisional TLS connections 2986 o Bootstrapping data now supports scripts 2987 o Device Details section overhauled 2989 o Security Considerations expanded 2991 o Filled in enumerations for notification types 2993 C.7. 05 to 06 2995 o Minor update 2997 o Added many Normative and Informative references. 2999 o Added new section Other Considerations. 3001 C.8. 06 to 07 3003 o Minor update 3005 o Added an Editorial Note section for RFC Editor. 3007 o Updated the IANA Considerations section. 3009 C.9. 07 to 08 3011 o Minor update 3013 o Updated to reflect review from Michael Richardson. 3015 C.10. 08 to 09 3017 o Added in missing "Signature" artifact example. 3019 o Added recommendation for manufacturers to use interoperable 3020 formats and file naming conventions for removable storage devices. 3022 o Added configuration-handling leaf to guide if config should be 3023 merged, replaced, or processed like an edit-config/yang-patch 3024 document. 3026 o Added a pre-configuration script, in addition to the post- 3027 configuration script from -05 (issue #15). 3029 C.11. 09 to 10 3031 o Factored ownership vocher and voucher revocation to a separate 3032 document: draft-kwatsen-netconf-voucher. (issue #11) 3034 o Removed options 'edit-config' and yang- 3035 patch'. (issue #12) 3037 o Defined how a signature over signed-data returned from a bootstrap 3038 server is processed. (issue #13) 3040 o Added recommendation for removable storage devices to use open/ 3041 standard file systems when possible. (issue #14) 3043 o Replaced notifications "script-[warning/error]" with "[pre/post]- 3044 script-[warning/error]". (goes with issue #15) 3046 o switched owner-certificate to be encoded using the pkcs#7 format. 3047 (issue #16) 3049 o Replaced md5/sha1 with sha256 inside a choice statement, for 3050 future extensibility. (issue #17) 3052 o A ton of editorial changes, as I went thru the entire draft with a 3053 fine-toothed comb. 3055 C.12. 10 to 11 3057 o fixed yang validation issues found by IETFYANGPageCompilation. 3058 note: these issues were NOT found by pyang --ietf or by the 3059 submission-time validator... 3061 o fixed a typo in the yang module, someone the config false 3062 statement was removed. 3064 C.13. 11 to 12 3066 o fixed typo that prevented Appendix B from loading the examples 3067 correctly. 3069 o fixed more yang validation issues found by 3070 IETFYANGPageCompilation. note: again, these issues were NOT found 3071 by pyang --ietf or by the submission-time validator... 3073 o updated a few of the notification enumerations to be more 3074 consistent with the other enumerations (following the warning/ 3075 error pattern). 3077 o updated the information-type artifact to state how it's encoded, 3078 matching the language that was in Appendix B. 3080 C.14. 12 to 13 3082 o defined a standalone artifact to encode the old information-type 3083 into a PKCS#7 structure. 3085 o standalone information artifact hardcodes JSON encoding (to match 3086 the voucher draft). 3088 o combined the information and signature PKCS#7 structures into a 3089 single PKCS#7 structure. 3091 o moved the certificate-revocations into the owner-certificate's 3092 PKCS#7 structure. 3094 o eliminated support for voucher-revocations, to reflect the 3095 voucher-draft's switch from revocations to renewals. 3097 C.15. 13 to 14 3099 o Renamed "bootstrap information" to "onboarding information". 3101 o Rewrote DHCP sections to address the packet-size limitation issue, 3102 as discussed in Chicago. 3104 o Added Ian as an author for his text-contributions to the DHCP 3105 sections. 3107 o Removed the Guiding Principles section. 3109 C.16. 14 to 15 3111 o Renamed action 'notification' to 'update-progress' and, likewise 3112 'notification-type' to 'update-type'. 3114 o Updated examples to use "base64encodedvalue==" for binary values. 3116 o Greatly simplified the 'Artifact Groupings' section, and moved it 3117 as a subsection to the 'Artifacts' section. 3119 o Moved the 'Workflow Overview' section to the Appendix. 3121 o Renamed 'bootstrap information' to 'update information'. 3123 o Removed 'Other Considerations' section. 3125 o Tons of editorial updates. 3127 C.17. 15 to 16 3129 o tweaked language to refer to "initial state" rather than "factory 3130 default configuration", so as accommodate white-box scenarios. 3132 o added a paragraph to Intro regarding how the solution primarily 3133 regards physical machines, but could be extended to VMs by a 3134 future document. 3136 o added a pointer to the Workflow Overview section (recently moved 3137 to the Appendix) to the Intro. 3139 o added a note that, in order to simplify the verification process, 3140 the "Zerotouch Information" PKCS#7 structure MUST also contain the 3141 signing X.509 certificate. 3143 o noted that the owner certificate's must either have no Key Usage 3144 or the Key Usage must set the "digitalSignature" bit. 3146 o noted that the owner certificate's subject and subjectAltName 3147 values are not constrained. 3149 o moved/consolidated some text from the Artifacts section down to 3150 the Device Details section. 3152 o tightened up some ambiguous language, for instance, by referring 3153 to specific leaf names in the Voucher artifact. 3155 o reverted a previously overzealous s/unique-id/serial-number/ 3156 change. 3158 o modified language for when ZTP runs from when factory-default 3159 config is running to when ZTP is configured, which the factory- 3160 defaults should set . 3162 C.18. 16 to 17 3164 o Added an example for how to promote an untrusted connection to a 3165 trusted connection. 3167 o Added a "query parameters" section defining some parameters 3168 enabling scenarios raised in last call. 3170 o Added a "Disclosing Information to Untrusted Servers" section to 3171 the Security Considerations. 3173 Authors' Addresses 3175 Kent Watsen 3176 Juniper Networks 3178 EMail: kwatsen@juniper.net 3180 Mikael Abrahamsson 3181 T-Systems 3183 EMail: mikael.abrahamsson@t-systems.se 3185 Ian Farrer 3186 Deutsche Telekom AG 3188 EMail: ian.farrer@telekom.de