draft-ietf-jose-json-web-key-11.txt   draft-ietf-jose-json-web-key-12.txt 
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track May 28, 2013 Intended status: Standards Track July 11, 2013
Expires: November 29, 2013 Expires: January 12, 2014
JSON Web Key (JWK) JSON Web Key (JWK)
draft-ietf-jose-json-web-key-11 draft-ietf-jose-json-web-key-12
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. Web Algorithms (JWA) specification.
skipping to change at page 1, line 35 skipping to change at page 1, line 35
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 29, 2013. This Internet-Draft will expire on January 12, 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 21 skipping to change at page 2, line 21
3. JSON Web Key (JWK) Format . . . . . . . . . . . . . . . . . . 4 3. JSON Web Key (JWK) Format . . . . . . . . . . . . . . . . . . 4
3.1. "kty" (Key Type) Parameter . . . . . . . . . . . . . . . . 4 3.1. "kty" (Key Type) Parameter . . . . . . . . . . . . . . . . 4
3.2. "use" (Key Use) Parameter . . . . . . . . . . . . . . . . 5 3.2. "use" (Key Use) Parameter . . . . . . . . . . . . . . . . 5
3.3. "alg" (Algorithm) Parameter . . . . . . . . . . . . . . . 5 3.3. "alg" (Algorithm) Parameter . . . . . . . . . . . . . . . 5
3.4. "kid" (Key ID) Parameter . . . . . . . . . . . . . . . . . 5 3.4. "kid" (Key ID) Parameter . . . . . . . . . . . . . . . . . 5
3.5. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . . . 5 3.5. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . . . 5
3.6. "x5t" (X.509 Certificate Thumbprint) Header Parameter . . 6 3.6. "x5t" (X.509 Certificate Thumbprint) Header Parameter . . 6
3.7. "x5c" (X.509 Certificate Chain) Parameter . . . . . . . . 6 3.7. "x5c" (X.509 Certificate Chain) Parameter . . . . . . . . 6
4. JSON Web Key Set (JWK Set) Format . . . . . . . . . . . . . . 6 4. JSON Web Key Set (JWK Set) Format . . . . . . . . . . . . . . 6
4.1. "keys" (JSON Web Key Set) Parameter . . . . . . . . . . . 6 4.1. "keys" (JSON Web Key Set) Parameter . . . . . . . . . . . 6
5. String Comparison Rules . . . . . . . . . . . . . . . . . . . 6 5. String Comparison Rules . . . . . . . . . . . . . . . . . . . 7
6. Encrypted JWK and Encrypted JWK Set Formats . . . . . . . . . 7 6. Encrypted JWK and Encrypted JWK Set Formats . . . . . . . . . 7
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
7.1. JSON Web Key Parameters Registry . . . . . . . . . . . . . 8 7.1. JSON Web Key Parameters Registry . . . . . . . . . . . . . 8
7.1.1. Registration Template . . . . . . . . . . . . . . . . 8 7.1.1. Registration Template . . . . . . . . . . . . . . . . 8
7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 8 7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 9
7.2. JSON Web Key Set Parameters Registry . . . . . . . . . . . 9 7.2. JSON Web Key Set Parameters Registry . . . . . . . . . . . 9
7.2.1. Registration Template . . . . . . . . . . . . . . . . 9 7.2.1. Registration Template . . . . . . . . . . . . . . . . 10
7.2.2. Initial Registry Contents . . . . . . . . . . . . . . 10 7.2.2. Initial Registry Contents . . . . . . . . . . . . . . 10
7.3. JSON Web Signature and Encryption Type Values 7.3. JSON Web Signature and Encryption Type Values
Registration . . . . . . . . . . . . . . . . . . . . . . . 10 Registration . . . . . . . . . . . . . . . . . . . . . . . 10
7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 10 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 10
7.4. Media Type Registration . . . . . . . . . . . . . . . . . 10 7.4. Media Type Registration . . . . . . . . . . . . . . . . . 10
7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 10 7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 11
8. Security Considerations . . . . . . . . . . . . . . . . . . . 11 8. Security Considerations . . . . . . . . . . . . . . . . . . . 12
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
9.1. Normative References . . . . . . . . . . . . . . . . . . . 12 9.1. Normative References . . . . . . . . . . . . . . . . . . . 12
9.2. Informative References . . . . . . . . . . . . . . . . . . 13 9.2. Informative References . . . . . . . . . . . . . . . . . . 14
Appendix A. Example JSON Web Key Sets . . . . . . . . . . . . . . 14 Appendix A. Example JSON Web Key Sets . . . . . . . . . . . . . . 14
A.1. Example Public Keys . . . . . . . . . . . . . . . . . . . 14 A.1. Example Public Keys . . . . . . . . . . . . . . . . . . . 14
A.2. Example Private Keys . . . . . . . . . . . . . . . . . . . 15 A.2. Example Private Keys . . . . . . . . . . . . . . . . . . . 15
A.3. Example Symmetric Keys . . . . . . . . . . . . . . . . . . 17 A.3. Example Symmetric Keys . . . . . . . . . . . . . . . . . . 17
Appendix B. Example Use of "x5c" (X.509 Certificate Chain) Appendix B. Example Use of "x5c" (X.509 Certificate Chain)
Parameter . . . . . . . . . . . . . . . . . . . . . . 17 Parameter . . . . . . . . . . . . . . . . . . . . . . 17
Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 18 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 18
Appendix D. Document History . . . . . . . . . . . . . . . . . . 19 Appendix D. Document History . . . . . . . . . . . . . . . . . . 19
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 22 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 22
skipping to change at page 4, line 23 skipping to change at page 4, line 23
A JSON Web Key (JWK) is a JSON object containing specific members, as A JSON Web Key (JWK) is a JSON object containing specific members, as
specified below. Those members that are common to all key types are specified below. Those members that are common to all key types are
defined below. defined below.
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 5 of the JSON Web represent the parameters of the key. Section 5 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; objects with duplicate The member names within a JWK MUST be unique; receipients MUST either
member names MUST be rejected. reject JWKs with duplicate member names or use a JSON parser that
returns only the lexically last duplicate member name, as specified
in Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript].
Additional members MAY be present in the JWK. If not understood by Additional members MAY 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 kinds of names used for representing key parameters for different kinds of
keys need not be distinct. Any new member name SHOULD either be keys need not be distinct. Any new member name SHOULD either be
registered in the IANA JSON Web Key Parameters registry Section 7.1 registered in the IANA JSON Web Key Parameters registry Section 7.1
or be a value that contains a Collision Resistant Namespace. or be a value that contains a Collision Resistant Namespace.
3.1. "kty" (Key Type) Parameter 3.1. "kty" (Key Type) Parameter
skipping to change at page 6, line 15 skipping to change at page 6, line 15
3.6. "x5t" (X.509 Certificate Thumbprint) Header Parameter 3.6. "x5t" (X.509 Certificate Thumbprint) Header Parameter
The "x5t" (X.509 Certificate Thumbprint) member is a base64url The "x5t" (X.509 Certificate 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 bare public key represented by other members of the JWK. Use of the bare public key represented by other members of the JWK. Use of
this member is OPTIONAL. this member is OPTIONAL.
3.7. "x5c" (X.509 Certificate Chain) Parameter 3.7. "x5c" (X.509 Certificate Chain) Parameter
x5c The "x5c" (X.509 Certificate Chain) member contains a chain of The "x5c" (X.509 Certificate Chain) member contains a chain of one or
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 -- string in the array is a base64 encoded ([RFC4648] Section 4 -- not
not base64url encoded) DER [ITU.X690.1994] PKIX certificate value. base64url encoded) DER [ITU.X690.1994] PKIX certificate value. The
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, certificate. This MAY be followed by additional certificates, with
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 previous one. The key in the first certificate MUST match the bare
bare public key represented by other members of the JWK. Use of public key represented by other members of the JWK. Use of this
this member is OPTIONAL. member is OPTIONAL.
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 that contains an array A JSON Web Key Set (JWK Set) is a JSON object that contains an array
of JSON Web Key values as the value of its "keys" member. of JSON Web Key values as the value of its "keys" member.
The member names within a JWK Set MUST be unique; objects with The member names within a JWK Set MUST be unique; receipients MUST
duplicate member names MUST be rejected. either reject JWK Sets with duplicate member names or use a JSON
parser that returns only the lexically last duplicate member name, as
specified in Section 15.12 (The JSON Object) of ECMAScript 5.1
[ECMAScript].
Additional members MAY be present in the JWK Set. If not understood Additional members MAY 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
Section 7.2 or be a value that contains a Collision Resistant Section 7.2 or be a value that contains a Collision Resistant
Namespace. Namespace.
4.1. "keys" (JSON Web Key Set) Parameter 4.1. "keys" (JSON Web Key Set) Parameter
skipping to change at page 10, line 32 skipping to change at page 10, line 35
o Parameter Name: "keys" o Parameter Name: "keys"
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1 of [[ this document ]] o Specification Document(s): Section 4.1 of [[ this document ]]
7.3. JSON Web Signature and Encryption Type Values Registration 7.3. JSON Web Signature and Encryption Type Values Registration
7.3.1. Registry Contents 7.3.1. Registry Contents
This specification registers the "JWK" and "JWK-SET" type values in This specification registers the "JWK" and "JWK-SET" type values in
the IANA JSON Web Signature and Encryption Type Values registry the IANA JSON Web Signature and Encryption Type Values registry
[JWS]: [JWS], which can be used to indicate, respectively, that the content
is a JWK or a JWK Set.
o "typ" Header Parameter Value: "JWK" o "typ" Header Parameter Value: "JWK"
o Abbreviation for MIME Type: application/jwk+json o Abbreviation for MIME Type: application/jwk+json
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 3 of [[ this document ]] o Specification Document(s): Section 3 of [[ this document ]]
o "typ" Header Parameter Value: "JWK-SET" o "typ" Header Parameter Value: "JWK-SET"
o Abbreviation for MIME Type: application/jwk-set+json o Abbreviation for MIME Type: application/jwk-set+json
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4 of [[ this document ]] o Specification Document(s): Section 4 of [[ this document ]]
skipping to change at page 10, line 45 skipping to change at page 11, line 4
o Abbreviation for MIME Type: application/jwk+json o Abbreviation for MIME Type: application/jwk+json
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 3 of [[ this document ]] o Specification Document(s): Section 3 of [[ this document ]]
o "typ" Header Parameter Value: "JWK-SET" o "typ" Header Parameter Value: "JWK-SET"
o Abbreviation for MIME Type: application/jwk-set+json o Abbreviation for MIME Type: application/jwk-set+json
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4 of [[ this document ]] o Specification Document(s): Section 4 of [[ this document ]]
7.4. Media Type Registration 7.4. Media Type Registration
7.4.1. Registry Contents 7.4.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
Type registry [RFC4288] to indicate, respectively, that the content Type registry [RFC4288], which can be used to indicate, respectively,
is a JWK or a JWK Set. 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
o Encoding considerations: application/jwk+json values are o Encoding considerations: application/jwk+json values are
represented as JSON object; UTF-8 encoding SHOULD be employed for represented as JSON object; UTF-8 encoding SHOULD be employed for
the JSON object. the JSON object.
o Security Considerations: See the Security Considerations section o Security Considerations: See the Security Considerations section
of [[ this document ]] of [[ this document ]]
skipping to change at page 12, line 25 skipping to change at page 12, line 33
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 also apply to [RFC6030] about protecting private and symmetric keys also apply to
this specification. this specification.
The security considerations in XML DSIG 2.0 The security considerations in XML DSIG 2.0
[W3C.CR-xmldsig-core2-20120124], about key representations also apply [W3C.CR-xmldsig-core2-20120124], about key representations also apply
to this specification, other than those that are XML specific. to this specification, other than those that are XML specific.
The TLS Requirements in [JWS] also apply to this specification.
9. References 9. References
9.1. Normative References 9.1. Normative References
[ECMAScript]
Ecma International, "ECMAScript Language Specification,
5.1 Edition", ECMA 262, June 2011.
[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),
May 2013. July 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), May 2013. (work in progress), July 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), May 2013. in progress), July 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 19, line 19 skipping to change at page 19, line 19
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 D. Document History Appendix D. 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 ]]
-12
o Stated that receipients MUST either reject JWKs and JWK Sets with
duplicate member names or use a JSON parser that returns only the
lexically last duplicate member name.
-11 -11
o Stated that when "kid" values are used within a JWK Set, different o Stated that when "kid" values are used within a JWK Set, different
keys within the JWK Set SHOULD use distinct "kid" values. keys within the JWK Set SHOULD use distinct "kid" values.
o Added optional "x5u" (X.509 URL), "x5t" (X.509 Certificate o Added optional "x5u" (X.509 URL), "x5t" (X.509 Certificate
Thumbprint), and "x5c" (X.509 Certificate Chain) JWK parameters. Thumbprint), and "x5c" (X.509 Certificate Chain) JWK parameters.
o Added section on Encrypted JWK and Encrypted JWK Set Formats. o Added section on Encrypted JWK and Encrypted JWK Set Formats.
 End of changes. 20 change blocks. 
32 lines changed or deleted 49 lines changed or added

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