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