JSON Web Key (JWK)Microsoftmbj@microsoft.comhttp://self-issued.info/
Security
JOSE Working GroupRFCRequest for CommentsI-DInternet-DraftAssertionSimple Web TokenSecurity TokenSWTJavaScript Object NotationJSONJSON Web TokenJWTJSON Web SignatureJWSJSON Web EncryptionJWEJSON Web KeyJWK
A JSON Web Key (JWK) is a JSON data structure that represents
a set of public keys.
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 RFC 2119.
A JSON Web Key (JWK) is a JSON data structure that represents
a set of public keys as a JSON object . The JWK format is used to
represent bare keys; representing certificate chains is an
explicit non-goal of this specification. JSON Web Keys are
referenced in JSON Web Signature (JWS)
using the jku (JSON Key URL)
header parameter and in
JSON Web Encryption (JWE)
using the jku (JSON Key URL)
and epk (Ephemeral Public Key)
header parameters.
A JSON data structure that represents a set of public
keys. A JWK consists of a single JWK Container Object
that contains an array of JWK Key Objects.
A JSON object that contains an array of JWK Key Objects as
a member.
A JSON object that represents a single public key.
For the purposes of this specification, this term always
refers to 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 B of
for notes on implementing base64url
encoding without padding.)
It is sometimes useful to be able to reference public key
representations, for instance, in order to verify the
digital signature on content signed with the corresponding private
key. The JSON Web Key (JWK) data structure provides a
convenient JSON representation for sets of public keys
utilizing either the Elliptic Curve or RSA families of algorithms.
The following example JWK contains two public keys: 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. Both provide a Key ID for 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.)
A JWK consists of a JWK Container Object, which is a JSON
object that contains an array of JWK Key Objects as a member.
This section specifies the format of these objects.
A JWK Container Object is a JSON object containing a
specific member. This member is:
Member NameJSON Value TypeContainer Object Member Semanticsjwkarray
The jwk member value
contains an array of JWK Key Objects. This member is
REQUIRED.
Additional members MAY be present in the JWK Container
Object. If present, they MUST be understood by
implementations using that JWK.
A JWK Key Object is a JSON object containing specific
members. Those members that are common to all key types are
as follows:
Member NameJSON Value TypeKey Object Member Semanticsalgstring
The alg member
identifies the cryptographic algorithm family used with the key.
Values defined by this specification are EC and RSA. Specific additional members are
required to represent the key, depending upon the alg value. The alg value is case sensitive.
This member is REQUIRED.
usestring
The use member identifies the
intended use of the key. Values defined by this
specification are sig (signature)
and enc (encryption). Other values
MAY be used. The use value is
case sensitive. This member is OPTIONAL.
kidstring
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 the JWK
during key rollover. The kid value MAY correspond to a JWS
kid value. The interpretation
of the kid value is
unspecified. This member is OPTIONAL.
Additional members MAY be present in the JWK Key Object. If
present, they MUST be understood by implementations using
that key.
JWKs can represent Elliptic Curve keys. In
this case, the alg
member value MUST be EC.
Furthermore, these additional members MUST be present:
Member NameJSON Value TypeKey Object Member Semanticscrvstring
The crv member identifies
the cryptographic curve used with the key. Values
defined by this specification are P-256, P-384 and P-521. Additional crv values MAY be used, provided
they are understood by implementations using that Elliptic Curve
key. The crv value is
case sensitive.
xstring
The x member contains the x
coordinate for the elliptic curve point. It is
represented as the base64url encoding of the
coordinate's big endian representation.
ystring
The y member contains the y
coordinate for the elliptic curve point. It is
represented as the base64url encoding of the
coordinate's big endian representation.
JWKs can represent RSA keys. In
this case, the alg
member value MUST be RSA.
Furthermore, these additional members MUST be present:
Member NameJSON Value TypeKey Object Member Semanticsmodstring
The mod member contains
the modulus value for the RSA public key. It is
represented as the base64url encoding of the value's big
endian representation.
expstring
The exp member contains
the exponent value for the RSA public key. It is
represented as the base64url encoding of the value's big
endian representation.
JWKs make use of the base64url encoding as defined in RFC 4648. As allowed by Section 3.2 of
the RFC, this specification mandates that base64url encoding
when used with JWKs MUST NOT use padding. Notes on
implementing base64url encoding can be found in the JWS specification.
No IANA actions are required by this specification.
TBD
The following items remain to be done in this draft:
Write the Security Considerations section.
Digital Signature Standard (DSS)National Institute of Standards and
TechnologyMagic SignaturesJSON Web Signature (JWS)Microsoftmbj@microsoft.comhttp://self-issued.info/independentve7jtb@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.com
A JSON representation for RSA public keys was previously
introduced in Magic
Signatures.
-00
Created the initial IETF draft based upon
draft-jones-json-web-key-03 with no normative changes.