< draft-ietf-jose-json-web-key-31.txt   draft-ietf-jose-json-web-key-32.txt >
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track July 4, 2014 Intended status: Standards Track September 23, 2014
Expires: January 5, 2015 Expires: March 27, 2015
JSON Web Key (JWK) JSON Web Key (JWK)
draft-ietf-jose-json-web-key-31 draft-ietf-jose-json-web-key-32
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 January 5, 2015. This Internet-Draft will expire on March 27, 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 2, line 47 skipping to change at page 2, line 47
8.3.2. Initial Registry Contents . . . . . . . . . . . . . . 16 8.3.2. Initial Registry Contents . . . . . . . . . . . . . . 16
8.4. JSON Web Key Set Parameters Registry . . . . . . . . . . . 17 8.4. JSON Web Key Set Parameters Registry . . . . . . . . . . . 17
8.4.1. Registration Template . . . . . . . . . . . . . . . . 17 8.4.1. Registration Template . . . . . . . . . . . . . . . . 17
8.4.2. Initial Registry Contents . . . . . . . . . . . . . . 18 8.4.2. Initial Registry Contents . . . . . . . . . . . . . . 18
8.5. Media Type Registration . . . . . . . . . . . . . . . . . 18 8.5. Media Type Registration . . . . . . . . . . . . . . . . . 18
8.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 8.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
9. Security Considerations . . . . . . . . . . . . . . . . . . . 19 9. Security Considerations . . . . . . . . . . . . . . . . . . . 19
9.1. Key Provenance and Trust . . . . . . . . . . . . . . . . . 19 9.1. Key Provenance and Trust . . . . . . . . . . . . . . . . . 19
9.2. Preventing Disclosure of Non-Public Key Information . . . 20 9.2. Preventing Disclosure of Non-Public Key Information . . . 20
9.3. RSA Private Key Representations and Blinding . . . . . . . 20 9.3. RSA Private Key Representations and Blinding . . . . . . . 20
9.4. Key Entropy and Random Values . . . . . . . . . . . . . . 20
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20
10.1. Normative References . . . . . . . . . . . . . . . . . . . 20 10.1. Normative References . . . . . . . . . . . . . . . . . . . 20
10.2. Informative References . . . . . . . . . . . . . . . . . . 22 10.2. Informative References . . . . . . . . . . . . . . . . . . 22
Appendix A. Example JSON Web Key Sets . . . . . . . . . . . . . . 23 Appendix A. Example JSON Web Key Sets . . . . . . . . . . . . . . 23
A.1. Example Public Keys . . . . . . . . . . . . . . . . . . . 23 A.1. Example Public Keys . . . . . . . . . . . . . . . . . . . 23
A.2. Example Private Keys . . . . . . . . . . . . . . . . . . . 23 A.2. Example Private Keys . . . . . . . . . . . . . . . . . . . 23
A.3. Example Symmetric Keys . . . . . . . . . . . . . . . . . . 25 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 . . . . . . . . . . . . . . . . . . . . . . 25 Parameter . . . . . . . . . . . . . . . . . . . . . . 25
Appendix C. Example Encrypted RSA Private Key . . . . . . . . . . 26 Appendix C. Example Encrypted RSA Private Key . . . . . . . . . . 26
C.1. Plaintext RSA Private Key . . . . . . . . . . . . . . . . 27 C.1. Plaintext RSA Private Key . . . . . . . . . . . . . . . . 27
C.2. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . 30 C.2. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . 30
C.3. Content Encryption Key (CEK) . . . . . . . . . . . . . . . 30 C.3. Content Encryption Key (CEK) . . . . . . . . . . . . . . . 30
skipping to change at page 5, line 36 skipping to change at page 5, line 36
"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.
4. JSON Web Key (JWK) Format 4. JSON Web Key (JWK) Format
A JSON Web Key (JWK) is a JSON object that represents a cryptographic A JSON Web Key (JWK) is a JSON object that represents a cryptographic
key. The members of the object represent properties of the key, key. The members of the object represent properties of the key,
including its value. This document defines the key parameters that including its value. This JSON object MAY contain white space and/or
are not algorithm specific, and thus common to many keys. line breaks. 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
skipping to change at page 10, line 4 skipping to change at page 10, line 4
public key may also be populated when an "x5t#S256" member is public key may also be populated when an "x5t#S256" member is
present. If other members are present, the contents of those members present. If other members are present, the contents of those members
MUST be semantically consistent with the related fields in the MUST be semantically consistent with the related fields in the
referenced certificate. See the last paragraph of Section 4.6 for referenced certificate. See the last paragraph of Section 4.6 for
additional guidance on this. additional guidance on this.
5. JSON Web Key Set (JWK Set) Format 5. JSON Web Key Set (JWK Set) Format
A JSON Web Key Set (JWK Set) is a JSON object that represents a set 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 of JWKs. The JSON object MUST have a "keys" member, which is an
array of JWK objects. array of JWK objects. This JSON object MAY contain white space
and/or line breaks.
The member names within a JWK Set MUST be unique; 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
skipping to change at page 19, line 32 skipping to change at page 19, line 32
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 that are pertinent to any cryptographic All of the security issues that are pertinent to any cryptographic
application must be addressed by JWS/JWE/JWK agents. Among these application must be addressed by JWS/JWE/JWK agents. Among these
issues are protecting the user's asymmetric private and symmetric issues are protecting the user's asymmetric private and symmetric
secret keys, preventing various attacks, and helping avoid mistakes secret keys and employing countermeasures to various attacks.
such as inadvertently encrypting a message to the wrong recipient.
The entire list of security considerations is beyond the scope of
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. See Section 10.3 of [JWS]
for security considerations on key origin authentication.
The security considerations in Section 12.3 of XML DSIG 2.0 The security considerations in Section 12.3 of XML DSIG 2.0
[W3C.NOTE-xmldsig-core2-20130411] about the strength of a signature [W3C.NOTE-xmldsig-core2-20130411] about the strength of a signature
depending upon all the links in the security chain also apply to this depending upon all the links in the security chain also apply to this
specification. specification.
The TLS Requirements in [JWS] also apply to this specification. The TLS Requirements in Section 8 of [JWS] also apply to this
specification.
9.2. Preventing Disclosure of Non-Public Key Information 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
skipping to change at page 20, line 31 skipping to change at page 20, line 31
the public exponent "e", but only include the modulus "n" and the the public exponent "e", but only include the modulus "n" and the
private exponent "d". This is true, for instance, of the Java private exponent "d". This is true, for instance, of the Java
RSAPrivateKeySpec API, which does not include the public exponent "e" RSAPrivateKeySpec API, which does not include the public exponent "e"
as a parameter. So as to enable RSA key blinding, such as a parameter. So as to enable RSA key blinding, such
representations should be avoided. For Java, the representations should be avoided. For Java, the
RSAPrivateCrtKeySpec API can be used instead. Section 8.2.2(i) of RSAPrivateCrtKeySpec API can be used instead. Section 8.2.2(i) of
the Handbook of Applied Cryptography [HAC] discusses how to compute the Handbook of Applied Cryptography [HAC] discusses how to compute
the remaining RSA private key parameters, if needed, using only "n", the remaining RSA private key parameters, if needed, using only "n",
"e", and "d". "e", and "d".
9.4. Key Entropy and Random Values
See Section 10.1 of [JWS] for security considerations on key entropy
and random values.
10. References 10. References
10.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
skipping to change at page 21, line 4 skipping to change at page 21, line 9
[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),
July 2014. September 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),
July 2014. September 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), July 2014. in progress), September 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 37, line 29 skipping to change at page 37, line 29
Hannes Tschofenig, 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 ]]
-32
o Addressed Gen-ART review comments by Russ Housley.
o Addressed secdir review comments by Stephen Kent.
-31 -31
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.
-30 -30
o Added references and cleaned up the reference syntax in a few o Added references and cleaned up the reference syntax in a few
places. places.
o Applied minor wording changes to the Security Considerations o Applied minor wording changes to the Security Considerations
 End of changes. 15 change blocks. 
16 lines changed or deleted 30 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/