One document matched: draft-ietf-ace-cbor-web-token-00.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?xml-stylesheet type='text/xsl' href='http://xml2rfc.tools.ietf.org/authoring/rfc2629.xslt' ?>
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="4"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="no"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc strict="no"?>
<?rfc compact="no"?>
<?rfc subcompact="no"?>
<rfc category="info" ipr="trust200902" docName="draft-ietf-ace-cbor-web-token-00">
<front>
<title abbrev="CBOR Web Token">CBOR Web Token (CWT)</title>
<author initials="E." surname="Wahlström" fullname="Erik Wahlström">
<organization>Nexus Technology</organization>
<address>
<postal>
<street></street>
<city></city>
<code></code>
<country>Sweden</country>
</postal>
<phone></phone>
<email>erik.wahlstrom@nexusgroup.com</email>
<uri>https://www.nexusgroup.com</uri>
</address>
</author>
<author fullname="Michael B. Jones" initials="M.B." surname="Jones">
<organization>Microsoft</organization>
<address>
<email>mbj@microsoft.com</email>
<uri>http://self-issued.info/</uri>
</address>
</author>
<author fullname="Hannes Tschofenig" initials="H." surname="Tschofenig">
<organization>ARM Ltd.</organization>
<address>
<postal>
<street></street>
<code>6060</code> <city>Hall in Tirol</city>
<country>Austria</country>
</postal>
<email>Hannes.Tschofenig@arm.com</email>
</address>
</author>
<date day="20" month="May" year="2016" />
<area>Security</area>
<workgroup>ACE Working Group</workgroup>
<keyword>Internet-Draft</keyword>
<keyword>JSON Web Token</keyword>
<keyword>JWT</keyword>
<keyword>Claims</keyword>
<keyword>CBOR</keyword>
<keyword>COSE</keyword>
<keyword>OAuth</keyword>
<keyword>ACE</keyword>
<abstract>
<t>
CBOR Web Token (CWT) is a compact means of representing claims to be
transferred between two parties. CWT is a profile of the JSON Web
Token (JWT) that is optimized for constrained devices. The claims in a
CWT are encoded in the Concise Binary Object Representation (CBOR) and
CBOR Object Signing and Encryption (COSE) is used for added application
layer security protection. A claim is a piece of information asserted
about a subject and is represented as a name/value pair consisting of a
claim name and a claim value.
</t>
</abstract>
</front>
<middle>
<!-- ====================================================================== -->
<section anchor="introduction" title="Introduction">
<t>
The JSON Web Token (JWT) <xref target="RFC7519"/> is a standardized security token format
that has found use in OAuth 2.0 and OpenID Connect deployments, among other applications.
JWT uses JSON Web Signatures (JWS) <xref target="RFC7515"/> and
JSON Web Encryption (JWE) <xref target="RFC7516"/> to secure the contents of the JWT,
which is a set of claims represented in JSON <xref target="RFC7519"/>.
The use of JSON for encoding information is popular for
Web and native applications, but it is considered inefficient for some
Internet of Things (IoT) systems that use low power radio technologies.
</t>
<t>
In this document an alternative encoding of claims is defined. Instead
of using JSON, as provided by JWTs, this specification uses
CBOR <xref target="RFC7049"/> and calls this new structure "CBOR Web Token (CWT)", which is a
compact means of representing secured claims to be transferred between two
parties. CWT is closely related to JWT. It references the JWT claims
and both its name and pronunciation are derived from JWT. To protect the
claims contained in CWTs, the CBOR Object Signing and Encryption (COSE)
<xref target="I-D.ietf-cose-msg"/>
specification is used.
</t>
<t>
The suggested pronunciation of CWT is the same as the English word
"cot".
</t>
</section>
<!-- /////////////////////////////////////////////////////////////////////// -->
<section title="Terminology">
<t>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 "Key words for use in
RFCs to Indicate Requirement Levels" <xref target="RFC2119"/>.</t>
<t>
This document reuses terminology from JWT
<xref target="RFC7519"/> and COSE <xref target="I-D.ietf-cose-msg" />.
</t>
<t>
<list style="hanging">
<t hangText="Type3StringOrURI:"><vspace blankLines="1"/>
The "Type3StringOrURI" term has the same meaning, syntax, and
processing rules as the "StringOrUri" term defined in Section 2
of JWT <xref target="RFC7519" />, except that Type3StringOrURI uses
CBOR major type 3 instead of a JSON string value.
</t>
<t>
FIXME: Use tag 32 for URIs?
</t>
<t hangText="Type6NumericDate:"><vspace blankLines="1"/>
The "Type6NumericDate" term has the same meaning, syntax, and
processing rules as the "NumericDate" term defined in Section 2
of JWT <xref target="RFC7519" />, except that Type6NumericDate uses
CBOR major type 6, with tag value 1, instead of a numeric JSON
value.
</t>
<t hangText="CBOR encoded claim key:"><vspace blankLines="1"/>
The key used to identify a claim value.
</t>
</list>
</t>
</section>
<section title="Claims">
<t>
The set of claims that a CWT must contain to be considered valid is
context dependent and is outside the scope of this specification.
Specific applications of CWTs will require implementations to
understand and process some claims in particular ways. However, in
the absence of such requirements, all claims that are not understood
by implementations MUST be ignored.
</t>
<t>
To keep CWTs as small as possible, the CBOR encoded claim keys are
represented using CBOR major type 0.
<xref target="CWTCNMajorTypesSummery" /> summaries all keys used to
identity the claims defined in this document.
</t>
<section anchor="CWTClaimNames" title="Claim Names">
<t>
None of the claims defined below are intended to be
mandatory to use or implement. They rather provide
a starting point for a set of useful, interoperable claims.
Applications using CWTs should define which specific claims they
use and when they are required or optional.
</t>
<section anchor="CWTCNiss" title="iss (Issuer) Claim">
<t>
The <spanx style="verb">iss</spanx> (issuer) claim has the same meaning, syntax, and
processing rules as the <spanx style="verb">iss</spanx> claim defined in Section 4.1.1
of JWT <xref target="RFC7519" />, except that the format MUST be a
Type3StringOrURI. The CBOR encoded claim key 1 MUST be used to
identify this claim.
</t>
</section>
<section anchor="CWTCNsub" title="sub (Subject) Claim">
<t>
The <spanx style="verb">sub</spanx> (subject) claim has the same meaning, syntax, and
processing rules as the <spanx style="verb">sub</spanx> claim defined in Section 4.1.2
of JWT <xref target="RFC7519" />, except that the format MUST be a
Type3StringOrURI. The CBOR encoded claim key 2 MUST be used to
identify this claim.
</t>
</section>
<section anchor="CWTCNaud" title="aud (Audience) Claim">
<t>
The <spanx style="verb">aud</spanx> (audience) claim has the same meaning, syntax, and
processing rules as the <spanx style="verb">aud</spanx> claim defined in Section 4.1.3
of JWT <xref target="RFC7519" />, except that the format MUST be a
Type3StringOrURI. The CBOR encoded claim key 3 MUST be used to
identify this claim.
</t>
</section>
<section anchor="CWTCNexp" title="exp (Expiration Time) Claim">
<t>
The <spanx style="verb">exp</spanx> (expiration time) claim has the same meaning, syntax,
and processing rules as the <spanx style="verb">exp</spanx> claim defined in Section
4.1.4 of JWT <xref target="RFC7519" />, except that the format
MUST be a Type6NumericDate. The CBOR encoded claim key 4 MUST be
used to identify this claim.
</t>
</section>
<section anchor="CWTCNnbf" title="nbf (Not Before) Claim">
<t>
The <spanx style="verb">nbf</spanx> (not before) claim has the same meaning, syntax,
and processing rules as the <spanx style="verb">nbf</spanx> claim defined in Section
4.1.5 of JWT <xref target="RFC7519" />, except that the format
MUST be a Type6NumericDate. The CBOR encoded claim key 5 MUST be
used to identify this claim.
</t>
</section>
<section anchor="CWTCNiat" title="iat (Issued At) Claim">
<t>
The <spanx style="verb">iat</spanx> (issued at) claim has the same meaning, syntax,
and processing rules as the <spanx style="verb">iat</spanx> claim defined in Section
4.1.6 of JWT <xref target="RFC7519" />, except that the format
MUST be a Type6NumericDate. The CBOR encoded claim key 6 MUST be
used to identify this claim.
</t>
</section>
<section anchor="CWTCNcti" title="cti (CWT ID) Claim">
<t>
The <spanx style="verb">cti</spanx> (CWT ID) claim has the same meaning, syntax,
and processing rules as the <spanx style="verb">jti</spanx> claim defined in Section
4.1.7 of JWT <xref target="RFC7519" />, except that the format
MUST be of major type 3 with a case-sensitive string value. The
CBOR encoded claim key 7 MUST be used to identify this claim.
</t>
</section>
<!--
Let's literally just reference all the claims defined in JWT and define other claims in other specs.
<section anchor="CWTCNcks" title="cks (COSE Key Structure) Claim">
<t>
The <spanx style="verb">cks</spanx> (COSE Key Structure) claim holds members representing a
COSE Key Structure. The members of the structure can be found in
Section 7.1 of <xref target="I-D.ietf-cose-msg" />. The <spanx style="verb">cks</spanx>
value is a case-sensitive string and MUST be of CBOR major type 2,
byte string. The CBOR encoded claim key 8 MUST be used to identify
this claim.
<!== TBD: Check this section number periodically ==>
</t>
</section>
-->
</section>
</section>
<section anchor="CWTCNMajorTypesSummery"
title="Summary of the values, CBOR major types and encoded claim keys">
<t>
<figure align="center" anchor="fig:cborMappingValuesAccessTokens"
title="Summary of the values, CBOR major types and encoded claim keys.">
<artwork align="left"><![CDATA[
/---------+------------------------+--------------------------\
| Claim | CBOR encoded claim key | CBOR major type of value |
|---------+------------------------+--------------------------|
| iss | 1 | 3 |
| sub | 2 | 3 |
| aud | 3 | 3 |
| exp | 4 | 6 tag value 1 |
| nbf | 5 | 6 tag value 1 |
| iat | 6 | 6 tag value 1 |
| cti | 7 | 3 |
\---------+------------------------+--------------------------/
]]></artwork>
<!--
| cks | 8 | 3 |
-->
</figure>
</t>
<t>
Note: Claims defined by the OpenID Foundation have not yet been
included in the table above.
</t>
</section>
<!--
<section anchor="CWTCreation" title="CWT creation">
<t>TBD</t>
<t>
Rewrite section 7 from <xref target="RFC7519"/>.
</t>
<t>
Reference section 4.2 in <xref target="I-D.ietf-cose-msg" /> for
descriptions on how to sign and encrypt the claims.
</t>
</section>
<section anchor="CWTValidation" title="CWT validation">
<t>TBD</t>
<t>
Rewrite section 7 from <xref target="RFC7519"/>.
</t>
<t>
Reference section 4.2 in <xref target="I-D.ietf-cose-msg" /> for
descriptions on how to sign and encrypt the claims.
</t>
</section>
<section title="Data Type Mapping">
<t>The data types listed along with the claim definitions in <xref target="claims"/> need to be mapped to data types available with CBOR. This document has not yet attempted to provide such mapping.</t>
</section>
-->
<section title="Security Considerations">
<t>The security of the CWT is dependent on the protection offered by COSE. Without protecting the claims contained in a CWT an adversary is able to modify, add or remove claims. Since the claims conveyed in a CWT are used to make authorization decisions it is not only important to protect the CWT in transit but also to ensure that the recipient is able to authenticate the party that collected the claims and created the CWT. Without trust of the recipient in the party that created the CWT no sensible authorization decision can be made. Furthermore, the creator of the CWT needs to carefully evaluate each claim value prior to including it in the CWT so that the recipient can be assured about the correctness of the provided information.</t>
</section>
<!-- /////////////////////////////////////////////////////////////////////// -->
<section anchor="iana" title="IANA Considerations">
<t>
This section will create a registry for CWT claims, possibly relating them to the JWT Claims Registry.
</t>
</section>
<!-- /////////////////////////////////////////////////////////////////////// -->
</middle>
<back>
<references title='Normative References'>
<?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml' ?>
<?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7159.xml' ?>
<?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7515.xml' ?>
<?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7516.xml' ?>
<?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7519.xml' ?>
<?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7049.xml' ?>
<?rfc include="http://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.ietf-cose-msg"?>
<?rfc include="http://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.seitz-ace-oauth-authz"?>
</references>
<!--
<references title='Informative References'>
</references>
-->
<section title="Examples">
<t>Three examples of CWTs follow.</t>
<section title='CWT with "aud" and symmetric key'
anchor="exampleAudSymmetric">
<t>
A CWT used in the context of ACE requires at least the <spanx style="verb">aud</spanx> and a
<spanx style="verb">cks</spanx> claim (defined elsewhere).
This means that <spanx style="verb">iss</spanx>, <spanx style="verb">alg</spanx>, <spanx style="verb">key_ops</spanx> and
others are pre-established and assumed.
This would look like this non-normative JSON.
</t>
<t>
<figure align="center" anchor="fig:exampleAudSymmetricJSON"
title='"aud" claim and symmetric key in non-normative JSON'>
<artwork align="left"><![CDATA[
{
"aud":"coap://light.example.com",
"cks":
[ // COSE_Key is a CBOR map with an array of keys
{
"kty":4, // symmetric key is indicated using kty 4
"k": "loremipsum" // the symmetric key
}
]
}
]]></artwork>
</figure>
</t>
<t>
Using the CBOR encoded claim keys according to
<xref target="CWTCNMajorTypesSummery" /> and COSE
<xref target="I-D.ietf-cose-msg" /> makes a CWT with <spanx style="verb">aud</spanx> and a
symmetric key look like this in CBOR diagnostic notation:
</t>
<t>
<figure align="center" anchor="fig:exampleAudSymmetricDiag"
title="CWT in CBOR diagnostic notation">
<artwork align="left"><![CDATA[
{
3: "coap://light.example.com",
8:
[
{
1: 4,
-1: "loremipsum"
}
]
}
]]></artwork>
</figure>
</t>
<t>
Defined in CBOR.
</t>
<t>
<figure align="center" anchor="fig:exampleAudSymmetricCBOR"
title='CWT with "aud" and symmetric key in CBOR'>
<artwork align="left"><![CDATA[
a2 # map(2)
03 # unsigned(3)
78 18 # text(24)
636f61703a2f2f6c696768742e6578616d706c652e636f6d # "coap://light.example.com"
08 # unsigned(8)
81 # array(1)
a2 # map(2)
01 # unsigned(1)
04 # unsigned(4)
20 # negative(0)
6a # text(10)
6c6f72656d697073756d # "loremipsum"
]]></artwork>
</figure>
</t>
<t>
Size of the CWT with a symmetric key of 10 bytes is 45 bytes. This is
then packaged signed and encrypted using COSE.
</t>
</section>
<section title='CWT with "aud" and EC key'
anchor="exampleAudEC">
<t>
Token with <spanx style="verb">aud</spanx> set to "coap://light.example.com" and an EC key with
<spanx style="verb">kid</spanx> set to <spanx style="verb">11</spanx>.
</t>
<t>
<figure align="center" anchor="fig:exampleAudECJSON"
title='"aud" claim and EC key in non-normative JSON'>
<artwork align="left"><![CDATA[
{
"aud": "coap://light.example.com",
"cks":
[ // COSE_Key is a CBOR map with an array of keys
{
"kty": "EC",
"kid": "11",
"crv": 1, // using P-384
"x": h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff',
"y": h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e'
}
]
}
]]></artwork>
</figure>
</t>
<t>
Using the CBOR encoded claim keys according to
<xref target="CWTCNMajorTypesSummery" /> and COSE
<xref target="I-D.ietf-cose-msg" /> makes a CWT with <spanx style="verb">aud</spanx> and an EC key
look like this in CBOR diagnostic notation:
</t>
<t>
<figure align="center" anchor="fig:exampleAudECDiag"
title="CWT with EC key in CBOR diagnostic notation">
<artwork align="left"><![CDATA[
{
3: "coap://light.example.com",
8:
[
{
1: 2,
2: "11",
-1: 1,
-2: h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff',
-3: h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e'
}
]
}
]]></artwork>
</figure>
</t>
<t>
Defined in CBOR.
</t>
<t>
<figure align="center" anchor="fig:exampleECCBOR"
title="CWT with EC in CBOR">
<artwork align="left"><![CDATA[
a2 # map(2)
03 # unsigned(3)
78 18 # text(24)
636f61703a2f2f6c696768742e6578616d706c652e636f6d # "coap://light.example.com"
08 # unsigned(8)
81 # array(1)
a5 # map(5)
01 # unsigned(1)
02 # unsigned(2)
02 # unsigned(2)
62 # text(2)
3131 # "11"
20 # negative(0)
01 # unsigned(1)
21 # negative(1)
58 20 # bytes(32)
bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff # "\xBA\xC5\xB1\x1C\xAD\x8F\x99\xF9\xC7+\x05\xCFK\x9E&\xD2D\xDC\x18\x9FtR(%Z!\x9A\x86\xD6\xA0\x9E\xFF"
22 # negative(2)
58 20 # bytes(32)
20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e # "\x13\x8B\xF8-\xC1\xB6\xD5b\xBE\x0F\xA5J\xB7\x80J:d\xB6\xD7,\xCF\xEDko\xB6\xED(\xBB\xFC\x11~"
]]></artwork>
</figure>
</t>
<t>
Size of the CWT with an EC key is 109 bytes. This is
then packaged signed and encrypted using COSE.
</t>
</section>
<section title="Full CWT" anchor="exampleFull">
<t>
CWT using all claims defined by this specification, plus extensions for AIF and an EC key.
</t>
<t>
<figure align="center" anchor="fig:exampleFullJSON"
title='All claims, "aif" and EC key in non-normative JSON'>
<artwork align="left"><![CDATA[
{
"iss": "coap://as.example.com",
"aud": "coap://light.example.com",
"sub": "erikw",
"exp": 1444064944,
"nbf": 1443944944,
"iat": 1443944944,
"cti": 2929,
"cks":
[ // COSE_Key is a CBOR map with an array of keys
{
"kty": "EC",
"kid": "11",
"crv": 1, // using P-384
"x": h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff',
"y": h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e'
}
],
"aif": [["/s/light", 1], ["/a/led", 5], ["/dtls", 2]]
}
]]></artwork>
</figure>
</t>
<t>
Using the CBOR encoded claim keys according to
<xref target="CWTCNMajorTypesSummery" /> and COSE
<xref target="I-D.ietf-cose-msg" /> makes a full CWT look like this
in CBOR diagnostic notation:
</t>
<t>
<figure align="center" anchor="fig:exampleFullDiag"
title="Full CWT with EC key in CBOR diagnostic notation">
<artwork align="left"><![CDATA[
{
1: "coap://as.example.com",
3: "coap://light.example.com",
2: "erikw",
4: 1(1444064944),
5: 1(1443944944),
6: 1(1443944944),
7: 2929,
8: [
{
1: 2,
2: "11",
-1: 1,
-2: h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff',
-3: h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e'
}
],
9: [["/s/light", 1], ["/a/led", 5], ["/dtls", 2]]
}
]]></artwork>
</figure>
</t>
<t>
Defined in CBOR.
</t>
<t>
<figure align="center" anchor="fig:exampleFullCBOR"
title="Full CWT with EC in CBOR">
<artwork align="left"><![CDATA[
a9 # map(9)
01 # unsigned(1)
75 # text(21)
636f61703a2f2f61732e6578616d706c652e636f6d # "coap://as.example.com"
03 # unsigned(3)
78 18 # text(24)
636f61703a2f2f6c696768742e6578616d706c652e636f6d # "coap://light.example.com"
02 # unsigned(2)
65 # text(5)
6572696b77 # "erikw"
04 # unsigned(4)
c1 # tag(1)
1a 5612aeb0 # unsigned(1444064944)
05 # unsigned(5)
c1 # tag(1)
1a 5610d9f0 # unsigned(1443944944)
06 # unsigned(6)
c1 # tag(1)
1a 5610d9f0 # unsigned(1443944944)
07 # unsigned(7)
19 0b71 # unsigned(2929)
08 # unsigned(8)
81 # array(1)
a5 # map(5)
01 # unsigned(1)
02 # unsigned(2)
02 # unsigned(2)
62 # text(2)
3131 # "11"
20 # negative(0)
01 # unsigned(1)
21 # negative(1)
58 20 # bytes(32)
bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff # "\xBA\xC5\xB1\x1C\xAD\x8F\x99\xF9\xC7+\x05\xCFK\x9E&\xD2D\xDC\x18\x9FtR(%Z!\x9A\x86\xD6\xA0\x9E\xFF"
22 # negative(2)
58 20 # bytes(32)
20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e # "\x13\x8B\xF8-\xC1\xB6\xD5b\xBE\x0F\xA5J\xB7\x80J:d\xB6\xD7,\xCF\xEDko\xB6\xED(\xBB\xFC\x11~"
09 # unsigned(9)
83 # array(3)
82 # array(2)
68 # text(8)
2f732f6c69676874 # "/s/light"
01 # unsigned(1)
82 # array(2)
66 # text(6)
2f612f6c6564 # "/a/led"
05 # unsigned(5)
82 # array(2)
65 # text(5)
2f64746c73 # "/dtls"
02 # unsigned(2)
]]></artwork>
</figure>
</t>
<t>
Size of the CWT with an EC key is 194 bytes. This is
then packaged signed and encrypted using COSE.
</t>
</section>
</section>
<section title="Acknowledgements">
<t>
A straw man proposal of CWT was written in the draft
"Authorization for the Internet of Things using OAuth 2.0"
<xref target="I-D.seitz-ace-oauth-authz" /> with the help of
Ludwig Seitz, Göran Selander, and Samuel Erdtman.
</t>
</section>
<section anchor="History" title="Document History">
<t>[[ to be removed by the RFC Editor before publication as an RFC ]]</t>
<t>
-00
<list style="symbols">
<t>
Created the initial working group version based on draft-wahlstroem-ace-cbor-web-token-00.
</t>
</list>
</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 03:38:03 |