JOSE Working Group M. Jones
Internet-Draft Microsoft
Intended status: Standards Track October 24, 2014
Expires: April 27, 2015
JSON Web Key (JWK)draft-ietf-jose-json-web-key-36
Abstract
A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data
structure that represents a cryptographic key. This specification
also defines a JSON Web Key Set (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 defined by
that specification.
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 April 27, 2015.
Copyright Notice
Copyright (c) 2014 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
Jones Expires April 27, 2015 [Page 1]

Internet-Draft JWK October 20141. 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 JSON Web Key Set (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 defined 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) [JWS] and
JSON Web Encryption (JWE) [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]. If
these words are used without being spelled in uppercase then they are
to be interpreted with their normal natural language meanings.
BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per
Section 2 of [JWS].
UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation
of STRING.
ASCII(STRING) denotes the octets of the ASCII [RFC20] representation
of STRING.
The concatenation of two values A and B is denoted as A || B.
2. Terminology
These terms defined by the JSON Web Signature (JWS) [JWS]
specification are incorporated into this specification: "Base64url
Encoding", "Collision-Resistant Name", "Header Parameter", and "JOSE
Header".
Jones Expires April 27, 2015 [Page 4]

Internet-Draft JWK October 2014
These terms defined by the Internet Security Glossary, Version 2
[RFC4949] are incorporated into this specification: "Ciphertext",
"Digital Signature", "Message Authentication Code (MAC)", and
"Plaintext".
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.
JSON Web Key Set (JWK Set)
A JSON object that represents a set of JWKs. The JSON object MUST
have a "keys" member, which is an array of JWK objects.
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 A.3 example"
}
Additional example JWK values can be found in Appendix A.
4. JSON Web Key (JWK) Format
A JSON Web Key (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 white space 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
Jones Expires April 27, 2015 [Page 5]

Internet-Draft JWK October 2014
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 defined in
Section 8.1 or be a value that contains a Collision-Resistant Name.
4.1. "kty" (Key Type) Parameter
The "kty" (key type) member 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 defined
in [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 defined in [JWA]; the initial contents of this
registry are the values defined in Section 6.1 of the JSON Web
Algorithms (JWA) [JWA] specification.
The key type definitions include specification of the members to be
used for those key types. Additional members used with "kty" values
can also be found in the IANA JSON Web Key Parameters registry
defined in Section 8.1.
4.2. "use" (Public Key Use) Parameter
The "use" (public key use) member 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.
Jones Expires April 27, 2015 [Page 6]

Internet-Draft JWK October 2014
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 be used for public keys used for key agreement
operations.
Additional Public Key Use values can be registered in the IANA JSON
Web Key Use registry defined in 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.
4.3. "key_ops" (Key Operations) Parameter
The "key_ops" (key operations) member identifies the operation(s)
that the key is intended to be used for. 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 [WebCrypto]
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.
Jones Expires April 27, 2015 [Page 7]

Internet-Draft JWK October 2014
Additional Key Operations values can be registered in the IANA JSON
Web Key Operations registry defined in 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.
4.4. "alg" (Algorithm) Parameter
The "alg" (algorithm) member 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 defined in
[JWA] or be a value that contains a Collision-Resistant Name. Use of
this member is OPTIONAL.
4.5. "kid" (Key ID) Parameter
The "kid" (key ID) member 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) member 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.
Jones Expires April 27, 2015 [Page 8]

Internet-Draft JWK October 2014
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. 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, 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) member 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 ([RFC4648] Section 4 -- 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) member 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.
Jones Expires April 27, 2015 [Page 9]

Internet-Draft JWK October 20144.9. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Parameter
The "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) member 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. JSON Web Key Set (JWK Set) Format
A JSON Web Key Set (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 JWK objects. This JSON object MAY contain white
space 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
defined in 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, are missing
required members, or for which values are out of the supported
ranges.
5.1. "keys" Parameter
The value of the "keys" member 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
Jones Expires April 27, 2015 [Page 10]

Internet-Draft JWK October 2014
desired.
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.
Values are registered on a Specification Required [RFC5226] basis
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 Expert(s) may approve registration once they are
Jones Expires April 27, 2015 [Page 11]

Internet-Draft JWK October 2014
satisfied that such a specification will be published.
Registration requests must be sent to the jose-reg-review@ietf.org
mailing list for review and comment, with an appropriate subject
(e.g., "Request for access token type: example").
Within the review period, the Designated Expert(s) 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 Expert(s) includes
determining whether the proposed registration duplicates existing
functionality, determining whether it is likely to be of general
applicability or whether it is useful only for a single application,
and whether the registration description is clear.
IANA must only accept registry updates from the Designated Expert(s)
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
Expert(s).
[[ Note to the RFC Editor and IANA: Pearl Liang of ICANN had
requested that the draft supply the following proposed registry
description information. It is to be used for all registries
established by this specification.
o Protocol Category: JSON Object Signing and Encryption (JOSE)
o Registry Location: http://www.iana.org/assignments/jose
o Webpage Title: (same as the protocol category)
o Registry Name: (same as the section title, but excluding the word
"Registry", for example "JSON Web Key Parameters")
]]
Jones Expires April 27, 2015 [Page 12]

Internet-Draft JWK October 20148.1. JSON Web Key Parameters Registry
This specification 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
specification 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 Expert(s) state that
there is a compelling reason to allow an exception in this
particular case. 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 Expert(s) state that
there is a compelling reason to allow an exception in this
particular case.
Parameter Information Class:
Registers whether the parameter conveys public or private
information. Its value must be one the words Public or Private.
Jones Expires April 27, 2015 [Page 13]

Internet-Draft JWK October 2014
particular case.
Use Description:
Brief description of the use (e.g., "Digital Signature or MAC").
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 parameter,
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 Use Member Value: "sig"
o Use Description: Digital Signature or MAC
o Change Controller: IESG
o Specification Document(s): Section 4.2 of [[ this document ]]
o Use Member Value: "enc"
o Use Description: Encryption
o Change Controller: IESG
o Specification Document(s): Section 4.2 of [[ this document ]]
8.3. JSON Web Key Operations Registry
This specification 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 specification 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 Expert(s) state that
there is a compelling reason to allow an exception in this
particular case.
Jones Expires April 27, 2015 [Page 16]

Internet-Draft JWK October 2014
o Change Controller: IESG
o Specification Document(s): Section 4.3 of [[ this document ]]
o Key Operation Value: "deriveKey"
o Key Operation Description: Derive key
o Change Controller: IESG
o Specification Document(s): Section 4.3 of [[ this document ]]
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 [[ this document ]]
8.4. JSON Web Key Set Parameters Registry
This specification 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 specification 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 Expert(s) state that
there is a compelling reason to allow an exception in this
particular case.
Parameter Description:
Brief description of the parameter (e.g., "Array of JWK values").
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 parameter,
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.
Jones Expires April 27, 2015 [Page 18]

Internet-Draft JWK October 2014
o Security Considerations: See the Security Considerations section
of [[ this document ]]
o Interoperability Considerations: n/a
o Published Specification: [[ this document ]]
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.
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.
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.
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
Jones Expires April 27, 2015 [Page 20]

Internet-Draft JWK October 2014
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.
10. References10.1. Normative References
[ECMAScript]
Ecma International, "ECMAScript Language Specification,
5.1 Edition", ECMA 262, June 2011.
[IANA.MediaTypes]
Internet Assigned Numbers Authority (IANA), "MIME Media
Types", 2005.
[ITU.X690.1994]
International Telecommunications Union, "Information
Technology - ASN.1 encoding rules: Specification of Basic
Encoding Rules (BER), Canonical Encoding Rules (CER) and
Distinguished Encoding Rules (DER)", ITU-T Recommendation
X.690, 1994.
Jones Expires April 27, 2015 [Page 21]

Internet-Draft JWK October 2014
<http://www.w3.org/TR/2013/NOTE-xmldsig-core2-20130411/>.
[WebCrypto]
Sleevi, R. and M. Watson, "Web Cryptography API", World
Wide Web Consortium Draft, March 2014,
<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/>.
Appendix A. Example JSON Web Key SetsA.1. Example Public Keys
The following example JWK Set contains two public keys represented as
JWKs: one using an Elliptic Curve algorithm and a second one using an
RSA algorithm. The first specifies that the key is to be used for
encryption. The second specifies that the key is to be used with the
"RS256" algorithm. Both provide a Key ID for key matching purposes.
In both cases, integers are represented using the base64url encoding
of their big endian representations. (Long lines are broken are for
display purposes only.)
{"keys":
[
{"kty":"EC",
"crv":"P-256",
"x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
"y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
"use":"enc",
"kid":"1"},
{"kty":"RSA",
"n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx
4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs
tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2
QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI
SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb
w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
"e":"AQAB",
"alg":"RS256",
"kid":"2011-04-29"}
]
}
A.2. Example Private Keys
The following example JWK Set contains two keys represented as JWKs
containing both public and private key values: one using an Elliptic
Curve algorithm and a second one using an RSA algorithm. This
Jones Expires April 27, 2015 [Page 24]

Internet-Draft JWK October 2014A.3. Example Symmetric Keys
The following example JWK Set contains two symmetric keys represented
as JWKs: one designated as being for use with the AES Key Wrap
algorithm and a second one that is an HMAC key. (Line breaks are for
display purposes only.)
{"keys":
[
{"kty":"oct",
"alg":"A128KW",
"k":"GawgguFyGrWKav7AX4VKUg"},
{"kty":"oct",
"k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75
aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow",
"kid":"HMAC key used in JWS A.1 example"}
]
}
Appendix B. Example Use of "x5c" (X.509 Certificate Chain) ParameterJones Expires April 27, 2015 [Page 26]

Internet-Draft JWK October 2014
[MagicSignatures].
Thanks to Matt Miller for creating the encrypted key example and to
Edmund Jay and Brian Campbell for validating the example.
This specification is the work of the JOSE Working Group, which
includes dozens of active and dedicated participants. In particular,
the following individuals contributed ideas, feedback, and wording
that influenced this specification:
Dirk Balfanz, Richard Barnes, John Bradley, Brian Campbell, Breno de
Medeiros, Stephen Farrell, Joe Hildebrand, Edmund Jay, Stephen Kent,
Ben Laurie, James Manger, Matt Miller, Kathleen Moriarty, Chuck
Mortimore, Tony Nadalin, Axel Nennker, John Panzer, Eric Rescorla,
Pete Resnick, Nat Sakimura, Jim Schaad, Ryan Sleevi, Paul Tarjan,
Hannes Tschofenig, and Sean Turner.
Jim Schaad and Karen O'Donoghue chaired the JOSE working group and
Sean Turner, Stephen Farrell, and Kathleen Moriarty served as
Security area directors during the creation of this specification.
Appendix E. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]]
-36
o Stated that if both "use" and "key_ops" are used, the information
they convey MUST be consistent.
o Clarified where white space and line breaks may occur in JSON
objects by referencing Section 2 of RFC 7159.
o Specified that registration reviews occur on the
jose-reg-review@ietf.org mailing list.
-35
o Used real values for examples in the IANA Registration Templates.
-34
o Addressed IESG review comments by Pete Resnick, Stephen Farrell,
and Richard Barnes.
o Referenced RFC 4945 for PEM certificate delimiter syntax.
Jones Expires April 27, 2015 [Page 38]

Internet-Draft JWK October 2014
-33
o Addressed secdir review comments by Stephen Kent for which
resolutions had mistakenly been omitted in the previous draft.
o Acknowledged additional contributors.
-32
o Addressed Gen-ART review comments by Russ Housley.
o Addressed secdir review comments by Stephen Kent.
-31
o No changes were made, other than to the version number and date.
-30
o Added references and cleaned up the reference syntax in a few
places.
o Applied minor wording changes to the Security Considerations
section.
-29
o Replaced the terms JWS Header, JWE Header, and JWT Header with a
single JOSE Header term defined in the JWS specification. This
also enabled a single Header Parameter definition to be used and
reduced other areas of duplication between specifications.
-28
o Revised the introduction to the Security Considerations section.
o Refined the text about when applications using encrypted JWKs and
JWK Sets would not need to use the "cty" header parameter.
-27
o Added an example JWK early in the draft.
o Described additional security considerations.
o Added the "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) JWK
member.
Jones Expires April 27, 2015 [Page 39]

Internet-Draft JWK October 2014
-20
o Renamed "use_details" to "key_ops" (key operations).
o Clarified that "use" is meant for public key use cases, "key_ops"
is meant for use cases in which public, private, or symmetric keys
may be present, and that "use" and "key_ops" should not be used
together.
o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis,
addressing issue #90.
-19
o Added optional "use_details" (key use details) JWK member.
o Reordered the key selection parameters.
-18
o Changes to address editorial and minor issues #68, #69, #73, #74,
#76, #77, #78, #79, #82, #85, #89, and #135.
o Added and used Description registry fields.
-17
o Refined the "typ" and "cty" definitions to always be MIME Media
Types, with the omission of "application/" prefixes recommended
for brevity, addressing issue #50.
o Added an example encrypting an RSA private key with
"PBES2-HS256+A128KW" and "A128CBC-HS256". Thanks to Matt Miller
for producing this!
o Processing rules occurring in both JWS and JWK are now referenced
in JWS by JWK, rather than duplicated, addressing issue #57.
o Terms used in multiple documents are now defined in one place and
incorporated by reference. Some lightly used or obvious terms
were also removed. This addresses issue #58.
-16
o Changes to address editorial and minor issues #41, #42, #43, #47,
#51, #67, #71, #76, #80, #83, #84, #85, #86, #87, and #88.
-15
Jones Expires April 27, 2015 [Page 41]

Internet-Draft JWK October 2014
o Changes to address editorial issues #48, #64, #65, #66, and #91.
-14
o Relaxed language introducing key parameters since some parameters
are applicable to multiple, but not all, key types.
-13
o Applied spelling and grammar corrections.
-12
o Stated that recipients MUST either reject JWKs and JWK Sets with
duplicate member names or use a JSON parser that returns only the
lexically last duplicate member name.
-11
o Stated that when "kid" values are used within a JWK Set, different
keys within the JWK Set SHOULD use distinct "kid" values.
o Added optional "x5u" (X.509 URL), "x5t" (X.509 Certificate
Thumbprint), and "x5c" (X.509 Certificate Chain) JWK parameters.
o Added section on Encrypted JWK and Encrypted JWK Set Formats.
o Added a Parameter Information Class value to the JSON Web Key
Parameters registry, which registers whether the parameter conveys
public or private information.
o Registered "application/jwk+json" and "application/jwk-set+json"
MIME types and "JWK" and "JWK-SET" typ header parameter values,
addressing issue #21.
-10
o No changes were made, other than to the version number and date.
-09
o Expanded the scope of the JWK specification to include private and
symmetric key representations, as specified by
draft-jones-jose-json-private-and-symmetric-key-00.
o Defined that members that are not understood must be ignored.
-08
Jones Expires April 27, 2015 [Page 42]

Internet-Draft JWK October 2014
o Changed the name of the JWK key type parameter from "alg" to "kty"
to enable use of "alg" to indicate the particular algorithm that
the key is intended to be used with.
o Clarified statements of the form "This member is OPTIONAL" to "Use
of this member is OPTIONAL".
o Referenced String Comparison Rules in JWS.
o Added seriesInfo information to Internet Draft references.
-07
o Changed the name of the JWK RSA modulus parameter from "mod" to
"n" and the name of the JWK RSA exponent parameter from "xpo" to
"e", so that the identifiers are the same as those used in RFC3447.
-06
o Changed the name of the JWK RSA exponent parameter from "exp" to
"xpo" so as to allow the potential use of the name "exp" for a
future extension that might define an expiration parameter for
keys. (The "exp" name is already used for this purpose in the JWT
specification.)
o Clarify that the "alg" (algorithm family) member is REQUIRED.
o Correct an instance of "JWK" that should have been "JWK Set".
o Applied changes made by the RFC Editor to RFC 6749's registry
language to this specification.
-05
o Indented artwork elements to better distinguish them from the body
text.
-04
o Refer to the registries as the primary sources of defined values
and then secondarily reference the sections defining the initial
contents of the registries.
o Normatively reference XML DSIG 2.0 for its security
considerations.
Jones Expires April 27, 2015 [Page 43]

Internet-Draft JWK October 2014
o Added this language to Registration Templates: "This name is case
sensitive. Names that match other registered names in a case
insensitive manner SHOULD NOT be accepted."
o Described additional open issues.
o Applied editorial suggestions.
-03
o Clarified that "kid" values need not be unique within a JWK Set.
o Moved JSON Web Key Parameters registry to the JWK specification.
o Added "Collision Resistant Namespace" to the terminology section.
o Changed registration requirements from RFC Required to
Specification Required with Expert Review.
o Added Registration Template sections for defined registries.
o Added Registry Contents sections to populate registry values.
o Numerous editorial improvements.
-02
o Simplified JWK terminology to get replace the "JWK Key Object" and
"JWK Container Object" terms with simply "JSON Web Key (JWK)" and
"JSON Web Key Set (JWK Set)" and to eliminate potential confusion
between single keys and sets of keys. As part of this change, the
top-level member name for a set of keys was changed from "jwk" to
"keys".
o Clarified that values with duplicate member names MUST be
rejected.
o Established JSON Web Key Set Parameters registry.
o Explicitly listed non-goals in the introduction.
o Moved algorithm-specific definitions from JWK to JWA.
o Reformatted to give each member definition its own section
heading.
-01
Jones Expires April 27, 2015 [Page 44]