One document matched: draft-ietf-jose-json-web-key-01.xml
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?xml-stylesheet type='text/xsl' href='http://xml.resource.org/authoring/rfc2629.xslt' ?>
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="4"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" ipr="trust200902" docName="draft-ietf-jose-json-web-key-01">
<front>
<title abbrev="JWK">JSON Web Key (JWK)</title>
<author fullname="Michael B. Jones" initials="M.B." surname="Jones">
<organization>Microsoft</organization>
<address>
<email>mbj@microsoft.com</email>
<uri>http://self-issued.info/</uri>
</address>
</author>
<date day="12" month="March" year="2012" />
<area>Security</area>
<workgroup>JOSE Working Group</workgroup>
<keyword>RFC</keyword>
<keyword>Request for Comments</keyword>
<keyword>I-D</keyword>
<keyword>Internet-Draft</keyword>
<keyword>JavaScript Object Notation</keyword>
<keyword>JSON</keyword>
<keyword>JSON Web Token</keyword>
<keyword>JWT</keyword>
<keyword>JSON Web Signature</keyword>
<keyword>JWS</keyword>
<keyword>JSON Web Encryption</keyword>
<keyword>JWE</keyword>
<keyword>JSON Web Key</keyword>
<keyword>JWK</keyword>
<abstract>
<t>
A JSON Web Key (JWK) is a JSON data structure that represents
a set of public keys.
</t>
</abstract>
<note title="Requirements Language">
<t>
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 <xref target="RFC2119">RFC 2119</xref>.
</t>
</note>
</front>
<middle>
<section title="Introduction">
<t>
A JSON Web Key (JWK) is a JSON data structure that represents
a set of public keys as a JSON object <xref
target="RFC4627" />. 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) <xref target="JWS" />
using the <spanx style="verb">jku</spanx> (JSON Key URL)
header parameter and in
JSON Web Encryption (JWE) <xref target="JWE" />
using the <spanx style="verb">jku</spanx> (JSON Key URL)
and <spanx style="verb">epk</spanx> (Ephemeral Public Key)
header parameters.
</t>
</section>
<section title="Terminology">
<t>
<list style="hanging">
<t hangText="JSON Web Key (JWK)">
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.
</t>
<t hangText="JWK Container Object">
A JSON object that contains an array of JWK Key Objects as
a member.
</t>
<t hangText="JWK Key Object">
A JSON object that represents a single public key.
</t>
<t hangText="Base64url Encoding">
For the purposes of this specification, this term always
refers to the URL- and filename-safe Base64 encoding
described in <xref target="RFC4648">RFC 4648</xref>,
Section 5, with the (non URL-safe) '=' padding characters
omitted, as permitted by Section 3.2. (See Appendix B of
<xref target="JWS" /> for notes on implementing base64url
encoding without padding.)
</t>
</list>
</t>
</section>
<section title="JSON Web Key (JWK) Overview">
<t>
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.
</t>
<section title="Example JWK" anchor="ExampleJWK">
<t>
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.)
</t>
<figure><artwork><![CDATA[{"jwk":
[
{"alg":"EC",
"crv":"P-256",
"x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
"y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
"use":"enc",
"kid":"1"},
{"alg":"RSA",
"mod": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx
4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs
tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2
QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI
SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb
w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
"exp":"AQAB",
"kid":"2011-04-29"}
]
}]]></artwork></figure>
</section>
</section>
<section title="JWK Format">
<t>
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.
</t>
<section title="JWK Container Object Format">
<t>
A JWK Container Object is a JSON object containing a
specific member. This member is:
</t>
<texttable title="JWK Container Object Member">
<ttcol align="left">Member Name</ttcol>
<ttcol align="left">JSON Value Type</ttcol>
<ttcol align="left">Container Object Member Semantics</ttcol>
<c>jwk</c>
<c>array</c>
<c>
The <spanx style="verb">jwk</spanx> member value
contains an array of JWK Key Objects. This member is
REQUIRED.
</c>
</texttable>
<t>
Additional members MAY be present in the JWK Container
Object. If present, they MUST be understood by
implementations using that JWK.
</t>
</section>
<section title="JWK Key Object Format">
<t>
A JWK Key Object is a JSON object containing specific
members. Those members that are common to all key types are
as follows:
</t>
<texttable title="JWK Key Object Members">
<ttcol align="left">Member Name</ttcol>
<ttcol align="left">JSON Value Type</ttcol>
<ttcol align="left">Key Object Member Semantics</ttcol>
<c>alg</c>
<c>string</c>
<c>
The <spanx style="verb">alg</spanx> member
identifies the cryptographic algorithm family used with the key.
Values defined by this specification are <spanx
style="verb">EC</spanx> and <spanx
style="verb">RSA</spanx>. Specific additional members are
required to represent the key, depending upon the <spanx
style="verb">alg</spanx> value. The <spanx
style="verb">alg</spanx> value is case sensitive.
This member is REQUIRED.
</c>
<c>use</c>
<c>string</c>
<c>
The <spanx style="verb">use</spanx> member identifies the
intended use of the key. Values defined by this
specification are <spanx style="verb">sig</spanx> (signature)
and <spanx style="verb">enc</spanx> (encryption). Other values
MAY be used. The <spanx style="verb">use</spanx> value is
case sensitive. This member is OPTIONAL.
</c>
<c>kid</c>
<c>string</c>
<c>
The <spanx style="verb">kid</spanx> (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 <spanx
style="verb">kid</spanx> value MAY correspond to a JWS
<spanx style="verb">kid</spanx> value. The interpretation
of the <spanx style="verb">kid</spanx> value is
unspecified. This member is OPTIONAL.
</c>
</texttable>
<t>
Additional members MAY be present in the JWK Key Object. If
present, they MUST be understood by implementations using
that key.
</t>
<section title="JWK Key Object Members for Elliptic Curve Keys">
<t>
JWKs can represent Elliptic Curve <xref
target="FIPS.186-3" /> keys. In
this case, the <spanx style="verb">alg</spanx>
member value MUST be <spanx style="verb">EC</spanx>.
Furthermore, these additional members MUST be present:
</t>
<texttable title="Members for Elliptic Curve Keys">
<ttcol align="left">Member Name</ttcol>
<ttcol align="left">JSON Value Type</ttcol>
<ttcol align="left">Key Object Member Semantics</ttcol>
<c>crv</c>
<c>string</c>
<c>
The <spanx style="verb">crv</spanx> member identifies
the cryptographic curve used with the key. Values
defined by this specification are <spanx
style="verb">P-256</spanx>, <spanx
style="verb">P-384</spanx> and <spanx
style="verb">P-521</spanx>. Additional <spanx
style="verb">crv</spanx> values MAY be used, provided
they are understood by implementations using that Elliptic Curve
key. The <spanx style="verb">crv</spanx> value is
case sensitive.
</c>
<c>x</c>
<c>string</c>
<c>
The <spanx style="verb">x</spanx> member contains the x
coordinate for the elliptic curve point. It is
represented as the base64url encoding of the
coordinate's big endian representation.
</c>
<c>y</c>
<c>string</c>
<c>
The <spanx style="verb">y</spanx> member contains the y
coordinate for the elliptic curve point. It is
represented as the base64url encoding of the
coordinate's big endian representation.
</c>
</texttable>
</section>
<section title="JWK Key Object Members for RSA Keys">
<t>
JWKs can represent RSA <xref target="RFC3447" /> keys. In
this case, the <spanx style="verb">alg</spanx>
member value MUST be <spanx style="verb">RSA</spanx>.
Furthermore, these additional members MUST be present:
</t>
<texttable title="Members for RSA Keys">
<ttcol align="left">Member Name</ttcol>
<ttcol align="left">JSON Value Type</ttcol>
<ttcol align="left">Key Object Member Semantics</ttcol>
<c>mod</c>
<c>string</c>
<c>
The <spanx style="verb">mod</spanx> member contains
the modulus value for the RSA public key. It is
represented as the base64url encoding of the value's big
endian representation.
</c>
<c>exp</c>
<c>string</c>
<c>
The <spanx style="verb">exp</spanx> member contains
the exponent value for the RSA public key. It is
represented as the base64url encoding of the value's big
endian representation.
</c>
</texttable>
</section>
</section>
</section>
<section title="Base64url encoding as used by JWKs" anchor="base64urllogic">
<t>
JWKs make use of the base64url encoding as defined in <xref
target="RFC4648">RFC 4648</xref>. 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 <xref
target="JWS" /> specification.
</t>
</section>
<section title="IANA Considerations" anchor="IANA">
<t>
No IANA actions are required by this specification.
</t>
</section>
<section title="Security Considerations" anchor="Security">
<t>
TBD
</t>
</section>
<section title="Open Issues and Things To Be Done (TBD)" anchor="TBD">
<t>
The following items remain to be done in this draft:
<list style="symbols">
<t>
Consider how additional key families would be added.
</t>
<t>
Write the Security Considerations section.
</t>
</list>
</t>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.3447.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.4648.xml' ?>
<reference anchor="FIPS.186-3">
<front>
<title>Digital Signature Standard (DSS)</title>
<author>
<organization>National Institute of Standards and
Technology</organization>
</author>
<date month="June" year="2009" />
</front>
<seriesInfo name="FIPS" value="PUB 186-3" />
<format target="http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf" type="PDF" />
</reference>
</references>
<references title="Informative References">
<reference anchor="MagicSignatures">
<front>
<title>Magic Signatures</title>
<author fullname="John Panzer (editor)" initials="J." surname="Panzer (editor)"></author>
<author fullname="Ben Laurie" initials="B." surname="Laurie"></author>
<author fullname="Dirk Balfanz" initials="D." surname="Balfanz"></author>
<date day="7" month="January" year="2011" />
</front>
<format target="http://salmon-protocol.googlecode.com/svn/trunk/draft-panzer-magicsig-01.html" type="HTML" />
</reference>
<reference anchor="JWS">
<front>
<title>JSON Web Signature (JWS)</title>
<author fullname="Michael B. Jones" initials="M.B." surname="Jones">
<organization>Microsoft</organization>
<address>
<email>mbj@microsoft.com</email>
<uri>http://self-issued.info/</uri>
</address>
</author>
<author fullname="John Bradley" initials="J." surname="Bradley">
<organization>independent</organization>
<address>
<email>ve7jtb@ve7jtb.com</email>
</address>
</author>
<author fullname="Nat Sakimura" initials="N." surname="Sakimura">
<organization>Nomura Research Institute</organization>
<address>
<email>n-sakimura@nri.co.jp</email>
</address>
</author>
<date day="12" month="March" year="2012" />
</front>
<format target="http://tools.ietf.org/html/draft-ietf-jose-json-web-signature" type="HTML" />
</reference>
<reference anchor="JWE">
<front>
<title>JSON Web Encryption (JWE)</title>
<author fullname="Michael B. Jones" initials="M.B." surname="Jones">
<organization>Microsoft</organization>
<address>
<email>mbj@microsoft.com</email>
<uri>http://self-issued.info/</uri>
</address>
</author>
<author fullname="Eric Rescorla" initials="E." surname="Rescorla">
<organization>RTFM, Inc.</organization>
<address>
<email>ekr@rtfm.com</email>
</address>
</author>
<author fullname="Joe Hildebrand" initials="J." surname="Hildebrand">
<organization>Cisco Systems, Inc.</organization>
<address>
<email>jhildebr@cisco.com</email>
</address>
</author>
<date day="12" month="March" year="2012" />
</front>
<format target="http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption" type="HTML" />
</reference>
</references>
<section title="Acknowledgements" anchor="Acknowledgements">
<t>
A JSON representation for RSA public keys was previously
introduced in <xref target="MagicSignatures">Magic
Signatures</xref>.
</t>
</section>
<section title='Document History'>
<t>
-01
<list style='symbols'>
<t>
Corrected the Magic Signatures reference.
</t>
</list>
</t>
<t>
-00
<list style='symbols'>
<t>
Created the initial IETF draft based upon
draft-jones-json-web-key-03 with no normative changes.
</t>
</list>
</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 08:32:03 |