JSON Web Key (JWK)Microsoftmbj@microsoft.comhttp://self-issued.info/
Security
JOSE Working GroupRFCRequest for CommentsI-DInternet-DraftJavaScript Object NotationJSONJSON Object Signing and EncryptionJOSEJSON Web SignatureJWSJSON Web EncryptionJWEJSON Web KeyJWKJSON Web AlgorithmsJWA
A JSON Web Key (JWK) is a JavaScript Object Notation (JSON)
data structure that represents a cryptographic key.
This specification also defines a JSON Web Key Set (JWK Set)
JSON data structure for representing a set of JWKs.
Cryptographic algorithms and identifiers for use with this
specification are described in the separate
JSON Web Algorithms (JWA) specification.
A JSON Web Key (JWK) is a
JavaScript Object Notation (JSON)
data structure that represents a cryptographic key.
This specification also defines a JSON Web Key Set (JWK Set)
JSON data structure for representing a set of JWKs.
Cryptographic algorithms and identifiers for use with this
specification are described in the separate
JSON Web Algorithms (JWA) specification.
Goals for this specification do not include representing
certificate chains, representing certified keys, and replacing
X.509 certificates.
JWKs and JWK Sets are used in the
JSON Web Signature (JWS)
and
JSON Web Encryption (JWE)
specifications.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" in this document are to be interpreted as
described in
Key words for use in RFCs to Indicate Requirement Levels .
A JSON object that represents a cryptographic key.
A JSON object that contains an array of JWKs as
the value of its keys member.
The URL- and filename-safe Base64 encoding
described in RFC 4648,
Section 5, with the (non URL-safe) '=' padding characters
omitted, as permitted by Section 3.2. (See Appendix C of
for notes on implementing base64url
encoding without padding.)
A namespace that allows names to be allocated in a manner
such that they are highly unlikely to collide with other names.
For instance, collision resistance can be achieved through
administrative delegation of portions of the namespace or
through use of collision-resistant name allocation functions.
Examples of Collision Resistant Namespaces include:
Domain Names,
Object Identifiers (OIDs) as defined in the ITU-T X.660
and X.670 Recommendation series, and
Universally Unique IDentifiers (UUIDs)
.
When using an administratively 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.
A JWE with a JWK as its plaintext value.
A JWE with a JWK Set as its plaintext value.
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 defined below.
In addition to the common parameters, each JWK will have
members that are specific to the kind of key being represented.
These members represent the parameters of the key.
Section 5 of the JSON Web Algorithms (JWA) specification
defines multiple kinds of cryptographic keys and their associated members.
The member names within a JWK MUST be unique;
recipients MUST either 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 .
Additional members MAY be present in the JWK.
If not understood by implementations encountering them, they MUST be ignored.
Member names used for representing key parameters
for different kinds of keys need not be distinct.
Any new member name
SHOULD either be registered in the IANA JSON Web Key Parameters registry
or be
a value that contains a Collision Resistant Namespace.
The kty (key type) member
identifies the cryptographic algorithm family used with the key.
kty values SHOULD either be
registered in the IANA JSON Web Key Types registry
or be
a value that contains a Collision Resistant Namespace.
The kty value is a case sensitive string.
Use of this member is REQUIRED.
A list of defined kty values can be found
in the IANA JSON Web Key Types registry ;
the initial contents of this registry are the values defined in
Section 5.1 of the
JSON Web Algorithms (JWA) specification.
Additional members used with these kty values can be found
in the IANA JSON Web Key Parameters registry ;
the initial contents of this registry are the values defined in
Sections 5.2 and 5.3 of the
JSON Web Algorithms (JWA) specification.
The use (key use) member identifies the
intended use of the key. Values defined by this specification are:
sig (signature or MAC operation)enc (encryption)
Other values MAY be used.
The use value is a case sensitive string.
Use of this member is OPTIONAL.
The alg (algorithm) member identifies the
algorithm intended for use with the key.
The values used in this field are the same as those used in the
JWS and JWE alg and enc header parameters;
these values can be found in the
JSON Web Signature and Encryption Algorithms registry .
Use of this member is OPTIONAL.
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 Set
during key rollover.
The interpretation of the kid value is unspecified.
When kid values are used
within a JWK Set, different keys within the JWK Set SHOULD use distinct
kid values.
The kid 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 or JWE kid
header parameter value.
The x5u (X.509 URL) member
is a URI that refers to a resource for
an X.509 public key certificate or certificate chain .
The identified resource MUST provide a representation of
the certificate or certificate chain that conforms to
RFC 5280 in PEM encoded form
.
The key in the first certificate MUST match the bare public key
represented by other members of the JWK.
The protocol used to acquire the resource MUST provide
integrity protection; an HTTP GET request to retrieve the
certificate MUST use TLS ;
the identity of the server MUST be validated, as per
Section 3.1 of HTTP Over TLS .
Use of this member is OPTIONAL.
The x5t (X.509 Certificate Thumbprint)
member is a base64url encoded
SHA-1 thumbprint (a.k.a. digest) of the DER encoding of
an X.509 certificate .
The key in the certificate MUST match the bare public key
represented by other members of the JWK.
Use of this member is OPTIONAL.
The x5c (X.509 Certificate Chain) member
contains a chain of one or more PKIX certificates .
The certificate chain is represented as
a JSON array of certificate value strings.
Each string in the array is a base64 encoded
( Section 4 -- not base64url encoded)
DER PKIX certificate value.
The PKIX certificate containing the key value
MUST be the first certificate.
This MAY be followed by additional certificates, with each
subsequent certificate being the one used to certify the
previous one.
The key in the first certificate MUST match the bare public key
represented by other members of the JWK.
Use of this member is OPTIONAL.
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.
The member names within a JWK Set MUST be unique;
recipients MUST 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 .
Additional members MAY be present in the JWK Set.
If not understood by implementations encountering them, they MUST be ignored.
Parameters for representing additional properties of JWK Sets
SHOULD either be registered in the IANA JSON Web Key Set Parameters registry
or be
a value that contains a Collision Resistant Namespace.
The value of the keys (JSON Web Key Set)
member is an array of JSON Web Key (JWK) values.
Use of this member is REQUIRED.
Processing a JWK inevitably requires comparing known strings
to values in JSON objects. For example, in checking what the
key type is, the Unicode string encoding
kty will be
checked against the member names in the JWK
to see if there is a matching name.
Comparisons between JSON strings and other Unicode strings
MUST be performed by comparing Unicode code points without normalization
as specified in the String Comparison Rules in Section 5.3 of .
JWKs containing non-public key material will need to be encrypted
in some contexts to prevent the disclosure of private or symmetric
key values to unintended parties.
The use of an Encrypted JWK, which is a JWE with a JWK
as its plaintext value, is RECOMMENED for this purpose.
The processing of Encrypted JWKs is identical to
the processing of other JWEs.
A cty (content type) header parameter
value of JWK can be used to indicate
that the content of the JWE is a JWK in contexts where this is useful.
JWK Sets containing non-public key material will similarly need to be encrypted.
The use of an Encrypted JWK Set, which is a JWE with a JWK Set
as its plaintext value, is RECOMMENED for this purpose.
The processing of Encrypted JWK Sets is identical to
the processing of other JWEs.
A cty (content type) header parameter
value of JWK-SET can be used to indicate
that the content of the JWE is a JWK Set in contexts where this is useful.
The following registration procedure is used for all the
registries established by this specification.
Values are registered with a Specification Required
after a two-week review period on the [TBD]@ietf.org mailing
list, on the advice of one or more Designated Experts. However, to allow for the
allocation of values prior to publication, the Designated Expert(s) may approve
registration once they are satisfied that such a specification will be published.
Registration requests must be sent to the [TBD]@ietf.org mailing list for review and
comment, with an appropriate subject (e.g., "Request for access token type: example").
[[ Note to RFC-EDITOR: The name of the mailing list should be determined in consultation
with the IESG and IANA. Suggested name: jose-reg-review. ]]
Within the review period, the Designated Expert(s) will either approve or
deny the registration request, communicating this decision to the review list and IANA.
Denials should include an explanation and, if applicable, suggestions as to how to make
the request successful.
IANA must only accept registry updates from the Designated Expert(s) and should direct
all requests for registration to the review mailing list.
This specification establishes the
IANA JSON Web Key Parameters registry
for reserved JWK parameter names.
The registry records the reserved parameter name
and a reference to the specification that defines it.
It also records whether the parameter conveys public or private information.
This specification registers the parameter names defined in
.
The same JWK parameter name may be registered multiple times,
provided that duplicate parameter registrations are only for
algorithm-specific JWK parameters; in this case, the meaning
of the duplicate parameter name is disambiguated by the
kty value of the JWK containing it.
The name requested (e.g., "example").
This name is case sensitive. Names that match other registered names
in a case insensitive manner SHOULD NOT be accepted.
Registers whether the parameter conveys public or private information.
Its value must be one the words Public or Private.
For Standards Track RFCs, state "IETF". For others, give the name of the
responsible party. Other details (e.g., postal address, email address, home page
URI) may also be included.
Reference to the document(s) that specify the parameter, preferably including URI(s) that
can be used to retrieve copies of the document(s). An indication of the relevant
sections may also be included but is not required.
Parameter Name: kty
Parameter Information Class: Public
Change Controller: IETF
Specification Document(s): of [[ this document ]]
Parameter Name: use
Parameter Information Class: Public
Change Controller: IETF
Specification Document(s): of [[ this document ]]
Parameter Name: alg
Parameter Information Class: Public
Change Controller: IETF
Specification Document(s): of [[ this document ]]
Parameter Name: kid
Parameter Information Class: Public
Change Controller: IETF
Specification Document(s): of [[ this document ]]
Parameter Name: x5u
Parameter Information Class: Public
Change Controller: IETF
Specification Document(s): of [[ this document ]]
Parameter Name: x5t
Parameter Information Class: Public
Change Controller: IETF
Specification Document(s): of [[ this document ]]
Parameter Name: x5c
Parameter Information Class: Public
Change Controller: IETF
Specification Document(s): of [[ this document ]]
This specification establishes the
IANA JSON Web Key Set Parameters registry
for reserved JWK Set parameter names.
The registry records the reserved parameter name
and a reference to the specification that defines it.
This specification registers the parameter names defined in
.
The name requested (e.g., "example").
This name is case sensitive. Names that match other registered names
in a case insensitive manner SHOULD NOT be accepted.
For Standards Track RFCs, state "IETF". For others, give the name of the
responsible party. Other details (e.g., postal address, email address, home page
URI) may also be included.
Reference to the document(s) that specify the parameter, preferably including URI(s) that
can be used to retrieve copies of the document(s). An indication of the relevant
sections may also be included but is not required.
Parameter Name: keys
Change Controller: IETF
Specification Document(s): of [[ this document ]]
This specification registers the JWK
and JWK-SET
type values in the
IANA JSON Web Signature and Encryption Type Values registry ,
which can be used to indicate, respectively, that the content is
a JWK or
a JWK Set.
"typ" Header Parameter Value: JWK
Abbreviation for MIME Type: application/jwk+json
Change Controller: IETF
Specification Document(s): of [[ this document ]]
"typ" Header Parameter Value: JWK-SET
Abbreviation for MIME Type: application/jwk-set+json
Change Controller: IETF
Specification Document(s): of [[ this document ]]
This specification registers the
application/jwk+json and
application/jwk-set+json
Media Types
in the MIME Media Type registry ,
which can be used to indicate, respectively, that the content is
a JWK or
a JWK Set.
Type Name: application
Subtype Name: jwk+json
Required Parameters: n/a
Optional Parameters: n/a
Encoding considerations:
application/jwk+json values are represented as JSON object;
UTF-8 encoding SHOULD be employed for the JSON object.
Security Considerations: See the Security Considerations section of [[ this document ]]
Interoperability Considerations: n/a
Published Specification: [[ this document ]]
Applications that use this media type:
TBD
Additional Information: Magic number(s): n/a,
File extension(s): n/a,
Macintosh file type code(s): n/a
Person & email address to contact for further information: Michael B. Jones, mbj@microsoft.com
Intended Usage: COMMON
Restrictions on Usage: none
Author: Michael B. Jones, mbj@microsoft.com
Change Controller: IETF
Type Name: application
Subtype Name: jwk-set+json
Required Parameters: n/a
Optional Parameters: n/a
Encoding considerations:
application/jwk-set+json values are represented as a JSON Object;
UTF-8 encoding SHOULD be employed for the JSON object.
Security Considerations: See the Security Considerations section of [[ this document ]]
Interoperability Considerations: n/a
Published Specification: [[ this document ]]
Applications that use this media type:
TBD
Additional Information: Magic number(s): n/a,
File extension(s): n/a,
Macintosh file type code(s): n/a
Person & email address to contact for further information: Michael B. Jones, mbj@microsoft.com
Intended Usage: COMMON
Restrictions on Usage: none
Author: Michael B. Jones, mbj@microsoft.com
Change Controller: IETF
All of the security issues faced by any cryptographic application
must be faced by a JWS/JWE/JWK agent. Among these issues are protecting
the user's private and symmetric keys, preventing various attacks, and helping the
user avoid mistakes such as inadvertently encrypting a message for
the wrong recipient. The entire list of security considerations is
beyond the scope of this document, but some significant considerations are
listed here.
A key is no more trustworthy than the method by which it was received.
Private and symmetric keys must be protected from disclosure
to 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 the plaintext of a JWE.
The security considerations in
RFC 3447 and RFC 6030
about protecting private and symmetric keys also apply to this specification.
The security considerations in
XML DSIG 2.0,
about key representations also apply to this specification,
other than those that are XML specific.
The TLS Requirements in
also apply to this specification.
JSON Web Signature (JWS)Microsoftmbj@microsoft.comhttp://self-issued.info/Ping Identityve7jtb@ve7jtb.comNomura Research Instituten-sakimura@nri.co.jpJSON Web Encryption (JWE)Microsoftmbj@microsoft.comhttp://self-issued.info/RTFM, Inc.ekr@rtfm.comCisco Systems, Inc.jhildebr@cisco.comJSON Web Algorithms (JWA)Microsoftmbj@microsoft.comhttp://self-issued.info/ECMAScript Language Specification, 5.1 EditionEcma InternationalMagic Signatures
The following example JWK Set contains two public keys
represented as JWKs: one
using an Elliptic Curve algorithm and a second one using an
RSA algorithm. The first specifies that the key is to be
used for encryption.
The second specifies that the key is to be used with the
RS256 algorithm.
Both provide a Key ID for key matching
purposes. In both cases, integers are represented using the
base64url encoding of their big endian representations.
(Long lines are broken are for display purposes only.)
The following example JWK Set contains two keys represented
as JWKs containing both public and private key values:
one using an Elliptic Curve algorithm and
a second one using an RSA algorithm.
This example extends the example in
the previous section,
adding private key values.
(Line breaks are for display purposes only.)
The following example JWK Set contains two symmetric keys represented
as JWKs:
one designated as being for use with the AES Key Wrap algorithm and
a second one that is an HMAC key.
(Line breaks are for display purposes only.)
A JSON representation for RSA public keys was previously
introduced by John Panzer, Ben Laurie, and Dirk Balfanz
in Magic Signatures.
This specification is the work of the JOSE Working Group,
which includes dozens of active and dedicated participants.
In particular, the following individuals contributed ideas,
feedback, and wording that influenced this specification:
Dirk Balfanz,
Richard Barnes,
John Bradley,
Brian Campbell,
Breno de Medeiros,
Joe Hildebrand,
Edmund Jay,
Ben Laurie,
James Manger,
Matt Miller,
Tony Nadalin,
Axel Nennker,
John Panzer,
Eric Rescorla,
Nat Sakimura,
Jim Schaad,
Paul Tarjan,
Hannes Tschofenig,
and Sean Turner.
Jim Schaad and Karen O'Donoghue chaired the JOSE working group and
Sean Turner and Stephen Farrell served as Security area directors
during the creation of this specification.
[[ to be removed by the RFC editor before publication as an RFC ]]
-13
Applied spelling and grammar corrections.
-12
Stated that recipients 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
Stated that when kid values are used
within a JWK Set, different keys within the JWK Set SHOULD use distinct
kid values.
Added optional x5u (X.509 URL),
x5t (X.509 Certificate Thumbprint), and
x5c (X.509 Certificate Chain) JWK parameters.
Added section on Encrypted JWK and Encrypted JWK Set Formats.
Added a Parameter Information Class value to the
JSON Web Key Parameters registry, which registers whether
the parameter conveys public or private information.
Registered application/jwk+json and
application/jwk-set+json MIME types
and JWK and JWK-SET
typ header parameter values, addressing issue #21.
-10
No changes were made, other than to the version number and date.
-09
Expanded the scope of the JWK specification to include
private and symmetric key representations, as specified by
draft-jones-jose-json-private-and-symmetric-key-00.
Defined that members that are not understood must be ignored.
-08
Changed the name of the JWK key type parameter from
alg to kty
to enable use of alg to indicate
the particular algorithm that the key is intended to be used with.
Clarified statements of the form "This member is OPTIONAL"
to "Use of this member is OPTIONAL".
Referenced String Comparison Rules in JWS.
Added seriesInfo information to Internet Draft references.
-07
Changed the name of the JWK RSA modulus parameter from
mod to n
and the name of the JWK RSA exponent parameter from
xpo to e,
so that the identifiers are the same as those used in RFC 3447.
-06
Changed the name of the JWK RSA exponent parameter from
exp to xpo
so as to allow the potential use of the name exp
for a future extension that might define an expiration parameter for keys.
(The exp name is already used for this
purpose in the JWT specification.)
Clarify that the alg (algorithm family)
member is REQUIRED.
Correct an instance of "JWK" that should have been "JWK Set".
Applied changes made by the RFC Editor to RFC 6749's registry language
to this specification.
-05
Indented artwork elements to better distinguish them from the body text.
-04
Refer to the registries as the primary sources of defined
values and then secondarily reference the sections
defining the initial contents of the registries.
Normatively reference
XML DSIG 2.0
for its security considerations.
Added this language to Registration Templates:
"This name is case sensitive. Names that match other registered names
in a case insensitive manner SHOULD NOT be accepted."
Described additional open issues.
Applied editorial suggestions.
-03
Clarified that kid values need not be unique
within a JWK Set.
Moved JSON Web Key Parameters registry to the JWK specification.
Added "Collision Resistant Namespace" to the terminology section.
Changed registration requirements from RFC Required to
Specification Required with Expert Review.
Added Registration Template sections for defined registries.
Added Registry Contents sections to populate registry values.
Numerous editorial improvements.
-02
Simplified JWK terminology to get replace the "JWK Key Object" and
"JWK Container Object" terms with simply "JSON Web Key (JWK)"
and "JSON Web Key Set (JWK Set)" and to eliminate potential
confusion between single keys and sets of keys.
As part of this change, the top-level member name for a
set of keys was changed from jwk
to keys.
Clarified that values with duplicate member names MUST be rejected.
Established JSON Web Key Set Parameters registry.
Explicitly listed non-goals in the introduction.
Moved algorithm-specific definitions from JWK to JWA.
Reformatted to give each member definition its own section heading.
-01
Corrected the Magic Signatures reference.
-00
Created the initial IETF draft based upon
draft-jones-json-web-key-03 with no normative changes.