idnits 2.17.1 draft-wahlstroem-oauth-cbor-web-token-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 12, 2015) is 3088 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 7049 (ref. '2') (Obsoleted by RFC 8949) == Outdated reference: A later version (-24) exists of draft-ietf-cose-msg-07 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group E. Wahlstroem 3 Internet-Draft Nexus Technology 4 Intended status: Informational M. Jones 5 Expires: May 15, 2016 Microsoft 6 H. Tschofenig 7 ARM Ltd. 8 November 12, 2015 10 CBOR Web Token (CWT) 11 draft-wahlstroem-oauth-cbor-web-token-00 13 Abstract 15 CBOR Web Token (CWT) is a compact means of representing claims to be 16 transferred between two parties. CWT is a profile of the JSON Web 17 Token (JWT) that is optimized for constrained devices. The claims in 18 a CWT are encoded in the Concise Binary Object Representation (CBOR) 19 and CBOR Object Signing and Encryption (COSE) is used for added 20 application layer security protection. A claim is a piece of 21 information asserted about a subject and is represented as a name/ 22 value pair consisting of a claim name and a claim value. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on May 15, 2016. 41 Copyright Notice 43 Copyright (c) 2015 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 3. Claims . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 3.1. Claim Names . . . . . . . . . . . . . . . . . . . . . . . 3 62 3.1.1. iss (Issuer) Claim . . . . . . . . . . . . . . . . . 4 63 3.1.2. sub (Subject) Claim . . . . . . . . . . . . . . . . . 4 64 3.1.3. aud (Audience) Claim . . . . . . . . . . . . . . . . 4 65 3.1.4. exp (Expiration Time) Claim . . . . . . . . . . . . . 4 66 3.1.5. nbf (Not Before) Claim . . . . . . . . . . . . . . . 4 67 3.1.6. iat (Issued At) Claim . . . . . . . . . . . . . . . . 5 68 3.1.7. cti (CWT ID) Claim . . . . . . . . . . . . . . . . . 5 69 3.1.8. cks (COSE Key Structure) Claim . . . . . . . . . . . 5 70 4. Summary of CBOR major types used by defined claims . . 5 71 5. CBOR Web Token Example . . . . . . . . . . . . . . . . . . . 6 72 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6 73 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 74 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6 75 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 76 9.1. Normative References . . . . . . . . . . . . . . . . . . 7 77 9.2. Informative References . . . . . . . . . . . . . . . . . 7 78 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 7 80 1. Introduction 82 With JSON Web Tokens (JWTs) a standardized format of security tokens 83 has been defined and has found use in OAuth 2.0 and OpenID Connect 84 deployments. With JSON Web Signatures (JWS) and JSON Web Encryption 85 (JWE) security the content of the JWT, which comes in form of claims, 86 is protected. The use of JSON for encoding information is popular 87 for Web applications but it is still considered inefficient for use 88 in many IoT systems that use low power radio technologies. 90 In this document an alternative encoding of claims is defined. 91 Instead of using JSON, as provided by JWTs, this specification 92 suggests the use of CBOR and calls this new structure 'CBOR Web Token 93 (CWT)', which is a compact means of representing claims to be 94 transferred between two parties. To protect the claims inside the 95 CWT the CBOR Object Signing and Encryption (COSE) specification is 96 re-used. 98 The suggested pronunciation of CWT is the same as the English word 99 "cot". 101 2. Terminology 103 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 104 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 105 document are to be interpreted as described in "Key words for use in 106 RFCs to Indicate Requirement Levels" [1]. 108 This document reuses terminology and definitions from the CBOR [6] 109 and COSE [4] specifications. 111 The following data types are used in this document: 113 StringOrURI: 115 A CBOR major type 3, string value, with the additional requirement 116 that while arbitrary string values MAY be used, any value 117 containing a ":" character MUST be a URI [3]. StringOrURI values 118 are compared as case-sensitive strings with no transformations or 119 canonicalizations applied. 121 DateTime: 123 The date/time strings are defined in Section 2.4.1 in RFC 7049 [2] 124 as a CBOR major type 6, with tag value 0. 126 3. Claims 128 The set of claims that a CWT must contain to be considered valid is 129 context dependent and is outside the scope of this specification. 130 Specific applications of CWTs will require implementations to 131 understand and process some claims in particular ways. However, in 132 the absence of such requirements, all claims that are not understood 133 by implementations MUST be ignored. 135 3.1. Claim Names 137 None of the claims defined below are intended to be mandatory to use 138 or mandatory implement. They rather provide a starting point for a 139 set of useful, interoperable claims. Applications using CWTs should 140 define which specific claims they use and when they are required or 141 optional. 143 3.1.1. iss (Issuer) Claim 145 The "iss" (issuer) claim identifies the principal that issued the 146 CWT. The "iss" value is a case-sensitive string containing a 147 StringOrURI value. 149 3.1.2. sub (Subject) Claim 151 The "sub" (subject) claim identifies the principal that is the 152 subject of the CWT. The claims in a CWT are normally statements 153 about the subject. The subject value MUST either be scoped to be 154 locally unique in the context of the issuer or be globally unique. 155 The processing of this claim is generally application specific. The 156 "sub" value is a case-sensitive string containing a StringOrURI 157 value. 159 3.1.3. aud (Audience) Claim 161 The "aud" (audience) claim identifies the recipients that the CWT is 162 intended for. Each principal intended to process the CWT MUST 163 identify itself with a value in the audience claim. If the principal 164 processing the claim does not identify itself with a value in the 165 "aud" claim when this claim is present, then the CWT MUST be 166 rejected. In the general case, the "aud" value is an array of case- 167 sensitive strings, each containing a StringOrURI value. In the 168 special case when the CWT has one audience, the "aud" value MAY be a 169 single case-sensitive string containing a StringOrURI value. 171 3.1.4. exp (Expiration Time) Claim 173 The "exp" (expiration time) claim identifies the expiration time on 174 or after which the CWT MUST NOT be accepted for processing. The 175 processing of the "exp" claim requires that the current date/time 176 MUST be before the expiration date/time listed in the "exp" claim. 177 Implementers MAY provide for some small leeway, usually no more than 178 a few minutes, to account for clock skew. Its value MUST be a number 179 containing a DateTime value. 181 3.1.5. nbf (Not Before) Claim 183 The "nbf" (not before) claim identifies the time before which the CWT 184 MUST NOT be accepted for processing. The processing of the "nbf" 185 claim requires that the current date/time MUST be after or equal to 186 the not-before date/time listed in the "nbf" claim. Implementers MAY 187 provide for some small leeway, usually no more than a few minutes, to 188 account for clock skew. Its value MUST be a number containing a 189 DateTime value. 191 3.1.6. iat (Issued At) Claim 193 The "iat" (issued at) claim identifies the time at which the CWT was 194 issued. This claim can be used to determine the age of the CWT. Its 195 value MUST be a number containing a DateTime value. 197 3.1.7. cti (CWT ID) Claim 199 The "cti" (CWT ID) claim provides a unique identifier for the CWT. 200 The identifier value MUST be assigned in a manner that ensures that 201 there is a negligible probability that the same value will be 202 accidentally assigned to a different data object; if the application 203 uses multiple issuers, collisions MUST be prevented among values 204 produced by different issuers as well. The "cti" claim can be used 205 to prevent the CWT from being replayed. The "cti" value is a case- 206 sensitive string of CBOR major type 3. 208 3.1.8. cks (COSE Key Structure) Claim 210 The "cks" (COSE Key Structure) claim holds members representing a 211 COSE Key Structure. The members of the structure can be found in 212 Section 7.1 of [4]. The "cti" value is a case-sensitive string of 213 CBOR major type 2, byte string. 215 4. Summary of CBOR major types used by defined claims 217 /-----------+---------------+-----------------------\ 218 | Value | Major Type | Key | 219 |-----------+---------------+-----------------------| 220 | 1 | 3 | iss | 221 | 2 | 3 | sub | 222 | 3 | 3 | aud | 223 | 4 | 6 tag value 0 | exp | 224 | 5 | 6 tag value 0 | nbf | 225 | 6 | 6 tag value 0 | iat | 226 | 7 | 3 | cti | 227 | 8 | 2 | cks | 228 \-----------+---------------+-----------------------/ 230 Figure 1: Summary of CBOR major types used by defined Claims. 232 Note: Claims defined by the OpenID Foundation have not yet been 233 included in the table above. 235 5. CBOR Web Token Example 237 This section illustrates a CWT in the CBOR diagnostic notation. This 238 example CWT was issued by the AS identified as 239 "coap://as.example.com" in the "iss" (issuer) claim. The CWT is only 240 valid at a resource server at "coap://light.example.com". Its 241 validity is 2 minutes. 243 { 244 "iss": "coap://as.example.com", 245 "aud": "coap://light.example.com", 246 "exp": 1444064944, 247 "iat": 1443944944 248 } 250 Figure 2: CWT Example in the CBOR Diagnostic Notation. 252 6. Security Considerations 254 The security of the CWT is dependent on the protection offered by 255 COSE. Without protecting the claims contained in a CWT an adversary 256 is able to modify, add or remove claims. Since the claims conveyed 257 in a CWT are used to make authorization decisions it is not only 258 important to protect the CWT in transit but also to ensure that the 259 recipient is able to authenticate the party that collected the claims 260 and created the CWT. Without trust of the recipient in the party 261 that created the CWT no sensible authorization decision can be made. 262 Furthermore, the creator of the CWT needs to carefully evaluate each 263 claim value prior to including it in the CWT so that the recipient 264 can be assured about the correctness of the provided information. 266 7. IANA Considerations 268 This section will create a registry for CWT claims, possibly relating 269 them to the JWT Claims Registry. 271 8. Acknowledgements 273 Add your name here. 275 A straw man proposal of CWT was written in the draft "Authorization 276 for the Internet of Things using OAuth 2.0" [5] with the help of 277 Ludwig Seitz, Goeran Selander, and Samuel Erdtman. 279 9. References 281 9.1. Normative References 283 [1] Bradner, S., "Key words for use in RFCs to Indicate 284 Requirement Levels", BCP 14, RFC 2119, 285 DOI 10.17487/RFC2119, March 1997, 286 . 288 [2] Bormann, C. and P. Hoffman, "Concise Binary Object 289 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 290 October 2013, . 292 [3] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 293 Resource Identifier (URI): Generic Syntax", STD 66, 294 RFC 3986, DOI 10.17487/RFC3986, January 2005, 295 . 297 [4] Schaad, J., "CBOR Encoded Message Syntax", draft-ietf- 298 cose-msg-07 (work in progress), November 2015. 300 9.2. Informative References 302 [5] Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 303 H. Tschofenig, "Authorization for the Internet of Things 304 using OAuth 2.0", draft-seitz-ace-oauth-authz-00 (work in 305 progress), October 2015. 307 [6] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 308 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 309 . 311 Authors' Addresses 313 Erik Wahlstroem 314 Nexus Technology 315 Sweden 317 Email: erik.wahlstrom@nexusgroup.com 318 URI: https://www.nexusgroup.com 320 Michael B. Jones 321 Microsoft 323 Email: mbj@microsoft.com 324 URI: http://self-issued.info/ 325 Hannes Tschofenig 326 ARM Ltd. 327 Hall in Tirol 6060 328 Austria 330 Email: Hannes.Tschofenig@arm.com