< draft-ietf-jose-json-web-key-26.txt   draft-ietf-jose-json-web-key-27.txt >
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track April 30, 2014 Intended status: Standards Track June 10, 2014
Expires: November 1, 2014 Expires: December 12, 2014
JSON Web Key (JWK) JSON Web Key (JWK)
draft-ietf-jose-json-web-key-26 draft-ietf-jose-json-web-key-27
Abstract Abstract
A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data
structure that represents a cryptographic key. This specification structure that represents a cryptographic key. This specification
also defines a JSON Web Key Set (JWK Set) JSON data structure for also defines a JSON Web Key Set (JWK Set) JSON data structure that
representing a set of JWKs. Cryptographic algorithms and identifiers represents a set of JWKs. Cryptographic algorithms and identifiers
for use with this specification are described in the separate JSON for use with this specification are described in the separate JSON
Web Algorithms (JWA) specification and IANA registries defined by Web Algorithms (JWA) specification and IANA registries defined by
that specification. that specification.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 1, 2014. This Internet-Draft will expire on December 12, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 12 skipping to change at page 2, line 12
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. JSON Web Key (JWK) Format . . . . . . . . . . . . . . . . . . 5 3. Example JWK . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1. "kty" (Key Type) Parameter . . . . . . . . . . . . . . . . 5 4. JSON Web Key (JWK) Format . . . . . . . . . . . . . . . . . . 5
3.2. "use" (Public Key Use) Parameter . . . . . . . . . . . . . 6 4.1. "kty" (Key Type) Parameter . . . . . . . . . . . . . . . . 6
3.3. "key_ops" (Key Operations) Parameter . . . . . . . . . . . 6 4.2. "use" (Public Key Use) Parameter . . . . . . . . . . . . . 6
3.4. "alg" (Algorithm) Parameter . . . . . . . . . . . . . . . 7 4.3. "key_ops" (Key Operations) Parameter . . . . . . . . . . . 7
3.5. "kid" (Key ID) Parameter . . . . . . . . . . . . . . . . . 7 4.4. "alg" (Algorithm) Parameter . . . . . . . . . . . . . . . 7
3.6. "x5u" (X.509 URL) Parameter . . . . . . . . . . . . . . . 7 4.5. "kid" (Key ID) Parameter . . . . . . . . . . . . . . . . . 8
3.7. "x5c" (X.509 Certificate Chain) Parameter . . . . . . . . 8 4.6. "x5u" (X.509 URL) Parameter . . . . . . . . . . . . . . . 8
3.8. "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter . . . 8 4.7. "x5c" (X.509 Certificate Chain) Parameter . . . . . . . . 8
4. JSON Web Key Set (JWK Set) Format . . . . . . . . . . . . . . 9 4.8. "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter . . . 9
4.1. "keys" Parameter . . . . . . . . . . . . . . . . . . . . . 9 4.9. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint)
5. String Comparison Rules . . . . . . . . . . . . . . . . . . . 10 Parameter . . . . . . . . . . . . . . . . . . . . . . . . 9
6. Encrypted JWK and Encrypted JWK Set Formats . . . . . . . . . 10 5. JSON Web Key Set (JWK Set) Format . . . . . . . . . . . . . . 9
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 5.1. "keys" Parameter . . . . . . . . . . . . . . . . . . . . . 10
7.1. JSON Web Key Parameters Registry . . . . . . . . . . . . . 11 6. String Comparison Rules . . . . . . . . . . . . . . . . . . . 10
7.1.1. Registration Template . . . . . . . . . . . . . . . . 11 7. Encrypted JWK and Encrypted JWK Set Formats . . . . . . . . . 10
7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 12 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
7.2. JSON Web Key Use Registry . . . . . . . . . . . . . . . . 14 8.1. JSON Web Key Parameters Registry . . . . . . . . . . . . . 12
7.2.1. Registration Template . . . . . . . . . . . . . . . . 14 8.1.1. Registration Template . . . . . . . . . . . . . . . . 12
7.2.2. Initial Registry Contents . . . . . . . . . . . . . . 14 8.1.2. Initial Registry Contents . . . . . . . . . . . . . . 13
7.3. JSON Web Key Operations Registry . . . . . . . . . . . . . 15 8.2. JSON Web Key Use Registry . . . . . . . . . . . . . . . . 14
7.3.1. Registration Template . . . . . . . . . . . . . . . . 15 8.2.1. Registration Template . . . . . . . . . . . . . . . . 14
7.3.2. Initial Registry Contents . . . . . . . . . . . . . . 15 8.2.2. Initial Registry Contents . . . . . . . . . . . . . . 15
7.4. JSON Web Key Set Parameters Registry . . . . . . . . . . . 16 8.3. JSON Web Key Operations Registry . . . . . . . . . . . . . 15
7.4.1. Registration Template . . . . . . . . . . . . . . . . 16 8.3.1. Registration Template . . . . . . . . . . . . . . . . 15
7.4.2. Initial Registry Contents . . . . . . . . . . . . . . 17 8.3.2. Initial Registry Contents . . . . . . . . . . . . . . 16
7.5. Media Type Registration . . . . . . . . . . . . . . . . . 17 8.4. JSON Web Key Set Parameters Registry . . . . . . . . . . . 17
7.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 8.4.1. Registration Template . . . . . . . . . . . . . . . . 17
8. Security Considerations . . . . . . . . . . . . . . . . . . . 18 8.4.2. Initial Registry Contents . . . . . . . . . . . . . . 18
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 8.5. Media Type Registration . . . . . . . . . . . . . . . . . 18
9.1. Normative References . . . . . . . . . . . . . . . . . . . 19 8.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
9.2. Informative References . . . . . . . . . . . . . . . . . . 20 9. Security Considerations . . . . . . . . . . . . . . . . . . . 19
Appendix A. Example JSON Web Key Sets . . . . . . . . . . . . . . 21 9.1. Key Provenance and Trust . . . . . . . . . . . . . . . . . 19
A.1. Example Public Keys . . . . . . . . . . . . . . . . . . . 21 9.2. Preventing Disclosure of Non-Public Key Information . . . 20
A.2. Example Private Keys . . . . . . . . . . . . . . . . . . . 22 9.3. RSA Private Key Representations and Blinding . . . . . . . 20
A.3. Example Symmetric Keys . . . . . . . . . . . . . . . . . . 24 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20
10.1. Normative References . . . . . . . . . . . . . . . . . . . 20
10.2. Informative References . . . . . . . . . . . . . . . . . . 22
Appendix A. Example JSON Web Key Sets . . . . . . . . . . . . . . 23
A.1. Example Public Keys . . . . . . . . . . . . . . . . . . . 23
A.2. Example Private Keys . . . . . . . . . . . . . . . . . . . 23
A.3. Example Symmetric Keys . . . . . . . . . . . . . . . . . . 25
Appendix B. Example Use of "x5c" (X.509 Certificate Chain) Appendix B. Example Use of "x5c" (X.509 Certificate Chain)
Parameter . . . . . . . . . . . . . . . . . . . . . . 24 Parameter . . . . . . . . . . . . . . . . . . . . . . 25
Appendix C. Example Encrypted RSA Private Key . . . . . . . . . . 25 Appendix C. Example Encrypted RSA Private Key . . . . . . . . . . 26
C.1. Plaintext RSA Private Key . . . . . . . . . . . . . . . . 26 C.1. Plaintext RSA Private Key . . . . . . . . . . . . . . . . 27
C.2. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . 29 C.2. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . 30
C.3. Content Encryption Key (CEK) . . . . . . . . . . . . . . . 29 C.3. Content Encryption Key (CEK) . . . . . . . . . . . . . . . 30
C.4. Key Derivation . . . . . . . . . . . . . . . . . . . . . . 30 C.4. Key Derivation . . . . . . . . . . . . . . . . . . . . . . 31
C.5. Key Encryption . . . . . . . . . . . . . . . . . . . . . . 30 C.5. Key Encryption . . . . . . . . . . . . . . . . . . . . . . 31
C.6. Initialization Vector . . . . . . . . . . . . . . . . . . 30 C.6. Initialization Vector . . . . . . . . . . . . . . . . . . 31
C.7. Additional Authenticated Data . . . . . . . . . . . . . . 31 C.7. Additional Authenticated Data . . . . . . . . . . . . . . 32
C.8. Content Encryption . . . . . . . . . . . . . . . . . . . . 31 C.8. Content Encryption . . . . . . . . . . . . . . . . . . . . 32
C.9. Complete Representation . . . . . . . . . . . . . . . . . 34 C.9. Complete Representation . . . . . . . . . . . . . . . . . 35
Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 35 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 36
Appendix E. Document History . . . . . . . . . . . . . . . . . . 36 Appendix E. Document History . . . . . . . . . . . . . . . . . . 37
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 41 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 42
1. Introduction 1. Introduction
A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) [RFC7159] A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) [RFC7159]
data structure that represents a cryptographic key. This data structure that represents a cryptographic key. This
specification also defines a JSON Web Key Set (JWK Set) JSON data specification also defines a JSON Web Key Set (JWK Set) JSON data
structure for representing a set of JWKs. Cryptographic algorithms structure that represents a set of JWKs. Cryptographic algorithms
and identifiers for use with this specification are described in the and identifiers for use with this specification are described in the
separate JSON Web Algorithms (JWA) [JWA] specification and IANA separate JSON Web Algorithms (JWA) [JWA] specification and IANA
registries defined by that specification. registries defined by that specification.
Goals for this specification do not include representing certificate
chains, representing certified keys, and replacing X.509
certificates.
JWKs and JWK Sets are used in the JSON Web Signature (JWS) [JWS] and JWKs and JWK Sets are used in the JSON Web Signature (JWS) [JWS] and
JSON Web Encryption (JWE) [JWE] specifications. JSON Web Encryption (JWE) [JWE] specifications.
Names defined by this specification are short because a core goal is Names defined by this specification are short because a core goal is
for the resulting representations to be compact. for the resulting representations to be compact.
1.1. Notational Conventions 1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
skipping to change at page 5, line 6 skipping to change at page 5, line 6
2. Terminology 2. Terminology
These terms defined by the JSON Web Signature (JWS) [JWS] These terms defined by the JSON Web Signature (JWS) [JWS]
specification are incorporated into this specification: "Base64url specification are incorporated into this specification: "Base64url
Encoding" and "Collision-Resistant Name". Encoding" and "Collision-Resistant Name".
These terms are defined for use by this specification: These terms are defined for use by this specification:
JSON Web Key (JWK) JSON Web Key (JWK)
A JSON object that represents a cryptographic key. 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) JSON Web Key Set (JWK Set)
A JSON object that contains an array of JWKs as the value of its A JSON object that represents a set of JWKs. The JSON object MUST
"keys" member. have a "keys" member, which is an array of JWK objects.
3. JSON Web Key (JWK) Format 3. Example JWK
A JSON Web Key (JWK) is a JSON object. The members of the object This section provides an example of a JWK. The following example JWK
represent properties of the key, including its value. This document declares that the key is an an elliptic curve key, it is used with
defines the key parameters that are not algorithm specific, and thus the P-256 elliptic curve, and its x and y coordinates are the
common to many keys. 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 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 In addition to the common parameters, each JWK will have members that
are specific to the kind of key being represented. These members are specific to the kind of key being represented. These members
represent the parameters of the key. Section 6 of the JSON Web represent the parameters of the key. Section 6 of the JSON Web
Algorithms (JWA) [JWA] specification defines multiple kinds of Algorithms (JWA) [JWA] specification defines multiple kinds of
cryptographic keys and their associated members. cryptographic keys and their associated members.
The member names within a JWK MUST be unique; recipients MUST either The member names within a JWK MUST be unique; recipients MUST either
reject JWKs with duplicate member names or use a JSON parser that reject JWKs with duplicate member names or use a JSON parser that
returns only the lexically last duplicate member name, as specified returns only the lexically last duplicate member name, as specified
in Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]. in Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript].
Additional members can be present in the JWK; if not understood by Additional members can be present in the JWK; if not understood by
implementations encountering them, they MUST be ignored. Member implementations encountering them, they MUST be ignored. Member
names used for representing key parameters for different keys types names used for representing key parameters for different keys types
need not be distinct. Any new member name should either be need not be distinct. Any new member name should either be
registered in the IANA JSON Web Key Parameters registry defined in registered in the IANA JSON Web Key Parameters registry defined in
Section 7.1 or be a value that contains a Collision-Resistant Name. Section 8.1 or be a value that contains a Collision-Resistant Name.
3.1. "kty" (Key Type) Parameter 4.1. "kty" (Key Type) Parameter
The "kty" (key type) member identifies the cryptographic algorithm The "kty" (key type) member identifies the cryptographic algorithm
family used with the key. "kty" values should either be registered in family used with the key. "kty" values should either be registered in
the IANA JSON Web Key Types registry defined in [JWA] or be a value 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- that contains a Collision-Resistant Name. The "kty" value is a case-
sensitive string. This member MUST be present in a JWK. 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 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 Types registry defined in [JWA]; the initial contents of this
registry are the values defined in Section 6.1 of the JSON Web registry are the values defined in Section 6.1 of the JSON Web
Algorithms (JWA) [JWA] specification. Algorithms (JWA) [JWA] specification.
The key type definitions include specification of the members to be The key type definitions include specification of the members to be
used for those key types. Additional members used with "kty" values used for those key types. Additional members used with "kty" values
can also be found in the IANA JSON Web Key Parameters registry can also be found in the IANA JSON Web Key Parameters registry
defined in Section 7.1. defined in Section 8.1.
3.2. "use" (Public Key Use) Parameter 4.2. "use" (Public Key Use) Parameter
The "use" (public key use) member identifies the intended use of the The "use" (public key use) member identifies the intended use of the
public key. The "use" parameter is intended for use cases in which public key. The "use" parameter is intended for use cases in which
it is useful to distinguish between public signing keys and public it is useful to distinguish between public signing keys and public
encryption keys. encryption keys.
Values defined by this specification are: Values defined by this specification are:
o "sig" (signature) o "sig" (signature)
o "enc" (encryption) o "enc" (encryption)
Other values MAY be used. Public Key Use values can be registered in Other values MAY be used. Public Key Use values can be registered in
the IANA JSON Web Key Use registry defined in Section 7.2. The "use" the IANA JSON Web Key Use registry defined in Section 8.2. The "use"
value is a case-sensitive string. Use of the "use" member is value is a case-sensitive string. Use of the "use" member is
OPTIONAL, unless the application requires its presence. OPTIONAL, unless the application requires its presence.
When a key is used to wrap another key and a key use designation for When a key is used to wrap another key and a key use designation for
the first key is desired, the "enc" (encryption) key use value SHOULD the first key is desired, the "enc" (encryption) key use value SHOULD
be used, since key wrapping is a kind of encryption. The "enc" value be used, since key wrapping is a kind of encryption. The "enc" value
SHOULD also be used for public keys used for key agreement SHOULD also be used for public keys used for key agreement
operations. (The "alg" member can be used to specify the particular operations. (The "alg" member can be used to specify the particular
cryptographic operation to be performed, when desired.) cryptographic operation to be performed, when desired.)
3.3. "key_ops" (Key Operations) Parameter 4.3. "key_ops" (Key Operations) Parameter
The "key_ops" (key operations) member identifies the operation(s) The "key_ops" (key operations) member identifies the operation(s)
that the key is intended to be used for. The "key_ops" parameter is 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 intended for use cases in which public, private, or symmetric keys
may be present. may be present.
Its value is an array of key operation values. Values defined by Its value is an array of key operation values. Values defined by
this specification are: this specification are:
o "sign" (compute signature or MAC) o "sign" (compute signature or MAC)
skipping to change at page 7, line 7 skipping to change at page 7, line 29
o "wrapKey" (encrypt key) o "wrapKey" (encrypt key)
o "unwrapKey" (decrypt key and validate decryption, if applicable) o "unwrapKey" (decrypt key and validate decryption, if applicable)
o "deriveKey" (derive key) o "deriveKey" (derive key)
o "deriveBits" (derive bits not to be used as a key) o "deriveBits" (derive bits not to be used as a key)
(Note that the "key_ops" values intentionally match the "KeyUsage" (Note that the "key_ops" values intentionally match the "KeyUsage"
values defined in the Web Cryptography API [WebCrypto] values defined in the Web Cryptography API [WebCrypto]
specification.) specification.)
Other values MAY be used. Key operation values can be registered in Other values MAY be used. Key operation values can be registered in
the IANA JSON Web Key Operations registry defined in Section 7.3. the IANA JSON Web Key Operations registry defined in Section 8.3.
The key operation values are case-sensitive strings. Duplicate key The key operation values are case-sensitive strings. Duplicate key
operation values MUST NOT be present in the array. operation values MUST NOT be present in the array.
Use of the "key_ops" member is OPTIONAL, unless the application Use of the "key_ops" member is OPTIONAL, unless the application
requires its presence. requires its presence.
Multiple unrelated key operations SHOULD NOT be specified for a key Multiple unrelated key operations SHOULD NOT be specified for a key
because of the potential vulnerabilities associated with using the because of the potential vulnerabilities associated with using the
same key with multiple algorithms. Thus, the combinations "sign" same key with multiple algorithms. Thus, the combinations "sign"
with "verify", "encrypt" with "decrypt", and "wrapKey" with with "verify", "encrypt" with "decrypt", and "wrapKey" with
"unwrapKey" are permitted, but other combinations SHOULD NOT be used. "unwrapKey" are permitted, but other combinations SHOULD NOT be used.
The "use" and "key_ops" JWK members SHOULD NOT be used together. The "use" and "key_ops" JWK members SHOULD NOT be used together.
Applications should specify which of these members they use, if Applications should specify which of these members they use, if
either is to be used by the application. either is to be used by the application.
3.4. "alg" (Algorithm) Parameter 4.4. "alg" (Algorithm) Parameter
The "alg" (algorithm) member identifies the algorithm intended for The "alg" (algorithm) member identifies the algorithm intended for
use with the key. The values used should either be registered in the use with the key. The values used should either be registered in the
IANA JSON Web Signature and Encryption Algorithms registry defined in IANA JSON Web Signature and Encryption Algorithms registry defined in
[JWA] or be a value that contains a Collision-Resistant Name. Use of [JWA] or be a value that contains a Collision-Resistant Name. Use of
this member is OPTIONAL. this member is OPTIONAL.
3.5. "kid" (Key ID) Parameter 4.5. "kid" (Key ID) Parameter
The "kid" (key ID) member can be used to match a specific key. This The "kid" (key ID) member can be used to match a specific key. This
can be used, for instance, to choose among a set of keys within a JWK can be used, for instance, to choose among a set of keys within a JWK
Set during key rollover. The structure of the "kid" value is Set during key rollover. The structure of the "kid" value is
unspecified. When "kid" values are used within a JWK Set, different unspecified. When "kid" values are used within a JWK Set, different
keys within the JWK Set SHOULD use distinct "kid" values. (One keys within the JWK Set SHOULD use distinct "kid" values. (One
example in which different keys might use the same "kid" value is if 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 they have different "kty" (key type) values but are considered to be
equivalent alternatives by the application using them.) The "kid" equivalent alternatives by the application using them.) The "kid"
value is a case-sensitive string. Use of this member is OPTIONAL. 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 When used with JWS or JWE, the "kid" value is used to match a JWS or
JWE "kid" Header Parameter value. JWE "kid" Header Parameter value.
3.6. "x5u" (X.509 URL) Parameter 4.6. "x5u" (X.509 URL) Parameter
The "x5u" (X.509 URL) member is a URI [RFC3986] that refers to a 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 resource for an X.509 public key certificate or certificate chain
[RFC5280]. The identified resource MUST provide a representation of [RFC5280]. The identified resource MUST provide a representation of
the certificate or certificate chain that conforms to RFC 5280 the certificate or certificate chain that conforms to RFC 5280
[RFC5280] in PEM encoded form [RFC1421]. The key in the first [RFC5280] in PEM encoded form [RFC1421]. The key in the first
certificate MUST match the public key represented by other members of certificate MUST match the public key represented by other members of
the JWK. The protocol used to acquire the resource MUST provide the JWK. The protocol used to acquire the resource MUST provide
integrity protection; an HTTP GET request to retrieve the certificate integrity protection; an HTTP GET request to retrieve the certificate
MUST use TLS [RFC2818] [RFC5246]; the identity of the server MUST be MUST use TLS [RFC2818] [RFC5246]; the identity of the server MUST be
skipping to change at page 8, line 24 skipping to change at page 8, line 45
representing the public key be populated when an "x5u" member is representing the public key be populated when an "x5u" member is
present, doing so may improve interoperability for applications that present, doing so may improve interoperability for applications that
do not handle PKIX certificates. If other members are present, the do not handle PKIX certificates. If other members are present, the
contents of those members MUST be semantically consistent with the contents of those members MUST be semantically consistent with the
related fields in the first certificate. For instance, if the "use" related fields in the first certificate. For instance, if the "use"
member is present, then it needs to allow for only a subset of the member is present, then it needs to allow for only a subset of the
usages that are permitted by the certificate. Similarly, if the usages that are permitted by the certificate. Similarly, if the
"alg" member is present, it should represent an algorithm that the "alg" member is present, it should represent an algorithm that the
certificate allows. certificate allows.
3.7. "x5c" (X.509 Certificate Chain) Parameter 4.7. "x5c" (X.509 Certificate Chain) Parameter
The "x5c" (X.509 Certificate Chain) member contains a chain of one or The "x5c" (X.509 Certificate Chain) member contains a chain of one or
more PKIX certificates [RFC5280]. The certificate chain is more PKIX certificates [RFC5280]. The certificate chain is
represented as a JSON array of certificate value strings. Each represented as a JSON array of certificate value strings. Each
string in the array is a base64 encoded ([RFC4648] Section 4 -- not string in the array is a base64 encoded ([RFC4648] Section 4 -- not
base64url encoded) DER [ITU.X690.1994] PKIX certificate value. The base64url encoded) DER [ITU.X690.1994] PKIX certificate value. The
PKIX certificate containing the key value MUST be the first PKIX certificate containing the key value MUST be the first
certificate. This MAY be followed by additional certificates, with certificate. This MAY be followed by additional certificates, with
each subsequent certificate being the one used to certify the each subsequent certificate being the one used to certify the
previous one. The key in the first certificate MUST match the public 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 key represented by other members of the JWK. Use of this member is
OPTIONAL. OPTIONAL.
As with the "x5u" member, members other than those representing the As with the "x5u" member, members other than those representing the
public key may also be populated when an "x5c" member is present. If public key may also be populated when an "x5c" member is present. If
other members are present, the contents of those members MUST be other members are present, the contents of those members MUST be
semantically consistent with the related fields in the first semantically consistent with the related fields in the first
certificate. See the last paragraph of Section 3.6 for additional certificate. See the last paragraph of Section 4.6 for additional
guidance on this. guidance on this.
3.8. "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter 4.8. "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter
The "x5t" (X.509 Certificate SHA-1 Thumbprint) member is a base64url 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 encoded SHA-1 thumbprint (a.k.a. digest) of the DER encoding of an
X.509 certificate [RFC5280]. The key in the certificate MUST match X.509 certificate [RFC5280]. The key in the certificate MUST match
the public key represented by other members of the JWK. Use of this the public key represented by other members of the JWK. Use of this
member is OPTIONAL. member is OPTIONAL.
If, in the future, certificate thumbprints need to be computed using
hash functions other than SHA-1, it is suggested that additional
related JWK parameters be defined for that purpose. For example, it
is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint
using SHA-256) JWK parameter could be defined by registering it in
the IANA JSON Web Key Parameters registry defined in Section 7.1.
As with the "x5u" member, members other than those representing the As with the "x5u" member, members other than those representing the
public key may also be populated when an "x5t" member is present. If public key may also be populated when an "x5t" member is present. If
other members are present, the contents of those members MUST be other members are present, the contents of those members MUST be
semantically consistent with the related fields in the referenced semantically consistent with the related fields in the referenced
certificate. See the last paragraph of Section 3.6 for additional certificate. See the last paragraph of Section 4.6 for additional
guidance on this. guidance on this.
4. JSON Web Key Set (JWK Set) Format 4.9. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Parameter
A JSON Web Key Set (JWK Set) is a JSON object representing a set of The "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) member is a
JWKs. The JSON object MUST have a "keys" member, which is an array base64url encoded SHA-256 thumbprint (a.k.a. digest) of the DER
of JWK objects. encoding of an X.509 certificate [RFC5280]. 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, members other than those representing the
public key may also be populated when an "x5t#S256" member is
present. 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, which is an
array of JWK objects.
The member names within a JWK Set MUST be unique; recipients MUST The member names within a JWK Set MUST be unique; recipients MUST
either reject JWK Sets with duplicate member names or use a JSON either reject JWK Sets with duplicate member names or use a JSON
parser that returns only the lexically last duplicate member name, as parser that returns only the lexically last duplicate member name, as
specified in Section 15.12 (The JSON Object) of ECMAScript 5.1 specified in Section 15.12 (The JSON Object) of ECMAScript 5.1
[ECMAScript]. [ECMAScript].
Additional members can be present in the JWK Set; if not understood Additional members can be present in the JWK Set; if not understood
by implementations encountering them, they MUST be ignored. by implementations encountering them, they MUST be ignored.
Parameters for representing additional properties of JWK Sets should Parameters for representing additional properties of JWK Sets should
either be registered in the IANA JSON Web Key Set Parameters registry either be registered in the IANA JSON Web Key Set Parameters registry
defined in Section 7.4 or be a value that contains a Collision- defined in Section 8.4 or be a value that contains a Collision-
Resistant Name. Resistant Name.
Implementations SHOULD ignore JWKs within a JWK Set that use "kty" Implementations SHOULD ignore JWKs within a JWK Set that use "kty"
(key type) values that are not understood by them, are missing (key type) values that are not understood by them, are missing
required members, or for which values are out of the supported required members, or for which values are out of the supported
ranges. ranges.
4.1. "keys" Parameter 5.1. "keys" Parameter
The value of the "keys" member is an array of JWK values. By 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 default, the order of the JWK values within the array does not imply
an order of preference among them, although applications of JWK Sets an order of preference among them, although applications of JWK Sets
can choose to assign a meaning to the order for their purposes, if can choose to assign a meaning to the order for their purposes, if
desired. This member MUST be present in a JWK Set. desired. This member MUST be present in a JWK Set.
5. String Comparison Rules 6. String Comparison Rules
The string comparison rules for this specification are the same as The string comparison rules for this specification are the same as
those defined in Section 5.3 of [JWS]. those defined in Section 5.3 of [JWS].
6. Encrypted JWK and Encrypted JWK Set Formats 7. Encrypted JWK and Encrypted JWK Set Formats
JWKs containing non-public key material will need to be encrypted in JWKs containing non-public key material will need to be encrypted
some contexts to prevent the disclosure of private or symmetric key when potentially observable by parties without legitimate access to
values to unintended parties. The use of an Encrypted JWK, which is the non-public information to prevent the disclosure of private or
a JWE with the UTF-8 encoding of a JWK as its plaintext value, is symmetric key values to unintended parties. The use of an Encrypted
recommended for this purpose. The processing of Encrypted JWKs is JWK, which is a JWE with the UTF-8 encoding of a JWK as its plaintext
identical to the processing of other JWEs. A "cty" (content type) value, is recommended for this purpose. The processing of Encrypted
Header Parameter value of "jwk+json" MUST be used to indicate that JWKs is identical to the processing of other JWEs. A "cty" (content
the content of the JWE is a JWK, unless the application knows that type) Header Parameter value of "jwk+json" MUST be used to indicate
the encrypted content is a JWK by another means or convention. 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.
JWK Sets containing non-public key material will similarly need to be JWK Sets containing non-public key material will also need to be
encrypted. The use of an Encrypted JWK Set, which is a JWE with the encrypted under these circumstances. The use of an Encrypted JWK
UTF-8 encoding of a JWK Set as its plaintext value, is recommended Set, which is a JWE with the UTF-8 encoding of a JWK Set as its
for this purpose. The processing of Encrypted JWK Sets is identical plaintext value, is recommended for this purpose. The processing of
to the processing of other JWEs. A "cty" (content type) Header Encrypted JWK Sets is identical to the processing of other JWEs. A
Parameter value of "jwk-set+json" MUST be used to indicate that the "cty" (content type) Header Parameter value of "jwk-set+json" MUST be
content of the JWE is a JWK Set, unless the application knows that used to indicate that the content of the JWE is a JWK Set, unless the
the encrypted content is a JWK Set by another means or convention. application knows that the encrypted content is a JWK Set by another
means or convention.
See Appendix C for an example encrypted JWK. See Appendix C for an example encrypted JWK.
7. IANA Considerations 8. IANA Considerations
The following registration procedure is used for all the registries The following registration procedure is used for all the registries
established by this specification. established by this specification.
Values are registered with a Specification Required [RFC5226] after a Values are registered with a Specification Required [RFC5226] after a
two-week review period on the [TBD]@ietf.org mailing list, on the two-week review period on the [TBD]@ietf.org mailing list, on the
advice of one or more Designated Experts. However, to allow for the advice of one or more Designated Experts. However, to allow for the
allocation of values prior to publication, the Designated Expert(s) allocation of values prior to publication, the Designated Expert(s)
may approve registration once they are satisfied that such a may approve registration once they are satisfied that such a
specification will be published. specification will be published.
skipping to change at page 11, line 30 skipping to change at page 12, line 13
list. list.
It is suggested that multiple Designated Experts be appointed who are It is suggested that multiple Designated Experts be appointed who are
able to represent the perspectives of different applications using able to represent the perspectives of different applications using
this specification, in order to enable broadly-informed review of this specification, in order to enable broadly-informed review of
registration decisions. In cases where a registration decision could registration decisions. In cases where a registration decision could
be perceived as creating a conflict of interest for a particular be perceived as creating a conflict of interest for a particular
Expert, that Expert should defer to the judgment of the other Expert, that Expert should defer to the judgment of the other
Expert(s). Expert(s).
7.1. JSON Web Key Parameters Registry 8.1. JSON Web Key Parameters Registry
This specification establishes the IANA JSON Web Key Parameters This specification establishes the IANA JSON Web Key Parameters
registry for JWK parameter names. The registry records the parameter registry for JWK parameter names. The registry records the parameter
name, the key type(s) that the parameter is used with, and a name, the key type(s) that the parameter is used with, and a
reference to the specification that defines it. It also records reference to the specification that defines it. It also records
whether the parameter conveys public or private information. This whether the parameter conveys public or private information. This
specification registers the parameter names defined in Section 3. specification registers the parameter names defined in Section 4.
The same JWK parameter name may be registered multiple times, The same JWK parameter name may be registered multiple times,
provided that duplicate parameter registrations are only for key type provided that duplicate parameter registrations are only for key type
specific JWK parameters; in this case, the meaning of the duplicate specific JWK parameters; in this case, the meaning of the duplicate
parameter name is disambiguated by the "kty" value of the JWK parameter name is disambiguated by the "kty" value of the JWK
containing it. containing it.
7.1.1. Registration Template 8.1.1. Registration Template
Parameter Name: Parameter Name:
The name requested (e.g., "example"). Because a core goal of this The name requested (e.g., "example"). Because a core goal of this
specification is for the resulting representations to be compact, specification is for the resulting representations to be compact,
it is RECOMMENDED that the name be short -- not to exceed 8 it is RECOMMENDED that the name be short -- not to exceed 8
characters without a compelling reason to do so. This name is characters without a compelling reason to do so. This name is
case-sensitive. Names may not match other registered names in a case-sensitive. Names may not match other registered names in a
case-insensitive manner unless the Designated Expert(s) state that case-insensitive manner unless the Designated Expert(s) state that
there is a compelling reason to allow an exception in this there is a compelling reason to allow an exception in this
particular case. However, matching names may be registered, particular case. However, matching names may be registered,
skipping to change at page 12, line 39 skipping to change at page 13, line 21
For Standards Track RFCs, state "IESG". For others, give the name For Standards Track RFCs, state "IESG". For others, give the name
of the responsible party. Other details (e.g., postal address, of the responsible party. Other details (e.g., postal address,
email address, home page URI) may also be included. email address, home page URI) may also be included.
Specification Document(s): Specification Document(s):
Reference to the document(s) that specify the parameter, Reference to the document(s) that specify the parameter,
preferably including URI(s) that can be used to retrieve copies of preferably including URI(s) that can be used to retrieve copies of
the document(s). An indication of the relevant sections may also the document(s). An indication of the relevant sections may also
be included but is not required. be included but is not required.
7.1.2. Initial Registry Contents 8.1.2. Initial Registry Contents
o Parameter Name: "kty" o Parameter Name: "kty"
o Parameter Description: Key Type o Parameter Description: Key Type
o Used with "kty" Value(s): * o Used with "kty" Value(s): *
o Parameter Information Class: Public o Parameter Information Class: Public
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.1 of [[ this document ]] o Specification Document(s): Section 4.1 of [[ this document ]]
o Parameter Name: "use" o Parameter Name: "use"
o Parameter Description: Public Key Use o Parameter Description: Public Key Use
o Used with "kty" Value(s): * o Used with "kty" Value(s): *
o Parameter Information Class: Public o Parameter Information Class: Public
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.2 of [[ this document ]] o Specification Document(s): Section 4.2 of [[ this document ]]
o Parameter Name: "key_ops" o Parameter Name: "key_ops"
o Parameter Description: Key Operations o Parameter Description: Key Operations
o Used with "kty" Value(s): * o Used with "kty" Value(s): *
o Parameter Information Class: Public o Parameter Information Class: Public
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.3 of [[ this document ]] o Specification Document(s): Section 4.3 of [[ this document ]]
o Parameter Name: "alg" o Parameter Name: "alg"
o Parameter Description: Algorithm o Parameter Description: Algorithm
o Used with "kty" Value(s): * o Used with "kty" Value(s): *
o Parameter Information Class: Public o Parameter Information Class: Public
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.4 of [[ this document ]] o Specification Document(s): Section 4.4 of [[ this document ]]
o Parameter Name: "kid" o Parameter Name: "kid"
o Parameter Description: Key ID o Parameter Description: Key ID
o Used with "kty" Value(s): * o Used with "kty" Value(s): *
o Parameter Information Class: Public o Parameter Information Class: Public
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.5 of [[ this document ]] o Specification Document(s): Section 4.5 of [[ this document ]]
o Parameter Name: "x5u" o Parameter Name: "x5u"
o Parameter Description: X.509 URL o Parameter Description: X.509 URL
o Used with "kty" Value(s): * o Used with "kty" Value(s): *
o Parameter Information Class: Public o Parameter Information Class: Public
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.6 of [[ this document ]] o Specification Document(s): Section 4.6 of [[ this document ]]
o Parameter Name: "x5c" o Parameter Name: "x5c"
o Parameter Description: X.509 Certificate Chain o Parameter Description: X.509 Certificate Chain
o Used with "kty" Value(s): * o Used with "kty" Value(s): *
o Parameter Information Class: Public o Parameter Information Class: Public
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.7 of [[ this document ]] o Specification Document(s): Section 4.7 of [[ this document ]]
o Parameter Name: "x5t" o Parameter Name: "x5t"
o Parameter Description: X.509 Certificate SHA-1 Thumbprint o Parameter Description: X.509 Certificate SHA-1 Thumbprint
o Used with "kty" Value(s): * o Used with "kty" Value(s): *
o Parameter Information Class: Public o Parameter Information Class: Public
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.8 of [[ this document ]] o Specification Document(s): Section 4.8 of [[ this document ]]
7.2. JSON Web Key Use Registry 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 [[ this document ]]
8.2. JSON Web Key Use Registry
This specification establishes the IANA JSON Web Key Use registry for This specification establishes the IANA JSON Web Key Use registry for
JWK "use" (public key use) member values. The registry records the JWK "use" (public key use) member values. The registry records the
public key use value and a reference to the specification that public key use value and a reference to the specification that
defines it. This specification registers the parameter names defined defines it. This specification registers the parameter names defined
in Section 3.2. in Section 4.2.
7.2.1. Registration Template
8.2.1. Registration Template
Use Member Value: Use Member Value:
The name requested (e.g., "example"). Because a core goal of this The name requested (e.g., "example"). Because a core goal of this
specification is for the resulting representations to be compact, specification is for the resulting representations to be compact,
it is RECOMMENDED that the name be short -- not to exceed 8 it is RECOMMENDED that the name be short -- not to exceed 8
characters without a compelling reason to do so. This name is characters without a compelling reason to do so. This name is
case-sensitive. Names may not match other registered names in a case-sensitive. Names may not match other registered names in a
case-insensitive manner unless the Designated Expert(s) state that case-insensitive manner unless the Designated Expert(s) state that
there is a compelling reason to allow an exception in this there is a compelling reason to allow an exception in this
particular case. particular case.
skipping to change at page 14, line 39 skipping to change at page 15, line 28
For Standards Track RFCs, state "IESG". For others, give the name For Standards Track RFCs, state "IESG". For others, give the name
of the responsible party. Other details (e.g., postal address, of the responsible party. Other details (e.g., postal address,
email address, home page URI) may also be included. email address, home page URI) may also be included.
Specification Document(s): Specification Document(s):
Reference to the document(s) that specify the parameter, Reference to the document(s) that specify the parameter,
preferably including URI(s) that can be used to retrieve copies of preferably including URI(s) that can be used to retrieve copies of
the document(s). An indication of the relevant sections may also the document(s). An indication of the relevant sections may also
be included but is not required. be included but is not required.
7.2.2. Initial Registry Contents 8.2.2. Initial Registry Contents
o Use Member Value: "sig" o Use Member Value: "sig"
o Use Description: Signature or MAC o Use Description: Signature or MAC
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.2 of [[ this document ]] o Specification Document(s): Section 4.2 of [[ this document ]]
o Use Member Value: "enc" o Use Member Value: "enc"
o Use Description: Encryption o Use Description: Encryption
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.2 of [[ this document ]] o Specification Document(s): Section 4.2 of [[ this document ]]
7.3. JSON Web Key Operations Registry 8.3. JSON Web Key Operations Registry
This specification establishes the IANA JSON Web Key Operations This specification establishes the IANA JSON Web Key Operations
registry for values of JWK "key_ops" array elements. The registry registry for values of JWK "key_ops" array elements. The registry
records the key operation value and a reference to the specification records the key operation value and a reference to the specification
that defines it. This specification registers the parameter names that defines it. This specification registers the parameter names
defined in Section 3.3. defined in Section 4.3.
7.3.1. Registration Template
8.3.1. Registration Template
Key Operation Value: Key Operation Value:
The name requested (e.g., "example"). Because a core goal of this The name requested (e.g., "example"). Because a core goal of this
specification is for the resulting representations to be compact, specification is for the resulting representations to be compact,
it is RECOMMENDED that the name be short -- not to exceed 8 it is RECOMMENDED that the name be short -- not to exceed 8
characters without a compelling reason to do so. This name is characters without a compelling reason to do so. This name is
case-sensitive. Names may not match other registered names in a case-sensitive. Names may not match other registered names in a
case-insensitive manner unless the Designated Expert(s) state that case-insensitive manner unless the Designated Expert(s) state that
there is a compelling reason to allow an exception in this there is a compelling reason to allow an exception in this
particular case. particular case.
skipping to change at page 15, line 40 skipping to change at page 16, line 29
For Standards Track RFCs, state "IESG". For others, give the name For Standards Track RFCs, state "IESG". For others, give the name
of the responsible party. Other details (e.g., postal address, of the responsible party. Other details (e.g., postal address,
email address, home page URI) may also be included. email address, home page URI) may also be included.
Specification Document(s): Specification Document(s):
Reference to the document(s) that specify the parameter, Reference to the document(s) that specify the parameter,
preferably including URI(s) that can be used to retrieve copies of preferably including URI(s) that can be used to retrieve copies of
the document(s). An indication of the relevant sections may also the document(s). An indication of the relevant sections may also
be included but is not required. be included but is not required.
7.3.2. Initial Registry Contents 8.3.2. Initial Registry Contents
o Key Operation Value: "sign" o Key Operation Value: "sign"
o Key Operation Description: Compute signature or MAC o Key Operation Description: Compute signature or MAC
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.3 of [[ this document ]] o Specification Document(s): Section 4.3 of [[ this document ]]
o Key Operation Value: "verify" o Key Operation Value: "verify"
o Key Operation Description: Verify signature or MAC o Key Operation Description: Verify signature or MAC
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.3 of [[ this document ]] o Specification Document(s): Section 4.3 of [[ this document ]]
o Key Operation Value: "encrypt" o Key Operation Value: "encrypt"
o Key Operation Description: Encrypt content o Key Operation Description: Encrypt content
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.3 of [[ this document ]] o Specification Document(s): Section 4.3 of [[ this document ]]
o Key Operation Value: "decrypt" o Key Operation Value: "decrypt"
o Key Operation Description: Decrypt content and validate o Key Operation Description: Decrypt content and validate
decryption, if applicable decryption, if applicable
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.3 of [[ this document ]] o Specification Document(s): Section 4.3 of [[ this document ]]
o Key Operation Value: "wrapKey" o Key Operation Value: "wrapKey"
o Key Operation Description: Encrypt key o Key Operation Description: Encrypt key
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.3 of [[ this document ]] o Specification Document(s): Section 4.3 of [[ this document ]]
o Key Operation Value: "unwrapKey" o Key Operation Value: "unwrapKey"
o Key Operation Description: Decrypt key and validate decryption, if o Key Operation Description: Decrypt key and validate decryption, if
applicable applicable
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.3 of [[ this document ]] o Specification Document(s): Section 4.3 of [[ this document ]]
o Key Operation Value: "deriveKey" o Key Operation Value: "deriveKey"
o Key Operation Description: Derive key o Key Operation Description: Derive key
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.3 of [[ this document ]] o Specification Document(s): Section 4.3 of [[ this document ]]
o Key Operation Value: "deriveBits" o Key Operation Value: "deriveBits"
o Key Operation Description: Derive bits not to be used as a key o Key Operation Description: Derive bits not to be used as a key
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.3 of [[ this document ]] o Specification Document(s): Section 4.3 of [[ this document ]]
7.4. JSON Web Key Set Parameters Registry 8.4. JSON Web Key Set Parameters Registry
This specification establishes the IANA JSON Web Key Set Parameters This specification establishes the IANA JSON Web Key Set Parameters
registry for JWK Set parameter names. The registry records the registry for JWK Set parameter names. The registry records the
parameter name and a reference to the specification that defines it. parameter name and a reference to the specification that defines it.
This specification registers the parameter names defined in This specification registers the parameter names defined in
Section 4. Section 5.
7.4.1. Registration Template 8.4.1. Registration Template
Parameter Name: Parameter Name:
The name requested (e.g., "example"). Because a core goal of this The name requested (e.g., "example"). Because a core goal of this
specification is for the resulting representations to be compact, specification is for the resulting representations to be compact,
it is RECOMMENDED that the name be short -- not to exceed 8 it is RECOMMENDED that the name be short -- not to exceed 8
characters without a compelling reason to do so. This name is characters without a compelling reason to do so. This name is
case-sensitive. Names may not match other registered names in a case-sensitive. Names may not match other registered names in a
case-insensitive manner unless the Designated Expert(s) state that case-insensitive manner unless the Designated Expert(s) state that
there is a compelling reason to allow an exception in this there is a compelling reason to allow an exception in this
particular case. particular case.
skipping to change at page 17, line 22 skipping to change at page 18, line 16
For Standards Track RFCs, state "IESG". For others, give the name For Standards Track RFCs, state "IESG". For others, give the name
of the responsible party. Other details (e.g., postal address, of the responsible party. Other details (e.g., postal address,
email address, home page URI) may also be included. email address, home page URI) may also be included.
Specification Document(s): Specification Document(s):
Reference to the document(s) that specify the parameter, Reference to the document(s) that specify the parameter,
preferably including URI(s) that can be used to retrieve copies of preferably including URI(s) that can be used to retrieve copies of
the document(s). An indication of the relevant sections may also the document(s). An indication of the relevant sections may also
be included but is not required. be included but is not required.
7.4.2. Initial Registry Contents 8.4.2. Initial Registry Contents
o Parameter Name: "keys" o Parameter Name: "keys"
o Parameter Description: Array of JWK values o Parameter Description: Array of JWK values
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.1 of [[ this document ]] o Specification Document(s): Section 5.1 of [[ this document ]]
7.5. Media Type Registration 8.5. Media Type Registration
7.5.1. Registry Contents 8.5.1. Registry Contents
This specification registers the "application/jwk+json" and This specification registers the "application/jwk+json" and
"application/jwk-set+json" Media Types [RFC2046] in the MIME Media "application/jwk-set+json" Media Types [RFC2046] in the MIME Media
Types registry [IANA.MediaTypes], which can be used to indicate, Types registry [IANA.MediaTypes], which can be used to indicate,
respectively, that the content is a JWK or a JWK Set. respectively, that the content is a JWK or a JWK Set.
o Type Name: application o Type Name: application
o Subtype Name: jwk+json o Subtype Name: jwk+json
o Required Parameters: n/a o Required Parameters: n/a
o Optional Parameters: n/a o Optional Parameters: n/a
skipping to change at page 18, line 34 skipping to change at page 19, line 27
o Applications that use this media type: TBD o Applications that use this media type: TBD
o Additional Information: Magic number(s): n/a, File extension(s): o Additional Information: Magic number(s): n/a, File extension(s):
n/a, Macintosh file type code(s): n/a n/a, Macintosh file type code(s): n/a
o Person & email address to contact for further information: Michael o Person & email address to contact for further information: Michael
B. Jones, mbj@microsoft.com B. Jones, mbj@microsoft.com
o Intended Usage: COMMON o Intended Usage: COMMON
o Restrictions on Usage: none o Restrictions on Usage: none
o Author: Michael B. Jones, mbj@microsoft.com o Author: Michael B. Jones, mbj@microsoft.com
o Change Controller: IESG o Change Controller: IESG
8. Security Considerations 9. Security Considerations
All of the security issues faced by any cryptographic application All of the security issues faced by any cryptographic application
must be faced by a JWS/JWE/JWK agent. Among these issues are must be faced by a JWS/JWE/JWK agent. Among these issues are
protecting the user's private and symmetric keys, preventing various protecting the user's private and symmetric keys, preventing various
attacks, and helping the user avoid mistakes such as inadvertently attacks, and helping the user avoid mistakes such as inadvertently
encrypting a message for the wrong recipient. The entire list of encrypting a message for the wrong recipient. The entire list of
security considerations is beyond the scope of this document, but security considerations is beyond the scope of this document, but
some significant considerations are listed here. some significant considerations are listed here.
9.1. Key Provenance and Trust
One should place no more trust in the data associated with a key than One should place no more trust in the data associated with a key than
in than the method by which it was obtained and in the in than the method by which it was obtained and in the
trustworthiness of the entity asserting an association with the key. trustworthiness of the entity asserting an association with the key.
Any data associated with a key that is obtained in an untrusted Any data associated with a key that is obtained in an untrusted
manner should be treated with skepticism. manner should be treated with skepticism.
The security considerations in Section 12.3 of XML DSIG 2.0
[W3C.NOTE-xmldsig-core2-20130411] about the strength of a signature
depending upon all the links in the security chain also apply to this
specification.
The TLS Requirements in [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 Private and symmetric keys MUST be protected from disclosure to
unintended parties. One recommended means of doing so is to encrypt 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 JWKs or JWK Sets containing them by using the JWK or JWK Set value as
the plaintext of a JWE. the plaintext of a JWE.
The security considerations in RFC 3447 [RFC3447] and RFC 6030 The security considerations in RFC 3447 [RFC3447] and RFC 6030
[RFC6030] about protecting private and symmetric keys, key usage, and [RFC6030] about protecting private and symmetric keys, key usage, and
information leakage also apply to this specification. information leakage also apply to this specification.
The security considerations in XML DSIG 2.0 9.3. RSA Private Key Representations and Blinding
[W3C.NOTE-xmldsig-core2-20130411], about key representations also
apply to this specification, other than those that are XML specific.
The TLS Requirements in [JWS] also apply to this specification. 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. References 10. References
9.1. Normative References 10.1. Normative References
[ECMAScript] [ECMAScript]
Ecma International, "ECMAScript Language Specification, Ecma International, "ECMAScript Language Specification,
5.1 Edition", ECMA 262, June 2011. 5.1 Edition", ECMA 262, June 2011.
[IANA.MediaTypes] [IANA.MediaTypes]
Internet Assigned Numbers Authority (IANA), "MIME Media Internet Assigned Numbers Authority (IANA), "MIME Media
Types", 2005. Types", 2005.
[ITU.X690.1994] [ITU.X690.1994]
International Telecommunications Union, "Information International Telecommunications Union, "Information
Technology - ASN.1 encoding rules: Specification of Basic Technology - ASN.1 encoding rules: Specification of Basic
Encoding Rules (BER), Canonical Encoding Rules (CER) and Encoding Rules (BER), Canonical Encoding Rules (CER) and
Distinguished Encoding Rules (DER)", ITU-T Recommendation Distinguished Encoding Rules (DER)", ITU-T Recommendation
X.690, 1994. X.690, 1994.
[JWA] Jones, M., "JSON Web Algorithms (JWA)", [JWA] Jones, M., "JSON Web Algorithms (JWA)",
draft-ietf-jose-json-web-algorithms (work in progress), draft-ietf-jose-json-web-algorithms (work in progress),
April 2014. June 2014.
[JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
draft-ietf-jose-json-web-encryption (work in progress), draft-ietf-jose-json-web-encryption (work in progress),
April 2014. June 2014.
[JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", draft-ietf-jose-json-web-signature (work Signature (JWS)", draft-ietf-jose-json-web-signature (work
in progress), April 2014. in progress), June 2014.
[RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic
Mail: Part I: Message Encryption and Authentication Mail: Part I: Message Encryption and Authentication
Procedures", RFC 1421, February 1993. Procedures", RFC 1421, February 1993.
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046, Extensions (MIME) Part Two: Media Types", RFC 2046,
November 1996. November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
skipping to change at page 20, line 46 skipping to change at page 22, line 10
(PKIX) Certificates in the Context of Transport Layer (PKIX) Certificates in the Context of Transport Layer
Security (TLS)", RFC 6125, March 2011. Security (TLS)", RFC 6125, March 2011.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014. Interchange Format", RFC 7159, March 2014.
[USASCII] American National Standards Institute, "Coded Character [USASCII] American National Standards Institute, "Coded Character
Set -- 7-bit American Standard Code for Information Set -- 7-bit American Standard Code for Information
Interchange", ANSI X3.4, 1986. Interchange", ANSI X3.4, 1986.
9.2. Informative References 10.2. Informative References
[HAC] Menezes, A., van Oorschot, P., and S. Vanstone, "Handbook
of Applied Cryptography", CRC Press, 1996,
<http://cacr.uwaterloo.ca/hac/about/chap8.pdf>.
[Kocher] Kocher, P., "Timing Attacks on Implementations of Diffe-
Hellman, RSA, DSS, and Other Systems", In Proceedings of
the 16th Annual International Cryptology Conference
Advances in Cryptology, Springer-Verlag, pp. 104-113,
1996.
[MagicSignatures] [MagicSignatures]
Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic
Signatures", January 2011. Signatures", January 2011.
[RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography
Standards (PKCS) #1: RSA Cryptography Specifications Standards (PKCS) #1: RSA Cryptography Specifications
Version 2.1", RFC 3447, February 2003. Version 2.1", RFC 3447, February 2003.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
skipping to change at page 36, line 18 skipping to change at page 37, line 18
Edmund Jay and Brian Campbell for validating the example. Edmund Jay and Brian Campbell for validating the example.
This specification is the work of the JOSE Working Group, which This specification is the work of the JOSE Working Group, which
includes dozens of active and dedicated participants. In particular, includes dozens of active and dedicated participants. In particular,
the following individuals contributed ideas, feedback, and wording the following individuals contributed ideas, feedback, and wording
that influenced this specification: that influenced this specification:
Dirk Balfanz, Richard Barnes, John Bradley, Brian Campbell, Breno de Dirk Balfanz, Richard Barnes, John Bradley, Brian Campbell, Breno de
Medeiros, Joe Hildebrand, Edmund Jay, Ben Laurie, James Manger, Matt Medeiros, Joe Hildebrand, Edmund Jay, Ben Laurie, James Manger, Matt
Miller, Tony Nadalin, Axel Nennker, John Panzer, Eric Rescorla, Nat Miller, Tony Nadalin, Axel Nennker, John Panzer, Eric Rescorla, Nat
Sakimura, Jim Schaad, Paul Tarjan, Hannes Tschofenig, and Sean Sakimura, Jim Schaad, Ryan Sleevi, Paul Tarjan, Hannes Tschofenig,
Turner. and Sean Turner.
Jim Schaad and Karen O'Donoghue chaired the JOSE working group and Jim Schaad and Karen O'Donoghue chaired the JOSE working group and
Sean Turner, Stephen Farrell, and Kathleen Moriarty served as Sean Turner, Stephen Farrell, and Kathleen Moriarty served as
Security area directors during the creation of this specification. Security area directors during the creation of this specification.
Appendix E. Document History Appendix E. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]] [[ to be removed by the RFC Editor before publication as an RFC ]]
-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.
o Addressed a few editorial issues.
-26 -26
o Referenced Section 6 of RFC 6125 for TLS server certificate o Referenced Section 6 of RFC 6125 for TLS server certificate
identity validation. identity validation.
o Deleted misleading non-normative phrase from the "use" o Deleted misleading non-normative phrase from the "use"
description. description.
o Noted that octet sequences are depicted using JSON array notation. o Noted that octet sequences are depicted using JSON array notation.
 End of changes. 86 change blocks. 
169 lines changed or deleted 245 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/