Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add comments on key discovery #111

Merged
merged 17 commits into from
Jul 5, 2023
Merged

Add comments on key discovery #111

Changes from 11 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
c5741bd
Add comments on key discovery
OR13 Jun 26, 2023
b86dda3
Update index.html
OR13 Jun 26, 2023
07427cb
Update index.html
OR13 Jun 26, 2023
ea70a52
Update index.html
OR13 Jun 29, 2023
1dc05ff
Update index.html
OR13 Jun 29, 2023
dad4ff7
Update index.html
OR13 Jun 29, 2023
79e45d1
Update index.html
OR13 Jun 29, 2023
6b0288d
Update index.html
OR13 Jun 29, 2023
aeb49e2
Update index.html
OR13 Jun 29, 2023
b9beba9
Update index.html
OR13 Jun 29, 2023
b04c4b2
Update index.html
OR13 Jun 29, 2023
7c7edbd
Update index.html
OR13 Jun 30, 2023
74ec3e4
Update index.html
OR13 Jun 30, 2023
47fb837
Update index.html
OR13 Jun 30, 2023
89d431b
Merge branch 'main' of github.com:w3c/vc-jwt into feat/key-discovery
OR13 Jul 5, 2023
65741c1
Fix broken tag
OR13 Jul 5, 2023
a4bed8c
Add issue markers for open issues
OR13 Jul 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 87 additions & 4 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@ <h5>Verifiable Credentials Data Model</h5>
<h2>Securing JSON</h2>
<p>
This section
provides guidance on how to use JSON [[RFC7159]] claimsets with JWT registered claims to construct
provides guidance on how to use JSON [[RFC7159]] claimsets with JWT <a href="#registered-claim-names">registered claims</a> to construct
a JWT that can be mapped to a verifiable credential. This section also describes
how to use content types and token types to distinguish different representations of verifiable credentials.
</p>
Expand Down Expand Up @@ -321,6 +321,88 @@ <h2>Securing JSON-LD VCs with COSE</h2>
</section>
</section>



<section class="normative">
<h2>Key Discovery</h2>
<p>
In order to complete the <a data-cite="VC-DATA-MODEL#dfn-verify">verification</a> process,
a <a data-cite="VC-DATA-MODEL#dfn-verifier">verifier</a> needs to obtain the cryptographic keys used to secure the
<a data-cite="VC-DATA-MODEL#dfn-credential">credential</a>.
</p>
<p>
There are several different ways to discover the verification keys of
the <a data-cite="VC-DATA-MODEL#dfn-issuers">issuers</a>
and <a data-cite="VC-DATA-MODEL#dfn-holders">holders</a>.
OR13 marked this conversation as resolved.
Show resolved Hide resolved
</p>

<section>
<h2>Registered Claim Names</h2>
<p>
When found in the <a data-cite="RFC7515#section-4.1">Protected Header</a>, or
the <a data-cite="RFC7519#section-4.1.1">Protected Claimset</a>, members present in
<a href="https://www.iana.org/assignments/jwt/jwt.xhtml">IANA Assignments for JSON Web Token (JWT)</a> and
<a href="https://www.iana.org/assignments/jose/jose.xhtml">IANA Assignments for JSON Object Signing and Encryption (JOSE)</a>
are to be interpreted according to the associated specifications referenced by IANA.
</p>
<p>
<a href="#registered-claim-names">Registered claims</a> that are present in either
the <a data-cite="RFC7515#section-4.1">Protected Header</a>
or the <a data-cite="RFC7519#section-4.1.1">Claimset</a> can be used to help
<a data-cite="VC-DATA-MODEL#dfn-verifier">verifiers</a> discover verification keys.
</p>
<section>
<h2>kid</h2>
<p>
If <code>kid</code> is present in the <a data-cite="RFC7515#section-4.1">Protected Header</a>,
a <a data-cite="VC-DATA-MODEL#dfn-verifier">verifier</a> can use this parameter
to obtain a <a data-cite="RFC7517#section-4">JSON Web Key</a> to use in the
<a data-cite="VC-DATA-MODEL#dfn-verify">verification</a> process.
</p>
</section>
<section>
<h2>iss</h2>
<p>
If <code>iss</code> is present in the <a data-cite="RFC7515#section-4.1">Protected Header</a>
or the <a data-cite="RFC7519#section-4.1.1">JWT Claims </a>,
a <a data-cite="VC-DATA-MODEL#dfn-verifier">verifier</a> can use this parameter
to obtain a <a data-cite="RFC7517#section-4">JSON Web Key</a> to use in the
<a data-cite="VC-DATA-MODEL#dfn-verify">verification</a> process.
OR13 marked this conversation as resolved.
Show resolved Hide resolved
</p>
<p>
If <code>kid</code> is also present, it is expected to be useful to distinguish the specific key used.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this mean kid could be in the payload? It's defined as a header parameter:

https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.4

Or is this just referring to kid appearing in the header and iss in the payload? How should "also present" be interpreted here?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, how is kid to be useful to distinguish the specific key used? This cries out for an example, or a fair amount of additional prose.

Copy link
Contributor Author

@OR13 OR13 Jun 29, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AFAIK, kid is legal in payload, in the same way that baz or alg is legal in payload.

The sentence is not attempting to be specific about where kid can be found, but kid does have special meaning when its in the protected header.

can you make a concrete change suggestion?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I've made a suggestion to clarify that we're talking about kid being present in the protected header.

OR13 marked this conversation as resolved.
Show resolved Hide resolved
</p>
</section>
OR13 marked this conversation as resolved.
Show resolved Hide resolved

<section>
<h2>cnf</h2>
<p>
If <code>cnf</code> is present in the <a data-cite="RFC7515#section-4.1">Protected Header</a>
or the <a data-cite="RFC7519#section-4.1.1">JWT Claims </a>,
a <a data-cite="VC-DATA-MODEL#dfn-verifier">verifier</a> can use this parameter
to obtain a <a data-cite="RFC7517#section-4">JSON Web Key</a> to use in the
<a data-cite="VC-DATA-MODEL#dfn-verify">verification</a> process.
</p>
<p>
If <code>kid</code> is also present, it is expected to be useful to distinguish the specific key used.
OR13 marked this conversation as resolved.
Show resolved Hide resolved
</p>
</section>
</section>

<section>
<h2>Well Known URIs</h2>
<p class="issue">
The working group is currently exploring how
<a data-cite="RFC5785#section-3">Defining Well-Known Uniform Resource Identifiers (URIs)</a>
could be leveraged to assist a <a data-cite="VC-DATA-MODEL#dfn-verifier">verifier</a> in discovering verification keys for
<a data-cite="VC-DATA-MODEL#dfn-issuers">issuers</a>
and <a data-cite="VC-DATA-MODEL#dfn-holders">holders</a>.
</p>
</section>


</section>

<section id="conformance">
<section class="normative">
<h2>JSON Web Token Header Parameters</h2>
Expand All @@ -347,7 +429,7 @@ <h2>JSON Web Token Header Parameters</h2>
This includes but is not limited to: <code>iss</code>, <code>kid</code>, <code>alg</code>, <code>iat</code>, <code>exp</code> and <code>cnf</code>.
</p>
<p>
The registered claim names <code>vc</code> and <code>vp</code> MUST NOT be present as header parameters.
The <a href="#registered-claim-names">registered claim</a> names <code>vc</code> and <code>vp</code> MUST NOT be present as header parameters.
</p>
<p>
When present, members of the header are to be interpreted and processed according to
Expand All @@ -360,7 +442,7 @@ <h2>JSON Web Token Header Parameters</h2>
</section>
<section class="normative">
<h2>Securing Verifiable Credentials</h2>
<p>The [[VC-DATA-MODEL]] describes the approach taken by JSON Web Tokens to securing claimsets as applying an <code>external proof</code>.</p>
<p>The <a data-cite="VC-DATA-MODEL#proof-formats"></a> describes the approach taken by JSON Web Tokens to secure claimsets as <i>applying an <code>external proof</code></i>.</p>
<p>The normative statements in <a data-cite="VC-DATA-MODEL#securing-verifiable-credentials">Securing Verifiable Credentials</a> apply to
securing <code>application/vc+ld+json</code> and <code>application/vp+ld+json</code>
as <code>application/vc+ld+jwt</code> and <code>application/vp+ld+jwt</code>.
Expand Down Expand Up @@ -419,6 +501,7 @@ <h2>Securing Verifiable Credentials</h2>
</p>
<p>Issuers, Holders and Verifiers MUST ignore all claimsets that have no integrity protection.</p>
</section>

</section>

<section class="normative">
Expand Down Expand Up @@ -951,7 +1034,7 @@ <h3>Example Mapping</h3>
<ul>
<li>
Extract <code>iss</code>, <code>sub</code>, <code>iat</code>, <code>nbf</code>,
<code>exp</code>, <code>jti</code>, and <code>aud</code> as registered claims.
<code>exp</code>, <code>jti</code>, and <code>aud</code> as <a href="#registered-claim-names">registered claims</a>.
</li>
<li>
Set aside all other claims as subject claims.
Expand Down