OAuth Working Group E. Wahlstroem
Internet-Draft Nexus Technology
Intended status: Informational M. Jones
Expires: May 15, 2016 Microsoft
H. Tschofenig
ARM Ltd.
November 12, 2015

CBOR Web Token (CWT)
draft-wahlstroem-oauth-cbor-web-token-00

Abstract

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.

Status of This Memo

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 http://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 May 15, 2016.

Copyright Notice

Copyright (c) 2015 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 (http://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 Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.


Table of Contents

1. Introduction

With JSON Web Tokens (JWTs) a standardized format of security tokens has been defined and has found use in OAuth 2.0 and OpenID Connect deployments. With JSON Web Signatures (JWS) and JSON Web Encryption (JWE) security the content of the JWT, which comes in form of claims, is protected. The use of JSON for encoding information is popular for Web applications but it is still considered inefficient for use in many IoT systems that use low power radio technologies.

In this document an alternative encoding of claims is defined. Instead of using JSON, as provided by JWTs, this specification suggests the use of CBOR and calls this new structure 'CBOR Web Token (CWT)', which is a compact means of representing claims to be transferred between two parties. To protect the claims inside the CWT the CBOR Object Signing and Encryption (COSE) specification is re-used.

The suggested pronunciation of CWT is the same as the English word "cot".

2. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD 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" [1].

This document reuses terminology and definitions from the CBOR [6] and COSE [4] specifications.

The following data types are used in this document:

StringOrURI:


A CBOR major type 3, string value, with the additional requirement that while arbitrary string values MAY be used, any value containing a ":" character MUST be a URI [3]. StringOrURI values are compared as case-sensitive strings with no transformations or canonicalizations applied.
DateTime:


The date/time strings are defined in Section 2.4.1 in RFC 7049 [2] as a CBOR major type 6, with tag value 0.

3. Claims

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.

3.1. Claim Names

None of the claims defined below are intended to be mandatory to use or mandatory 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.

3.1.1. iss (Issuer) Claim

The "iss" (issuer) claim identifies the principal that issued the CWT. The "iss" value is a case-sensitive string containing a StringOrURI value.

3.1.2. sub (Subject) Claim

The "sub" (subject) claim identifies the principal that is the subject of the CWT. The claims in a CWT are normally statements about the subject. The subject value MUST either be scoped to be locally unique in the context of the issuer or be globally unique. The processing of this claim is generally application specific. The "sub" value is a case-sensitive string containing a StringOrURI value.

3.1.3. aud (Audience) Claim

The "aud" (audience) claim identifies the recipients that the CWT is intended for. Each principal intended to process the CWT MUST identify itself with a value in the audience claim. If the principal processing the claim does not identify itself with a value in the "aud" claim when this claim is present, then the CWT MUST be rejected. In the general case, the "aud" value is an array of case-sensitive strings, each containing a StringOrURI value. In the special case when the CWT has one audience, the "aud" value MAY be a single case-sensitive string containing a StringOrURI value.

3.1.4. exp (Expiration Time) Claim

The "exp" (expiration time) claim identifies the expiration time on or after which the CWT MUST NOT be accepted for processing. The processing of the "exp" claim requires that the current date/time MUST be before the expiration date/time listed in the "exp" claim. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value MUST be a number containing a DateTime value.

3.1.5. nbf (Not Before) Claim

The "nbf" (not before) claim identifies the time before which the CWT MUST NOT be accepted for processing. The processing of the "nbf" claim requires that the current date/time MUST be after or equal to the not-before date/time listed in the "nbf" claim. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value MUST be a number containing a DateTime value.

3.1.6. iat (Issued At) Claim

The "iat" (issued at) claim identifies the time at which the CWT was issued. This claim can be used to determine the age of the CWT. Its value MUST be a number containing a DateTime value.

3.1.7. cti (CWT ID) Claim

The "cti" (CWT ID) claim provides a unique identifier for the CWT. The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object; if the application uses multiple issuers, collisions MUST be prevented among values produced by different issuers as well. The "cti" claim can be used to prevent the CWT from being replayed. The "cti" value is a case-sensitive string of CBOR major type 3.

3.1.8. cks (COSE Key Structure) Claim

The "cks" (COSE Key Structure) claim holds members representing a COSE Key Structure. The members of the structure can be found in Section 7.1 of [4]. The "cti" value is a case-sensitive string of CBOR major type 2, byte string.

4. Summary of CBOR major types used by defined claims

/-----------+---------------+-----------------------\
| Value     | Major Type    | Key                   |
|-----------+---------------+-----------------------|
| 1         | 3             | iss                   |
| 2         | 3             | sub                   |
| 3         | 3             | aud                   |
| 4         | 6 tag value 0 | exp                   |
| 5         | 6 tag value 0 | nbf                   |
| 6         | 6 tag value 0 | iat                   |
| 7         | 3             | cti                   |
| 8         | 2             | cks                   |
\-----------+---------------+-----------------------/
          

Figure 1: Summary of CBOR major types used by defined Claims.

Note: Claims defined by the OpenID Foundation have not yet been included in the table above.

5. CBOR Web Token Example

This section illustrates a CWT in the CBOR diagnostic notation. This example CWT was issued by the AS identified as "coap://as.example.com" in the "iss" (issuer) claim. The CWT is only valid at a resource server at "coap://light.example.com". Its validity is 2 minutes.

{
  "iss": "coap://as.example.com",
  "aud": "coap://light.example.com",
  "exp": 1444064944,
  "iat": 1443944944
}
          

Figure 2: CWT Example in the CBOR Diagnostic Notation.

6. Security Considerations

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.

7. IANA Considerations

This section will create a registry for CWT claims, possibly relating them to the JWT Claims Registry.

8. Acknowledgements

Add your name here.

A straw man proposal of CWT was written in the draft "Authorization for the Internet of Things using OAuth 2.0" [5] with the help of Ludwig Seitz, Göran Selander, and Samuel Erdtman.

9. References

9.1. Normative References

[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
[2] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, October 2013.
[3] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005.
[4] Schaad, J., "CBOR Encoded Message Syntax", Internet-Draft draft-ietf-cose-msg-07, November 2015.

9.2. Informative References

[5] Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S. and H. Tschofenig, "Authorization for the Internet of Things using OAuth 2.0", Internet-Draft draft-seitz-ace-oauth-authz-00, October 2015.
[6] Jones, M., Bradley, J. and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015.

Authors' Addresses

Erik Wahlstroem Nexus Technology Sweden EMail: erik.wahlstrom@nexusgroup.com URI: https://www.nexusgroup.com
Michael B. Jones Microsoft EMail: mbj@microsoft.com URI: http://self-issued.info/
Hannes Tschofenig ARM Ltd. Hall in Tirol, 6060 Austria EMail: Hannes.Tschofenig@arm.com