draft-ietf-jose-json-web-key-40.txt   draft-ietf-jose-json-web-key-41.txt 
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track January 13, 2015 Intended status: Standards Track January 16, 2015
Expires: July 17, 2015 Expires: July 20, 2015
JSON Web Key (JWK) JSON Web Key (JWK)
draft-ietf-jose-json-web-key-40 draft-ietf-jose-json-web-key-41
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 July 17, 2015. This Internet-Draft will expire on July 20, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2015 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 28 skipping to change at page 2, line 28
4.5. "kid" (Key ID) Parameter . . . . . . . . . . . . . . . . . 8 4.5. "kid" (Key ID) Parameter . . . . . . . . . . . . . . . . . 8
4.6. "x5u" (X.509 URL) Parameter . . . . . . . . . . . . . . . 8 4.6. "x5u" (X.509 URL) Parameter . . . . . . . . . . . . . . . 8
4.7. "x5c" (X.509 Certificate Chain) Parameter . . . . . . . . 9 4.7. "x5c" (X.509 Certificate Chain) Parameter . . . . . . . . 9
4.8. "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter . . . 9 4.8. "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter . . . 9
4.9. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) 4.9. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint)
Parameter . . . . . . . . . . . . . . . . . . . . . . . . 10 Parameter . . . . . . . . . . . . . . . . . . . . . . . . 10
5. JSON Web Key Set (JWK Set) Format . . . . . . . . . . . . . . 10 5. JSON Web Key Set (JWK Set) Format . . . . . . . . . . . . . . 10
5.1. "keys" Parameter . . . . . . . . . . . . . . . . . . . . . 11 5.1. "keys" Parameter . . . . . . . . . . . . . . . . . . . . . 11
6. String Comparison Rules . . . . . . . . . . . . . . . . . . . 11 6. String Comparison Rules . . . . . . . . . . . . . . . . . . . 11
7. Encrypted JWK and Encrypted JWK Set Formats . . . . . . . . . 11 7. Encrypted JWK and Encrypted JWK Set Formats . . . . . . . . . 11
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
8.1. JSON Web Key Parameters Registry . . . . . . . . . . . . . 13 8.1. JSON Web Key Parameters Registry . . . . . . . . . . . . . 13
8.1.1. Registration Template . . . . . . . . . . . . . . . . 13 8.1.1. Registration Template . . . . . . . . . . . . . . . . 13
8.1.2. Initial Registry Contents . . . . . . . . . . . . . . 14 8.1.2. Initial Registry Contents . . . . . . . . . . . . . . 14
8.2. JSON Web Key Use Registry . . . . . . . . . . . . . . . . 15 8.2. JSON Web Key Use Registry . . . . . . . . . . . . . . . . 15
8.2.1. Registration Template . . . . . . . . . . . . . . . . 15 8.2.1. Registration Template . . . . . . . . . . . . . . . . 16
8.2.2. Initial Registry Contents . . . . . . . . . . . . . . 16 8.2.2. Initial Registry Contents . . . . . . . . . . . . . . 16
8.3. JSON Web Key Operations Registry . . . . . . . . . . . . . 16 8.3. JSON Web Key Operations Registry . . . . . . . . . . . . . 16
8.3.1. Registration Template . . . . . . . . . . . . . . . . 16 8.3.1. Registration Template . . . . . . . . . . . . . . . . 17
8.3.2. Initial Registry Contents . . . . . . . . . . . . . . 17 8.3.2. Initial Registry Contents . . . . . . . . . . . . . . 17
8.4. JSON Web Key Set Parameters Registry . . . . . . . . . . . 18 8.4. JSON Web Key Set Parameters Registry . . . . . . . . . . . 18
8.4.1. Registration Template . . . . . . . . . . . . . . . . 18 8.4.1. Registration Template . . . . . . . . . . . . . . . . 18
8.4.2. Initial Registry Contents . . . . . . . . . . . . . . 19 8.4.2. Initial Registry Contents . . . . . . . . . . . . . . 19
8.5. Media Type Registration . . . . . . . . . . . . . . . . . 19 8.5. Media Type Registration . . . . . . . . . . . . . . . . . 19
8.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 19 8.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 19
9. Security Considerations . . . . . . . . . . . . . . . . . . . 20 9. Security Considerations . . . . . . . . . . . . . . . . . . . 20
9.1. Key Provenance and Trust . . . . . . . . . . . . . . . . . 20 9.1. Key Provenance and Trust . . . . . . . . . . . . . . . . . 20
9.2. Preventing Disclosure of Non-Public Key Information . . . 21 9.2. Preventing Disclosure of Non-Public Key Information . . . 21
9.3. RSA Private Key Representations and Blinding . . . . . . . 21 9.3. RSA Private Key Representations and Blinding . . . . . . . 21
9.4. Key Entropy and Random Values . . . . . . . . . . . . . . 21 9.4. Key Entropy and Random Values . . . . . . . . . . . . . . 22
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22
10.1. Normative References . . . . . . . . . . . . . . . . . . . 22 10.1. Normative References . . . . . . . . . . . . . . . . . . . 22
10.2. Informative References . . . . . . . . . . . . . . . . . . 23 10.2. Informative References . . . . . . . . . . . . . . . . . . 24
Appendix A. Example JSON Web Key Sets . . . . . . . . . . . . . . 24 Appendix A. Example JSON Web Key Sets . . . . . . . . . . . . . . 25
A.1. Example Public Keys . . . . . . . . . . . . . . . . . . . 24 A.1. Example Public Keys . . . . . . . . . . . . . . . . . . . 25
A.2. Example Private Keys . . . . . . . . . . . . . . . . . . . 25 A.2. Example Private Keys . . . . . . . . . . . . . . . . . . . 25
A.3. Example Symmetric Keys . . . . . . . . . . . . . . . . . . 27 A.3. Example Symmetric Keys . . . . . . . . . . . . . . . . . . 27
Appendix B. Example Use of "x5c" (X.509 Certificate Chain) Appendix B. Example Use of "x5c" (X.509 Certificate Chain)
Parameter . . . . . . . . . . . . . . . . . . . . . . 27 Parameter . . . . . . . . . . . . . . . . . . . . . . 27
Appendix C. Example Encrypted RSA Private Key . . . . . . . . . . 28 Appendix C. Example Encrypted RSA Private Key . . . . . . . . . . 28
C.1. Plaintext RSA Private Key . . . . . . . . . . . . . . . . 29 C.1. Plaintext RSA Private Key . . . . . . . . . . . . . . . . 29
C.2. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . 32 C.2. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . 32
C.3. Content Encryption Key (CEK) . . . . . . . . . . . . . . . 32 C.3. Content Encryption Key (CEK) . . . . . . . . . . . . . . . 32
C.4. Key Derivation . . . . . . . . . . . . . . . . . . . . . . 33 C.4. Key Derivation . . . . . . . . . . . . . . . . . . . . . . 33
C.5. Key Encryption . . . . . . . . . . . . . . . . . . . . . . 33 C.5. Key Encryption . . . . . . . . . . . . . . . . . . . . . . 33
C.6. Initialization Vector . . . . . . . . . . . . . . . . . . 33 C.6. Initialization Vector . . . . . . . . . . . . . . . . . . 33
C.7. Additional Authenticated Data . . . . . . . . . . . . . . 34 C.7. Additional Authenticated Data . . . . . . . . . . . . . . 34
C.8. Content Encryption . . . . . . . . . . . . . . . . . . . . 34 C.8. Content Encryption . . . . . . . . . . . . . . . . . . . . 34
C.9. Complete Representation . . . . . . . . . . . . . . . . . 37 C.9. Complete Representation . . . . . . . . . . . . . . . . . 37
Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 39 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 39
Appendix E. Document History . . . . . . . . . . . . . . . . . . 39 Appendix E. Document History . . . . . . . . . . . . . . . . . . 39
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 46 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 47
1. Introduction 1. Introduction
A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) [RFC7159] A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) [RFC7159]
data structure that represents a cryptographic key. This data structure that represents a cryptographic key. This
specification also defines a JSON Web Key Set (JWK Set) JSON data specification also defines a JSON Web Key Set (JWK Set) JSON data
structure that represents a set of JWKs. Cryptographic algorithms structure that represents a set of JWKs. Cryptographic algorithms
and identifiers for use with this specification are described in the and identifiers for use with this specification are described in the
separate JSON Web Algorithms (JWA) [JWA] specification and IANA separate JSON Web Algorithms (JWA) [JWA] specification and IANA
registries defined by that specification. registries defined by that specification.
skipping to change at page 4, line 50 skipping to change at page 4, line 50
ASCII(STRING) denotes the octets of the ASCII [RFC20] representation ASCII(STRING) denotes the octets of the ASCII [RFC20] representation
of STRING, where STRING is a sequence of zero or more ASCII of STRING, where STRING is a sequence of zero or more ASCII
characters. characters.
The concatenation of two values A and B is denoted as A || B. The concatenation of two values A and B is denoted as A || B.
2. Terminology 2. Terminology
These terms defined by the JSON Web Signature (JWS) [JWS] These terms defined by the JSON Web Signature (JWS) [JWS]
specification are incorporated into this specification: "Base64url specification are incorporated into this specification: "JSON Web
Encoding", "Collision-Resistant Name", "Header Parameter", and "JOSE Signature (JWS)", "Base64url Encoding", "Collision-Resistant Name",
"Header Parameter", and "JOSE Header".
These terms defined by the JSON Web Encryption (JWE) [JWE]
specification are incorporated into this specification: "JSON Web
Encryption (JWE)", "Additional Authenticated Data (AAD)", "JWE
Authentication Tag", "JWE Ciphertext", "JWE Compact Serialization",
"JWE Encrypted Key", "JWE Initialization Vector", and "JWE Protected
Header". Header".
These terms defined by the Internet Security Glossary, Version 2 These terms defined by the Internet Security Glossary, Version 2
[RFC4949] are incorporated into this specification: "Ciphertext", [RFC4949] are incorporated into this specification: "Ciphertext",
"Digital Signature", "Message Authentication Code (MAC)", and "Digital Signature", "Message Authentication Code (MAC)", and
"Plaintext". "Plaintext".
These terms are defined by this specification: These terms are defined by this specification:
JSON Web Key (JWK) JSON Web Key (JWK)
skipping to change at page 9, line 12 skipping to change at page 9, line 19
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 optional JWK members providing key While there is no requirement that optional JWK members providing key
usage, algorithm, or other information be present when the "x5u" usage, algorithm, or other information be present when the "x5u"
member is used, doing so may improve interoperability for member is used, doing so may improve interoperability for
applications that do not handle PKIX certificates. If other members applications that do not handle PKIX certificates [RFC5280]. If
are present, the contents of those members MUST be semantically other members are present, the contents of those members MUST be
consistent with the related fields in the first certificate. For semantically consistent with the related fields in the first
instance, if the "use" member is present, then it MUST correspond to certificate. For instance, if the "use" member is present, then it
the usage that is specified in the certificate, when it includes this MUST correspond to the usage that is specified in the certificate,
information. Similarly, if the "alg" member is present, it MUST when it includes this information. Similarly, if the "alg" member is
correspond to the algorithm specified in the certificate. present, it MUST correspond to the algorithm specified in the
certificate.
4.7. "x5c" (X.509 Certificate Chain) Parameter 4.7. "x5c" (X.509 Certificate Chain) Parameter
The "x5c" (X.509 Certificate Chain) member contains a chain of one or The "x5c" (X.509 Certificate Chain) member contains a chain of one or
more PKIX certificates [RFC5280]. The certificate chain is more PKIX certificates [RFC5280]. The certificate chain is
represented as a JSON array of certificate value strings. Each represented as a JSON array of certificate value strings. Each
string in the array is a base64 encoded ([RFC4648] Section 4 -- not string in the array is a base64 encoded ([RFC4648] Section 4 -- not
base64url encoded) DER [ITU.X690.1994] PKIX certificate value. The base64url encoded) DER [ITU.X690.1994] PKIX certificate value. The
PKIX certificate containing the key value MUST be the first PKIX certificate containing the key value MUST be the first
certificate. This MAY be followed by additional certificates, with certificate. This MAY be followed by additional certificates, with
skipping to change at page 20, line 51 skipping to change at page 20, line 51
9.1. Key Provenance and Trust 9.1. Key Provenance and Trust
One should place no more trust in the data cryptographically secured One should place no more trust in the data cryptographically secured
by a key than in the method by which it was obtained and in the by a key than in 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. See Section 10.3 of [JWS] manner should be treated with skepticism. See Section 10.3 of [JWS]
for security considerations on key origin authentication. for security considerations on key origin authentication.
The security considerations in Section 12.3 of XML DSIG 2.0 In almost all cases, applications make decisions about whether to
trust a key based on attributes bound to the key, such as names,
roles, and the key origin, rather than based on the key itself. When
an application is deciding whether to trust a key, there are several
ways that it can bind attributes to a JWK. Two example mechanisms
are PKIX [RFC5280] and JSON Web Token (JWT) [JWT].
For instance, the creator of a JWK can include a PKIX certificate in
the JWK's "x5c" member. If the application validates the certificate
and verifies that the JWK corresponds to the subject public key in
the certificate, then the JWK can be associated with the attributes
in the certificate, such as the subject name, subject alternative
names, extended key usages, and its signature chain.
Also for instance, a JWT can be used to associate attributes with a
JWK by referencing the JWK as a claim in the JWT. The JWK can be
included directly as a claim value or the JWT can include a TLS-
secured URI from which to retrieve the JWK value. Either way, an
application that gets a JWK via a JWT claim can associate it with the
JWT's cryptographic properties and use these and possibly additional
claims in deciding whether to trust the key.
The security considerations in Section 12.3 of XML DSIG 2.0
[W3C.NOTE-xmldsig-core2-20130411] about the strength of a digital [W3C.NOTE-xmldsig-core2-20130411] about the strength of a digital
signature depending upon all the links in the security chain also signature depending upon all the links in the security chain also
apply to this specification. apply to this specification.
The TLS Requirements in Section 8 of [JWS] also apply to this The TLS Requirements in Section 8 of [JWS] also apply to this
specification, except that the "x5u" JWK member is the only feature specification, except that the "x5u" JWK member is the only feature
defined by this specification using TLS. defined by this specification using TLS.
9.2. Preventing Disclosure of Non-Public Key Information 9.2. Preventing Disclosure of Non-Public Key Information
skipping to change at page 23, line 43 skipping to change at page 24, line 14
10.2. Informative References 10.2. Informative References
[DSS] National Institute of Standards and Technology, "Digital [DSS] National Institute of Standards and Technology, "Digital
Signature Standard (DSS)", FIPS PUB 186-4, July 2013. 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>.
[JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", draft-ietf-oauth-json-web-token (work in
progress), January 2015.
[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.
[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.
skipping to change at page 39, line 34 skipping to change at page 39, line 34
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 ]]
-41
o Added Security Considerations text about binding attributes to
keys.
o Incorporated additional terms defined in the JWE spec by
reference.
-40 -40
o Clarified the definitions of UTF8(STRING) and ASCII(STRING). o Clarified the definitions of UTF8(STRING) and ASCII(STRING).
o Stated that line breaks are for display purposes only in places o Stated that line breaks are for display purposes only in places
where this disclaimer was needed and missing. where this disclaimer was needed and missing.
o Updated the WebCrypto reference to refer to the W3C Candidate o Updated the WebCrypto reference to refer to the W3C Candidate
Recommendation. Recommendation.
 End of changes. 16 change blocks. 
22 lines changed or deleted 63 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/