idnits 2.17.00 (12 Aug 2021) /tmp/idnits18597/draft-ietf-anima-rfc8366bis-00.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 23 instances of too long lines in the document, the longest one being 11 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document date (January 2022) is 119 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'TBD' is mentioned on line 870, but not defined == Missing Reference: 'RFCXXXX' is mentioned on line 905, but not defined == Missing Reference: 'RFC8366' is mentioned on line 907, but not defined == Missing Reference: 'RFCXXX' is mentioned on line 907, but not defined == Unused Reference: 'RFC6838' is defined on line 1082, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU-T.X690.2015' -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ANIMA Working Group K. Watsen 3 Internet-Draft Juniper Networks 4 Intended status: Standards Track M. Richardson 5 Expires: 15 July 2022 Sandelman Software 6 M. Pritikin 7 Cisco Systems 8 T. Eckert 9 Q. Ma 10 Huawei 11 January 2022 13 A Voucher Artifact for Bootstrapping Protocols 14 draft-ietf-anima-rfc8366bis-00 16 Abstract 18 This document defines a strategy to securely assign a pledge to an 19 owner using an artifact signed, directly or indirectly, by the 20 pledge's manufacturer. This artifact is known as a "voucher". 22 This document defines an artifact format as a YANG-defined JSON 23 document that has been signed using a Cryptographic Message Syntax 24 (CMS) structure. Other YANG-derived formats are possible. The 25 voucher artifact is normally generated by the pledge's manufacturer 26 (i.e., the Manufacturer Authorized Signing Authority (MASA)). 28 This document only defines the voucher artifact, leaving it to other 29 documents to describe specialized protocols for accessing it. 31 Discussion Venues 33 This note is to be removed before publishing as an RFC. 35 Discussion of this document takes place on the Autonomic Networking 36 Integrated Model and Approach Working Group mailing list 37 (anima@ietf.org), which is archived at 38 https://mailarchive.ietf.org/arch/browse/anima/. 40 Source for this draft and an issue tracker can be found at 41 https://github.com/anima-wg/voucher. 43 Status of This Memo 45 This Internet-Draft is submitted in full conformance with the 46 provisions of BCP 78 and BCP 79. 48 Internet-Drafts are working documents of the Internet Engineering 49 Task Force (IETF). Note that other groups may also distribute 50 working documents as Internet-Drafts. The list of current Internet- 51 Drafts is at https://datatracker.ietf.org/drafts/current/. 53 Internet-Drafts are draft documents valid for a maximum of six months 54 and may be updated, replaced, or obsoleted by other documents at any 55 time. It is inappropriate to use Internet-Drafts as reference 56 material or to cite them other than as "work in progress." 58 This Internet-Draft will expire on 5 July 2022. 60 Copyright Notice 62 Copyright (c) 2022 IETF Trust and the persons identified as the 63 document authors. All rights reserved. 65 This document is subject to BCP 78 and the IETF Trust's Legal 66 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 67 license-info) in effect on the date of publication of this document. 68 Please review these documents carefully, as they describe your rights 69 and restrictions with respect to this document. Code Components 70 extracted from this document must include Revised BSD License text as 71 described in Section 4.e of the Trust Legal Provisions and are 72 provided without warranty as described in the Revised BSD License. 74 Table of Contents 76 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 77 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 78 3. Requirements Language . . . . . . . . . . . . . . . . . . . . 5 79 4. Survey of Voucher Types . . . . . . . . . . . . . . . . . . . 5 80 5. Voucher Artifact . . . . . . . . . . . . . . . . . . . . . . 7 81 5.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 7 82 5.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8 83 5.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 9 84 5.3.1. "iana-voucher-assertion-type" Module . . . . . . . . 9 85 5.3.2. "ietf-voucher" Module . . . . . . . . . . . . . . . . 11 86 5.4. CMS Format Voucher Artifact . . . . . . . . . . . . . . . 15 87 6. Design Considerations . . . . . . . . . . . . . . . . . . . . 16 88 6.1. Renewals Instead of Revocations . . . . . . . . . . . . . 16 89 6.2. Voucher Per Pledge . . . . . . . . . . . . . . . . . . . 17 90 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 91 7.1. Clock Sensitivity . . . . . . . . . . . . . . . . . . . . 18 92 7.2. Protect Voucher PKI in HSM . . . . . . . . . . . . . . . 18 93 7.3. Test Domain Certificate Validity When Signing . . . . . . 18 94 7.4. YANG Module Security Considerations . . . . . . . . . . . 18 95 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 96 8.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 20 97 8.2. The YANG Module Names Registry . . . . . . . . . . . . . 20 98 8.3. The Media Types Registry . . . . . . . . . . . . . . . . 21 99 8.4. The SMI Security for S/MIME CMS Content Type Registry . . 22 100 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 101 9.1. Normative References . . . . . . . . . . . . . . . . . . 22 102 9.2. Informative References . . . . . . . . . . . . . . . . . 23 103 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 24 104 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 106 1. Introduction 108 This document defines a strategy to securely assign a candidate 109 device (pledge) to an owner using an artifact signed, directly or 110 indirectly, by the pledge's manufacturer, i.e., the Manufacturer 111 Authorized Signing Authority (MASA). This artifact is known as the 112 "voucher". 114 The voucher artifact is a JSON [RFC8259] document that conforms with 115 a data model described by YANG [RFC7950], is encoded using the rules 116 defined in [RFC8259], and is signed using (by default) a CMS 117 structure [RFC5652]. 119 The primary purpose of a voucher is to securely convey a certificate, 120 the "pinned-domain-cert", that a pledge can use to authenticate 121 subsequent interactions. A voucher may be useful in several 122 contexts, but the driving motivation herein is to support secure 123 bootstrapping mechanisms. Assigning ownership is important to 124 bootstrapping mechanisms so that the pledge can authenticate the 125 network that is trying to take control of it. 127 The lifetimes of vouchers may vary. In some bootstrapping protocols, 128 the vouchers may include a nonce restricting them to a single use, 129 whereas the vouchers in other bootstrapping protocols may have an 130 indicated lifetime. In order to support long lifetimes, this 131 document recommends using short lifetimes with programmatic renewal, 132 see Section 6.1. 134 This document only defines the voucher artifact, leaving it to other 135 documents to describe specialized protocols for accessing it. Some 136 bootstrapping protocols using the voucher artifact defined in this 137 document include: [ZERO-TOUCH], [SECUREJOIN], and [BRSKI]). 139 2. Terminology 141 This document uses the following terms: 143 Artifact: Used throughout to represent the voucher as instantiated 144 in the form of a signed structure. 146 Domain: The set of entities or infrastructure under common 147 administrative control. The goal of the bootstrapping protocol is 148 to enable a pledge to discover and join a domain. 150 Imprint: The process where a device obtains the cryptographic key 151 material to identify and trust future interactions with a network. 152 This term is taken from Konrad Lorenz's work in biology with new 153 ducklings: "during a critical period, the duckling would assume 154 that anything that looks like a mother duck is in fact their 155 mother" [Stajano99theresurrecting]. An equivalent for a device is 156 to obtain the fingerprint of the network's root certification 157 authority certificate. A device that imprints on an attacker 158 suffers a similar fate to a duckling that imprints on a hungry 159 wolf. Imprinting is a term from psychology and ethology, as 160 described in [imprinting]. 162 Join Registrar (and Coordinator): A representative of the domain 163 that is configured, perhaps autonomically, to decide whether a new 164 device is allowed to join the domain. The administrator of the 165 domain interfaces with a join registrar (and Coordinator) to 166 control this process. Typically, a join registrar is "inside" its 167 domain. For simplicity, this document often refers to this as 168 just "registrar". 170 MASA (Manufacturer Authorized Signing Authority): The entity that, 171 for the purpose of this document, signs the vouchers for a 172 manufacturer's pledges. In some bootstrapping protocols, the MASA 173 may have an Internet presence and be integral to the bootstrapping 174 process, whereas in other protocols the MASA may be an offline 175 service that has no active role in the bootstrapping process. 177 Owner: The entity that controls the private key of the "pinned- 178 domain-cert" certificate conveyed by the voucher. 180 Pledge: The prospective device attempting to find and securely join 181 a domain. When shipped, it only trusts authorized representatives 182 of the manufacturer. 184 Registrar: See join registrar. 186 TOFU (Trust on First Use): Where a pledge device makes no security 187 decisions but rather simply trusts the first domain entity it is 188 contacted by. Used similarly to [RFC7435]. This is also known as 189 the "resurrecting duckling" model. 191 Voucher: A signed statement from the MASA service that indicates to 192 a pledge the cryptographic identity of the domain it should trust. 194 3. Requirements Language 196 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 197 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 198 "OPTIONAL" in this document are to be interpreted as described in 199 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 200 capitals, as shown here. 202 4. Survey of Voucher Types 204 A voucher is a cryptographically protected statement to the pledge 205 device authorizing a zero-touch "imprint" on the join registrar of 206 the domain. The specific information a voucher provides is 207 influenced by the bootstrapping use case. 209 The voucher can impart the following information to the join 210 registrar and pledge: 212 Assertion Basis: Indicates the method that protects the imprint 213 (this is distinct from the voucher signature that protects the 214 voucher itself). This might include manufacturer-asserted 215 ownership verification, assured logging operations, or reliance on 216 pledge endpoint behavior such as secure root of trust of 217 measurement. The join registrar might use this information. Only 218 some methods are normatively defined in this document. Other 219 methods are left for future work. 221 Authentication of Join Registrar: Indicates how the pledge can 222 authenticate the join registrar. This document defines a 223 mechanism to pin the domain certificate. Pinning a symmetric key, 224 a raw key, or "CN-ID" or "DNS-ID" information (as defined in 225 [RFC6125]) is left for future work. 227 Anti-Replay Protections: Time- or nonce-based information to 228 constrain the voucher to time periods or bootstrap attempts. 230 A number of bootstrapping scenarios can be met using differing 231 combinations of this information. All scenarios address the primary 232 threat of a Man-in-The-Middle (MiTM) registrar gaining control over 233 the pledge device. The following combinations are "types" of 234 vouchers: 236 |Assertion |Registrar ID | Validity | 237 Voucher |Log-|Veri- |Trust |CN-ID or| RTC | Nonce | 238 Type | ged| fied |Anchor |DNS-ID | | | 239 ---------------------------------------------------------| 240 Audit | X | | X | | | X | 241 -------------|----|-------|-------|--------|-----|-------| 242 Nonceless | X | | X | | X | | 243 Audit | | | | | | | 244 -------------|----|-------|-------|--------|-----|-------| 245 Owner Audit | X | X | X | | X | X | 246 -------------|----|-------|-------|--------|-----|-------| 247 Owner ID | | X | X | X | X | | 248 -------------|----|-------|----------------|-----|-------| 249 Bearer | X | | wildcard | optional | 250 out-of-scope | | | | | 251 -------------|----|-------|----------------|-------------| 253 NOTE: All voucher types include a 'pledge ID serial-number' 254 (not shown here for space reasons). 256 Audit Voucher: An Audit Voucher is named after the logging assertion 257 mechanisms that the registrar then "audits" to enforce local 258 policy. The registrar mitigates a MiTM registrar by auditing that 259 an unknown MiTM registrar does not appear in the log entries. 260 This does not directly prevent the MiTM but provides a response 261 mechanism that ensures the MiTM is unsuccessful. The advantage is 262 that actual ownership knowledge is not required on the MASA 263 service. 265 Nonceless Audit Voucher: An Audit Voucher without a validity period 266 statement. Fundamentally, it is the same as an Audit Voucher 267 except that it can be issued in advance to support network 268 partitions or to provide a permanent voucher for remote 269 deployments. 271 Ownership Audit Voucher: An Audit Voucher where the MASA service has 272 verified the registrar as the authorized owner. The MASA service 273 mitigates a MiTM registrar by refusing to generate Audit Vouchers 274 for unauthorized registrars. The registrar uses audit techniques 275 to supplement the MASA. This provides an ideal sharing of policy 276 decisions and enforcement between the vendor and the owner. 278 Ownership ID Voucher: Named after inclusion of the pledge's CN-ID or 279 DNS-ID within the voucher. The MASA service mitigates a MiTM 280 registrar by identifying the specific registrar (via WebPKI) 281 authorized to own the pledge. 283 Bearer Voucher: A Bearer Voucher is named after the inclusion of a 284 registrar ID wildcard. Because the registrar identity is not 285 indicated, this voucher type must be treated as a secret and 286 protected from exposure as any 'bearer' of the voucher can claim 287 the pledge device. Publishing a nonceless bearer voucher 288 effectively turns the specified pledge into a "TOFU" device with 289 minimal mitigation against MiTM registrars. Bearer vouchers are 290 out of scope. 292 5. Voucher Artifact 294 The voucher's primary purpose is to securely assign a pledge to an 295 owner. The voucher informs the pledge which entity it should 296 consider to be its owner. 298 This document defines a voucher that is a JSON-encoded instance of 299 the YANG module defined in Section 5.3 that has been, by default, CMS 300 signed. 302 This format is described here as a practical basis for some uses 303 (such as in NETCONF), but more to clearly indicate what vouchers look 304 like in practice. This description also serves to validate the YANG 305 data model. 307 Future work is expected to define new mappings of the voucher to 308 Concise Binary Object Representation (CBOR) (from JSON) and to change 309 the signature container from CMS to JSON Object Signing and 310 Encryption (JOSE) or CBOR Object Signing and Encryption (COSE). XML 311 or ASN.1 formats are also conceivable. 313 This document defines a media type and a filename extension for the 314 CMS-encoded JSON type. Future documents on additional formats would 315 define additional media types. Signaling is in the form of a MIME 316 Content-Type, an HTTP Accept: header, or more mundane methods like 317 use of a filename extension when a voucher is transferred on a USB 318 key. 320 5.1. Tree Diagram 322 The following tree diagram illustrates a high-level view of a voucher 323 document. The notation used in this diagram is described in 324 [RFC8340]. Each node in the diagram is fully described by the YANG 325 module in Section 5.3. Please review the YANG module for a detailed 326 description of the voucher format. 328 module: ietf-voucher 330 grouping voucher-artifact-grouping 331 +-- voucher 332 +-- created-on yang:date-and-time 333 +-- expires-on? yang:date-and-time 334 +-- assertion ianavat:voucher-assertion 335 +-- serial-number string 336 +-- idevid-issuer? binary 337 +-- pinned-domain-cert binary 338 +-- domain-cert-revocation-checks? boolean 339 +-- nonce? binary 340 +-- last-renewal-date? yang:date-and-time 342 5.2. Examples 344 This section provides voucher examples for illustration purposes. 345 These examples conform to the encoding rules defined in [RFC8259]. 347 The following example illustrates an ephemeral voucher (uses a 348 nonce). The MASA generated this voucher using the 'logged' assertion 349 type, knowing that it would be suitable for the pledge making the 350 request. 352 { 353 "ietf-voucher:voucher": { 354 "created-on": "2016-10-07T19:31:42Z", 355 "assertion": "logged", 356 "serial-number": "JADA123456789", 357 "idevid-issuer": "base64encodedvalue==", 358 "pinned-domain-cert": "base64encodedvalue==", 359 "nonce": "base64encodedvalue==" 360 } 361 } 363 The following example illustrates a non-ephemeral voucher (no nonce). 364 While the voucher itself expires after two weeks, it presumably can 365 be renewed for up to a year. The MASA generated this voucher using 366 the 'verified' assertion type, which should satisfy all pledges. 368 { 369 "ietf-voucher:voucher": { 370 "created-on": "2016-10-07T19:31:42Z", 371 "expires-on": "2016-10-21T19:31:42Z", 372 "assertion": "verified", 373 "serial-number": "JADA123456789", 374 "idevid-issuer": "base64encodedvalue==", 375 "pinned-domain-cert": "base64encodedvalue==", 376 "domain-cert-revocation-checks": "true", 377 "last-renewal-date": "2017-10-07T19:31:42Z" 378 } 379 } 381 5.3. YANG Module 383 5.3.1. "iana-voucher-assertion-type" Module 385 Following is a YANG [RFC7950] module formally describing the 386 voucher's assertion type. 388 389 module iana-voucher-assertion-type { 390 namespace "urn:ietf:params:xml:ns:yang:iana-voucher-assertion-type"; 391 prefix ianavat; 393 organization 394 "IANA"; 395 contact 396 "Internet Assigned Numbers Authority 397 Postal: ICANN 398 12025 Waterfront Drive, Suite 300 399 Los Angeles, CA 90094-2536 400 United States of America 401 Tel: +1 310 301 5800 402 "; 403 description 404 "This YANG module defines a YANG enumeration type for IANA 405 -registered voucher assertion type. This YANG module is 406 maintained by IANA and reflects the 'voucher assertion types' 407 registry. The lastest revision of this YANG module can be 408 obtained from the IANA web site. Request for new enumerations 409 should be made to IANA via email(iana@iana.org). 411 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 412 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 413 'MAY', and 'OPTIONAL' in this document are to be interpreted as 414 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 415 they appear in all capitals, as shown here. 417 Copyright (c) 2018 IETF Trust and the persons identified as 418 authors of the code. All rights reserved. 420 Redistribution and use in source and binary forms, with or 421 without modification, is permitted pursuant to, and subject to 422 the license terms contained in, the Simplified BSD License set 423 forth in Section 4.c of the IETF Trust's Legal Provisions 424 Relating to IETF Documents 425 (https://trustee.ietf.org/license-info). 427 This version of this YANG module is part of RFC XXX; see the 428 RFC itself for full legal notices."; 430 revision 2021-07-04 { 431 description 432 "Initial version"; 433 reference "RFC XXXX: Voucher Artifact for Bootstrapping Protocols"; 434 } 436 typedef voucher-assertion { 437 type enumeration { 438 enum verified { 439 value 0; 440 description 441 "Indicates that the ownership has been positively verified 442 by the MASA (e.g., through sales channel integration)."; 443 } 444 enum logged { 445 value 1; 446 description 447 "Indicates that the voucher has been issued after 448 minimal verification of ownership or control. The 449 issuance has been logged for detection of 450 potential security issues (e.g., recipients of 451 vouchers might verify for themselves that unexpected 452 vouchers are not in the log). This is similar to 453 unsecured trust-on-first-use principles but with the 454 logging providing a basis for detecting unexpected 455 events."; 456 } 457 enum proximity { 458 value 2; 459 description 460 "Indicates that the voucher has been issued after 461 the MASA verified a proximity proof provided by the 462 device and target domain. The issuance has been logged 463 for detection of potential security issues. This is 464 stronger than just logging, because it requires some 465 verification that the pledge and owner are 466 in communication but is still dependent on analysis of 467 the logs to detect unexpected events."; 468 } 469 enum agent-proximity { 470 value 3; 471 description 472 "Indicates that the voucher has been issued after the 473 MASA...support of asynchronous enrollment in BRSKI"; 474 } 475 } 476 description "Indicates what kind of ownership is being asserted by voucher"; 477 } 478 } 479 481 5.3.2. "ietf-voucher" Module 483 The revised ietf-voucher YANG module imports the typedef defined in 484 "iana-voucher-assertion-type" YANG module specified in this document. 486 487 module ietf-voucher { 488 yang-version 1.1; 489 namespace "urn:ietf:params:xml:ns:yang:ietf-voucher"; 490 prefix vch; 492 import ietf-yang-types { 493 prefix yang; 494 reference "RFC 6991: Common YANG Data Types"; 495 } 496 import ietf-restconf { 497 prefix rc; 498 description 499 "This import statement is only present to access 500 the yang-data extension defined in RFC 8040."; 501 reference "RFC 8040: RESTCONF Protocol"; 502 } 504 import iana-voucher-assertion-type { 505 prefix ianavat; 506 reference "RFCZZZZ: Voucher Profile for Bootstrapping Protocols"; 507 } 509 organization 510 "IETF ANIMA Working Group"; 511 contact 512 "WG Web: 513 WG List: 514 Author: Kent Watsen 515 516 Author: Max Pritikin 517 518 Author: Michael Richardson 519 520 Author: Toerless Eckert 521 "; 522 description 523 "This module defines the format for a voucher, which is produced by 524 a pledge's manufacturer or delegate (MASA) to securely assign a 525 pledge to an 'owner', so that the pledge may establish a secure 526 connection to the owner's network infrastructure. 528 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 529 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 530 'MAY', and 'OPTIONAL' in this document are to be interpreted as 531 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, they 532 appear in all capitals, as shown here. 534 Copyright (c) 2018 IETF Trust and the persons identified as 535 authors of the code. All rights reserved. 537 Redistribution and use in source and binary forms, with or without 538 modification, is permitted pursuant to, and subject to the license 539 terms contained in, the Simplified BSD License set forth in Section 540 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents 541 (https://trustee.ietf.org/license-info). 543 This version of this YANG module is part of RFC 8366; see the RFC 544 itself for full legal notices."; 546 revision 2021-07-04 { 547 description 548 "updated to support new assertion enumerated type"; 549 reference "RFC ZZZZ Voucher Profile for Bootstrapping Protocols"; 550 } 552 // Top-level statement 553 rc:yang-data voucher-artifact { 554 uses voucher-artifact-grouping; 555 } 557 // Grouping defined for future augmentations 559 grouping voucher-artifact-grouping { 560 description 561 "Grouping to allow reuse/extensions in future work."; 562 container voucher { 563 description 564 "A voucher assigns a pledge to an owner (pinned-domain-cert)."; 565 leaf created-on { 566 type yang:date-and-time; 567 mandatory true; 568 description 569 "A value indicating the date this voucher was created. This 570 node is primarily for human consumption and auditing. Future 571 work MAY create verification requirements based on this 572 node."; 573 } 574 leaf expires-on { 575 type yang:date-and-time; 576 must 'not(../nonce)'; 577 description 578 "A value indicating when this voucher expires. The node is 579 optional as not all pledges support expirations, such as 580 pledges lacking a reliable clock. 582 If this field exists, then the pledges MUST ensure that 583 the expires-on time has not yet passed. A pledge without 584 an accurate clock cannot meet this requirement. 586 The expires-on value MUST NOT exceed the expiration date 587 of any of the listed 'pinned-domain-cert' certificates."; 588 } 589 leaf assertion { 590 type ianavat:voucher-assertion; 591 mandatory true; 592 description 593 "The assertion is a statement from the MASA regarding how 594 the owner was verified. This statement enables pledges 595 to support more detailed policy checks. Pledges MUST 596 ensure that the assertion provided is acceptable, per 597 local policy, before processing the voucher."; 598 } 599 leaf serial-number { 600 type string; 601 mandatory true; 602 description 603 "The serial-number of the hardware. When processing a 604 voucher, a pledge MUST ensure that its serial-number 605 matches this value. If no match occurs, then the 606 pledge MUST NOT process this voucher."; 607 } 608 leaf idevid-issuer { 609 type binary; 610 description 611 "The Authority Key Identifier OCTET STRING (as defined in 612 Section 4.2.1.1 of RFC 5280) from the pledge's IDevID 613 certificate. Optional since some serial-numbers are 614 already unique within the scope of a MASA. 615 Inclusion of the statistically unique key identifier 616 ensures statistically unique identification of the hardware. 617 When processing a voucher, a pledge MUST ensure that its 618 IDevID Authority Key Identifier matches this value. If no 619 match occurs, then the pledge MUST NOT process this voucher. 621 When issuing a voucher, the MASA MUST ensure that this field 622 is populated for serial-numbers that are not otherwise unique 623 within the scope of the MASA."; 624 } 625 leaf pinned-domain-cert { 626 type binary; 627 mandatory true; 628 description 629 "An X.509 v3 certificate structure, as specified by RFC 5280, 630 using Distinguished Encoding Rules (DER) encoding, as defined 631 in ITU-T X.690. 633 This certificate is used by a pledge to trust a Public Key 634 Infrastructure in order to verify a domain certificate 635 supplied to the pledge separately by the bootstrapping 636 protocol. The domain certificate MUST have this certificate 637 somewhere in its chain of certificates. This certificate 638 MAY be an end-entity certificate, including a self-signed 639 entity."; 640 reference 641 "RFC 5280: 642 Internet X.509 Public Key Infrastructure Certificate 643 and Certificate Revocation List (CRL) Profile. 644 ITU-T X.690: 645 Information technology - ASN.1 encoding rules: 646 Specification of Basic Encoding Rules (BER), 647 Canonical Encoding Rules (CER) and Distinguished 648 Encoding Rules (DER)."; 649 } 650 leaf domain-cert-revocation-checks { 651 type boolean; 652 description 653 "A processing instruction to the pledge that it MUST (true) 654 or MUST NOT (false) verify the revocation status for the 655 pinned domain certificate. If this field is not set, then 656 normal PKIX behavior applies to validation of the domain 657 certificate."; 658 } 659 leaf nonce { 660 type binary { 661 length "8..32"; 662 } 663 must 'not(../expires-on)'; 664 description 665 "A value that can be used by a pledge in some bootstrapping 666 protocols to enable anti-replay protection. This node is 667 optional because it is not used by all bootstrapping 668 protocols. 670 When present, the pledge MUST compare the provided nonce 671 value with another value that the pledge randomly generated 672 and sent to a bootstrap server in an earlier bootstrapping 673 message. If the values do not match, then the pledge MUST 674 NOT process this voucher."; 675 } 676 leaf last-renewal-date { 677 type yang:date-and-time; 678 must '../expires-on'; 679 description 680 "The date that the MASA projects to be the last date it 681 will renew a voucher on. This field is merely informative; it 682 is not processed by pledges. 684 Circumstances may occur after a voucher is generated that 685 may alter a voucher's validity period. For instance, a 686 vendor may associate validity periods with support contracts, 687 which may be terminated or extended over time."; 688 } 689 } // end voucher 690 } // end voucher-grouping 691 } 692 694 5.4. CMS Format Voucher Artifact 696 The IETF evolution of PKCS#7 is CMS [RFC5652]. A CMS-signed voucher, 697 the default type, contains a ContentInfo structure with the voucher 698 content. An eContentType of 40 indicates that the content is a JSON- 699 encoded voucher. 701 The signing structure is a CMS SignedData structure, as specified by 702 Section 5.1 of [RFC5652], encoded using ASN.1 Distinguished Encoding 703 Rules (DER), as specified in ITU-T X.690 [ITU-T.X690.2015]. 705 To facilitate interoperability, Section 8.3 in this document 706 registers the media type "application/voucher-cms+json" and the 707 filename extension ".vcj". 709 The CMS structure MUST contain a 'signerInfo' structure, as described 710 in Section 5.1 of [RFC5652], containing the signature generated over 711 the content using a private key trusted by the recipient. Normally, 712 the recipient is the pledge and the signer is the MASA. Another 713 possible use could be as a "signed voucher request" format 714 originating from the pledge or registrar toward the MASA. Within 715 this document, the signer is assumed to be the MASA. 717 Note that Section 5.1 of [RFC5652] includes a discussion about how to 718 validate a CMS object, which is really a PKCS7 object (cmsVersion=1). 719 Intermediate systems (such the Bootstrapping Remote Secure Key 720 Infrastructures [BRSKI] registrar) that might need to evaluate the 721 voucher in flight MUST be prepared for such an older format. No 722 signaling is necessary, as the manufacturer knows the capabilities of 723 the pledge and will use an appropriate format voucher for each 724 pledge. 726 The CMS structure SHOULD also contain all of the certificates leading 727 up to and including the signer's trust anchor certificate known to 728 the recipient. The inclusion of the trust anchor is unusual in many 729 applications, but third parties cannot accurately audit the 730 transaction without it. 732 The CMS structure MAY also contain revocation objects for any 733 intermediate certificate authorities (CAs) between the voucher issuer 734 and the trust anchor known to the recipient. However, the use of 735 CRLs and other validity mechanisms is discouraged, as the pledge is 736 unlikely to be able to perform online checks and is unlikely to have 737 a trusted clock source. As described below, the use of short-lived 738 vouchers and/or a pledge-provided nonce provides a freshness 739 guarantee. 741 6. Design Considerations 743 6.1. Renewals Instead of Revocations 745 The lifetimes of vouchers may vary. In some bootstrapping protocols, 746 the vouchers may be created and consumed immediately, whereas in 747 other bootstrapping solutions, there may be a significant time delay 748 between when a voucher is created and when it is consumed. In cases 749 when there is a time delay, there is a need for the pledge to ensure 750 that the assertions made when the voucher was created are still 751 valid. 753 A revocation artifact is generally used to verify the continued 754 validity of an assertion such as a PKIX certificate, web token, or a 755 "voucher". With this approach, a potentially long-lived assertion is 756 paired with a reasonably fresh revocation status check to ensure that 757 the assertion is still valid. However, this approach increases 758 solution complexity, as it introduces the need for additional 759 protocols and code paths to distribute and process the revocations. 761 Addressing the shortcomings of revocations, this document recommends 762 instead the use of lightweight renewals of short-lived non-revocable 763 vouchers. That is, rather than issue a long-lived voucher, where the 764 'expires-on' leaf is set to some distant date, the expectation is for 765 the MASA to instead issue a short-lived voucher, where the 'expires- 766 on' leaf is set to a relatively near date, along with a promise 767 (reflected in the 'last-renewal-date' field) to reissue the voucher 768 again when needed. Importantly, while issuing the initial voucher 769 may incur heavyweight verification checks ("Are you who you say you 770 are?" "Does the pledge actually belong to you?"), reissuing the 771 voucher should be a lightweight process, as it ostensibly only 772 updates the voucher's validity period. With this approach, there is 773 only the one artifact, and only one code path is needed to process 774 it; there is no possibility of a pledge choosing to skip the 775 revocation status check because, for instance, the OCSP Responder is 776 not reachable. 778 While this document recommends issuing short-lived vouchers, the 779 voucher artifact does not restrict the ability to create long-lived 780 voucher, if required; however, no revocation method is described. 782 Note that a voucher may be signed by a chain of intermediate CAs 783 leading up to the trust anchor certificate known by the pledge. Even 784 though the voucher itself is not revocable, it may still be revoked, 785 per se, if one of the intermediate CA certificates is revoked. 787 6.2. Voucher Per Pledge 789 The solution described herein originally enabled a single voucher to 790 apply to many pledges, using lists of regular expressions to 791 represent ranges of serial-numbers. However, it was determined that 792 blocking the renewal of a voucher that applied to many devices would 793 be excessive when only the ownership for a single pledge needed to be 794 blocked. Thus, the voucher format now only supports a single serial- 795 number to be listed. 797 7. Security Considerations 798 7.1. Clock Sensitivity 800 An attacker could use an expired voucher to gain control over a 801 device that has no understanding of time. The device cannot trust 802 NTP as a time reference, as an attacker could control the NTP stream. 804 There are three things to defend against this: 1) devices are 805 required to verify that the expires-on field has not yet passed, 2) 806 devices without access to time can use nonces to get ephemeral 807 vouchers, and 3) vouchers without expiration times may be used, which 808 will appear in the audit log, informing the security decision. 810 This document defines a voucher format that contains time values for 811 expirations, which require an accurate clock in order to be processed 812 correctly. Vendors planning on issuing vouchers with expiration 813 values must ensure that devices have an accurate clock when shipped 814 from manufacturing facilities and take steps to prevent clock 815 tampering. If it is not possible to ensure clock accuracy, then 816 vouchers with expirations should not be issued. 818 7.2. Protect Voucher PKI in HSM 820 Pursuant the recommendation made in Section 6.1 for the MASA to be 821 deployed as an online voucher signing service, it is RECOMMENDED that 822 the MASA's private key used for signing vouchers is protected by a 823 hardware security module (HSM). 825 7.3. Test Domain Certificate Validity When Signing 827 If a domain certificate is compromised, then any outstanding vouchers 828 for that domain could be used by the attacker. The domain 829 administrator is clearly expected to initiate revocation of any 830 domain identity certificates (as is normal in PKI solutions). 832 Similarly, they are expected to contact the MASA to indicate that an 833 outstanding (presumably short lifetime) voucher should be blocked 834 from automated renewal. Protocols for voucher distribution are 835 RECOMMENDED to check for revocation of domain identity certificates 836 before the signing of vouchers. 838 7.4. YANG Module Security Considerations 840 The YANG module specified in this document defines the schema for 841 data that is subsequently encapsulated by a CMS signed-data content 842 type, as described in Section 5 of [RFC5652]. As such, all of the 843 YANG modeled data is protected from modification. 845 Implementations should be aware that the signed data is only 846 protected from external modification; the data is still visible. 847 This potential disclosure of information doesn't affect security so 848 much as privacy. In particular, adversaries can glean information 849 such as which devices belong to which organizations and which CRL 850 Distribution Point and/or OCSP Responder URLs are accessed to 851 validate the vouchers. When privacy is important, the CMS signed- 852 data content type SHOULD be encrypted, either by conveying it via a 853 mutually authenticated secure transport protocol (e.g., TLS 854 [RFC5246]) or by encapsulating the signed-data content type with an 855 enveloped-data content type (Section 6 of [RFC5652]), though details 856 for how to do this are outside the scope of this document. 858 The use of YANG to define data structures, via the 'yang-data' 859 statement, is relatively new and distinct from the traditional use of 860 YANG to define an API accessed by network management protocols such 861 as NETCONF [RFC6241] and RESTCONF [RFC8040]. For this reason, these 862 guidelines do not follow template described by Section 3.7 of 863 [YANG-GUIDE]. 865 8. IANA Considerations 867 This section deals with actions and processes necessary for IANA to 868 undertake to maintain the "iana-voucher-assertion-type" YANG module. 869 The iana-voucher-assertion-type YANG module is intended to reflect 870 the "voucher assertion types" registry in [TBD]. 872 IANA is asked to create the "iana-voucher-assertion-type YANG module" 873 registry. 875 Voucher assertion types must not be directly added to the iana- 876 voucher-type YANG module. They must instead be added to the "voucher 877 assertion types" registry. 879 Whenever a new enumerated type is added to the "voucher assertion 880 types" registry, IANA must also update the "ietf-voucher-assertion- 881 type" YANG module and add a new "enum" statement to the "voucher- 882 assertion-type" type. The assigned name defined by the "enum" 883 statement SHALL be the same as the mnemonic name of the new assertion 884 type. The following substatements to the "enum" statement SHALL be 885 defined: 887 "value": Use the decimal value from the registry. 889 "status": Include only if a class or type registration has been 890 deprecated or obsoleted. IANA "deprecated" maps to YANG status 891 "deprecated", and IANA "obsolete" maps to YANG status 892 "obsolete". 894 "description": Replicate the corresponding information from the 895 registry, namely the full name of the new assertion type. 897 "reference": Replicate the reference(s) from the registry. 899 Each time the "iana-voucher-assertion-type" YANG module is updated, a 900 new "revision" statement SHALL be added before the existing 901 "revision" statements. IANA has added this note to the "voucher 902 assertion types" registries: 904 When this registry is modified, the YANG module "iana-voucher- 905 assertion-type" must be updated as defined in [RFCXXXX]. The 906 "Reference" text in the "voucher assertion types" registry has been 907 updated as follows: OLD: | [RFC8366] NEW: | [RFC8366][RFCXXX] 909 8.1. The IETF XML Registry 911 This document registers two URIs in the "IETF XML Registry" 912 [RFC3688]. 914 IANA has registered the following: 916 URI: urn:ietf:params:xml:ns:yang:ietf-voucher 917 Registrant Contact: The ANIMA WG of the IETF. 918 XML: N/A, the requested URI is an XML namespace. 920 IANA is asked to register a second URI as follows: 922 URI: urn:ietf:params:xml:ns:yang:iana-voucher-assertion-type 923 Registrant Contact: The ANIMA WG of the IETF. 924 XML: N/A, the requested URI is an XML namespace. 926 8.2. The YANG Module Names Registry 928 This document registers two YANG module in the "YANG Module Names" 929 registry [RFC6020]. 931 IANA is asked to registrar the following: 933 name: ietf-voucher 934 namespace: urn:ietf:params:xml:ns:yang:ietf-voucher 935 prefix: vch 937 reference: :RFC 8366 939 IANA is asked to register a second YANG module as follows: 941 name: iana-voucher-assertion-type 942 namespace: urn:ietf:params:xml:ns:yang:iana-voucher-assertion- 943 type 944 prefix: ianavat 945 reference: RFC XXXX 947 8.3. The Media Types Registry 949 This document requests IANA to update the following "Media Types" 950 entry to point to the RFC number that will be assigned to this 951 document: 953 Type name: application 955 Subtype name: voucher-cms+json 957 Required parameters: none 959 Optional parameters: none 961 Encoding considerations: CMS-signed JSON vouchers are ASN.1/DER 962 encoded. 964 Security considerations: See Section 7 966 Interoperability considerations: The format is designed to be 967 broadly interoperable. 969 Published specification: RFC 8366 971 Applications that use this media type: ANIMA, 6tisch, and NETCONF 972 zero-touch imprinting systems. 974 Fragment identifier considerations: none 976 Additional information: Deprecated alias names for this type: none 978 Magic number(s): None 980 File extension(s): .vcj 982 Macintosh file type code(s): none 984 Person and email address to contact for further information: IETF AN 985 IMA WG 987 Intended usage: LIMITED 989 Restrictions on usage: NONE 990 Author: ANIMA WG 992 Change controller: IETF 994 Provisional registration? (standards tree only): NO 996 8.4. The SMI Security for S/MIME CMS Content Type Registry 998 This document requests IANA to update this registered OID in the "SMI 999 Security for S/MIME CMS Content Type (1.2.840.113549.1.9.16.1)" 1000 registry to point to the RFC number to be assigned to this document: 1002 +=========+========================+============+ 1003 | Decimal | Description | References | 1004 +=========+========================+============+ 1005 | 40 | id-ct-animaJSONVoucher | RFC 8366 | 1006 +---------+------------------------+------------+ 1008 Table 1 1010 9. References 1012 9.1. Normative References 1014 [ITU-T.X690.2015] 1015 International Telecommunication Union, "Information 1016 Technology - ASN.1 encoding rules: Specification of Basic 1017 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1018 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1019 X.690, ISO/IEC 8825-1, August 2015, 1020 . 1022 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1023 Requirement Levels", BCP 14, RFC 2119, 1024 DOI 10.17487/RFC2119, March 1997, 1025 . 1027 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1028 RFC 5652, DOI 10.17487/RFC5652, September 2009, 1029 . 1031 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1032 the Network Configuration Protocol (NETCONF)", RFC 6020, 1033 DOI 10.17487/RFC6020, October 2010, 1034 . 1036 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1037 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1038 . 1040 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1041 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1042 May 2017, . 1044 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1045 Interchange Format", STD 90, RFC 8259, 1046 DOI 10.17487/RFC8259, December 2017, 1047 . 1049 9.2. Informative References 1051 [BRSKI] Pritikin, M., Richardson, M., Eckert, T., Behringer, M., 1052 and K. Watsen, "Bootstrapping Remote Secure Key 1053 Infrastructure (BRSKI)", RFC 8995, DOI 10.17487/RFC8995, 1054 May 2021, . 1056 [imprinting] 1057 Wikipedia, "Wikipedia article: Imprinting", February 2018, 1058 . 1061 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1062 DOI 10.17487/RFC3688, January 2004, 1063 . 1065 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1066 (TLS) Protocol Version 1.2", RFC 5246, 1067 DOI 10.17487/RFC5246, August 2008, 1068 . 1070 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1071 Verification of Domain-Based Application Service Identity 1072 within Internet Public Key Infrastructure Using X.509 1073 (PKIX) Certificates in the Context of Transport Layer 1074 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 1075 2011, . 1077 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1078 and A. Bierman, Ed., "Network Configuration Protocol 1079 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1080 . 1082 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1083 Specifications and Registration Procedures", BCP 13, 1084 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1085 . 1087 [RFC7435] Dukhovni, V., "Opportunistic Security: Some Protection 1088 Most of the Time", RFC 7435, DOI 10.17487/RFC7435, 1089 December 2014, . 1091 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1092 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1093 . 1095 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1096 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1097 . 1099 [SECUREJOIN] 1100 Richardson, M., "6tisch Secure Join protocol", Work in 1101 Progress, Internet-Draft, draft-ietf-6tisch-dtsecurity- 1102 secure-join-01, 25 February 2017, 1103 . 1106 [Stajano99theresurrecting] 1107 Stajano, F. and R. Anderson, "The Resurrecting Duckling: 1108 Security Issues for Ad-Hoc Wireless Networks", 1999, . 1112 [YANG-GUIDE] 1113 Bierman, A., "Guidelines for Authors and Reviewers of 1114 Documents Containing YANG Data Models", BCP 216, RFC 8407, 1115 DOI 10.17487/RFC8407, October 2018, 1116 . 1118 [ZERO-TOUCH] 1119 Watsen, K., Farrer, I., and M. Abrahamsson, "Secure Zero 1120 Touch Provisioning (SZTP)", RFC 8572, 1121 DOI 10.17487/RFC8572, April 2019, 1122 . 1124 Acknowledgements 1126 The authors would like to thank for following for lively discussions 1127 on list and in the halls (ordered by last name): William Atwood, 1128 Toerless Eckert, and Sheng Jiang. 1130 Russ Housley provided the upgrade from PKCS7 to CMS (RFC 5652) along 1131 with the detailed CMS structure diagram. 1133 Authors' Addresses 1135 Kent Watsen 1136 Juniper Networks 1138 Email: kwatsen@juniper.net 1140 Michael C. Richardson 1141 Sandelman Software 1143 Email: mcr+ietf@sandelman.ca 1144 URI: http://www.sandelman.ca/ 1146 Max Pritikin 1147 Cisco Systems 1149 Email: pritikin@cisco.com 1151 Toerless Eckert 1152 Futurewei Technologies Inc. 1153 2330 Central Expy 1154 Santa Clara, 95050 1155 United States of America 1157 Email: tte+ietf@cs.fau.de 1159 Qiufang Ma 1160 Huawei 1161 101 Software Avenue, Yuhua District 1162 Nanjing 1163 210012 1164 China 1166 Email: maqiufang1@huawei.com