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 3 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
c5741bd
Add comments on key discovery
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
Jul 5, 2023
65741c1
Fix broken tag
Jul 5, 2023
a4bed8c
Add issue markers for open issues
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
100 changes: 96 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,97 @@ <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 <a data-cite="VC-DATA-MODEL#dfn-issuers">issuers</a>
and <a data-cite="VC-DATA-MODEL#dfn-holders">holders</a>
verification keys.
</p>

<section>
<h2>Registered Claim Names</h2>
<p>
When present 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 associcated 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>,
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>
<p>
If <code>iss</code> is present in 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.
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 in the payload? Like if iss were to appear in the Verifiable Credential expressed as application/vc+ld+json? Or does it mean if iss appears alongside a vc claim in the 1.1 style?

I would think we'd want to avoid both cases in 2.0 and require these things to be in the protected header to keep layers separate for this external securing mechanism. Wouldn't getting key information from something in the payload also be incompatible with many existing JWT libraries?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I would think we'd want to avoid both cases in 2.0 and require these things to be in the protected header to keep layers separate for this external securing mechanism.

avoid both cases would mean banning the json member iss from application/vc+ld+json right?

I don't think that would get consensus... we tried similar things with proof... which is still both allowed to be present or optional.

Copy link
Contributor

Choose a reason for hiding this comment

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

There's a clear (and I think, agreed upon) way to do the security in this particular case, right? We want people to move on from the VC JWT 1.1 stuff and get a clean separation? If so, it seems we might have consensus here to clearly direct people not to put iss directly into the Verifiable Credential, but instead, if they are going to use it, put it in the protected header.

Copy link
Contributor Author

@OR13 OR13 Jun 30, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

There's a clear (and I think, agreed upon) way to do the security in this particular case, right?

Yes, I think so, the authority is IETF for terms registered with IANA that are from IETF RFCs... They define this behavior we profile on top of it.

We want people to move on from the VC JWT 1.1 stuff and get a clean separation?

Yes, we made typ and cty values that solved this.

If so, it seems we might have consensus here to clearly direct people not to put iss directly into the Verifiable Credential, but instead, if they are going to use it, put it in the protected header.

Disagree, we are not going to constrain the open world model... people WILL put iss wherever they are allowed to (which is everywhere)... We have to explain what doing that means (document existing usage).

We won't get consensus to "ban terms in specific places", so it will happen in the payload and the header.

By default it should be interpreted by the security conventions from the relevant RFCs, that is what this PR does. That is why the language just mirrors the RFCs, and doesn't constrain further.

This PR does not change anything an implementer can do today, it acknowledges that there are thing they can do that have special meaning today (registered names in header and claimset), and reminds them to be aware of how those terms are used today.

</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.

</p>
</section>

<section>
<h2>cnf</h2>
<p>
If <code>cnf</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>
<p>
<p>
If <code>cnf</code> is present in 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>
If <code>kid</code> is also present, it is expected to be useful to distinguish the specific key used.
</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">verifiers</a> in discoverying 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 +438,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 +451,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 securing claimsets as applying an <code>external proof</code>.</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 +510,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 +1043,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