< draft-ietf-jose-json-web-key-18.txt   draft-ietf-jose-json-web-key-19.txt >
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track November 12, 2013 Intended status: Standards Track December 29, 2013
Expires: May 16, 2014 Expires: July 2, 2014
JSON Web Key (JWK) JSON Web Key (JWK)
draft-ietf-jose-json-web-key-18 draft-ietf-jose-json-web-key-19
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 for
representing a set of JWKs. Cryptographic algorithms and identifiers representing 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.
skipping to change at page 1, line 36 skipping to change at page 1, line 36
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 May 16, 2014. This Internet-Draft will expire on July 2, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 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 15 skipping to change at page 2, line 15
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. JSON Web Key (JWK) Format . . . . . . . . . . . . . . . . . . 5
3.1. "kty" (Key Type) Parameter . . . . . . . . . . . . . . . . 5 3.1. "kty" (Key Type) Parameter . . . . . . . . . . . . . . . . 5
3.2. "use" (Key Use) Parameter . . . . . . . . . . . . . . . . 6 3.2. "use" (Key Use) Parameter . . . . . . . . . . . . . . . . 6
3.3. "alg" (Algorithm) Parameter . . . . . . . . . . . . . . . 6 3.3. "use_details" (Key Use Details) Parameter . . . . . . . . 6
3.4. "kid" (Key ID) Parameter . . . . . . . . . . . . . . . . . 6 3.4. "alg" (Algorithm) Parameter . . . . . . . . . . . . . . . 7
3.5. "x5u" (X.509 URL) Parameter . . . . . . . . . . . . . . . 7 3.5. "kid" (Key ID) Parameter . . . . . . . . . . . . . . . . . 7
3.6. "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter . . . 7 3.6. "x5u" (X.509 URL) Parameter . . . . . . . . . . . . . . . 8
3.7. "x5c" (X.509 Certificate Chain) Parameter . . . . . . . . 8 3.7. "x5c" (X.509 Certificate Chain) Parameter . . . . . . . . 8
4. JSON Web Key Set (JWK Set) Format . . . . . . . . . . . . . . 8 3.8. "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter . . . 9
4.1. "keys" Parameter . . . . . . . . . . . . . . . . . . . . . 9 4. JSON Web Key Set (JWK Set) Format . . . . . . . . . . . . . . 9
5. String Comparison Rules . . . . . . . . . . . . . . . . . . . 9 4.1. "keys" Parameter . . . . . . . . . . . . . . . . . . . . . 10
6. Encrypted JWK and Encrypted JWK Set Formats . . . . . . . . . 9 5. String Comparison Rules . . . . . . . . . . . . . . . . . . . 10
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 6. Encrypted JWK and Encrypted JWK Set Formats . . . . . . . . . 10
7.1. JSON Web Key Parameters Registry . . . . . . . . . . . . . 10 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
7.1.1. Registration Template . . . . . . . . . . . . . . . . 11 7.1. JSON Web Key Parameters Registry . . . . . . . . . . . . . 11
7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 11 7.1.1. Registration Template . . . . . . . . . . . . . . . . 12
7.2. JSON Web Key Use Registry . . . . . . . . . . . . . . . . 13 7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 12
7.2.1. Registration Template . . . . . . . . . . . . . . . . 13 7.2. JSON Web Key Use Registry . . . . . . . . . . . . . . . . 14
7.2.2. Initial Registry Contents . . . . . . . . . . . . . . 13 7.2.1. Registration Template . . . . . . . . . . . . . . . . 14
7.3. JSON Web Key Set Parameters Registry . . . . . . . . . . . 14 7.2.2. Initial Registry Contents . . . . . . . . . . . . . . 14
7.3.1. Registration Template . . . . . . . . . . . . . . . . 14 7.3. JSON Web Key Use Details Registry . . . . . . . . . . . . 15
7.3.2. Initial Registry Contents . . . . . . . . . . . . . . 14 7.3.1. Registration Template . . . . . . . . . . . . . . . . 15
7.4. Media Type Registration . . . . . . . . . . . . . . . . . 14 7.3.2. Initial Registry Contents . . . . . . . . . . . . . . 15
7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 14 7.4. JSON Web Key Set Parameters Registry . . . . . . . . . . . 16
8. Security Considerations . . . . . . . . . . . . . . . . . . . 15 7.4.1. Registration Template . . . . . . . . . . . . . . . . 17
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 7.4.2. Initial Registry Contents . . . . . . . . . . . . . . 17
9.1. Normative References . . . . . . . . . . . . . . . . . . . 16 7.5. Media Type Registration . . . . . . . . . . . . . . . . . 17
9.2. Informative References . . . . . . . . . . . . . . . . . . 18 7.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
Appendix A. Example JSON Web Key Sets . . . . . . . . . . . . . . 18 8. Security Considerations . . . . . . . . . . . . . . . . . . . 18
A.1. Example Public Keys . . . . . . . . . . . . . . . . . . . 18 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19
A.2. Example Private Keys . . . . . . . . . . . . . . . . . . . 19 9.1. Normative References . . . . . . . . . . . . . . . . . . . 19
A.3. Example Symmetric Keys . . . . . . . . . . . . . . . . . . 21 9.2. Informative References . . . . . . . . . . . . . . . . . . 21
Appendix A. Example JSON Web Key Sets . . . . . . . . . . . . . . 21
A.1. Example Public Keys . . . . . . . . . . . . . . . . . . . 21
A.2. Example Private Keys . . . . . . . . . . . . . . . . . . . 22
A.3. Example Symmetric Keys . . . . . . . . . . . . . . . . . . 24
Appendix B. Example Use of "x5c" (X.509 Certificate Chain) Appendix B. Example Use of "x5c" (X.509 Certificate Chain)
Parameter . . . . . . . . . . . . . . . . . . . . . . 21 Parameter . . . . . . . . . . . . . . . . . . . . . . 24
Appendix C. Example Encrypted RSA Private Key . . . . . . . . . . 22 Appendix C. Example Encrypted RSA Private Key . . . . . . . . . . 25
C.1. Plaintext RSA Private Key . . . . . . . . . . . . . . . . 23 C.1. Plaintext RSA Private Key . . . . . . . . . . . . . . . . 26
C.2. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . 26 C.2. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . 29
C.3. Content Encryption Key (CEK) . . . . . . . . . . . . . . . 26 C.3. Content Encryption Key (CEK) . . . . . . . . . . . . . . . 29
C.4. Key Encryption . . . . . . . . . . . . . . . . . . . . . . 27 C.4. Key Encryption . . . . . . . . . . . . . . . . . . . . . . 30
C.5. Initialization Vector . . . . . . . . . . . . . . . . . . 27 C.5. Initialization Vector . . . . . . . . . . . . . . . . . . 30
C.6. Additional Authenticated Data . . . . . . . . . . . . . . 27 C.6. Additional Authenticated Data . . . . . . . . . . . . . . 30
C.7. Content Encryption . . . . . . . . . . . . . . . . . . . . 28 C.7. Content Encryption . . . . . . . . . . . . . . . . . . . . 31
C.8. Complete Representation . . . . . . . . . . . . . . . . . 31 C.8. Complete Representation . . . . . . . . . . . . . . . . . 34
Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 32 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 35
Appendix E. Document History . . . . . . . . . . . . . . . . . . 33 Appendix E. Document History . . . . . . . . . . . . . . . . . . 36
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 37 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 40
1. Introduction 1. Introduction
A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) [RFC4627] A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) [RFC4627]
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 for representing 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.
skipping to change at page 6, line 27 skipping to change at page 6, line 27
value is a case-sensitive string. A "use" member SHOULD be present, value is a case-sensitive string. A "use" member SHOULD be present,
unless the application uses another means or convention to determine unless the application uses another means or convention to determine
the intended key usage. the intended key usage.
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 "alg" be used, since key wrapping is a kind of encryption. (The "alg"
member can be used to specify the particular kind of encryption to be member can be used to specify the particular kind of encryption to be
performed, when desired.) performed, when desired.)
3.3. "alg" (Algorithm) Parameter 3.3. "use_details" (Key Use Details) Parameter
The "use_details" (key use details) member identifies the fine-
grained details of the intended use of the key. Its value is an
array of key use detail values. Values defined by this specification
are:
o "sign" (compute signature or MAC)
o "verify" (verify signature or MAC)
o "encrypt" (encrypt content)
o "decrypt" (decrypt content and validate decryption, if applicable)
o "wrap" (encrypt key)
o "unwrap" (decrypt key and validate decryption, if applicable)
o "deriveKey" (derive key)
o "deriveBits" (derive bits not to be used as a key)
Other values MAY be used. Key Use Detail values can be registered in
the IANA JSON Web Key Use Details registry defined in Section 7.3.
The use detail values are case-sensitive strings. Duplicate use
detail values MUST NOT be present in the array.
Use of the "use_details" member is OPTIONAL, unless the application
requires use this member to record fine-grained key usage details.
(Note that the "use_details" values intentionally match the
"KeyUsage" values defined in the Web Cryptography API [WebCrypto]
specification.)
Multiple unrelated uses 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 "wrap" with "unwrap" are permitted, but
other combinations SHOULD NOT be used.
If both "use" and "use_details" JWK members are present, the usages
specified by them MUST be consistent. In particular, the "use" value
"sig" corresponds to "sign" and/or "verify". The "use" value "enc"
corresponds to all other values defined above. If "use_details"
values corresponding to both "sig" and "enc" "use" values are
present, the "use" member SHOULD NOT be present, and if present, its
value MUST NOT be either "sig" or "enc".
3.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.4. "kid" (Key ID) Parameter 3.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.5. "x5u" (X.509 URL) Parameter 3.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 7, line 30 skipping to change at page 8, line 30
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.6. "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]. The key in the certificate MUST match
the public key represented by other members of the JWK. Use of this
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
public key may also be populated when an "x5t" 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 3.5 for additional
guidance on this.
3.7. "x5c" (X.509 Certificate Chain) Parameter 3.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.5 for additional certificate. See the last paragraph of Section 3.6 for additional
guidance on this.
3.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]. The key in the certificate MUST match
the public key represented by other members of the JWK. Use of this
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
public key may also be populated when an "x5t" 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 3.6 for additional
guidance on this. guidance on this.
4. JSON Web Key Set (JWK Set) Format 4. JSON Web Key Set (JWK Set) Format
A JSON Web Key Set (JWK Set) is a JSON object representing a set of A JSON Web Key Set (JWK Set) is a JSON object representing a set of
JWKs. The JSON object MUST have a "keys" member, which is an array JWKs. The JSON object MUST have a "keys" member, which is an array
of JWK objects. 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.3 or be a value that contains a Collision- defined in Section 7.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 4.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
skipping to change at page 12, line 17 skipping to change at page 13, line 17
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 3.1 of [[ this document ]] o Specification Document(s): Section 3.1 of [[ this document ]]
o Parameter Name: "use" o Parameter Name: "use"
o Parameter Description: Key Use o Parameter Description: 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 3.2 of [[ this document ]]
o Parameter Name: "alg" o Parameter Name: "use_details"
o Parameter Description: Algorithm o Parameter Description: 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.3 of [[ this document ]] o Specification Document(s): Section 3.3 of [[ this document ]]
o Parameter Name: "kid" o Parameter Name: "alg"
o Parameter Description: Key ID 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 3.4 of [[ this document ]]
o Parameter Name: "x5u" o Parameter Name: "kid"
o Parameter Description: X.509 URL 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 3.5 of [[ this document ]]
o Parameter Name: "x5t" o Parameter Name: "x5u"
o Parameter Description: X.509 Certificate SHA-1 Thumbprint 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 3.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 3.7 of [[ this document ]]
o Parameter Name: "x5t"
o Parameter Description: X.509 Certificate SHA-1 Thumbprint
o Used with "kty" Value(s): *
o Parameter Information Class: Public
o Change Controller: IESG
o Specification Document(s): Section 3.8 of [[ this document ]]
7.2. JSON Web Key Use Registry 7.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" member values. The registry records the key use value and JWK "use" member values. The registry records the key use value and
a reference to the specification that defines it. This specification a reference to the specification that defines it. This specification
registers the parameter names defined in Section 3.2. registers the parameter names defined in Section 3.2.
7.2.1. Registration Template 7.2.1. Registration Template
Use Member Value: Use Member Value:
skipping to change at page 14, line 5 skipping to change at page 15, line 12
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 3.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 3.2 of [[ this document ]]
7.3. JSON Web Key Set Parameters Registry 7.3. JSON Web Key Use Details Registry
This specification establishes the IANA JSON Web Key Use Details
registry for values of JWK "use_details" array elements. The
registry records the key use detail value and a reference to the
specification that defines it. This specification registers the
parameter names defined in Section 3.3.
7.3.1. Registration Template
Use Detail Value:
The name requested (e.g., "example"). 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.
Use Detail Description:
Brief description of the use detail (e.g., "Example description").
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.
7.3.2. Initial Registry Contents
o Use Detail Value: "sign"
o Use Detail Description: Compute signature or MAC
o Change Controller: IESG
o Specification Document(s): Section 3.3 of [[ this document ]]
o Use Detail Value: "verify"
o Use Detail Description: Verify signature or MAC
o Change Controller: IESG
o Specification Document(s): Section 3.3 of [[ this document ]]
o Use Detail Value: "encrypt"
o Use Detail Description: Encrypt content
o Change Controller: IESG
o Specification Document(s): Section 3.3 of [[ this document ]]
o Use Detail Value: "decrypt"
o Use Detail Description: Decrypt content and validate decryption,
if applicable
o Change Controller: IESG
o Specification Document(s): Section 3.3 of [[ this document ]]
o Use Detail Value: "wrap"
o Use Detail Description: Encrypt key
o Change Controller: IESG
o Specification Document(s): Section 3.3 of [[ this document ]]
o Use Detail Value: "unwrap"
o Use Detail Description: Decrypt key and validate decryption, if
applicable
o Change Controller: IESG
o Specification Document(s): Section 3.3 of [[ this document ]]
o Use Detail Value: "deriveKey"
o Use Detail Description: Derive key
o Change Controller: IESG
o Specification Document(s): Section 3.3 of [[ this document ]]
o Use Detail Value: "deriveBits"
o Use Detail Description: Derive bits not to be used as a key
o Change Controller: IESG
o Specification Document(s): Section 3.3 of [[ this document ]]
7.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 4.
7.3.1. Registration Template 7.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 14, line 39 skipping to change at page 17, line 31
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 7.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 4.1 of [[ this document ]]
7.4. Media Type Registration 7.5. Media Type Registration
7.4.1. Registry Contents 7.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 17, line 7 skipping to change at page 19, line 47
[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),
November 2013. December 2013.
[JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web
Encryption (JWE)", draft-ietf-jose-json-web-encryption Encryption (JWE)", draft-ietf-jose-json-web-encryption
(work in progress), November 2013. (work in progress), December 2013.
[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), November 2013. in progress), December 2013.
[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 18, line 11 skipping to change at page 20, line 52
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, May 2008. (CRL) Profile", RFC 5280, May 2008.
[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.
[W3C.CR-xmldsig-core2-20120124] [W3C.CR-xmldsig-core2-20120124]
Eastlake, D., Reagle, J., Yiu, K., Solo, D., Datta, P., Cantor, S., Roessler, T., Eastlake, D., Yiu, K., Reagle,
Hirsch, F., Cantor, S., and T. Roessler, "XML Signature J., Solo, D., Datta, P., and F. Hirsch, "XML Signature
Syntax and Processing Version 2.0", World Wide Web Syntax and Processing Version 2.0", World Wide Web
Consortium CR CR-xmldsig-core2-20120124, January 2012, Consortium CR CR-xmldsig-core2-20120124, January 2012,
<http://www.w3.org/TR/2012/CR-xmldsig-core2-20120124>. <http://www.w3.org/TR/2012/CR-xmldsig-core2-20120124>.
9.2. Informative References 9.2. Informative References
[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.
[RFC6030] Hoyer, P., Pei, M., and S. Machani, "Portable Symmetric [RFC6030] Hoyer, P., Pei, M., and S. Machani, "Portable Symmetric
Key Container (PSKC)", RFC 6030, October 2010. Key Container (PSKC)", RFC 6030, October 2010.
[WebCrypto]
Sleevi, R., "Web Cryptography API", World Wide Web
Consortium Draft, December 2013, <https://dvcs.w3.org/hg/
webcrypto-api/raw-file/tip/spec/Overview.html>.
Appendix A. Example JSON Web Key Sets Appendix A. Example JSON Web Key Sets
A.1. Example Public Keys A.1. Example Public Keys
The following example JWK Set contains two public keys represented as The following example JWK Set contains two public keys represented as
JWKs: one using an Elliptic Curve algorithm and a second one using an 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 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 encryption. The second specifies that the key is to be used with the
"RS256" algorithm. Both provide a Key ID for key matching purposes. "RS256" algorithm. Both provide a Key ID for key matching purposes.
In both cases, integers are represented using the base64url encoding In both cases, integers are represented using the base64url encoding
skipping to change at page 33, line 26 skipping to change at page 36, line 26
Turner. 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 and Stephen Farrell served as Security area directors Sean Turner and Stephen Farrell served as Security area directors
during the creation of this specification. 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 ]]
-19
o Added optional "use_details" (key use details) JWK member.
o Reordered the key selection parameters.
-18 -18
o Changes to address editorial and minor issues #68, #69, #73, #74, o Changes to address editorial and minor issues #68, #69, #73, #74,
#76, #77, #78, #79, #82, #85, #89, and #135. #76, #77, #78, #79, #82, #85, #89, and #135.
o Added and used Description registry fields. o Added and used Description registry fields.
-17 -17
o Refined the "typ" and "cty" definitions to always be MIME Media o Refined the "typ" and "cty" definitions to always be MIME Media
skipping to change at page 34, line 45 skipping to change at page 38, line 4
o Added a Parameter Information Class value to the JSON Web Key o Added a Parameter Information Class value to the JSON Web Key
Parameters registry, which registers whether the parameter conveys Parameters registry, which registers whether the parameter conveys
public or private information. public or private information.
o Registered "application/jwk+json" and "application/jwk-set+json" o Registered "application/jwk+json" and "application/jwk-set+json"
MIME types and "JWK" and "JWK-SET" typ header parameter values, MIME types and "JWK" and "JWK-SET" typ header parameter values,
addressing issue #21. addressing issue #21.
-10 -10
o No changes were made, other than to the version number and date. o No changes were made, other than to the version number and date.
-09 -09
o Expanded the scope of the JWK specification to include private and o Expanded the scope of the JWK specification to include private and
symmetric key representations, as specified by 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. o Defined that members that are not understood must be ignored.
-08 -08
o Changed the name of the JWK key type parameter from "alg" to "kty" 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 to enable use of "alg" to indicate the particular algorithm that
the key is intended to be used with. the key is intended to be used with.
o Clarified statements of the form "This member is OPTIONAL" to "Use o Clarified statements of the form "This member is OPTIONAL" to "Use
 End of changes. 30 change blocks. 
91 lines changed or deleted 240 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/