tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 7517

Proposed STD
Pages: 40
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: JOSE

JSON Web Key (JWK)

Part 1 of 2, p. 1 to 21
None       Next RFC Part

 


Top       ToC       Page 1 
Internet Engineering Task Force (IETF)                          M. Jones
Request for Comments: 7517                                     Microsoft
Category: Standards Track                                       May 2015
ISSN: 2070-1721


                           JSON Web Key (JWK)

Abstract

   A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data
   structure that represents a cryptographic key.  This specification
   also defines a JWK Set JSON data structure that represents a set of
   JWKs.  Cryptographic algorithms and identifiers for use with this
   specification are described in the separate JSON Web Algorithms (JWA)
   specification and IANA registries established by that specification.

Status of This Memo

   This is an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of RFC 5741.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at
   http://www.rfc-editor.org/info/rfc7517.

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.

Top       Page 2 
Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Notational Conventions  . . . . . . . . . . . . . . . . .   3
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   4
   3.  Example JWK . . . . . . . . . . . . . . . . . . . . . . . . .   5
   4.  JSON Web Key (JWK) Format . . . . . . . . . . . . . . . . . .   5
     4.1.  "kty" (Key Type) Parameter  . . . . . . . . . . . . . . .   6
     4.2.  "use" (Public Key Use) Parameter  . . . . . . . . . . . .   6
     4.3.  "key_ops" (Key Operations) Parameter  . . . . . . . . . .   7
     4.4.  "alg" (Algorithm) Parameter . . . . . . . . . . . . . . .   8
     4.5.  "kid" (Key ID) Parameter  . . . . . . . . . . . . . . . .   8
     4.6.  "x5u" (X.509 URL) Parameter . . . . . . . . . . . . . . .   8
     4.7.  "x5c" (X.509 Certificate Chain) Parameter . . . . . . . .   9
     4.8.  "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter  . .   9
     4.9.  "x5t#S256" (X.509 Certificate SHA-256 Thumbprint)
           Parameter . . . . . . . . . . . . . . . . . . . . . . . .  10
   5.  JWK Set Format  . . . . . . . . . . . . . . . . . . . . . . .  10
     5.1.  "keys" Parameter  . . . . . . . . . . . . . . . . . . . .  10
   6.  String Comparison Rules . . . . . . . . . . . . . . . . . . .  11
   7.  Encrypted JWK and Encrypted JWK Set Formats . . . . . . . . .  11
   8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  11
     8.1.  JSON Web Key Parameters Registry  . . . . . . . . . . . .  12
       8.1.1.  Registration Template . . . . . . . . . . . . . . . .  12
       8.1.2.  Initial Registry Contents . . . . . . . . . . . . . .  13
     8.2.  JSON Web Key Use Registry . . . . . . . . . . . . . . . .  15
       8.2.1.  Registration Template . . . . . . . . . . . . . . . .  15
       8.2.2.  Initial Registry Contents . . . . . . . . . . . . . .  15
     8.3.  JSON Web Key Operations Registry  . . . . . . . . . . . .  16
       8.3.1.  Registration Template . . . . . . . . . . . . . . . .  16
       8.3.2.  Initial Registry Contents . . . . . . . . . . . . . .  16
     8.4.  JSON Web Key Set Parameters Registry  . . . . . . . . . .  17
       8.4.1.  Registration Template . . . . . . . . . . . . . . . .  17
       8.4.2.  Initial Registry Contents . . . . . . . . . . . . . .  18
     8.5.  Media Type Registration . . . . . . . . . . . . . . . . .  18
       8.5.1.  Registry Contents . . . . . . . . . . . . . . . . . .  18
   9.  Security Considerations . . . . . . . . . . . . . . . . . . .  19
     9.1.  Key Provenance and Trust  . . . . . . . . . . . . . . . .  20
     9.2.  Preventing Disclosure of Non-public Key Information . . .  20
     9.3.  RSA Private Key Representations and Blinding  . . . . . .  21
     9.4.  Key Entropy and Random Values . . . . . . . . . . . . . .  21
   10. References  . . . . . . . . . . . . . . . . . . . . . . . . .  21
     10.1.  Normative References . . . . . . . . . . . . . . . . . .  21
     10.2.  Informative References . . . . . . . . . . . . . . . . .  23
   Appendix A.  Example JSON Web Key Sets  . . . . . . . . . . . . .  25
     A.1.  Example Public Keys . . . . . . . . . . . . . . . . . . .  25
     A.2.  Example Private Keys  . . . . . . . . . . . . . . . . . .  25
     A.3.  Example Symmetric Keys  . . . . . . . . . . . . . . . . .  27

Top      ToC       Page 3 
   Appendix B.  Example Use of "x5c" (X.509 Certificate Chain)
                Parameter  . . . . . . . . . . . . . . . . . . . . .  28
   Appendix C.  Example Encrypted RSA Private Key  . . . . . . . . .  28
     C.1.  Plaintext RSA Private Key . . . . . . . . . . . . . . . .  29
     C.2.  JOSE Header . . . . . . . . . . . . . . . . . . . . . . .  32
     C.3.  Content Encryption Key (CEK)  . . . . . . . . . . . . . .  32
     C.4.  Key Derivation  . . . . . . . . . . . . . . . . . . . . .  33
     C.5.  Key Encryption  . . . . . . . . . . . . . . . . . . . . .  33
     C.6.  Initialization Vector . . . . . . . . . . . . . . . . . .  33
     C.7.  Additional Authenticated Data . . . . . . . . . . . . . .  34
     C.8.  Content Encryption  . . . . . . . . . . . . . . . . . . .  34
     C.9.  Complete Representation . . . . . . . . . . . . . . . . .  38
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  40
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  40

1.  Introduction

   A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) [RFC7159]
   data structure that represents a cryptographic key.  This
   specification also defines a JWK Set JSON data structure that
   represents a set of JWKs.  Cryptographic algorithms and identifiers
   for use with this specification are described in the separate JSON
   Web Algorithms (JWA) [JWA] specification and IANA registries
   established by that specification.

   Goals for this specification do not include representing new kinds of
   certificate chains, representing new kinds of certified keys, or
   replacing X.509 certificates.

   JWKs and JWK Sets are used in the JSON Web Signature [JWS] and JSON
   Web Encryption [JWE] specifications.

   Names defined by this specification are short because a core goal is
   for the resulting representations to be compact.

1.1.  Notational Conventions

   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" [RFC2119].
   The interpretation should only be applied when the terms appear in
   all capital letters.

   BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per
   Section 2 of [JWS].

Top      ToC       Page 4 
   UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation
   of STRING, where STRING is a sequence of zero or more Unicode
   [UNICODE] characters.

   ASCII(STRING) denotes the octets of the ASCII [RFC20] representation
   of STRING, where STRING is a sequence of zero or more ASCII
   characters.

   The concatenation of two values A and B is denoted as A || B.

2.  Terminology

   The terms "JSON Web Signature (JWS)", "Base64url Encoding",
   "Collision-Resistant Name", "Header Parameter", and "JOSE Header" are
   defined by the JWS specification [JWS].

   The terms "JSON Web Encryption (JWE)", "Additional Authenticated Data
   (AAD)", "JWE Authentication Tag", "JWE Ciphertext", "JWE Compact
   Serialization", "JWE Encrypted Key", "JWE Initialization Vector", and
   "JWE Protected Header" are defined by the JWE specification [JWE].

   The terms "Ciphertext", "Digital Signature", "Message Authentication
   Code (MAC)", and "Plaintext" are defined by the "Internet Security
   Glossary, Version 2" [RFC4949].

   These terms are defined by this specification:

   JSON Web Key (JWK)
      A JSON object that represents a cryptographic key.  The members of
      the object represent properties of the key, including its value.

   JWK Set
      A JSON object that represents a set of JWKs.  The JSON object MUST
      have a "keys" member, which is an array of JWKs.

Top      ToC       Page 5 
3.  Example JWK

   This section provides an example of a JWK.  The following example JWK
   declares that the key is an Elliptic Curve [DSS] key, it is used with
   the P-256 Elliptic Curve, and its x and y coordinates are the
   base64url-encoded values shown.  A key identifier is also provided
   for the key.

     {"kty":"EC",
      "crv":"P-256",
      "x":"f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
      "y":"x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
      "kid":"Public key used in JWS spec Appendix A.3 example"
     }

   Additional example JWK values can be found in Appendix A.

4.  JSON Web Key (JWK) Format

   A JWK is a JSON object that represents a cryptographic key.  The
   members of the object represent properties of the key, including its
   value.  This JSON object MAY contain whitespace and/or line breaks
   before or after any JSON values or structural characters, in
   accordance with Section 2 of RFC 7159 [RFC7159].  This document
   defines the key parameters that are not algorithm specific and, thus,
   common to many keys.

   In addition to the common parameters, each JWK will have members that
   are key type specific.  These members represent the parameters of the
   key.  Section 6 of the JSON Web Algorithms (JWA) [JWA] specification
   defines multiple kinds of cryptographic keys and their associated
   members.

   The member names within a JWK MUST be unique; JWK parsers MUST either
   reject JWKs with duplicate member names or use a JSON parser that
   returns only the lexically last duplicate member name, as specified
   in Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript].

   Additional members can be present in the JWK; if not understood by
   implementations encountering them, they MUST be ignored.  Member
   names used for representing key parameters for different keys types
   need not be distinct.  Any new member name should either be
   registered in the IANA "JSON Web Key Parameters" registry established
   by Section 8.1 or be a value that contains a Collision-Resistant
   Name.

Top      ToC       Page 6 
4.1.  "kty" (Key Type) Parameter

   The "kty" (key type) parameter identifies the cryptographic algorithm
   family used with the key, such as "RSA" or "EC".  "kty" values should
   either be registered in the IANA "JSON Web Key Types" registry
   established by [JWA] or be a value that contains a Collision-
   Resistant Name.  The "kty" value is a case-sensitive string.  This
   member MUST be present in a JWK.

   A list of defined "kty" values can be found in the IANA "JSON Web Key
   Types" registry established by [JWA]; the initial contents of this
   registry are the values defined in Section 6.1 of [JWA].

   The key type definitions include specification of the members to be
   used for those key types.  Members used with specific "kty" values
   can be found in the IANA "JSON Web Key Parameters" registry
   established by Section 8.1.

4.2.  "use" (Public Key Use) Parameter

   The "use" (public key use) parameter identifies the intended use of
   the public key.  The "use" parameter is employed to indicate whether
   a public key is used for encrypting data or verifying the signature
   on data.

   Values defined by this specification are:

   o  "sig" (signature)
   o  "enc" (encryption)

   Other values MAY be used.  The "use" value is a case-sensitive
   string.  Use of the "use" member is OPTIONAL, unless the application
   requires its presence.

   When a key is used to wrap another key and a public key use
   designation for the first key is desired, the "enc" (encryption) key
   use value is used, since key wrapping is a kind of encryption.  The
   "enc" value is also to be used for public keys used for key agreement
   operations.

   Additional "use" (public key use) values can be registered in the
   IANA "JSON Web Key Use" registry established by Section 8.2.
   Registering any extension values used is highly recommended when this
   specification is used in open environments, in which multiple
   organizations need to have a common understanding of any extensions
   used.  However, unregistered extension values can be used in closed
   environments, in which the producing and consuming organization will
   always be the same.

Top      ToC       Page 7 
4.3.  "key_ops" (Key Operations) Parameter

   The "key_ops" (key operations) parameter identifies the operation(s)
   for which the key is intended to be used.  The "key_ops" parameter is
   intended for use cases in which public, private, or symmetric keys
   may be present.

   Its value is an array of key operation values.  Values defined by
   this specification are:

   o  "sign" (compute digital signature or MAC)
   o  "verify" (verify digital signature or MAC)
   o  "encrypt" (encrypt content)
   o  "decrypt" (decrypt content and validate decryption, if applicable)
   o  "wrapKey" (encrypt key)
   o  "unwrapKey" (decrypt key and validate decryption, if applicable)
   o  "deriveKey" (derive key)
   o  "deriveBits" (derive bits not to be used as a key)

   (Note that the "key_ops" values intentionally match the "KeyUsage"
   values defined in the Web Cryptography API
   [W3C.CR-WebCryptoAPI-20141211] specification.)

   Other values MAY be used.  The key operation values are case-
   sensitive strings.  Duplicate key operation values MUST NOT be
   present in the array.  Use of the "key_ops" member is OPTIONAL,
   unless the application requires its presence.

   Multiple unrelated key operations SHOULD NOT be specified for a key
   because of the potential vulnerabilities associated with using the
   same key with multiple algorithms.  Thus, the combinations "sign"
   with "verify", "encrypt" with "decrypt", and "wrapKey" with
   "unwrapKey" are permitted, but other combinations SHOULD NOT be used.

   Additional "key_ops" (key operations) values can be registered in the
   IANA "JSON Web Key Operations" registry established by Section 8.3.
   The same considerations about registering extension values apply to
   the "key_ops" member as do for the "use" member.

   The "use" and "key_ops" JWK members SHOULD NOT be used together;
   however, if both are used, the information they convey MUST be
   consistent.  Applications should specify which of these members they
   use, if either is to be used by the application.

Top      ToC       Page 8 
4.4.  "alg" (Algorithm) Parameter

   The "alg" (algorithm) parameter identifies the algorithm intended for
   use with the key.  The values used should either be registered in the
   IANA "JSON Web Signature and Encryption Algorithms" registry
   established by [JWA] or be a value that contains a Collision-
   Resistant Name.  The "alg" value is a case-sensitive ASCII string.
   Use of this member is OPTIONAL.

4.5.  "kid" (Key ID) Parameter

   The "kid" (key ID) parameter is used to match a specific key.  This
   is used, for instance, to choose among a set of keys within a JWK Set
   during key rollover.  The structure of the "kid" value is
   unspecified.  When "kid" values are used within a JWK Set, different
   keys within the JWK Set SHOULD use distinct "kid" values.  (One
   example in which different keys might use the same "kid" value is if
   they have different "kty" (key type) values but are considered to be
   equivalent alternatives by the application using them.)  The "kid"
   value is a case-sensitive string.  Use of this member is OPTIONAL.
   When used with JWS or JWE, the "kid" value is used to match a JWS or
   JWE "kid" Header Parameter value.

4.6.  "x5u" (X.509 URL) Parameter

   The "x5u" (X.509 URL) parameter is a URI [RFC3986] that refers to a
   resource for an X.509 public key certificate or certificate chain
   [RFC5280].  The identified resource MUST provide a representation of
   the certificate or certificate chain that conforms to RFC 5280
   [RFC5280] in PEM-encoded form, with each certificate delimited as
   specified in Section 6.1 of RFC 4945 [RFC4945].  The key in the first
   certificate MUST match the public key represented by other members of
   the JWK.  The protocol used to acquire the resource MUST provide
   integrity protection; an HTTP GET request to retrieve the certificate
   MUST use TLS [RFC2818] [RFC5246]; the identity of the server MUST be
   validated, as per Section 6 of RFC 6125 [RFC6125].  Use of this
   member is OPTIONAL.

   While there is no requirement that optional JWK members providing key
   usage, algorithm, or other information be present when the "x5u"
   member is used, doing so may improve interoperability for
   applications that do not handle PKIX certificates [RFC5280].  If
   other members are present, the contents of those members MUST be
   semantically consistent with the related fields in the first
   certificate.  For instance, if the "use" member is present, then it
   MUST correspond to the usage that is specified in the certificate,

Top      ToC       Page 9 
   when it includes this information.  Similarly, if the "alg" member is
   present, it MUST correspond to the algorithm specified in the
   certificate.

4.7.  "x5c" (X.509 Certificate Chain) Parameter

   The "x5c" (X.509 certificate chain) parameter contains a chain of one
   or more PKIX certificates [RFC5280].  The certificate chain is
   represented as a JSON array of certificate value strings.  Each
   string in the array is a base64-encoded (Section 4 of [RFC4648] --
   not base64url-encoded) DER [ITU.X690.1994] PKIX certificate value.
   The PKIX certificate containing the key value MUST be the first
   certificate.  This MAY be followed by additional certificates, with
   each subsequent certificate being the one used to certify the
   previous one.  The key in the first certificate MUST match the public
   key represented by other members of the JWK.  Use of this member is
   OPTIONAL.

   As with the "x5u" member, optional JWK members providing key usage,
   algorithm, or other information MAY also be present when the "x5c"
   member is used.  If other members are present, the contents of those
   members MUST be semantically consistent with the related fields in
   the first certificate.  See the last paragraph of Section 4.6 for
   additional guidance on this.

4.8.  "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter

   The "x5t" (X.509 certificate SHA-1 thumbprint) parameter is a
   base64url-encoded SHA-1 thumbprint (a.k.a. digest) of the DER
   encoding of an X.509 certificate [RFC5280].  Note that certificate
   thumbprints are also sometimes known as certificate fingerprints.
   The key in the certificate MUST match the public key represented by
   other members of the JWK.  Use of this member is OPTIONAL.

   As with the "x5u" member, optional JWK members providing key usage,
   algorithm, or other information MAY also be present when the "x5t"
   member is used.  If other members are present, the contents of those
   members MUST be semantically consistent with the related fields in
   the referenced certificate.  See the last paragraph of Section 4.6
   for additional guidance on this.

Top      ToC       Page 10 
4.9.  "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Parameter

   The "x5t#S256" (X.509 certificate SHA-256 thumbprint) parameter is a
   base64url-encoded SHA-256 thumbprint (a.k.a. digest) of the DER
   encoding of an X.509 certificate [RFC5280].  Note that certificate
   thumbprints are also sometimes known as certificate fingerprints.
   The key in the certificate MUST match the public key represented by
   other members of the JWK.  Use of this member is OPTIONAL.

   As with the "x5u" member, optional JWK members providing key usage,
   algorithm, or other information MAY also be present when the
   "x5t#S256" member is used.  If other members are present, the
   contents of those members MUST be semantically consistent with the
   related fields in the referenced certificate.  See the last paragraph
   of Section 4.6 for additional guidance on this.

5.  JWK Set Format

   A JWK Set is a JSON object that represents a set of JWKs.  The JSON
   object MUST have a "keys" member, with its value being an array of
   JWKs.  This JSON object MAY contain whitespace and/or line breaks.

   The member names within a JWK Set MUST be unique; JWK Set parsers
   MUST either reject JWK Sets with duplicate member names or use a JSON
   parser that returns only the lexically last duplicate member name, as
   specified in Section 15.12 ("The JSON Object") of ECMAScript 5.1
   [ECMAScript].

   Additional members can be present in the JWK Set; if not understood
   by implementations encountering them, they MUST be ignored.
   Parameters for representing additional properties of JWK Sets should
   either be registered in the IANA "JSON Web Key Set Parameters"
   registry established by Section 8.4 or be a value that contains a
   Collision-Resistant Name.

   Implementations SHOULD ignore JWKs within a JWK Set that use "kty"
   (key type) values that are not understood by them, that are missing
   required members, or for which values are out of the supported
   ranges.

5.1.  "keys" Parameter

   The value of the "keys" parameter is an array of JWK values.  By
   default, the order of the JWK values within the array does not imply
   an order of preference among them, although applications of JWK Sets
   can choose to assign a meaning to the order for their purposes, if
   desired.

Top      ToC       Page 11 
6.  String Comparison Rules

   The string comparison rules for this specification are the same as
   those defined in Section 5.3 of [JWS].

7.  Encrypted JWK and Encrypted JWK Set Formats

   Access to JWKs containing non-public key material by parties without
   legitimate access to the non-public information MUST be prevented.
   This can be accomplished by encrypting the JWK when potentially
   observable by such parties to prevent the disclosure of private or
   symmetric key values.  The use of an Encrypted JWK, which is a JWE
   with the UTF-8 encoding of a JWK as its plaintext value, is
   recommended for this purpose.  The processing of Encrypted JWKs is
   identical to the processing of other JWEs.  A "cty" (content type)
   Header Parameter value of "jwk+json" MUST be used to indicate that
   the content of the JWE is a JWK, unless the application knows that
   the encrypted content is a JWK by another means or convention, in
   which case the "cty" value would typically be omitted.

   JWK Sets containing non-public key material will also need to be
   encrypted under these circumstances.  The use of an Encrypted JWK
   Set, which is a JWE with the UTF-8 encoding of a JWK Set as its
   plaintext value, is recommended for this purpose.  The processing of
   Encrypted JWK Sets is identical to the processing of other JWEs.  A
   "cty" (content type) Header Parameter value of "jwk-set+json" MUST be
   used to indicate that the content of the JWE is a JWK Set, unless the
   application knows that the encrypted content is a JWK Set by another
   means or convention, in which case the "cty" value would typically be
   omitted.

   See Appendix C for an example encrypted JWK.

8.  IANA Considerations

   The following registration procedure is used for all the registries
   established by this specification.

   The registration procedure for values is Specification Required
   [RFC5226] after a three-week review period on the
   jose-reg-review@ietf.org mailing list, on the advice of one or more
   Designated Experts.  However, to allow for the allocation of values
   prior to publication, the Designated Experts may approve registration
   once they are satisfied that such a specification will be published.

   Registration requests sent to the mailing list for review should use
   an appropriate subject (e.g., "Request to register JWK parameter:
   example").

Top      ToC       Page 12 
   Within the review period, the Designated Experts will either approve
   or deny the registration request, communicating this decision to the
   review list and IANA.  Denials should include an explanation and, if
   applicable, suggestions as to how to make the request successful.
   Registration requests that are undetermined for a period longer than
   21 days can be brought to the IESG's attention (using the
   iesg@ietf.org mailing list) for resolution.

   Criteria that should be applied by the Designated Experts include
   determining whether the proposed registration duplicates existing
   functionality, whether it is likely to be of general applicability or
   useful only for a single application, and whether the registration
   description is clear.

   IANA must only accept registry updates from the Designated Experts
   and should direct all requests for registration to the review mailing
   list.

   It is suggested that multiple Designated Experts be appointed who are
   able to represent the perspectives of different applications using
   this specification, in order to enable broadly informed review of
   registration decisions.  In cases where a registration decision could
   be perceived as creating a conflict of interest for a particular
   Expert, that Expert should defer to the judgment of the other
   Experts.

8.1.  JSON Web Key Parameters Registry

   This section establishes the IANA "JSON Web Key Parameters" registry
   for JWK parameter names.  The registry records the parameter name,
   the key type(s) that the parameter is used with, and a reference to
   the specification that defines it.  It also records whether the
   parameter conveys public or private information.  This section
   registers the parameter names defined in Section 4.  The same JWK
   parameter name may be registered multiple times, provided that
   duplicate parameter registrations are only for key-type-specific JWK
   parameters; in this case, the meaning of the duplicate parameter name
   is disambiguated by the "kty" value of the JWK containing it.

8.1.1.  Registration Template

   Parameter Name:
      The name requested (e.g., "kid").  Because a core goal of this
      specification is for the resulting representations to be compact,
      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.  Names may not match other registered names in a
      case-insensitive manner unless the Designated Experts state that

Top      ToC       Page 13 
      there is a compelling reason to allow an exception.  However,
      matching names may be registered, provided that the accompanying
      sets of "kty" values that the parameter name is used with are
      disjoint; for the purposes of matching "kty" values, "*" matches
      all values.

   Parameter Description:
      Brief description of the parameter (e.g., "Key ID").

   Used with "kty" Value(s):
      The key type parameter value(s) that the parameter name is to be
      used with, or the value "*" if the parameter value is used with
      all key types.  Values may not match other registered "kty" values
      in a case-insensitive manner when the registered parameter name is
      the same (including when the parameter name matches in a case-
      insensitive manner) unless the Designated Experts state that there
      is a compelling reason to allow an exception.

   Parameter Information Class:
      Registers whether the parameter conveys public or private
      information.  Its value must be either Public or Private.

   Change Controller:
      For Standards Track RFCs, list the "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 or documents that specify the parameter,
      preferably including URIs that can be used to retrieve copies of
      the documents.  An indication of the relevant sections may also be
      included but is not required.

8.1.2.  Initial Registry Contents

   o  Parameter Name: "kty"
   o  Parameter Description: Key Type
   o  Used with "kty" Value(s): *
   o  Parameter Information Class: Public
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.1 of RFC 7517

   o  Parameter Name: "use"
   o  Parameter Description: Public Key Use
   o  Used with "kty" Value(s): *
   o  Parameter Information Class: Public
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.2 of RFC 7517

Top      ToC       Page 14 
   o  Parameter Name: "key_ops"
   o  Parameter Description: Key Operations
   o  Used with "kty" Value(s): *
   o  Parameter Information Class: Public
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.3 of RFC 7517

   o  Parameter Name: "alg"
   o  Parameter Description: Algorithm
   o  Used with "kty" Value(s): *
   o  Parameter Information Class: Public
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.4 of RFC 7517

   o  Parameter Name: "kid"
   o  Parameter Description: Key ID
   o  Used with "kty" Value(s): *
   o  Parameter Information Class: Public
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.5 of RFC 7517

   o  Parameter Name: "x5u"
   o  Parameter Description: X.509 URL
   o  Used with "kty" Value(s): *
   o  Parameter Information Class: Public
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.6 of RFC 7517

   o  Parameter Name: "x5c"
   o  Parameter Description: X.509 Certificate Chain
   o  Used with "kty" Value(s): *
   o  Parameter Information Class: Public
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.7 of RFC 7517

   o  Parameter Name: "x5t"
   o  Parameter Description: X.509 Certificate SHA-1 Thumbprint
   o  Used with "kty" Value(s): *
   o  Parameter Information Class: Public
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.8 of RFC 7517

   o  Parameter Name: "x5t#S256"
   o  Parameter Description: X.509 Certificate SHA-256 Thumbprint
   o  Used with "kty" Value(s): *
   o  Parameter Information Class: Public
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.9 of RFC 7517

Top      ToC       Page 15 
8.2.  JSON Web Key Use Registry

   This section establishes the IANA "JSON Web Key Use" registry for JWK
   "use" (public key use) member values.  The registry records the
   public key use value and a reference to the specification that
   defines it.  This section registers the parameter names defined in
   Section 4.2.

8.2.1.  Registration Template

   Use Member Value:
      The name requested (e.g., "sig").  Because a core goal of this
      specification is for the resulting representations to be compact,
      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.  Names may not match other registered names in a
      case-insensitive manner unless the Designated Experts state that
      there is a compelling reason to allow an exception.

   Use Description:
      Brief description of the use (e.g., "Digital Signature or MAC").

   Change Controller:
      For Standards Track RFCs, list the "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 or documents that specify the parameter,
      preferably including URIs that can be used to retrieve copies of
      the documents.  An indication of the relevant sections may also be
      included but is not required.

8.2.2.  Initial Registry Contents

   o  Use Member Value: "sig"
   o  Use Description: Digital Signature or MAC
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.2 of RFC 7517

   o  Use Member Value: "enc"
   o  Use Description: Encryption
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.2 of RFC 7517

Top      ToC       Page 16 
8.3.  JSON Web Key Operations Registry

   This section establishes the IANA "JSON Web Key Operations" registry
   for values of JWK "key_ops" array elements.  The registry records the
   key operation value and a reference to the specification that defines
   it.  This section registers the parameter names defined in
   Section 4.3.

8.3.1.  Registration Template

   Key Operation Value:
      The name requested (e.g., "sign").  Because a core goal of this
      specification is for the resulting representations to be compact,
      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.  Names may not match other registered names in a
      case-insensitive manner unless the Designated Experts state that
      there is a compelling reason to allow an exception.

   Key Operation Description:
      Brief description of the key operation (e.g., "Compute digital
      signature or MAC").

   Change Controller:
      For Standards Track RFCs, list the "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 or documents that specify the parameter,
      preferably including URIs that can be used to retrieve copies of
      the documents.  An indication of the relevant sections may also be
      included but is not required.

8.3.2.  Initial Registry Contents

   o  Key Operation Value: "sign"
   o  Key Operation Description: Compute digital signature or MAC
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.3 of RFC 7517

   o  Key Operation Value: "verify"
   o  Key Operation Description: Verify digital signature or MAC
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.3 of RFC 7517

Top      ToC       Page 17 
   o  Key Operation Value: "encrypt"
   o  Key Operation Description: Encrypt content
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.3 of RFC 7517

   o  Key Operation Value: "decrypt"
   o  Key Operation Description: Decrypt content and validate
      decryption, if applicable
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.3 of RFC 7517

   o  Key Operation Value: "wrapKey"
   o  Key Operation Description: Encrypt key
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.3 of RFC 7517

   o  Key Operation Value: "unwrapKey"
   o  Key Operation Description: Decrypt key and validate decryption, if
      applicable
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.3 of RFC 7517

   o  Key Operation Value: "deriveKey"
   o  Key Operation Description: Derive key
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.3 of RFC 7517
   o  Key Operation Value: "deriveBits"
   o  Key Operation Description: Derive bits not to be used as a key
   o  Change Controller: IESG
   o  Specification Document(s): Section 4.3 of RFC 7517

8.4.  JSON Web Key Set Parameters Registry

   This section establishes the IANA "JSON Web Key Set Parameters"
   registry for JWK Set parameter names.  The registry records the
   parameter name and a reference to the specification that defines it.
   This section registers the parameter names defined in Section 5.

8.4.1.  Registration Template

   Parameter Name:
      The name requested (e.g., "keys").  Because a core goal of this
      specification is for the resulting representations to be compact,
      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.  Names may not match other registered names in a
      case-insensitive manner unless the Designated Experts state that
      there is a compelling reason to allow an exception.

Top      ToC       Page 18 
   Parameter Description:
      Brief description of the parameter (e.g., "Array of JWK values").

   Change Controller:
      For Standards Track RFCs, list the "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 or documents that specify the parameter,
      preferably including URIs that can be used to retrieve copies of
      the documents.  An indication of the relevant sections may also be
      included but is not required.

8.4.2.  Initial Registry Contents

   o  Parameter Name: "keys"
   o  Parameter Description: Array of JWK Values
   o  Change Controller: IESG
   o  Specification Document(s): Section 5.1 of RFC 7517

8.5.  Media Type Registration

8.5.1.  Registry Contents

   This section registers the "application/jwk+json" and "application/
   jwk-set+json" media types [RFC2046] in the "Media Types" registry
   [IANA.MediaTypes] in the manner described in RFC 6838 [RFC6838],
   which can be used to indicate that the content is a JWK or a JWK Set,
   respectively.

   o  Type Name: application
   o  Subtype Name: jwk+json
   o  Required Parameters: n/a
   o  Optional Parameters: n/a
   o  Encoding considerations: 8bit; application/jwk+json values are
      represented as a JSON object; UTF-8 encoding SHOULD be employed
      for the JSON object.
   o  Security Considerations: See the Security Considerations section
      of RFC 7517.
   o  Interoperability Considerations: n/a
   o  Published Specification: RFC 7517
   o  Applications that use this media type: OpenID Connect, Salesforce,
      Google, Android, Windows Azure, W3C WebCrypto API, numerous others
   o  Fragment identifier considerations: n/a

Top      ToC       Page 19 
   o  Additional Information:

         Magic number(s): n/a
         File extension(s): n/a
         Macintosh file type code(s): n/a

   o  Person & email address to contact for further information:
      Michael B.  Jones, mbj@microsoft.com
   o  Intended Usage: COMMON
   o  Restrictions on Usage: none
   o  Author: Michael B.  Jones, mbj@microsoft.com
   o  Change Controller: IESG
   o  Provisional registration?  No

   o  Type Name: application
   o  Subtype Name: jwk-set+json
   o  Required Parameters: n/a
   o  Optional Parameters: n/a
   o  Encoding considerations: 8bit; application/jwk-set+json values are
      represented as a JSON Object; UTF-8 encoding SHOULD be employed
      for the JSON object.
   o  Security Considerations: See the Security Considerations section
      of RFC 7517.
   o  Interoperability Considerations: n/a
   o  Published Specification: RFC 7517
   o  Applications that use this media type: OpenID Connect, Salesforce,
      Google, Android, Windows Azure, W3C WebCrypto API, numerous others
   o  Fragment identifier considerations: n/a
   o  Additional Information:

         Magic number(s): n/a
         File extension(s): n/a
         Macintosh file type code(s): n/a

   o  Person & email address to contact for further information:
      Michael B.  Jones, mbj@microsoft.com
   o  Intended Usage: COMMON
   o  Restrictions on Usage: none
   o  Author: Michael B.  Jones, mbj@microsoft.com
   o  Change Controller: IESG
   o  Provisional registration?  No

9.  Security Considerations

   All of the security issues that are pertinent to any cryptographic
   application must be addressed by JWS/JWE/JWK agents.  Among these
   issues are protecting the user's asymmetric private and symmetric
   secret keys and employing countermeasures to various attacks.

Top      ToC       Page 20 
9.1.  Key Provenance and Trust

   One should place no more trust in the data cryptographically secured
   by a key than in the method by which it was obtained and in the
   trustworthiness of the entity asserting an association with the key.
   Any data associated with a key that is obtained in an untrusted
   manner should be treated with skepticism.  See Section 10.3 of [JWS]
   for security considerations on key origin authentication.

   In almost all cases, applications make decisions about whether to
   trust a key based on attributes bound to the key, such as names,
   roles, and the key origin, rather than based on the key itself.  When
   an application is deciding whether to trust a key, there are several
   ways that it can bind attributes to a JWK.  Two example mechanisms
   are PKIX [RFC5280] and JSON Web Token (JWT) [JWT].

   For instance, the creator of a JWK can include a PKIX certificate in
   the JWK's "x5c" member.  If the application validates the certificate
   and verifies that the JWK corresponds to the subject public key in
   the certificate, then the JWK can be associated with the attributes
   in the certificate, such as the subject name, subject alternative
   names, extended key usages, and its signature chain.

   As another example, a JWT can be used to associate attributes with a
   JWK by referencing the JWK as a claim in the JWT.  The JWK can be
   included directly as a claim value or the JWT can include a TLS-
   secured URI from which to retrieve the JWK value.  Either way, an
   application that gets a JWK via a JWT claim can associate it with the
   JWT's cryptographic properties and use these and possibly additional
   claims in deciding whether to trust the key.

   The security considerations in Section 12.3 of XML DSIG 2.0
   [W3C.NOTE-xmldsig-core2-20130411] about the strength of a digital
   signature depending upon all the links in the security chain also
   apply to this specification.

   The TLS Requirements in Section 8 of [JWS] also apply to this
   specification, except that the "x5u" JWK member is the only feature
   defined by this specification using TLS.

9.2.  Preventing Disclosure of Non-public Key Information

   Private and symmetric keys MUST be protected from disclosure to
   unintended parties.  One recommended means of doing so is to encrypt
   JWKs or JWK Sets containing them by using the JWK or JWK Set value as
   the plaintext of a JWE.  Of course, this requires that there be a

Top      ToC       Page 21 
   secure way to obtain the key used to encrypt the non-public key
   information to the intended party and a secure way for that party to
   obtain the corresponding decryption key.

   The security considerations in RFC 3447 [RFC3447] and RFC 6030
   [RFC6030] about protecting private and symmetric keys, key usage, and
   information leakage also apply to this specification.

9.3.  RSA Private Key Representations and Blinding

   The RSA Key blinding operation [Kocher], which is a defense against
   some timing attacks, requires all of the RSA key values "n", "e", and
   "d".  However, some RSA private key representations do not include
   the public exponent "e", but only include the modulus "n" and the
   private exponent "d".  This is true, for instance, of the Java
   RSAPrivateKeySpec API, which does not include the public exponent "e"
   as a parameter.  So as to enable RSA key blinding, such
   representations should be avoided.  For Java, the
   RSAPrivateCrtKeySpec API can be used instead.  Section 8.2.2(i) of
   the "Handbook of Applied Cryptography" [HAC] discusses how to compute
   the remaining RSA private key parameters, if needed, using only "n",
   "e", and "d".

9.4.  Key Entropy and Random Values

   See Section 10.1 of [JWS] for security considerations on key entropy
   and random values.



(page 21 continued on part 2)

Next RFC Part