A Voucher Artifact for Bootstrapping Protocols
Extracted elements (25)
Bearer vouchers (with wildcard registrar identity) are explicitly out of scope because any bearer of such a voucher can claim the pledge; a nonceless bearer voucher effectively turns the pledge into a TOFU device with minimal MiTM mitigation.
The voucher format was changed from supporting a single voucher for many pledges (using regular expressions for serial-number ranges) to supporting only a single serial-number per voucher, because blocking renewal of a multi-device voucher would be excessive when only one pledge's ownership needs to be revoked.
This document recommends short-lived vouchers with programmatic renewal (reflected in 'last-renewal-date') instead of long-lived vouchers with revocation, because renewal requires only one artifact and one code path, eliminating the risk of pledges skipping revocation checks (e.g., when OCSP is unreachable).
Future work is expected to define voucher encodings in CBOR (replacing JSON) and alternative signature containers using JOSE or COSE (replacing CMS). XML and ASN.1 formats are also conceivable; each new format would register its own media type.
A pledge MUST ensure that its serial-number matches the 'serial-number' field in the voucher. If no match occurs, the pledge MUST NOT process the voucher.
If the 'expires-on' field exists in a voucher, pledges MUST ensure that the expires-on time has not yet passed. The 'expires-on' value MUST NOT exceed the expiration date of any listed 'pinned-domain-cert' certificate.
Intermediate systems such as a BRSKI registrar that may evaluate a CMS voucher in-flight MUST be prepared for older PKCS7 format (cmsVersion=1), as the manufacturer knows the pledge's capabilities and will use an appropriate format.
Pledges MUST ensure that the assertion provided is acceptable per local policy before processing the voucher. The 'assertion' field (verified/logged/proximity) indicates how the owner was verified by the MASA.
The CMS structure MUST contain a 'signerInfo' structure (per RFC 5652 Section 5.1) containing the signature over the content using a private key trusted by the recipient.
The CMS structure SHOULD contain all certificates leading up to and including the signer's trust anchor certificate known to the recipient, as third parties cannot accurately audit the transaction without the trust anchor.
When a 'nonce' field is present, the pledge MUST compare it with a value the pledge randomly generated and sent to a bootstrap server earlier. If the values do not match, the pledge MUST NOT process the voucher.
When an 'idevid-issuer' field is present, a pledge MUST ensure that its IDevID Authority Key Identifier matches this value; if no match occurs, the pledge MUST NOT process the voucher. When issuing a voucher, the MASA MUST populate this field for serial-numbers not otherwise unique within the MASA's scope.
A voucher is a signed artifact produced by the Manufacturer Authorized Signing Authority (MASA) that securely assigns a pledge device to an owner by conveying the 'pinned-domain-cert' certificate the pledge uses to authenticate subsequent interactions with the owner's network.
The 'assertion' enumeration defines three values: 'verified' (MASA positively verified ownership via sales channel), 'logged' (minimal verification with issuance logged for audit), and 'proximity' (MASA verified a proximity proof from device and target domain, with logging).
The 'pinned-domain-cert' field is a mandatory binary field containing a DER-encoded X.509v3 certificate. The domain certificate presented to the pledge by the bootstrapping protocol MUST have this certificate somewhere in its chain; the field MAY be an end-entity or self-signed certificate.
The voucher artifact is a JSON document conforming to the YANG module 'ietf-voucher', encoded per RFC 8259, and signed using a CMS SignedData structure (DER-encoded per ITU-T X.690). The default media type is 'application/voucher-cms+json' with filename extension '.vcj'.
The YANG module constraint 'must not(../nonce)' on 'expires-on' and 'must not(../expires-on)' on 'nonce' enforces mutual exclusivity: a voucher cannot have both an expiration time and a nonce simultaneously.
IANA registered OID decimal 40 ('id-ct-animaJSONVoucher') in the SMI Security for S/MIME CMS Content Type registry (1.2.840.113549.1.9.16.1), identifying the eContentType for JSON-encoded vouchers in CMS structures.
IANA registered the media type 'application/voucher-cms+json' (file extension '.vcj') in the Media Types Registry. This media type denotes CMS-signed JSON voucher artifacts used by ANIMA, 6tisch, and NETCONF zero-touch imprinting systems.
IANA registered the URI 'urn:ietf:params:xml:ns:yang:ietf-voucher' in the IETF XML Registry, and registered the YANG module 'ietf-voucher' (namespace urn:ietf:params:xml:ns:yang:ietf-voucher, prefix vch) in the YANG Module Names Registry.
An attacker could use an expired voucher against a device without a reliable clock. Defenses include: requiring pledges to verify 'expires-on', allowing devices without clocks to use nonces for ephemeral vouchers, and using nonceless vouchers that appear in audit logs to inform security decisions.
If a domain certificate is compromised, any outstanding vouchers for that domain could be used by an attacker. Protocols for voucher distribution are RECOMMENDED to check for revocation of domain identity certificates before signing vouchers, and the MASA should be notified to block automated renewal.
It is RECOMMENDED that the MASA's private key used for signing vouchers be protected by a hardware security module (HSM), given that the MASA should be deployed as an online voucher signing service.
The CMS signed-data content protects voucher data from modification but not disclosure. Adversaries can observe device-to-organization mappings and CRL/OCSP URLs. When privacy is important, the signed-data SHOULD be encrypted via mutually authenticated TLS or wrapped in a CMS enveloped-data structure.
The voucher container includes mandatory fields 'created-on' (yang:date-and-time), 'assertion' (enumeration: verified/logged/proximity), 'serial-number' (string), and 'pinned-domain-cert' (binary, DER-encoded X.509v3 certificate). Optional fields include 'expires-on', 'idevid-issuer', 'domain-cert-revocation-checks', 'nonce' (8–32 bytes binary), and 'last-renewal-date'.