draft-ietf-jose-json-web-key-29.txt   draft-ietf-jose-json-web-key-30.txt 
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track June 20, 2014 Intended status: Standards Track July 1, 2014
Expires: December 22, 2014 Expires: January 2, 2015
JSON Web Key (JWK) JSON Web Key (JWK)
draft-ietf-jose-json-web-key-29 draft-ietf-jose-json-web-key-30
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 that also defines a JSON Web Key Set (JWK Set) JSON data structure that
represents 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.
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 December 22, 2014. This Internet-Draft will expire on January 2, 2015.
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 5, line 18 skipping to change at page 5, line 18
A JSON object that represents a cryptographic key. The members of A JSON object that represents a cryptographic key. The members of
the object represent properties of the key, including its value. 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 represents a set of JWKs. The JSON object MUST A JSON object that represents a set of JWKs. The JSON object MUST
have a "keys" member, which is an array of JWK objects. have a "keys" member, which is an array of JWK objects.
3. Example JWK 3. Example JWK
This section provides an example of a JWK. The following example JWK This section provides an example of a JWK. The following example JWK
declares that the key is an elliptic curve key, it is used with the declares that the key is an Elliptic Curve [DSS] key, it is used with
P-256 elliptic curve, and its x and y coordinates are the base64url the P-256 Elliptic Curve, and its x and y coordinates are the
encoded values shown. A key identifier is also provided for the key. base64url encoded values shown. A key identifier is also provided
for the key.
{"kty":"EC", {"kty":"EC",
"crv":"P-256", "crv":"P-256",
"x":"f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU", "x":"f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
"y":"x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0", "y":"x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
"kid":"Public key used in JWS A.3 example" "kid":"Public key used in JWS A.3 example"
} }
Additional example JWK values can be found in Appendix A. Additional example JWK values can be found in Appendix A.
skipping to change at page 8, line 30 skipping to change at page 8, line 30
4.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
validated, as per Section 6 of RFC 6125 [RFC6125]. Use of this validated, as per Section 6 of RFC 6125 [RFC6125]. Use of this
member is OPTIONAL. member is OPTIONAL.
While there is no requirement that members other than those While there is no requirement that members other than those
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
skipping to change at page 11, line 24 skipping to change at page 11, line 24
means or convention, in which case the "cty" value would typically be means or convention, in which case the "cty" value would typically be
omitted. omitted.
See Appendix C for an example encrypted JWK. See Appendix C for an example encrypted JWK.
8. 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 on a Specification Required [RFC5226] basis
two-week review period on the [TBD]@ietf.org mailing list, on the after a two-week review period on the [TBD]@ietf.org mailing list, on
advice of one or more Designated Experts. However, to allow for the the advice of one or more Designated Experts. However, to allow for
allocation of values prior to publication, the Designated Expert(s) the allocation of values prior to publication, the Designated
may approve registration once they are satisfied that such a Expert(s) may approve registration once they are satisfied that such
specification will be published. a specification will be published.
Registration requests must be sent to the [TBD]@ietf.org mailing list Registration requests must be sent to the [TBD]@ietf.org mailing list
for review and comment, with an appropriate subject (e.g., "Request for review and comment, with an appropriate subject (e.g., "Request
for access token type: example"). [[ Note to the RFC Editor: The name for access token type: example"). [[ Note to the RFC Editor: The name
of the mailing list should be determined in consultation with the of the mailing list should be determined in consultation with the
IESG and IANA. Suggested name: jose-reg-review. ]] IESG and IANA. Suggested name: jose-reg-review. ]]
Within the review period, the Designated Expert(s) will either Within the review period, the Designated Expert(s) will either
approve or deny the registration request, communicating this decision approve or deny the registration request, communicating this decision
to the review list and IANA. Denials should include an explanation to the review list and IANA. Denials should include an explanation
skipping to change at page 19, line 29 skipping to change at page 19, line 29
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
9. Security Considerations 9. Security Considerations
All of the security issues faced by any cryptographic application All of the security issues that are pertinent to any cryptographic
must be faced by a JWS/JWE/JWK agent. Among these issues are application must be addressed by JWS/JWE/JWK agents. Among these
protecting the user's asymmetric private and symmetric secret keys, issues are protecting the user's asymmetric private and symmetric
preventing various attacks, and helping avoid mistakes such as secret keys, preventing various attacks, and helping avoid mistakes
inadvertently encrypting a message to the wrong recipient. The such as inadvertently encrypting a message to the wrong recipient.
entire list of security considerations is beyond the scope of this The entire list of security considerations is beyond the scope of
document, but some significant considerations are listed here. this document, but some significant considerations are listed here.
9.1. Key Provenance and Trust 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 The security considerations in Section 12.3 of XML DSIG 2.0
skipping to change at page 21, line 4 skipping to change at page 21, line 4
[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),
June 2014. July 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),
June 2014. July 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), June 2014. in progress), July 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 22, line 12 skipping to change at page 22, line 12
[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.
10.2. Informative References 10.2. Informative References
[DSS] National Institute of Standards and Technology, "Digital
Signature Standard (DSS)", FIPS PUB 186-4, July 2013.
[HAC] Menezes, A., van Oorschot, P., and S. Vanstone, "Handbook [HAC] Menezes, A., van Oorschot, P., and S. Vanstone, "Handbook
of Applied Cryptography", CRC Press, 1996, of Applied Cryptography", CRC Press, 1996,
<http://cacr.uwaterloo.ca/hac/about/chap8.pdf>. <http://cacr.uwaterloo.ca/hac/about/chap8.pdf>.
[Kocher] Kocher, P., "Timing Attacks on Implementations of Diffe- [Kocher] Kocher, P., "Timing Attacks on Implementations of Diffe-
Hellman, RSA, DSS, and Other Systems", In Proceedings of Hellman, RSA, DSS, and Other Systems", In Proceedings of
the 16th Annual International Cryptology Conference the 16th Annual International Cryptology Conference
Advances in Cryptology, Springer-Verlag, pp. 104-113, Advances in Cryptology, Springer-Verlag, pp. 104-113,
1996. 1996.
skipping to change at page 37, line 17 skipping to change at page 37, line 17
Thanks to Matt Miller for creating the encrypted key example and to Thanks to Matt Miller for creating the encrypted key example and to
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, Kathleen Moriarty, Tony Nadalin, Axel Nennker, John Panzer,
Sakimura, Jim Schaad, Ryan Sleevi, Paul Tarjan, Hannes Tschofenig, Eric Rescorla, Nat Sakimura, Jim Schaad, Ryan Sleevi, Paul Tarjan,
and Sean Turner. Hannes Tschofenig, 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 ]]
-30
o Added references and cleaned up the reference syntax in a few
places.
o Applied minor wording changes to the Security Considerations
section.
-29 -29
o Replaced the terms JWS Header, JWE Header, and JWT Header with a o Replaced the terms JWS Header, JWE Header, and JWT Header with a
single JOSE Header term defined in the JWS specification. This single JOSE Header term defined in the JWS specification. This
also enabled a single Header Parameter definition to be used and also enabled a single Header Parameter definition to be used and
reduced other areas of duplication between specifications. reduced other areas of duplication between specifications.
-28 -28
o Revised the introduction to the Security Considerations section. o Revised the introduction to the Security Considerations section.
 End of changes. 13 change blocks. 
27 lines changed or deleted 39 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/