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