draft-ietf-jose-json-web-key-14.txt   draft-ietf-jose-json-web-key-15.txt 
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track July 29, 2013 Intended status: Standards Track September 3, 2013
Expires: January 30, 2014 Expires: March 7, 2014
JSON Web Key (JWK) JSON Web Key (JWK)
draft-ietf-jose-json-web-key-14 draft-ietf-jose-json-web-key-15
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 and IANA registries defined by
that specification.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 30, 2014. This Internet-Draft will expire on March 7, 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 16 skipping to change at page 2, line 17
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
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) Parameter . . . . . . . . . . . . . . . 5
3.6. "x5t" (X.509 Certificate Thumbprint) Header Parameter . . 6 3.6. "x5t" (X.509 Certificate Thumbprint) 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 . . . . . . . . . . . . . . . . . . . 7 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 . . . . . . . . . . . . . . 9 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
skipping to change at page 3, line 12 skipping to change at page 3, line 12
Appendix D. Document History . . . . . . . . . . . . . . . . . . 19 Appendix D. Document History . . . . . . . . . . . . . . . . . . 19
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 22 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 22
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. separate JSON Web Algorithms (JWA) [JWA] specification and IANA
registries defined by that specification.
Goals for this specification do not include representing certificate Goals for this specification do not include representing certificate
chains, representing certified keys, and replacing X.509 chains, representing certified keys, and replacing X.509
certificates. certificates.
JWKs and JWK Sets are used in the JSON Web Signature (JWS) [JWS] and JWKs and JWK Sets are used in the JSON Web Signature (JWS) [JWS] and
JSON Web Encryption (JWE) [JWE] specifications. JSON Web Encryption (JWE) [JWE] specifications.
Names defined by this specification are short because a core goal is
for the resulting representations to be compact.
1.1. Notational Conventions 1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in Key words for use in document are to be interpreted as described in Key words for use in
RFCs to Indicate Requirement Levels [RFC2119]. RFCs to Indicate Requirement Levels [RFC2119].
2. Terminology 2. Terminology
JSON Web Key (JWK) A JSON object that represents a cryptographic JSON Web Key (JWK) A JSON object that represents a cryptographic
key. key.
JSON Web Key Set (JWK Set) A JSON object that contains an array of JSON Web Key Set (JWK Set) A JSON object that contains an array of
JWKs as the value of its "keys" member. JWKs as the value of its "keys" member.
Base64url Encoding The URL- and filename-safe Base64 encoding Base64url Encoding Base64 encoding using the URL- and filename-safe
described in RFC 4648 [RFC4648], Section 5, with the (non URL- character set defined in Section 5 of RFC 4648 [RFC4648], with all
safe) '=' padding characters omitted, as permitted by Section 3.2. trailing '=' characters omitted (as permitted by Section 3.2).
(See Appendix C of [JWS] for notes on implementing base64url (See Appendix C of [JWS] for notes on implementing base64url
encoding without padding.) encoding without padding.)
Collision Resistant Namespace A namespace that allows names to be Collision Resistant Namespace A namespace that allows names to be
allocated in a manner such that they are highly unlikely to allocated in a manner such that they are highly unlikely to
collide with other names. For instance, collision resistance can collide with other names. Examples of Collision Resistant
be achieved through administrative delegation of portions of the Namespaces include: Domain Names, Object Identifiers (OIDs) as
namespace or through use of collision-resistant name allocation defined in the ITU-T X.660 and X.670 Recommendation series, and
functions. Examples of Collision Resistant Namespaces include: Universally Unique IDentifiers (UUIDs) [RFC4122]. When using an
Domain Names, Object Identifiers (OIDs) as defined in the ITU-T administratively delegated namespace, the definer of a name needs
X.660 and X.670 Recommendation series, and Universally Unique to take reasonable precautions to ensure they are in control of
IDentifiers (UUIDs) [RFC4122]. When using an administratively the portion of the namespace they use to define the name.
delegated namespace, the definer of a name needs to take
reasonable precautions to ensure they are in control of the
portion of the namespace they use to define the name.
Encrypted JWK A JWE with a JWK as its plaintext value.
Encrypted JWK Set A JWE with a JWK Set as its plaintext value.
3. JSON Web Key (JWK) Format 3. JSON Web Key (JWK) Format
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 multiple key types specified below. Those members that are common to multiple key types
are defined below. are 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
skipping to change at page 5, line 39 skipping to change at page 5, line 38
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 interpretation of the "kid" value is Set during key rollover. The interpretation 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. The "kid" keys within the JWK Set SHOULD use distinct "kid" values. 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 can be used to match a JWS When used with JWS or JWE, the "kid" value can be used to match a JWS
or JWE "kid" header parameter value. or JWE "kid" header parameter value.
3.5. "x5u" (X.509 URL) Header Parameter 3.5. "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 bare public key represented by other certificate MUST match the bare public key represented by other
members of the JWK. The protocol used to acquire the resource MUST members of the JWK. The protocol used to acquire the resource MUST
provide integrity protection; an HTTP GET request to retrieve the provide integrity protection; an HTTP GET request to retrieve the
certificate MUST use TLS [RFC2818] [RFC5246]; the identity of the certificate MUST use TLS [RFC2818] [RFC5246]; the identity of the
server MUST be validated, as per Section 3.1 of HTTP Over TLS server MUST be validated, as per Section 3.1 of HTTP Over TLS
[RFC2818]. Use of this member is OPTIONAL. [RFC2818]. Use of this member is OPTIONAL.
3.6. "x5t" (X.509 Certificate Thumbprint) Header Parameter 3.6. "x5t" (X.509 Certificate Thumbprint) 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
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
skipping to change at page 12, line 20 skipping to change at page 12, line 20
must be faced by a JWS/JWE/JWK agent. Among these issues are must be faced by a JWS/JWE/JWK agent. Among these issues are
protecting the user's private and symmetric keys, preventing various protecting the user's private and symmetric keys, preventing various
attacks, and helping the user avoid mistakes such as inadvertently attacks, and helping the user avoid mistakes such as inadvertently
encrypting a message for the wrong recipient. The entire list of encrypting a message for the wrong recipient. The entire list of
security considerations is beyond the scope of this document, but security considerations is beyond the scope of this document, but
some significant considerations are listed here. some significant considerations are listed here.
A key is no more trustworthy than the method by which it was A key is no more trustworthy than the method by which it was
received. received.
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 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
skipping to change at page 13, line 7 skipping to change at page 13, line 7
[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 2013. September 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), July 2013. (work in progress), September 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), July 2013. in progress), September 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 4 skipping to change at page 18, line 4
"k":"GawgguFyGrWKav7AX4VKUg"}, "k":"GawgguFyGrWKav7AX4VKUg"},
{"kty":"oct", {"kty":"oct",
"k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75 "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75
aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow", aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow",
"kid":"HMAC key used in JWS A.1 example"} "kid":"HMAC key used in JWS A.1 example"}
] ]
} }
Appendix B. Example Use of "x5c" (X.509 Certificate Chain) Parameter Appendix B. Example Use of "x5c" (X.509 Certificate Chain) Parameter
The following is a non-normative example of a JWK with a RSA signing The following is an example of a JWK with a RSA signing key
key represented both as a bare public key and as an X.509 certificate represented both as a bare public key and as an X.509 certificate
using the "x5c" parameter: using the "x5c" parameter:
{"kty":"RSA", {"kty":"RSA",
"use":"sig", "use":"sig",
"kid":"1b94c", "kid":"1b94c",
"n":"vrjOfz9Ccdgx5nQudyhdoR17V-IubWMeOZCwX_jj0hgAsz2J_pqYW08 "n":"vrjOfz9Ccdgx5nQudyhdoR17V-IubWMeOZCwX_jj0hgAsz2J_pqYW08
PLbK_PdiVGKPrqzmDIsLI7sA25VEnHU1uCLNwBuUiCO11_-7dYbsr4iJmG0Q PLbK_PdiVGKPrqzmDIsLI7sA25VEnHU1uCLNwBuUiCO11_-7dYbsr4iJmG0Q
u2j8DsVyT1azpJC_NG84Ty5KKthuCaPod7iI7w0LK9orSMhBEwwZDCxTWq4a u2j8DsVyT1azpJC_NG84Ty5KKthuCaPod7iI7w0LK9orSMhBEwwZDCxTWq4a
YWAchc8t-emd9qOvWtVMDC2BXksRngh6X5bUYLy6AyHKvj-nUy1wgzjYQDwH YWAchc8t-emd9qOvWtVMDC2BXksRngh6X5bUYLy6AyHKvj-nUy1wgzjYQDwH
MTplCoLtU-o-8SNnZ1tmRoGE9uJkBLdh5gFENabWnU5m1ZqZPdwS-qo-meMv MTplCoLtU-o-8SNnZ1tmRoGE9uJkBLdh5gFENabWnU5m1ZqZPdwS-qo-meMv
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 ]]
-15
o Changes to address editorial issues #48, #64, #65, #66, and #91.
-14 -14
o Relaxed language introducing key parameters since some parameters o Relaxed language introducing key parameters since some parameters
are applicable to multiple, but not all, key types. are applicable to multiple, but not all, key types.
-13 -13
o Applied spelling and grammar corrections. o Applied spelling and grammar corrections.
-12 -12
 End of changes. 17 change blocks. 
33 lines changed or deleted 35 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/