CBOR Web Token (CWT)

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".

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" . This document reuses terminology and definitions from the CBOR and COSE specifications. The following data types are used in this document: 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 . StringOrURI values are compared as case-sensitive strings with no transformations or canonicalizations applied. The date/time strings are defined in Section 2.4.1 in RFC 7049 as a CBOR major type 6, with tag value 0.

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.

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.

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

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.

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.

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.

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.

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.

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.

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 . The "cti" value is a case-sensitive string of CBOR major type 2, byte string.

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

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.

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.

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

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" with the help of Ludwig Seitz, Göran Selander, and Samuel Erdtman.