Internet-Draft | JWS-voucher | July 2022 |
Werner & Richardson | Expires 12 January 2023 | [Page] |
[RFC8366] defines a digital artifact called voucher as a YANG-defined JSON document that has been signed using a Cryptographic Message Syntax (CMS) structure. This memo introduces a variant of the voucher structure in which CMS is replaced by the JSON Object Signing and Encryption (JOSE) mechanism described in RFC7515 to better support use-cases in which JOSE is preferred over CMS.¶
In addition to explaining how the format is created, MIME types are registered and examples are provided.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 12 January 2023.¶
Copyright (c) 2022 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) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
"A Voucher Artifact for Bootstrapping Protocols" [RFC8366] describes a voucher artifact used in "Bootstrapping Remote Secure Key Infrastructure" [BRSKI] and "Secure Zero Touch Provisioning" [SZTP] to transfer ownership of a device from a manufacturer to an owner. That document defines the base YANG module and the serialization to JSON [RFC8259] with a CMS signature according to [RFC5652]. The resulting Voucher artifact has the media type "application/voucher-cms+json".¶
Other work, [I-D.ietf-anima-constrained-voucher] provides a mapping of the YANG to CBOR [RFC8949] with a signature format of COSE [RFC8812].¶
This document provides an equivalent mapping of JSON format with the signature format JSON Web Signature (JWS) [RFC7515]. The encoding specified in this document is used by [I-D.ietf-anima-brski-prm] and may be preferred for use cases requiring signed JSON objects.¶
This document does not extend the YANG definition of [RFC8366].¶
With the availability of different encoded vouchers, it is up to an industry specific application statement to indicate/decide which voucher signature format is to be used. There is no provision across the different voucher signature formats that a receiver could safely recognize which format it uses unless additional context is provided. For example, [BRSKI] provides this context via the MIME-Type for the voucher artifact.¶
This document should be considered an update to [RFC8366] in the category of "See Also" as per [I-D.kuehlewind-update-tag].¶
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.¶
The voucher [RFC8366] JSON structure consists of a nested map, the outer part of which is:¶
{ "ietf-voucher:voucher" : { some inner items }}¶
this is considered the JSON payload as described in [RFC7515] section 3.¶
A JWS JSON Serialization Overview is given by The following serializations are defined:[RFC7515] in section 3.2 and section 7 provides more details.¶
"JWS JSON Serialization" in, [RFC7515] section 7.2¶
- "General JWS JSON Serialization Syntax", [RFC7515] section 7.2.1¶
- "Flattened JWS JSON Serialization Syntax", [RFC7515] section 7.2.2¶
This document makes use of the "General JWS JSON Serialization Syntax" to support multi signatures.¶
[RFC Editor: please delete] /* TODO: ... */¶
[RFC Editor: please delete] /* TODO: ... */¶
There are a number of attributes. They are:¶
[RFC Editor: please delete] /* TODO: ... */¶
The standard "typ" and "alg" values described in [RFC7515] are expected in the protected headers.¶
It remains to be determined (XXX), what values, if any, should go into the "typ" header, as in the [BRSKI] use cases, there are additional HTTP MIME type headers to indicate content types.¶
The "alg" should contain the algorithm type such as "ES256".¶
If PKIX [RFC5280] format certificates are used then the [RFC7515] section 4.1.6 "x5c" certificate chain SHOULD be used to contain the certificate and chain. Vouchers will often need all certificates in the chain, including what would be considered the trust anchor certificate because intermediate devices (such as the Registrar) may need to audit the artifact, or end systems may need to pin a trust anchor for future operations. This is consistent with [BRSKI] section 5.5.2.¶
The Voucher Request reveals the IDevID of the component (Pledge) that is on-boarding.¶
This request occurs over HTTP-over-TLS, however the Pledge to Registrar transaction is over a provisional TLS session, and it is subject to disclosure via by a Dolev-Yao attacker (a "malicious messenger")[onpath]. This is explained in [BRSKI] section 10.2.¶
The use of a JWS header brings no new privacy considerations.¶
The issues of how [RFC8366] vouchers are used in a [BRSKI] system is addressed in section 11 of that document. This document does not change any of those issues, it just changes the signature technology used for vouchers and voucher requests.¶
[SZTP] section 9 deals with voucher use in Secure Zero Touch Provisioning, and this document also makes no changes to security.¶
This section registers the 'application/voucher-jws+json' in the "Media Types" registry.¶
Type name: application Subtype name: voucher-jws+json Required parameters: none Optional parameters: none Encoding considerations: JWS+JSON vouchers are JOSE objects signed with one signer. Security considerations: See Security Considerations, Section Interoperability considerations: The format is designed to be broadly interoperable. Published specification: THIS RFC. Applications that use this media type: ANIMA, 6tisch, and other zero-touch imprinting systems Additional information: Magic number(s): None File extension(s): .vjj Macintosh file type code(s): none Person & 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): NO¶
These examples are folded according to [RFC8792] Single Backslash rule.¶
The following is an example request sent from a Pledge to the Registrar, in "General JWS JSON Serialization".¶
The term parboiled refers to food which is partially cooked. In [BRSKI], the term refers to a Pledge voucher-request (PVR) which has been received by the Registrar, and then has been processed by the Registrar ("cooked"), and is now being forwarded to the MASA.¶
The following is an example Registrar voucher-request (RVR) sent from the Registrar to the MASA, in "General JWS JSON Serialization". Note that the previous PVR can be seen in the payload as "prior-signed-voucher-request".¶
The following is an example voucher response from MASA to Pledge via Registrar, in "General JWS JSON Serialization".¶