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