RFC 8366
A Voucher Artifact for Bootstrapping Protocols
RFC 8366: A Voucher Artifact for Bootstrapping Protocols 🦋
okay bestie, let's dive into RFC 8366 💅 This one's a Standards Track doc from the IETF, published May 2018, with ISSN 2070-1721. The authors are K. Watsen (Juniper Networks), M. Richardson (Sandelman Software), M. Pritikin (Cisco Systems), and T. Eckert (Huawei) 🫶 It doesn't obsolete or update anything, since its title block doesn't list either.
Abstract ✨
okay so the big idea here is a way to securely hand a pledge (a brand-new device) over to its owner 🎀 The trick is an artifact that's signed, directly or indirectly, by the pledge's manufacturer. That artifact is called a "voucher" and it's basically the manufacturer's stamp of approval 💜
The voucher is defined as a YANG-defined JSON document that's been signed using a Cryptographic Message Syntax (CMS) structure. other YANG-derived formats are possible too 🌈 The voucher is normally generated by the manufacturer, which is the Manufacturer Authorized Signing Authority (MASA) 👑
This doc only defines the voucher artifact itself. Other documents get to decide how the specialized protocols for accessing it work 💖
Status of This Memo
This is an Internet Standards Track document 🌸
It's a product of the Internet Engineering Task Force (IETF), so it represents the consensus of the IETF community. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). More info on Internet Standards is in Section 2 of RFC 7841 ✨
For the current status, any errata, and how to send feedback, check out https://www.rfc-editor.org/info/rfc8366 🦋
Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved 💅
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as in effect on the date of publication. Please actually read these, bestie, because they spell out your rights and restrictions for this document 🙈 Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they're provided without warranty as described in the Simplified BSD License ⭐
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Requirements Language . . . . . . . . . . . . . . . . . . . . 5
4. Survey of Voucher Types . . . . . . . . . . . . . . . . . . . 5
5. Voucher Artifact . . . . . . . . . . . . . . . . . . . . . . 7
5.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 8
5.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8
5.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 9
5.4. CMS Format Voucher Artifact . . . . . . . . . . . . . . . 15
6. Design Considerations . . . . . . . . . . . . . . . . . . . . 16
6.1. Renewals Instead of Revocations . . . . . . . . . . . . . 16
6.2. Voucher Per Pledge . . . . . . . . . . . . . . . . . . . 17
7. Security Considerations . . . . . . . . . . . . . . . . . . . 17
7.1. Clock Sensitivity . . . . . . . . . . . . . . . . . . . . 17
7.2. Protect Voucher PKI in HSM . . . . . . . . . . . . . . . 17
7.3. Test Domain Certificate Validity When Signing . . . . . . 17
7.4. YANG Module Security Considerations . . . . . . . . . . . 18
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18
8.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 18
8.2. The YANG Module Names Registry . . . . . . . . . . . . . 19
8.3. The Media Types Registry . . . . . . . . . . . . . . . . 19
8.4. The SMI Security for S/MIME CMS Content Type Registry . . 20
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 20
9.1. Normative References . . . . . . . . . . . . . . . . . . 20
9.2. Informative References . . . . . . . . . . . . . . . . . 21
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 23
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 231. Introduction ✨
okay so this doc defines a way to securely assign a candidate device (the pledge) to an owner 🎀 The assignment uses an artifact signed, directly or indirectly, by the pledge's manufacturer, which is the Manufacturer Authorized Signing Authority (MASA). That artifact is the "voucher" 💜
The voucher is a JSON [RFC8259] document. It follows a data model described in YANG [RFC7950], it's encoded using the rules in [RFC8259], and it's signed using (by default) a CMS structure [RFC5652] 🌸
The main job of a voucher is to securely carry a certificate, the "pinned-domain-cert", that the pledge can use to authenticate later interactions 🫶 Vouchers could be handy in plenty of contexts, but the real reason they exist here is to support secure bootstrapping mechanisms. Assigning ownership matters for bootstrapping because it lets the pledge authenticate the network that's trying to take control of it 🔥
Voucher lifetimes can vary 🦋 Some bootstrapping protocols might have the voucher include a nonce that limits it to a single use, while others give a voucher an indicated lifetime instead. To support long lifetimes, this document recommends using short lifetimes with programmatic renewal. See Section 6.1 for more on that 💖
Like the abstract said, this doc only defines the voucher artifact, and it leaves the specialized protocols for accessing it to other documents. A few bootstrapping protocols that use this voucher artifact are: [ZERO-TOUCH], [SECUREJOIN], and [KEYINFRA]) 🍓
2. Terminology
okay here are the terms this doc uses, and they're all important 🧚
Artifact: This is the voucher as it shows up in the form of a signed structure. It's used all throughout the doc ✨
Domain: This is the set of entities or infrastructure under common administrative control. The bootstrapping protocol's goal is to help a pledge discover and join a domain 🏰
Imprint: This is the process where a device gets the cryptographic key material it needs to identify and trust future interactions with a network 🦆 The term comes from Konrad Lorenz's work in biology with new ducklings: "during a critical period, the duckling would assume that anything that looks like a mother duck is in fact their mother" [Stajano99theresurrecting]. For a device, the equivalent is getting the fingerprint of the network's root certification authority certificate. A device that imprints on an attacker suffers a similar fate to a duckling that imprints on a hungry wolf 🐺 Imprinting is a term from psychology and ethology, as described in [imprinting] 🙈
Join Registrar (and Coordinator): This is a representative of the domain that's configured, maybe autonomically, to decide whether a new device is allowed to join the domain 🎀 The domain's administrator works with a join registrar (and Coordinator) to control this process. A join registrar is typically "inside" its domain. To keep things simple, this doc often just calls it the "registrar" 💅
MASA (Manufacturer Authorized Signing Authority): This is the entity that, for this document's purposes, signs the vouchers for a manufacturer's pledges 👑 In some bootstrapping protocols the MASA may have an Internet presence and be part of the bootstrapping process. In others, the MASA may be an offline service with no active role in bootstrapping 🌙
Owner: This is the entity that controls the private key of the "pinned-domain-cert" certificate that the voucher carries 🔑
Pledge: This is the prospective device trying to find and securely join a domain. When it ships, it only trusts authorized representatives of the manufacturer 📦
Registrar: See join registrar 💫
TOFU (Trust on First Use): This is where a pledge device makes no security decisions and just trusts the first domain entity it gets contacted by. It's used similarly to [RFC7435], and it's also known as the "resurrecting duckling" model 🦆💜
Voucher: This is a signed statement from the MASA service that tells a pledge which cryptographic identity of the domain it should trust 🌈
3. Requirements Language
okay bestie, this part is the official BCP 14 vibe check 🧐 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 💖
4. Survey of Voucher Types 💅
okay so a voucher is a cryptographically protected statement sent to the pledge device that authorizes a zero-touch "imprint" on the join registrar of the domain 🔐✨ bestie, what info a voucher carries depends on the bootstrapping use case, so it's giving customizable 🎀
The voucher can share the following info with the join registrar and the pledge 🫶
Assertion Basis: this tells you the method that protects the imprint (this is different from the voucher signature, which protects the voucher itself) 🦋 it could be things like manufacturer-asserted ownership verification, assured logging operations, or relying on pledge endpoint behavior such as a secure root of trust of measurement 🧚 the join registrar might use this info. Only some methods are normatively defined in this document, and the other methods are left for future work 🔮
Authentication of Join Registrar: this shows how the pledge can authenticate the join registrar 🔑 this document defines a mechanism to pin the domain certificate 💖 pinning a symmetric key, a raw key, or "CN-ID" or "DNS-ID" info (as defined in [RFC6125]) is left for future work 🌸
Anti-Replay Protections: time-based or nonce-based info that limits the voucher to certain time periods or bootstrap attempts ⏰
A bunch of bootstrapping scenarios can be covered by mixing and matching this info 🌈 every scenario is trying to stop the main threat, which is a Man-in-The-Middle (MiTM) registrar taking control of the pledge device 😭 the following combos are the "types" of vouchers 👑
|Assertion |Registrar ID | Validity |
Voucher |Log-|Veri- |Trust |CN-ID or| RTC | Nonce |
Type | ged| fied |Anchor |DNS-ID | | |
---------------------------------------------------------|
Audit | X | | X | | | X |
----------|----|-------|-------|--------|-----|-------|
Nonceless | X | | X | | X | |
Audit | | | | | | |
----------|----|-------|-------|--------|-----|-------|
Owner | X | X | X | | X | X |
Audit | | | | | | |
----------|----|-------|-------|--------|-----|-------|
Owner ID | | X | X | X | X | |
----------|----|-------|----------------|-----|-------|
Bearer | X | | wildcard | optional |
out-of- | | | | |
scope | | | | |
----------|----|-------|----------------|-------------|NOTE: All voucher types include a 'pledge ID serial-number' (not shown here for space reasons). 🙈
Audit Voucher: this one is named after the logging assertion mechanisms that the registrar then "audits" to enforce local policy 📋 the registrar handles a MiTM registrar by auditing that an unknown MiTM registrar does not show up in the log entries 🕵️♀️ this doesn't directly stop the MiTM, but it gives a response mechanism that makes sure the MiTM fails 💀 the big perk is that actual ownership knowledge is not needed on the MASA service 🙌
Nonceless Audit Voucher: an Audit Voucher without a validity period statement 🫠 basically it's the same as an Audit Voucher, except it can be issued in advance to support network partitions or to give a permanent voucher for remote deployments 🏝️
Ownership Audit Voucher: an Audit Voucher where the MASA service has verified the registrar as the authorized owner 🪪 the MASA service handles a MiTM registrar by refusing to generate Audit Vouchers for unauthorized registrars 🚫 the registrar uses audit techniques to back up the MASA, which is an ideal split of policy decisions and enforcement between the vendor and the owner 🤝 so iconic 😤
Ownership ID Voucher: named after including the pledge's CN-ID or DNS-ID inside the voucher 📛 the MASA service handles a MiTM registrar by identifying the specific registrar (via WebPKI) that's authorized to own the pledge 🎯
Bearer Voucher: named after including a registrar ID wildcard ✨ since the registrar identity isn't indicated, this voucher type must be treated as a secret and protected from exposure, because any 'bearer' of the voucher can claim the pledge device 🫣 publishing a nonceless bearer voucher effectively turns the specified pledge into a "TOFU" device with minimal mitigation against MiTM registrars 💔 bearer vouchers are out of scope 🚧
5. Voucher Artifact 🎀
the voucher's main job is to securely assign a pledge to an owner 💖 the voucher tells the pledge which entity it should consider to be its owner 👑
this document defines a voucher that's a JSON-encoded instance of the YANG module defined in Section 5.3, which has been, by default, CMS signed 📦
this format is described here as a practical basis for some uses (such as in NETCONF), but more to clearly indicate what vouchers look like in practice 🧚 this description also helps validate the YANG data model ✅
future work is expected to define new mappings of the voucher to Concise Binary Object Representation (CBOR) (from JSON), and to swap the signature container from CMS to JSON Object Signing and Encryption (JOSE) or CBOR Object Signing and Encryption (COSE) 🔄 XML or ASN.1 formats are also conceivable 🌸
this document defines a media type and a filename extension for the CMS-encoded JSON type 🏷️ future documents on additional formats would define additional media types 📚 signaling happens with a MIME Content-Type, an HTTP Accept: header, or more mundane methods like using a filename extension when a voucher is transferred on a USB key 🔌 lowkey iconic 🥹
5.1. Tree Diagram 🌳
the following tree diagram gives a high-level view of a voucher document 🍓 the notation used in this diagram is described in [RFC8340] 📖 each node in the diagram is fully described by the YANG module in Section 5.3, so please review the YANG module for a detailed description of the voucher format 🫶
module: ietf-voucher
yang-data voucher-artifact:
+---- voucher
+---- created-on yang:date-and-time
+---- expires-on? yang:date-and-time
+---- assertion enumeration
+---- serial-number string
+---- idevid-issuer? binary
+---- pinned-domain-cert binary
+---- domain-cert-revocation-checks? boolean
+---- nonce? binary
+---- last-renewal-date? yang:date-and-time5.2. Examples 🧁
this section has voucher examples for illustration purposes 🎨 these examples follow the encoding rules defined in [RFC8259] 🤓
the first example is an ephemeral voucher (it uses a nonce) ⏳ the MASA generated this voucher using the 'logged' assertion type, knowing it would be suitable for the pledge making the request 🦋
{
"ietf-voucher:voucher": {
"created-on": "2016-10-07T19:31:42Z",
"assertion": "logged",
"serial-number": "JADA123456789",
"idevid-issuer": "base64encodedvalue==",
"pinned-domain-cert": "base64encodedvalue==",
"nonce": "base64encodedvalue=="
}
}the second example is a non-ephemeral voucher (no nonce) 🌈 while the voucher itself expires after two weeks, it presumably can be renewed for up to a year 📅 the MASA generated this voucher using the 'verified' assertion type, which should satisfy all pledges 💅
{
"ietf-voucher:voucher": {
"created-on": "2016-10-07T19:31:42Z",
"expires-on": "2016-10-21T19:31:42Z",
"assertion": "verified",
"serial-number": "JADA123456789",
"idevid-issuer": "base64encodedvalue==",
"pinned-domain-cert": "base64encodedvalue==",
"domain-cert-revocation-checks": "true",
"last-renewal-date": "2017-10-07T19:31:42Z"
}
}5.3. YANG Module 🧠
next up is a YANG [RFC7950] module that formally describes the voucher's JSON document structure 🛠️ it's the blueprint, bestie 📐
<CODE BEGINS> file "ietf-voucher@2018-05-09.yang"module ietf-voucher {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-voucher";
prefix vch;
import ietf-yang-types {
prefix yang;
reference "RFC 6991: Common YANG Data Types";
}
import ietf-restconf {
prefix rc;
description
"This import statement is only present to access
the yang-data extension defined in RFC 8040.";
reference "RFC 8040: RESTCONF Protocol";
}
organization
"IETF ANIMA Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/anima/>
WG List: <mailto:anima@ietf.org>
Author: Kent Watsen
<mailto:kwatsen@juniper.net>
Author: Max Pritikin
<mailto:pritikin@cisco.com>
Author: Michael Richardson
<mailto:mcr+ietf@sandelman.ca>
Author: Toerless Eckert
<mailto:tte+ietf@cs.fau.de>";
description
"This module defines the format for a voucher, which is produced by
a pledge's manufacturer or delegate (MASA) to securely assign a
pledge to an 'owner', so that the pledge may establish a secure
connection to the owner's network infrastructure.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
'MAY', and 'OPTIONAL' in this document are to be interpreted as
described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, they
appear in all capitals, as shown here.
Copyright (c) 2018 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, is permitted pursuant to, and subject to the license
terms contained in, the Simplified BSD License set forth in Section
4.c of the IETF Trust's Legal Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC 8366; see the RFC
itself for full legal notices.";
revision 2018-05-09 {
description
"Initial version";
reference "RFC 8366: Voucher Profile for Bootstrapping Protocols";
}
// Top-level statement
rc:yang-data voucher-artifact {
uses voucher-artifact-grouping;
}
// Grouping defined for future augmentations
grouping voucher-artifact-grouping {
description
"Grouping to allow reuse/extensions in future work.";
container voucher {
description
"A voucher assigns a pledge to an owner (pinned-domain-cert).";
leaf created-on {
type yang:date-and-time;
mandatory true;
description
"A value indicating the date this voucher was created. This
node is primarily for human consumption and auditing. Future
work MAY create verification requirements based on this
node.";
}
leaf expires-on {
type yang:date-and-time;
must 'not(../nonce)';
description
"A value indicating when this voucher expires. The node is
optional as not all pledges support expirations, such as
pledges lacking a reliable clock.
If this field exists, then the pledges MUST ensure that
the expires-on time has not yet passed. A pledge without
an accurate clock cannot meet this requirement.
The expires-on value MUST NOT exceed the expiration date
of any of the listed 'pinned-domain-cert' certificates.";
}
leaf assertion {
type enumeration {
enum verified {
description
"Indicates that the ownership has been positively
verified by the MASA (e.g., through sales channel
integration).";
}
enum logged {
description
"Indicates that the voucher has been issued after
minimal verification of ownership or control. The
issuance has been logged for detection of
potential security issues (e.g., recipients of
vouchers might verify for themselves that unexpected
vouchers are not in the log). This is similar to
unsecured trust-on-first-use principles but with the
logging providing a basis for detecting unexpected
events.";
}
enum proximity {
description
"Indicates that the voucher has been issued after
the MASA verified a proximity proof provided by the
device and target domain. The issuance has been logged
for detection of potential security issues. This is
stronger than just logging, because it requires some
verification that the pledge and owner are
in communication but is still dependent on analysis of
the logs to detect unexpected events.";
}
}
mandatory true;
description
"The assertion is a statement from the MASA regarding how
the owner was verified. This statement enables pledges
to support more detailed policy checks. Pledges MUST
ensure that the assertion provided is acceptable, per
local policy, before processing the voucher.";
}
leaf serial-number {
type string;
mandatory true;
description
"The serial-number of the hardware. When processing a
voucher, a pledge MUST ensure that its serial-number
matches this value. If no match occurs, then the
pledge MUST NOT process this voucher.";
}
leaf idevid-issuer {
type binary;
description
"The Authority Key Identifier OCTET STRING (as defined in
Section 4.2.1.1 of RFC 5280) from the pledge's IDevID
certificate. Optional since some serial-numbers are
already unique within the scope of a MASA.
Inclusion of the statistically unique key identifier
ensures statistically unique identification of the hardware.
When processing a voucher, a pledge MUST ensure that its
IDevID Authority Key Identifier matches this value. If no
match occurs, then the pledge MUST NOT process this voucher.
When issuing a voucher, the MASA MUST ensure that this field
is populated for serial-numbers that are not otherwise unique
within the scope of the MASA.";
}
leaf pinned-domain-cert {
type binary;
mandatory true;
description
"An X.509 v3 certificate structure, as specified by RFC 5280,
using Distinguished Encoding Rules (DER) encoding, as defined
in ITU-T X.690.
This certificate is used by a pledge to trust a Public Key
Infrastructure in order to verify a domain certificate
supplied to the pledge separately by the bootstrapping
protocol. The domain certificate MUST have this certificate
somewhere in its chain of certificates. This certificate
MAY be an end-entity certificate, including a self-signed
entity.";
reference
"RFC 5280:
Internet X.509 Public Key Infrastructure Certificate
and Certificate Revocation List (CRL) Profile.
ITU-T X.690:
Information technology - ASN.1 encoding rules:
Specification of Basic Encoding Rules (BER),
Canonical Encoding Rules (CER) and Distinguished
Encoding Rules (DER).";
}
leaf domain-cert-revocation-checks {
type boolean;
description
"A processing instruction to the pledge that it MUST (true)
or MUST NOT (false) verify the revocation status for the
pinned domain certificate. If this field is not set, then
normal PKIX behavior applies to validation of the domain
certificate.";
}
leaf nonce {
type binary {
length "8..32";
}
must 'not(../expires-on)';
description
"A value that can be used by a pledge in some bootstrapping
protocols to enable anti-replay protection. This node is
optional because it is not used by all bootstrapping
protocols.
When present, the pledge MUST compare the provided nonce
value with another value that the pledge randomly generated
and sent to a bootstrap server in an earlier bootstrapping
message. If the values do not match, then the pledge MUST
NOT process this voucher.";
}
leaf last-renewal-date {
type yang:date-and-time;
must '../expires-on';
description
"The date that the MASA projects to be the last date it
will renew a voucher on. This field is merely informative;
it is not processed by pledges.
Circumstances may occur after a voucher is generated that
may alter a voucher's validity period. For instance, a
vendor may associate validity periods with support contracts,
which may be terminated or extended over time.";
}
} // end voucher
} // end voucher-grouping
}
<CODE ENDS>5.4. CMS Format Voucher Artifact ✨
Okay so the IETF's glow-up of PKCS#7 is CMS [RFC5652] 💅. A CMS-signed voucher is the default flavour, and it wraps the voucher content inside a ContentInfo structure. An eContentType of 40 tells you the content is a JSON-encoded voucher 🎀.
The signing wrapper is a CMS SignedData structure, as specified in Section 5.1 of [RFC5652], and it's encoded using ASN.1 Distinguished Encoding Rules (DER), as specified in ITU-T X.690 [ITU.X690.2015] 🧁.
To keep things interoperable, Section 8.3 in this document registers the media type application/voucher-cms+json and the filename extension .vcj 🦋.
The CMS structure MUST contain a signerInfo structure, as described in Section 5.1 of [RFC5652], holding the signature that's generated over the content with a private key the recipient trusts 🔐. Normally the recipient is the pledge and the signer is the MASA. Another possible use is as a "signed voucher request" format that goes from the pledge or registrar to the MASA. In this document, the signer is assumed to be the MASA 👑.
Heads up, bestie 👀: Section 5.1 of [RFC5652] talks about validating a CMS object, which is really a PKCS7 object (cmsVersion=1). Intermediate systems (like the Bootstrapping Remote Secure Key Infrastructures (BRSKI) registrar) that might need to peek at the voucher in flight MUST be prepared for that older format. No signaling needed, because the manufacturer knows what the pledge can do and picks a suitable format voucher for each pledge 💖.
The CMS structure SHOULD also carry all the certificates leading up to and including the signer's trust anchor certificate that the recipient knows about. Including the trust anchor is unusual in lots of apps, but third parties can't accurately audit the transaction without it 🧐.
The CMS structure MAY also contain revocation objects for any intermediate certificate authorities (CAs) between the voucher issuer and the trust anchor the recipient knows. However, using CRLs and other validity mechanisms is discouraged 🙅♀️, because the pledge is unlikely to be able to do online checks and is unlikely to have a trusted clock source. As described below, short-lived vouchers and/or a pledge-provided nonce give you a freshness guarantee ⏰✨.
6. Design Considerations ✨
6.1. Renewals Instead of Revocations 🔄
okay so voucher lifetimes are not all the same, bestie 🌸 In some bootstrapping protocols, the voucher gets created and used basically right away. In others, there can be a huge gap between when it's made and when it's consumed. When there's a time gap, the pledge needs a way to make sure the stuff the voucher claimed when it was created is still true 🧐
A revocation artifact is usually how we check that a long-lived assertion is still valid, like a PKIX certificate, a web token, or a "voucher." You pair the potentially long-lived assertion with a fairly fresh revocation status check. That works, but it makes the whole solution way more complicated, because now you need extra protocols and code paths just to distribute and process the revocations 😩
So this document suggests a different vibe: lightweight renewals of short-lived, non-revocable vouchers ✨ Instead of issuing a long-lived voucher with expires-on set to some far-off date, the MASA is expected to issue a short-lived voucher where expires-on is set to a fairly near date. It also comes with a promise, reflected in the last-renewal-date field, to reissue the voucher when needed. The key thing is that issuing the initial voucher can involve heavyweight verification checks ("Are you who you say you are?" "Does the pledge actually belong to you?"), but reissuing it should be lightweight, since it's basically just updating the voucher's validity period 💖 That means there's only one artifact, only one code path to process it, and no chance of a pledge skipping the revocation status check just because, say, the OCSP Responder isn't reachable 🙅♀️
Even though this document recommends short-lived vouchers, the voucher artifact doesn't stop you from creating a long-lived voucher if you really need one 🦋 Just know that no revocation method is described for that case.
Also, a voucher may be signed by a chain of intermediate CAs leading up to the trust anchor certificate the pledge knows about. The voucher itself isn't revocable, but it can still be revoked, per se, if one of those intermediate CA certificates gets revoked 🌈
6.2. Voucher Per Pledge 🎀
The solution originally let a single voucher apply to lots of pledges, using lists of regular expressions to represent ranges of serial-numbers 🍓 But then it was decided that blocking the renewal of a voucher that covered many devices was overkill when only one pledge's ownership needed blocking. So now the voucher format only supports listing a single serial-number 💅
7. Security Considerations 🚨
7.1. Clock Sensitivity ⏰
Okay, this one is serious bestie 😭 An attacker could use an expired voucher to take control of a device that has no understanding of time. The device can't trust NTP as a time reference, because an attacker could control the NTP stream.
There are three things to defend against: 1) devices are required to verify that the expires-on field has not yet passed, 2) devices without access to time can use nonces to get ephemeral vouchers, and 3) vouchers without expiration times may be used, which will show up in the audit log and inform the security decision.
This document defines a voucher format that contains time values for expirations, and those need an accurate clock to be processed correctly ⏳ Vendors planning to issue vouchers with expiration values need to make sure devices have an accurate clock when they ship from manufacturing facilities, and take steps to prevent clock tampering. If it isn't possible to ensure clock accuracy, then vouchers with expirations should not be issued.
7.2. Protect Voucher PKI in HSM 🔐
Following the recommendation in Section 6.1 that the MASA be deployed as an online voucher signing service, it is RECOMMENDED that the MASA's private key used for signing vouchers is protected by a hardware security module (HSM) 🛡️
7.3. Test Domain Certificate Validity When Signing 🕵️
If a domain certificate gets compromised, then any outstanding vouchers for that domain could be used by the attacker 😱 The domain administrator is clearly expected to initiate revocation of any domain identity certificates (as is normal in PKI solutions).
Similarly, they are expected to contact the MASA to indicate that an outstanding (presumably short lifetime) voucher should be blocked from automated renewal. Protocols for voucher distribution are RECOMMENDED to check for revocation of domain identity certificates before the signing of vouchers 💜
7.4. YANG Module Security Considerations 🧁
The YANG module specified in this document defines the schema for data that then gets encapsulated by a CMS signed-data content type, as described in Section 5 of [RFC5652]. So all of the YANG modeled data is protected from modification 🙌
Implementations should be aware that the signed data is only protected from external modification. The data is still visible! This potential disclosure of information doesn't affect security so much as privacy 👀 In particular, adversaries can glean information such as which devices belong to which organizations, and which CRL Distribution Point and/or OCSP Responder URLs are accessed to validate the vouchers. When privacy matters, the CMS signed-data content type SHOULD be encrypted, either by conveying it via a mutually authenticated secure transport protocol (e.g., TLS [RFC5246]) or by encapsulating the signed-data content type with an enveloped-data content type (Section 6 of [RFC5652]). Details for how to do this are outside the scope of this document 🤫
The use of YANG to define data structures, via the 'yang-data' statement, is relatively new and different from the traditional use of YANG to define an API accessed by network management protocols such as NETCONF [RFC6241] and RESTCONF [RFC8040]. For this reason, these guidelines don't follow the template described by Section 3.7 of [YANG-GUIDE] 🧚
8. IANA Considerations 🌷
8.1. The IETF XML Registry 📇
This document registers a URI in the "IETF XML Registry" [RFC3688]. IANA has registered the following:
URI: urn:ietf:params:xml:ns:yang:ietf-voucher
Registrant Contact: The ANIMA WG of the IETF.
XML: N/A, the requested URI is an XML namespace.8.2. The YANG Module Names Registry 🗂️
This document registers a YANG module in the "YANG Module Names" registry [RFC6020]. IANA has registered the following:
name: ietf-voucher
namespace: urn:ietf:params:xml:ns:yang:ietf-voucher
prefix: vch
reference: RFC 83668.3. The Media Types Registry 🦄
This document registers a new media type in the "Media Types" registry [RFC6838]. IANA has registered the following:
Type name: application
Subtype name: voucher-cms+json
Required parameters: none
Optional parameters: none
Encoding considerations: CMS-signed JSON vouchers are ASN.1/DER
encoded.
Security considerations: See Section 7
Interoperability considerations: The format is designed to be
broadly interoperable.
Published specification: RFC 8366
Applications that use this media type: ANIMA, 6tisch, and NETCONF
zero-touch imprinting systems.
Fragment identifier considerations: none
Additional information:
Deprecated alias names for this type: none
Magic number(s): None
File extension(s): .vcj
Macintosh file type code(s): none
Person and email address to contact for further information:
IETF ANIMA WG
Intended usage: LIMITED
Restrictions on usage: NONE
Author: ANIMA WG
Change controller: IETF
Provisional registration? (standards tree only): NO8.4. The SMI Security for S/MIME CMS Content Type Registry 🏷️
IANA has registered the following OID in the "SMI Security for S/MIME CMS Content Type (1.2.840.113549.1.9.16.1)" registry:
Decimal Description References
------- -------------------------------------- ----------
40 id-ct-animaJSONVoucher RFC 83669. References 📚
9.1. Normative References 🧠
[ITU.X690.2015]
International Telecommunication Union, "Information
Technology - ASN.1 encoding rules: Specification of
Basic Encoding Rules (BER), Canonical Encoding Rules
(CER) and Distinguished Encoding Rules (DER)", ITU-T
Recommendation X.690, ISO/IEC 8825-1, August 2015,
<https://www.itu.int/rec/T-REC-X.690/>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)",
STD 70, RFC 5652, DOI 10.17487/RFC5652, September 2009,
<https://www.rfc-editor.org/info/rfc5652>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020,
DOI 10.17487/RFC6020, October 2010,
<https://www.rfc-editor.org/info/rfc6020>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling
Language", RFC 7950, DOI 10.17487/RFC7950, August 2016,
<https://www.rfc-editor.org/info/rfc7950>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON)
Data Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>.9.2. Informative References 📚
Okay, now the bonus reading list 🤓 These are the extra sources the spec points to, and they're all useful if you want the full story. The citations are copied exactly, so you can look up every one.
[imprinting] Wikipedia, "Wikipedia article: Imprinting", February
2018, <https://en.wikipedia.org/w/index.php?title=
Imprinting_(psychology)&oldid=825757556>.
[KEYINFRA] Pritikin, M., Richardson, M., Behringer, M., Bjarnason,
S., and K. Watsen, "Bootstrapping Remote Secure Key
Infrastructures (BRSKI)", Work in Progress,
draft-ietf-anima-bootstrapping-keyinfra-12, March 2018.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
DOI 10.17487/RFC3688, January 2004,
<https://www.rfc-editor.org/info/rfc3688>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer
Security (TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC5246, August 2008,
<https://www.rfc-editor.org/info/rfc5246>.
[RFC6125] Saint-Andre, P. and J. Hodges, "Representation and
Verification of Domain-Based Application Service
Identity within Internet Public Key Infrastructure Using
X.509 (PKIX) Certificates in the Context of Transport
Layer Security (TLS)", RFC 6125, DOI 10.17487/RFC6125,
March 2011, <https://www.rfc-editor.org/info/rfc6125>.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J.,
Ed., and A. Bierman, Ed., "Network Configuration
Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241,
June 2011, <https://www.rfc-editor.org/info/rfc6241>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13,
RFC 6838, DOI 10.17487/RFC6838, January 2013,
<https://www.rfc-editor.org/info/rfc6838>.
[RFC7435] Dukhovni, V., "Opportunistic Security: Some Protection
Most of the Time", RFC 7435, DOI 10.17487/RFC7435,
December 2014,
<https://www.rfc-editor.org/info/rfc7435>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
<https://www.rfc-editor.org/info/rfc8040>.
[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
<https://www.rfc-editor.org/info/rfc8340>.
[SECUREJOIN] Richardson, M., "6tisch Secure Join protocol", Work in
Progress, draft-ietf-6tisch-dtsecurity-secure-join-01,
February 2017.
[Stajano99theresurrecting]
Stajano, F. and R. Anderson, "The Resurrecting Duckling:
Security Issues for Ad-Hoc Wireless Networks", 1999,
<https://www.cl.cam.ac.uk/research/dtg/www/files/
publications/public/files/tr.1999.2.pdf>.
[YANG-GUIDE] Bierman, A., "Guidelines for Authors and Reviewers of
YANG Data Model Documents", Work in Progress,
draft-ietf-netmod-rfc6087bis-20, March 2018.
[ZERO-TOUCH] Watsen, K., Abrahamsson, M., and I. Farrer, "Zero Touch
Provisioning for Networking Devices", Work in Progress,
draft-ietf-netconf-zerotouch-21, March 2018.Acknowledgements 🫶
Huge shoutout to everyone who helped shape this 💜 The authors want to thank the following people for their lively discussions on the list and in the halls (ordered by last name): William Atwood, Toerless Eckert, and Sheng Jiang.
Russ Housley did the upgrade from PKCS7 to CMS (RFC 5652) and also drew the detailed CMS structure diagram 🎀 Absolute legend behaviour.
Authors' Addresses 🦋
Here's where you can find the authors, bestie 💌
Kent Watsen
Juniper Networks
Email: kwatsen@juniper.net
Michael C. Richardson
Sandelman Software
Email: mcr+ietf@sandelman.ca
URI: http://www.sandelman.ca/
Max Pritikin
Cisco Systems
Email: pritikin@cisco.com
Toerless Eckert
Huawei USA - Futurewei Technologies Inc.
2330 Central Expy
Santa Clara 95050
United States of America
Email: tte+ietf@cs.fau.de, toerless.eckert@huawei.com📦 where this page comes from
- ietf: rfc8366 2018-05
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms