| Internet-Draft | JWS-voucher | March 2022 |
| Richardson & Werner | Expires 8 September 2022 | [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 8 September 2022.¶
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 also the initial serialization to JSON [RFC8259], with a signature provided by [RFC5652].¶
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 as JSON Web Signature (JWS) [RFC7515]. The encoding specified in this document is required for [I-D.ietf-anima-brski-prm] and may be required and/or preferred in other use cases, for example when JWS is already used in other parts of the use case, but CMS is not.¶
This document does not extend the YANG definition of [RFC8366] at all, but accepts that other efforts such as [I-D.richardson-anima-voucher-delegation], [I-D.friel-anima-brski-cloud], and [I-D.ietf-anima-brski-prm] do. This document supports signing any of the extended schemas defined in those documents and any new documents that may appear after this one.¶
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 payload.¶
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.¶
[RFC Editor: please delete] /* TODO: ... */¶
[RFC7515] defines two serializations: the "JWS Compact Serialization" and the "JWS JSON Serialization".¶
The [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 [RFC7515] in section 3.2 and section 7.2.1 provides more details. It works out to:¶
[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.¶
{
"payload": {
"ietf-voucher:voucher": {
"assertion": "logged",
"serial-number": "0123456789",
"nonce": "5742698422680472",
"created-on": "2022-03-02T03:01:24.618Z",
"pinned-domain-cert": "base64encodedvalue=="
}
},
"signatures": [
{
"protected": {
"x5c": [
"base64encodedvalue=="
],
"alg": "ES256"
},
"signature": "base64encodedvalue=="
}
]
}
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".¶
{
"payload":
"eyJpZXRmLXZvdWNoZXItcmVxdWVzdDp2b3VjaGVyIjp7ImNyZWF0ZWQ
tb24iOiIyMDE5LTAyLTE4VDA3OjM5OjAzLjAwMFoiLCJub25jZSI6IjU
3NDI2OTg0MjI2ODA0NzIifX0",
"signatures":[
{
"protected":
"eyJhbGciOiJFUzI1NiIsIng1YyI6WyJNSUlCMmpDQ0FZQ2dBd0lCQWd
JR0FXZWdkY1NMTUFvR0NDcUdTTTQ5QkFNQ01EMHhDekFKQmdOVkJBWVR
Ba0ZSTVJVd0V3WURWUVFLREF4S2FXNW5TbWx1WjBOdmNuQXhGekFWQmd
OVkJBTU1Ea3BwYm1kS2FXNW5WR1Z6ZEVOQk1DQVhEVEU0TVRJeE1qQXp
NamcxTVZvWUR6azVPVGt4TWpNeE1qTTFPVFU1V2pCU01Rc3dDUVlEVlF
RR0V3SkJVVEVWTUJNR0ExVUVDZ3dNU21sdVowcHBibWREYjNKd01STXd
FUVlEVlFRRkV3b3dNVEl6TkRVMk56ZzVNUmN3RlFZRFZRUUREQTVLYVc
1blNtbHVaMFJsZG1salpUQlpNQk1HQnlxR1NNNDlBZ0VHQ0NxR1NNNDl
Bd0VIQTBJQUJNVkdHOFo1cGpmNWpYbnlyVXJYeVoxa1BncUJlM05YdTF
kVEFEZStyL3Y2SnpJSGwzNTVJZ2NIQzNheHBpYnFKTS9iV1JhRXlqcWN
DSmo0akprb3dDdWpWVEJUTUN3R0NTc0dBUVFCZ3U1U0FnUWZEQjF0WVh
OaExYUmxjM1F1YzJsbGJXVnVjeTFpZEM1dVpYUTZPVFEwTXpBVEJnTlZ
IU1VFRERBS0JnZ3JCZ0VGQlFjREFqQU9CZ05WSFE4QkFmOEVCQU1DQjR
Bd0NnWUlLb1pJemowRUF3SURTQUF3UlFJZ1d0UHpJSVhZMml4UlhKdEV
4S0VoaFpkYTRYK0VwbFpvbUVJMnpBMGRzam9DSVFDM0pwUW1SWE1Hbi9
wNEJ1OWl6aWk5MmVjbFR4NC9PNHJsbTdNeUxxa2hkQT09Il19",
"signature":
"xURZmcWSFaBD2cNkr37azT9osWfzTZ_veCsVho3fwdD6NR4ghL61VJm
Y_ra0a42SvoW2Tu4XlldzzD8VDtCCDg"
}
]
}
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".¶
{
"payload":
"eyJpZXRmLXZvdWNoZXItcmVxdWVzdDp2b3VjaGVyIjp7InNlcmlhbC1
udW1iZXIiOiIwMTIzNDU2Nzg5Iiwibm9uY2UiOiI1NzQyNjk4NDIyNjg
wNDcyIiwicHJpb3Itc2lnbmVkLXZvdWNoZXItcmVxdWVzdCI6ImV5Snd
ZWGxzYjJGa0lqb2laWGxLY0ZwWVVtMU1XRnAyWkZkT2IxcFlTWFJqYlZ
aNFpGZFdlbVJFY0RKaU0xWnFZVWRXZVVscWNEZEpiVTU1V2xkR01GcFh
VWFJpTWpScFQybEplVTFFUlRWTVZFRjVURlJGTkZaRVFUTlBhazAxVDJ
wQmVreHFRWGROUm05cFRFTktkV0l5TldwYVUwazJTV3BWTTA1RVNUSlB
WR2N3VFdwSk1rOUVRVEJPZWtscFpsZ3dJaXdpYzJsbmJtRjBkWEpsY3l
JNlczc2ljSEp2ZEdWamRHVmtJam9pWlhsS2FHSkhZMmxQYVVwR1ZYcEp
NVTVwU1hOSmJtY3hXWGxKTmxkNVNrNVRWV3hEVFcxd1JGRXdSbHBSTW1
SQ1pEQnNRMUZYWkVwU01FWllXbGRrYTFreFRrMVVWVVoyVWpCT1JHTlZ
aRlJVVkZFMVVXdEdUbEV3TVVWTlNHaEVaV3RHUzFGdFpFOVdhMHBDVjF
aU1FtRXdXbE5VVmtwV1pEQldNMWRWVWxkVlZrWk1Va1ZHTkZNeVJsaE9
WelZVWWxkNE1WZHFRazlrYlU1MVVWaG9SMlZyUmxkUmJXUlBWbXRLUWx
SVk1VVmhNMEozV1cweGExTXlSbGhPVnpWWFVqRmFObHBGVms5UmF6RkV
VVlpvUlZaRlZUQlVWbEpLWlVVeGNWRlljRTVoYldONFZGWmFkbGRWVWp
aaGVsWlFWa2QwTkZSWGNFNWxSVEZ4VkZSR1VGWkdWVEZXTW5CRFZUQXh
VbU16WkVSVlZteEZWbXhHVWxJd1ZqTlRhMHBXVmtWV1YxUlZTazVTTUV
WNFZsVldSRm96WkU1Vk1qRnpaRlp2ZDJOSVFtbGlWMUpGV1dwT1MyUXd
NVk5VV0dSR1ZWWnNSVlpzUmxKU2ExWXpZak5rVGxaRmJEWlVhMUpXVFd
zMU5scDZWazVWYlU0elVteEdXbEpHV2xKVlZWSkZVVlJXVEZsV1l6Rml
iRTUwWWtoV1lVMUdTbk5hUnpGellXeHdWVkZzY0U1UmF6RklVVzVzZUZ
JeFRrNU9SR3hDV2pCV1NGRXdUbmhTTVU1T1RrUnNRbVF3VmtsUlZFSkt
VVlZLVGxaclpFaFBSbTh4WTBkd2JVNVhjRmxpYm14NVZsaEtXV1ZXYjN
oaE1VSnVZMVZLYkUwd05WbGtWRVpyVmtWR1JWcFRkSGxNTTFreVUyNXd
TbE5IZDNwT1ZGWktXakpPU1ZGNlRtaGxTRUp3V1c1R1MxUlRPV2xXTVV
wb1VsaHNjV05YVGtSVGJXOHdZV3R3Y21JelpFUmtWM0JYVmtWS1ZWUlZ
Uak5TTUU1VVl6QmtRbFZXUmtOYU0xVXhWVEJHYmxWWFdrVlJha1l3VjF
ab1QyRkZlRmxWYlhocVRURkdNVmw2U25OaVIwcFlWbTVXYW1WVVJuQmF
SVTB4WkZad1dWVlVXbEJXUmtWM1ZGaHdRbFpGU201VWJGcEpWVEZXUmx
KRlVrSlRNRXB1V2pOS1Exb3dWa2RSYkVacVVrVkdjVkZWT1VOYU1EVlh
VMFpGTkZGclJtMVBSVlpEVVZVeFJGRnFVa0prTUU1dVYxVnNUR0l4Y0V
wbGJXOTNVbFZHTTFOVlVsUlJWVVl6Vld4R1Nsb3haREJWU0hCS1UxWm9
XazF0YkRSVmJHaExaRVZXTkZNd1ZtOWhSbkJyV1ZSU1dVc3dWbmRpUm5
CMllsVldTazF1Y0VKTlIxSjZZVzA1UkZOV1JrUk5NSEIzVlZjeFUxZEZ
NVWhpYVRsM1RrVktNVTlYYkRaaFYyczFUVzFXYW1KR1VqUk9RemxRVGt
oS2MySlVaRTVsVlhoNFlUSm9hMUZVTURsSmJERTVJaXdpYzJsbmJtRjB
kWEpsSWpvaWVGVlNXbTFqVjFOR1lVSkVNbU5PYTNJek4yRjZWRGx2YzF
kbWVsUmFYM1psUTNOV2FHOHpabmRrUkRaT1VqUm5hRXcyTVZaS2JWbGZ
jbUV3WVRReVUzWnZWekpVZFRSWWJHeGtlbnBFT0ZaRWRFTkRSR2NpZlY
xOSIsImNyZWF0ZWQtb24iOiIyMDIyLTAzLTAyVDAzOjAxOjI0LjQ2Nlo
ifX0",
"signatures":[
{
"protected":
"eyJ4NWMiOlsiTUlJQm96Q0NBVXFnQXdJQkFnSUdBVzBlTHVJRk1Bb0d
DQ3FHU000OUJBTUNNRFV4RXpBUkJnTlZCQW9NQ2sxNVFuVnphVzVsYzN
NeERUQUxCZ05WQkFjTUJGTnBkR1V4RHpBTkJnTlZCQU1NQmxSbGMzUkR
RVEFlRncweE9UQTVNVEV3TWpNM016SmFGdzB5T1RBNU1URXdNak0zTXp
KYU1GUXhFekFSQmdOVkJBb01DazE1UW5WemFXNWxjM014RFRBTEJnTlZ
CQWNNQkZOcGRHVXhMakFzQmdOVkJBTU1KVkpsWjJsemRISmhjaUJXYjN
WamFHVnlJRkpsY1hWbGMzUWdVMmxuYm1sdVp5QkxaWGt3V1RBVEJnY3F
oa2pPUFFJQkJnZ3Foa2pPUFFNQkJ3TkNBQVQ2eFZ2QXZxVHoxWlVpdU5
XaFhwUXNrYVB5N0FISFFMd1hpSjBpRUx0NnVOUGFuQU4wUW5XTVlPXC8
wQ0RFaklrQlFvYnc4WUtxanR4SkhWU0dUajlLT295Y3dKVEFUQmdOVkh
TVUVEREFLQmdnckJnRUZCUWNESERBT0JnTlZIUThCQWY4RUJBTUNCNEF
3Q2dZSUtvWkl6ajBFQXdJRFJ3QXdSQUlnWXIyTGZxb2FDS0RGNFJBY01
tSmkrTkNacWRTaXVWdWdJU0E3T2hLUnEzWUNJRHhuUE1NbnBYQU1UclB
KdVBXeWNlRVIxMVB4SE9uKzBDcFNIaTJxZ3BXWCIsIk1JSUJwRENDQVV
tZ0F3SUJBZ0lHQVcwZUx1SCtNQW9HQ0NxR1NNNDlCQU1DTURVeEV6QVJ
CZ05WQkFvTUNrMTVRblZ6YVc1bGMzTXhEVEFMQmdOVkJBY01CRk5wZEd
VeER6QU5CZ05WQkFNTUJsUmxjM1JEUVRBZUZ3MHhPVEE1TVRFd01qTTN
NekphRncweU9UQTVNVEV3TWpNM016SmFNRFV4RXpBUkJnTlZCQW9NQ2s
xNVFuVnphVzVsYzNNeERUQUxCZ05WQkFjTUJGTnBkR1V4RHpBTkJnTlZ
CQU1NQmxSbGMzUkRRVEJaTUJNR0J5cUdTTTQ5QWdFR0NDcUdTTTQ5QXd
FSEEwSUFCT2t2a1RIdThRbFQzRkhKMVVhSTcrV3NIT2IwVVMzU0FMdEc
1d3VLUURqaWV4MDZcL1NjWTVQSmlidmdIVEIrRlwvUVRqZ2VsSEd5MVl
LcHdjTk1jc1N5YWpSVEJETUJJR0ExVWRFd0VCXC93UUlNQVlCQWY4Q0F
RRXdEZ1lEVlIwUEFRSFwvQkFRREFnSUVNQjBHQTFVZERnUVdCQlRvWkl
NelFkc0RcL2pcLytnWFwvN2NCSnVjSFwvWG1qQUtCZ2dxaGtqT1BRUUR
BZ05KQURCR0FpRUF0eFEzK0lMR0JQSXRTaDRiOVdYaFhOdWhxU1A2SCt
iXC9MQ1wvZlZZRGpRNm9DSVFERzJ1UkNIbFZxM3loQjU4VFhNVWJ6SDg
rT2xoV1V2T2xSRDNWRXFEZGNRdz09Il0sImFsZyI6IkVTMjU2In0",
"signature":
"zvtnaEDpOqL49XnYVRbLxVAaZCMRtDiaLqMeFSH3UsjHdz4FT0lFywV
7-5inMpafXTnqqxnD2Gpr3ClUXUyAJg"
}
]
}
The following is an example voucher response from MASA to Pledge via Registrar, in "General JWS JSON Serialization".¶
{
"payload":
"eyJpZXRmLXZvdWNoZXI6dm91Y2hlciI6eyJhc3NlcnRpb24iOiJsb2
dnZWQiLCJzZXJpYWwtbnVtYmVyIjoiMDEyMzQ1Njc4OSIsIm5vbmNlI
joiNTc0MjY5ODQyMjY4MDQ3MiIsImNyZWF0ZWQtb24iOiIyMDIyLTAz
LTAyVDAzOjAxOjI0LjYxOFoiLCJwaW5uZWQtZG9tYWluLWNlcnQiOiJ
NSUlCcERDQ0FVbWdBd0lCQWdJR0FXMGVMdUgrTUFvR0NDcUdTTTQ5Qk
FNQ01EVXhFekFSQmdOVkJBb01DazE1UW5WemFXNWxjM014RFRBTEJnT
lZCQWNNQkZOcGRHVXhEekFOQmdOVkJBTU1CbFJsYzNSRFFUQWVGdzB4
T1RBNU1URXdNak0zTXpKYUZ3MHlPVEE1TVRFd01qTTNNekphTURVeEV
6QVJCZ05WQkFvTUNrMTVRblZ6YVc1bGMzTXhEVEFMQmdOVkJBY01CRk
5wZEdVeER6QU5CZ05WQkFNTUJsUmxjM1JEUVRCWk1CTUdCeXFHU000O
UFnRUdDQ3FHU000OUF3RUhBMElBQk9rdmtUSHU4UWxUM0ZISjFVYUk3
K1dzSE9iMFVTM1NBTHRHNXd1S1FEamlleDA2L1NjWTVQSmlidmdIVEI
rRi9RVGpnZWxIR3kxWUtwd2NOTWNzU3lhalJUQkRNQklHQTFVZEV3RU
Ivd1FJTUFZQkFmOENBUUV3RGdZRFZSMFBBUUgvQkFRREFnSUVNQjBHQ
TFVZERnUVdCQlRvWklNelFkc0Qvai8rZ1gvN2NCSnVjSC9YbWpBS0Jn
Z3Foa2pPUFFRREFnTkpBREJHQWlFQXR4UTMrSUxHQlBJdFNoNGI5V1h
oWE51aHFTUDZIK2IvTEMvZlZZRGpRNm9DSVFERzJ1UkNIbFZxM3loQj
U4VFhNVWJ6SDgrT2xoV1V2T2xSRDNWRXFEZGNRdz09In19",
"signatures": [
{
"protected":
"eyJ4NWMiOlsiTUlJQmt6Q0NBVGlnQXdJQkFnSUdBV0ZCakNrWU1B
b0dDQ3FHU000OUJBTUNNRDB4Q3pBSkJnTlZCQVlUQWtGUk1SVXdFd
1lEVlFRS0RBeEthVzVuU21sdVowTnZjbkF4RnpBVkJnTlZCQU1NRG
twcGJtZEthVzVuVkdWemRFTkJNQjRYRFRFNE1ERXlPVEV3TlRJME1
Gb1hEVEk0TURFeU9URXdOVEkwTUZvd1R6RUxNQWtHQTFVRUJoTUNR
VkV4RlRBVEJnTlZCQW9NREVwcGJtZEthVzVuUTI5eWNERXBNQ2NHQ
TFVRUF3d2dTbWx1WjBwcGJtZERiM0p3SUZadmRXTm9aWElnVTJsbm
JtbHVaeUJMWlhrd1dUQVRCZ2NxaGtqT1BRSUJCZ2dxaGtqT1BRTUJ
Cd05DQUFTQzZiZUxBbWVxMVZ3NmlRclJzOFIwWlcrNGIxR1d5ZG1X
czJHQU1GV3diaXRmMm5JWEgzT3FIS1Z1OHMyUnZpQkdOaXZPS0dCS
Eh0QmRpRkVaWnZiN294SXdFREFPQmdOVkhROEJBZjhFQkFNQ0I0QX
dDZ1lJS29aSXpqMEVBd0lEU1FBd1JnSWhBSTRQWWJ4dHNzSFAyVkh
4XC90elVvUVwvU3N5ZEwzMERRSU5FdGNOOW1DVFhQQWlFQXZJYjNv
K0ZPM0JUbmNMRnNhSlpSQWtkN3pPdXNuXC9cL1pLT2FFS2JzVkRpV
T0iXSwiYWxnIjoiRVMyNTYifQ",
"signature":
"vyge3GENm1BNcijXT5VH7A8CJWW7wPzH61u2VCfR8E9v8H8Yr3g9
irYz4q5sYj2UnOVIh-hG_ogrZR0Tct_Vzw"
}
]
}