jwt-attr-cert-id.txt

Network Working Group                                          L. Howard
Internet-Draft                                                      PADL
Intended status: Experimental                          December 24, 2013
Expires: June 27, 2014


                    JWT Attribute Certificate (JAC)
                   draft-howard-jwt-attr-cert-00.txt

Abstract

   A JSON Web Token Attribute Certificate (JAC) contains additional
   claims, grouped by scope, to be presented alongside a primary JWT.

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 June 27, 2014.

Copyright Notice

   Copyright (c) 2013 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.






Howard                    Expires June 27, 2014                 [Page 1]

Internet-Draft       JWT Attribute Certificate (JAC)       December 2013


Table of Contents

   1.          Introduction . . . . . . . . . . . . . . . . . . . . .  3
   2.          Requirements notation  . . . . . . . . . . . . . . . .  4
   3.          Terminology  . . . . . . . . . . . . . . . . . . . . .  5
   4.          JWT Attribute Certificate (JAC) Overview . . . . . . .  6
   4.1.        Example JAC  . . . . . . . . . . . . . . . . . . . . .  6
   5.          JAC Claims . . . . . . . . . . . . . . . . . . . . . .  7
   5.1.        "cdi" (Certificate Digest Information) . . . . . . . .  7
   5.1.1.      "alg" (Digest Algorithm) . . . . . . . . . . . . . . .  7
   5.1.2.      "dig" (Digest Value) . . . . . . . . . . . . . . . . .  7
   5.2.        "scope" (Scope)  . . . . . . . . . . . . . . . . . . .  7
   5.3.        "scope_description" (Scope Description)  . . . . . . .  8
   6.          Rules for Creating and Validating a JAC  . . . . . . .  9
   7.          Security Considerations  . . . . . . . . . . . . . . . 11
   8.          IANA Considerations  . . . . . . . . . . . . . . . . . 12
   8.1.        JSON Web Token Claims Registry . . . . . . . . . . . . 12
   8.2.        JAC Digest Algorithm Registry  . . . . . . . . . . . . 12
   8.2.1.      Registration Template  . . . . . . . . . . . . . . . . 12
   8.2.2.      Initial Registry Contents  . . . . . . . . . . . . . . 13
   8.3.        JAC Scope Registry . . . . . . . . . . . . . . . . . . 13
   8.3.1.      Registration Template  . . . . . . . . . . . . . . . . 13
   8.3.2.      Initial Registry Contents  . . . . . . . . . . . . . . 14
   9.          References . . . . . . . . . . . . . . . . . . . . . . 16
   9.1.        Normative References . . . . . . . . . . . . . . . . . 16
   9.2.        Informative References . . . . . . . . . . . . . . . . 16
   Appendix A. BrowserID JAC Profile  . . . . . . . . . . . . . . . . 17
               Author's Address . . . . . . . . . . . . . . . . . . . 18























Howard                    Expires June 27, 2014                 [Page 2]

Internet-Draft       JWT Attribute Certificate (JAC)       December 2013


1.  Introduction

   JSON Web Tokens [I-D.ietf-oauth-json-web-token] may be used to convey
   certified claims about a subject.  For example, the [BrowserID]
   protocol uses a JWT containing an e-mail address and public key to
   bind an identity to a signing key.  JWTs may include a variety of
   claims, however doing so in a single token has some disadvantages.
   First, all claims must be issued by the same entity (or the issuer
   must contact other authorities).  Secondly, they must share the same
   validity period.  Finally, the disclosing party must either reveal
   all claims or none.

   Attribute certificates (similar to those described in [RFC3281])
   allow additional claims, grouped by scope, to be disclosed
   separately.  A special claim is used to bind the attribute
   certificate to the primary JWT with which it is associated.

   This document defines protocols, procedures and conventions for using
   a JWT as an attribute certificate.
































Howard                    Expires June 27, 2014                 [Page 3]

Internet-Draft       JWT Attribute Certificate (JAC)       December 2013


2.  Requirements notation

   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 [RFC2119].

   The reader is assumed to be familiar with the terms used in the base
   JWT specifications.











































Howard                    Expires June 27, 2014                 [Page 4]

Internet-Draft       JWT Attribute Certificate (JAC)       December 2013


3.  Terminology

   Certificate Digest Information  a claim binding a JAC to its Primary
      JWT

   Claims  individual properties in a JAC or other JWT

   JAC Validity  the time interval in which the JAC is valid, as
      expressed by the "nbf" ([I-D.ietf-oauth-json-web-token] Section
      4.1.5) and "exp" ([I-D.ietf-oauth-json-web-token] Section 4.1.4)
      claims

   JWT Attribute Certificate (JAC)  a JWT associated with a Primary JWT
      that containing additional claims about a subject

   JSON Web Token (JWT)  a signed or encrypted structure for
      representing a set of Claims to be transferred between two parties

   Primary JWT  a JWT certifying an identity and typically containing a
      public key

   Scope  a string that identifies the set of claims in a JAC

   Scope Description  a human readable description of the Scope suitable
      for displaying by a user agent


























Howard                    Expires June 27, 2014                 [Page 5]

Internet-Draft       JWT Attribute Certificate (JAC)       December 2013


4.  JWT Attribute Certificate (JAC) Overview

   A JWT Attribute Certificate is a JSON Web Token (per
   [I-D.ietf-oauth-json-web-token] Section 3) that contains the
   mandatory claims defined in Section 5 and is associated with another
   JWT (the Primary JWT).

4.1.  Example JAC

   The following is an example of a JAC Claims Set containing a end-
   user's profile claims:

          {
            "scope": "profile",
            "scope_description": "My standard profile",
            "cdi": {
              "alg": "S256",
              "dig": "fHf5HxJuzWTSuepVY3N0BvWlvuXPNiUHwqsk0HX1Cjc"
            },
            "iss": "ca.example.com",
            "name": "Luke Howard",
            "given_name": "Luke",
            "family_name": "Howard",
            "website": "www.example.com/~lukeh",
            "preferred_username": "lukeh"
          }

   The Claims Set is signed (in this case, by a key belonging to
   "ca.example.com") and encoded as a JWT; this encoding is the JAC.






















Howard                    Expires June 27, 2014                 [Page 6]

Internet-Draft       JWT Attribute Certificate (JAC)       December 2013


5.  JAC Claims

   The following Claim Names are defined for use in JACs.  JACs MAY
   contain other claims.  Claims present in the Primary JWT, with the
   exception of "iss", "aud", "exp", "nbf", "iat" and "jti", SHOULD NOT
   be present in a JAC.

5.1.  "cdi" (Certificate Digest Information)

   The "cdi" claim binds a JAC to its Primary JWT.  Its value is a JSON
   object containing the name/value pairs (sub-claims) defined below.
   Use of this claim is REQUIRED.

   (Note that the term "certificate" is used for consistency with
   [RFC3281]; however there is no explicit requirement that the Primary
   JWT contain a public key or otherwise function as a certificate.)

5.1.1.  "alg" (Digest Algorithm)

   This sub-claim contains a string identifying the digest algorithm
   used to create a digest of the Primary JWT.  Algorithms are defined
   in Section 8.2 of this document.

5.1.2.  "dig" (Digest Value)

   This sub-claim contains the digest of the JWS (per
   [I-D.ietf-jose-json-web-signature]) or JWE (per
   [I-D.ietf-jose-json-web-encryption]) Compact Serialization of the
   Primary JWT.  The digest algorithm is the one specified by the "alg"
   sub-claim.  The digest is encoded as a base 64 URL string.

   In the case where the Primary JWT has a JWS JSON Serialization and
   has multiple signatures, the first signature is used when
   constructing the JWS Compact Serialization for input to the digest
   algorithm.

5.2.  "scope" (Scope)

   The "scope" claim is a case-sensitive string identifying the set of
   claims contained in the JAC.  Use of this claim is REQUIRED.

   In order to prevent collisions, Scopes SHOULD either be registered in
   the IANA JAC Scopes registry defined in Section 8.3, or be a
   Collision-Resistant Name (per [I-D.ietf-oauth-json-web-token] Section
   2).  A producer and consumer of a JAC MAY agree to use Scopes that
   are not registered or Collision-Resistant, but this is discouraged
   owing to the possibility of collision.




Howard                    Expires June 27, 2014                 [Page 7]

Internet-Draft       JWT Attribute Certificate (JAC)       December 2013


   Where the subject of the Primary JWT is an end-user, support for the
   scopes defined in [OpenID.Core] Section 5.4 is RECOMMENDED.

5.3.  "scope_description" (Scope Description)

   The "scope_description" claim is a string suitable for displaying to
   an end-user that describes the set of claims contained in the JAC.
   Use of this claim is OPTIONAL.











































Howard                    Expires June 27, 2014                 [Page 8]

Internet-Draft       JWT Attribute Certificate (JAC)       December 2013


6.  Rules for Creating and Validating a JAC

   To create a JAC, one MUST perform these steps.  The order of the
   steps is not significant in cases where there are no dependencies
   between the inputs and outputs of the steps.

   1.  Choose a digest algorithm to be used in creating a digest of the
       Primary JWT.  Place the corresponding Algorithm Name in the "alg"
       sub-claim of the "cdi" claim.

   2.  Create a digest of the Primary JWT and place it in the "dig" sub-
       claim of the "cdi" claim.

   3.  Place the Scope in the "scope" claim.

   4.  Optionally, place a human readable description of the Scope in
       the "scope_description" claim.

   5.  Create a JWT containing a Claims Set with the above along with
       any additional claims relevant to the Scope.

   When validating a JAC, the following steps MUST be taken.  The order
   of the steps is not significant in cases where there are no
   dependencies between the inputs and outputs of the steps.  If any of
   the listed steps fails then the JAC MUST be rejected for processing.

   Note that the manner in which JACs are presented to the validating
   party is outside the scope of this specification.  However, it is
   assumed that the Primary JWT is available to the party validating the
   JAC.

   1.   The Primary JWT MUST be a valid JWT, per
        [I-D.ietf-oauth-json-web-token] Section 7.

   2.   The JAC MUST be a valid JWT, per [I-D.ietf-oauth-json-web-token]
        Section 7.

   3.   The algorithm in the "alg" sub-claim of the "cdi" claim MUST be
        a supported algorithm.

   4.   The digest in the "dig" sub-claim of the "cdi" claim MUST match
        the digest of the Primary JWT using the selected algorithm.

   5.   The "scope" claim of the JAC MUST be unique amongst all JACs
        presented with the Primary JWT.

   6.   To avoid ambiguity, the JAC SHOULD NOT have any claims that are
        present in the Primary JWT, other than "iss", "aud", "exp",



Howard                    Expires June 27, 2014                 [Page 9]

Internet-Draft       JWT Attribute Certificate (JAC)       December 2013


        "nbf", "iat" and "jti".

   7.   If the "iss" claim of the JAC is absent, or is present and
        matches the "iss" claim of the Primary JWT, the JAC MUST be
        signed with a key that signed the Primary JWT; otherwise, the
        signer of the JAC MUST be directly trusted (by configuration or
        otherwise).

   8.   The time for which the JAC is being validated MUST be within the
        JAC Validity.  If the evaluation time is equal to the time
        expressed by either of the "nbf" or "exp" claims, the JAC is
        timely and this check succeeds.  Note that in some applications,
        the evaluation time MAY not be the same as the current time.
        (This language is based on [RFC3281] Section 5.)

   9.   The JAC Validity MUST match or be within the interval specified
        by the "nbf" and "exp" claims of the Primary JWT, if present.

   10.  If the JAC contains an "aud" claim, and the validating party
        would normally process this claim in a Primary JWT, then the
        validating party MUST identify itself with one of its values
        (per [I-D.ietf-oauth-json-web-token] Section 4.1.3).  This claim
        has the effect of restricting any values of the "aud" claim in
        the primary JWT.

   Additional checks:

   1.  The JAC MAY be rejected on the basis of further validating party
       configuration.

   2.  The validating party MAY filter the attributes returned to the
       application on the basis of configuration information.



















Howard                    Expires June 27, 2014                [Page 10]

Internet-Draft       JWT Attribute Certificate (JAC)       December 2013


7.  Security Considerations

   JACs must be valid JWTs and are subject to the same validation policy
   as the Primary JWT.

   JAC issuers must protect their private keys.

   The binding between a JAC and the Primary JWT cannot be stronger than
   the algorithm used to generate the Certificate Digest Information.

   Claims Names that are present in both the Primary JWT and the JAC
   (other than those explicitly permitted by this specification) SHOULD
   be rejected.

   To avoid conflicts between identically named claims in different
   JACs, the validating party SHOULD group claims by Scope when
   surfacing them to the application.

   If the issuer of an JAC differs from the issuer of the Primary JWT,
   trust in any claims made by the JAC is subject to local policy (for
   example, different issuers may only be trusted to issue JACs for
   certain Scopes, and/or to issue certain claims).  If no such policy
   exists, the JAC MUST be ignored.

   User agents that permit selective disclosure of JACs SHOULD provide a
   means for the user to determine what claims are being made by a JAC,
   particularly in the cases where the JAC is not issued by the issuer
   of the Primary JWT, and/or only the Scope Description is displayed by
   default.

   The presentation of JACs is not defined by this document.  However,
   JACs SHOULD be presented over a secure channel and, when used with
   Primary JWTs that contain a public key, SHOULD be secured by the
   corresponding private key so that the choice of JACs is protected.

   This specification does not discuss revocation.  It is assumed that
   the JAC Validity will typically be less than the time required to
   issue and distribute revocation information (see [RFC3281] Section
   6).  If revocation is required, it SHOULD be discussed when profiling
   this specification for a particular application or protocol.











Howard                    Expires June 27, 2014                [Page 11]

Internet-Draft       JWT Attribute Certificate (JAC)       December 2013


8.  IANA Considerations

8.1.  JSON Web Token Claims Registry

   The following Claim Names are registered in the IANA JSON Web Token
   Claims registry created in [I-D.ietf-oauth-json-web-token] Section
   10.1.

   o  Claim Name: "cdi"

   o  Claim Description: Certificate Digest Information

   o  Change Controller: IESG

   o  Specification Document(s): Section 5.1 of [[ this document ]]

   o  Claim Name: "scope"

   o  Claim Description: JWT Attribute Certificate Scope

   o  Change Controller: IESG

   o  Specification Document(s): Section 5.2 of [[ this document ]]

   o  Claim Name: "scope_description"

   o  Claim Description: JWT Attribute Certificate Scope Description

   o  Change Controller: IESG

   o  Specification Document(s): Section 5.3 of [[ this document ]]

8.2.  JAC Digest Algorithm Registry

   This section creates a registry of digest algorithms for binding a
   JAC to its Primary JWT.

8.2.1.  Registration Template

   Algorithm Name:  A string identifying the digest algorithm.  It is
      RECOMMENDED that the name be short -- not to exceed 8 characters
      without a compelling reason to do so.  This name is case-
      sensitive.

   Algorithm Description:  Brief description of the digest algorithm.






Howard                    Expires June 27, 2014                [Page 12]

Internet-Draft       JWT Attribute Certificate (JAC)       December 2013


   Implementation Requirements:  The algorithm implementation
      requirements, which must be one the words Required, Recommended,
      Optional, Deprecated, or Prohibited.

   Change Controller:  For Standards Track RFCs, state "IESG".  For
      others, give the name of the responsible party.  Other details
      (e.g., postal address, email address, home page URI) may also be
      included.

   Specification Document(s):  Reference to the document(s) that specify
      the algorithm, preferably including URI(s) that can be used to
      retrieve copies of the document(s).  An indication of the relevant
      sections may also be included but is not required.

8.2.2.  Initial Registry Contents

   o  Algorithm Name: "S256"

   o  Algorithm Description: SHA-256 hash

   o  Implementation Requirements: Required

   o  Change Controller: IESG

   o  Specification Document(s): Section 6.2 of [SHS]

   o  Algorithm Name: "S512"

   o  Algorithm Description: SHA-512 hash

   o  Implementation Requirements: Optional

   o  Change Controller: IESG

   o  Specification Document(s): Section 6.4 of [SHS]

8.3.  JAC Scope Registry

   This section creates a registry of Scopes for grouping the set of
   claims in a JAC.

8.3.1.  Registration Template

   Scope Name:  A string identifying the Scope.







Howard                    Expires June 27, 2014                [Page 13]

Internet-Draft       JWT Attribute Certificate (JAC)       December 2013


   Scope Description:  Brief description of the Scope.  The description
      MAY include the Claim Names.

   Change Controller:  For Standards Track RFCs, state "IESG".  For
      others, give the name of the responsible party.  Other details
      (e.g., postal address, email address, home page URI) may also be
      included.

   Specification Document(s):  Reference to the document(s) that specify
      the algorithm, preferably including URI(s) that can be used to
      retrieve copies of the document(s).  An indication of the relevant
      sections may also be included but is not required.

8.3.2.  Initial Registry Contents

   o  Scope Name: "profile"

   o  Scope Description: The End-User's default profile claims, which
      are name, family_name, given_name, middle_name, nickname,
      preferred_username, profile, picture, website, gender, birthdate,
      zoneinfo, locale, and updated_at.

   o  Change Controller: The OpenID Foundation

   o  Specification Document(s): Section 5.4 of [OpenID.Core]

   o  Scope Name: "email"

   o  Scope Description: The email and email_verified claims

   o  Change Controller: The OpenID Foundation

   o  Specification Document(s): Section 5.4 of [OpenID.Core]

   o  Scope Name: "address"

   o  Scope Description: The address claim

   o  Change Controller: The OpenID Foundation

   o  Specification Document(s): Section 5.4 of [OpenID.Core]

   o  Scope Name: "phone"

   o  Scope Description: The phone_number and phone_number_verified
      claims





Howard                    Expires June 27, 2014                [Page 14]

Internet-Draft       JWT Attribute Certificate (JAC)       December 2013


   o  Change Controller: The OpenID Foundation

   o  Specification Document(s): Section 5.4 of [OpenID.Core]
















































Howard                    Expires June 27, 2014                [Page 15]

Internet-Draft       JWT Attribute Certificate (JAC)       December 2013


9.  References

9.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [I-D.ietf-jose-json-web-algorithms]
              Jones, M., "JSON Web Algorithms (JWA)",
              draft-ietf-jose-json-web-algorithms-18 (work in progress),
              November 2013.

   [I-D.ietf-jose-json-web-encryption]
              Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web
              Encryption (JWE)", draft-ietf-jose-json-web-encryption-18
              (work in progress), November 2013.

   [I-D.ietf-jose-json-web-key]
              Jones, M., "JSON Web Key (JWK)",
              draft-ietf-jose-json-web-key-18 (work in progress),
              November 2013.

   [I-D.ietf-jose-json-web-signature]
              Jones, M., Bradley, J., and N. Sakimura, "JSON Web
              Signature (JWS)", draft-ietf-jose-json-web-signature-18
              (work in progress), November 2013.

   [I-D.ietf-oauth-json-web-token]
              Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
              (JWT)", draft-ietf-oauth-json-web-token-13 (work in
              progress), November 2013.

   [OpenID.Core]
              Jones, M., "OpenID Connect Basic Client Implementer's
              Guide", December 2013.

   [SHS]      "Secure Hash Standard (SHS)", FIPS PUB 180-4, March 2012.

9.2.  Informative References

   [RFC3281]  Farrell, S. and R. Housley, "An Internet Attribute
              Certificate Profile for Authorization", RFC 3281,
              April 2002.

   [BrowserID]
              Adida, B., "BrowserID Specification", February 2013.





Howard                    Expires June 27, 2014                [Page 16]

Internet-Draft       JWT Attribute Certificate (JAC)       December 2013


Appendix A.  BrowserID JAC Profile

   This section is non-normative.

   A [BrowserID] user agent (UA) may present a set of JACs as a value of
   the "jac" claim in an assertion (that is, an array of strings where
   each value is a JAC).  This ensures that chosen set is authenticated
   by the user's private key.  BrowserID JACs MUST use the JWS Compact
   Serialization.

   The Primary JWT is the certificate issued by the user's identity
   provider (IdP).  The JAC validating party is the BrowserID Relying
   Party (RP).  The RP MAY provide the UA with a set of Scopes it
   desires in order to authorize the user; these should be divided into
   Essential Scopes (those which it deems necessary to authorize the
   user) and Voluntary Scopes (those which it deems useful but not
   necessary).  (This language is consistent with [OpenID.Core].)

   The IdP SHOULD localize the "scope_description" claim according to
   the UA locale.

   The UA SHOULD only present JACs when the RP has indicated its desire
   for specific Scopes, and the user has explicitly authorized
   disclosure of the JACs corresponding to those Scopes.  The RP SHOULD
   deal gracefully with a user who refuses to disclose Essential Scopes,
   for example by providing limited authorization rather than rejecting
   the request entirely.
























Howard                    Expires June 27, 2014                [Page 17]

Internet-Draft       JWT Attribute Certificate (JAC)       December 2013


Author's Address

   Luke Howard
   PADL Software
   PO Box 59
   Central Park, VIC  3145
   Australia

   Email: lukeh@padl.com










































Howard                    Expires June 27, 2014                [Page 18]