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

Use Correct Names for Things #156

Merged
merged 7 commits into from
Sep 21, 2023
Merged

Use Correct Names for Things #156

Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0a721fb
Use Correct Names for Things
selfissued Sep 13, 2023
99dac50
Update index.html
selfissued Sep 20, 2023
c3a64fa
Update index.html
selfissued Sep 20, 2023
73263ec
Update index.html
selfissued Sep 20, 2023
439e94d
Update index.html
selfissued Sep 20, 2023
ae9c34d
Resolved merge conflicts
selfissued Sep 20, 2023
f06fc20
Merge branch 'mbj-correct-names' of https://github.com/selfissued/vc-…
selfissued Sep 20, 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
85 changes: 41 additions & 44 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -346,14 +346,13 @@ <h2>Securing JSON-LD VCs with COSE</h2>
for the COSE "<code>typ</code>" (type) header parameter.
</p>
<p>When using this approach, the <code>content type (3)</code>
SHOULD be <code>application/vc+ld+json</code></p>
SHOULD be <code>application/vc+ld+json</code>.</p>
<p>
See <a data-cite="rfc9052#section-3.1">Common COSE Header
Parameters</a> for additional details.
</p>
<p>See <a href="https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml">Concise
Binary Object Representation (CBOR) Tags</a> for additional
details.</p>
<p>See the IANA <a href="https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml">Concise Binary Object Representation (CBOR) Tags</a> registry
for additional details.</p>
</section>
</section>
</section>
Expand Down Expand Up @@ -410,24 +409,24 @@ <h2>Key Discovery</h2>


<section>
<h2>Registered Claim Names</h2>
<h2>Registered Header Parameter and 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.
When present in
the <a data-cite="RFC7515#section-4">JOSE Header</a> or
the <a data-cite="RFC7519#section-4">JWT Claims Set</a>
members registered in
the IANA <a href="https://www.iana.org/assignments/jwt/jwt.xhtml">JSON Web Token Claims</a> registry or
the IANA <a href="https://www.iana.org/assignments/jose/jose.xhtml">JSON Web Signature and Encryption Header Parameters</a> registry
are to be interpreted as defined by the specifications referenced in the registries.
</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
These parameters and claims 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>,
If <code>kid</code> is present in the <a data-cite="RFC7515#section-4.1">JOSE 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.
Expand All @@ -436,7 +435,7 @@ <h2>kid</h2>
<section>
<h2>iss</h2>
<p>
If <code>iss</code> is present in the <a data-cite="RFC7515#section-4.1">Protected Header</a>
If <code>iss</code> is present in the <a data-cite="RFC7515#section-4.1">JOSE 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
Expand All @@ -450,7 +449,7 @@ <h2>iss</h2>
</p>
<p>
If <code>kid</code> is also present in the
<a data-cite="RFC7515#section-4.1">Protected Header</a>, it is expected to be useful to
<a data-cite="RFC7515#section-4.1">JOSE Header</a>, it is expected to be useful to
distinguish the specific key used.
</p>
<p class="issue" data-number="31">
Expand All @@ -462,15 +461,15 @@ <h2>iss</h2>
<section>
<h2>cnf</h2>
<p>
If <code>cnf</code> is present in the <a data-cite="RFC7515#section-4.1">Protected Header</a>
If <code>cnf</code> is present in the <a data-cite="RFC7515#section-4.1">JOSE 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 in the
<a data-cite="RFC7515#section-4.1">Protected Header</a>, it is expected to be
<a data-cite="RFC7515#section-4.1">JOSE Header</a>, it is expected to be
useful to distinguish the specific key used.
</p>
</section>
Expand Down Expand Up @@ -498,7 +497,7 @@ <h2>JWT Issuer</h2>
</section>

<section class="normative">
<h2>Protected Header Parameters</h2>
<h2>JOSE Header Parameters</h2>
<p>
The normative statements in <a data-cite="RFC7515#section-4.1">Registered Header Parameter
Names</a>
Expand All @@ -509,7 +508,7 @@ <h2>Protected Header Parameters</h2>
apply to securing credentials and presentations.
</p>
<p>
The data model for the protected header is JSON
The data model for the JOSE Header is JSON
(application/json), not JSON-LD (application/ld+json).
</p>
<p>
Expand All @@ -518,30 +517,28 @@ <h2>Protected Header Parameters</h2>
apply to securing claims about a credential subject.
</p>
<p>
When replicating claims from the claimset to the header, it is
RECOMMENDED to use [[RFC7519]], <a href="https://www.iana.org/assignments/jose/jose.xhtml">IANA
Assignments for Header Parameters</a>, and <a href="https://www.iana.org/assignments/jwt/jwt.xhtml">IANA
Assignments for JSON Web Token (JWT)</a>
to identify any reserved claims that might be confused with
members of the [[VC-DATA-MODEL]. This includes but is not
When replicating claims from the JWT Claims Set to Header Parameters, it is
RECOMMENDED to use [[RFC7519]],
the IANA <a href="https://www.iana.org/assignments/jwt/jwt.xhtml">JSON Web Token Claims</a> registry, and
the IANA <a href="https://www.iana.org/assignments/jose/jose.xhtml">JSON Web Signature and Encryption Header Parameters</a> registry
to identify any claims that might be confused with
members defined by the [[VC-DATA-MODEL]. These include but are not
limited to: <code>iss</code>, <code>kid</code>,
<code>alg</code>, <code>iat</code>,
<code>exp</code> and <code>cnf</code>.
<code>exp</code>, and <code>cnf</code>.
</p>
<p>
The <a href="#registered-claim-names">registered claim</a> names <code>vc</code> and <code>vp</code>
The JWT Claim 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
<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>.
processed according to the corresponding definitions found in
the IANA <a href="https://www.iana.org/assignments/jose/jose.xhtml">JSON Web Signature and Encryption Header Parameters</a> registry and
the IANA <a href="https://www.iana.org/assignments/jwt/jwt.xhtml">JSON Web Token Claims</a> registry.
</p>
<p>
Additional members may be present, if they are not understood,
Additional members may be present. If they are not understood,
they MUST be ignored.
</p>
</section>
Expand All @@ -551,7 +548,7 @@ <h2>Protected Header Parameters</h2>
<section class="normative">
<h2>Securing Verifiable Credentials</h2>
<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
Tokens to secure JWT Claims Sets 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
Expand Down Expand Up @@ -615,31 +612,31 @@ <h2>Securing Verifiable Credentials</h2>
Requirements</a>.
</p>
<p>
Accordingly, Issuers, Holders and Verifiers MUST understand the
Accordingly, Issuers, Holders, and Verifiers MUST understand the
JSON Web Token header parameter
<code>"alg": "none"</code> when securing the [[VC-DATA-MODEL]]
with JSON Web Tokens.
</p>
<p>
When content types from the [[VC-DATA-MODEL]] are secured using
JSON Web Tokens, the header parameter <code>"alg":
"none"</code>, MUST be used to communicate that a claimset (a
JSON Web Tokens, the header parameter <code>"alg": "none"</code>,
MUST be used to communicate that a JWT Claims Set (a
Verifiable Credential or a Verifiable Presentation) has no
integrity protection.
</p>
<p>
When a JSON Web Token claimset (a Verifiable Credential or a
When a JWT Claims Set (a Verifiable Credential or a
Verifiable Presentation) contains
<code>proof</code>, and the JSON Web Token header contains
<code>"alg": "none"</code>, the claimset MUST be considered to
<code>"alg": "none"</code>, the JWT Claims Set MUST be considered to
have no integrity protection.
</p>
<p class="advisement">
Verifiable Credentials and Verifiable Presenatations are not
required to be secured or integrity protected or to contain a
<code>proof</code> member.
</p>
<p>Issuers, Holders and Verifiers MUST ignore all claimsets that
<p>Issuers, Holders, and Verifiers MUST ignore all JWT Claims Sets that
have no integrity protection.</p>
</section>

Expand Down Expand Up @@ -1243,7 +1240,7 @@ <h3>Selective Disclosure</h3>
<p>The following examples are taken from <a data-cite="SD-JWT#name-example-4b-w3c-verifiable-c"></a>.</p>
<p class="issue">These example are from a work in progress draft.</p>
<p>
An issuer might start with a <code>vc+ld+json</code> claimset, for example:
An issuer might start with a <code>vc+ld+json</code> JWT Claims Set, for example:
</p>
<pre class="example">
{
Expand Down Expand Up @@ -1286,7 +1283,7 @@ <h3>Selective Disclosure</h3>
}
</pre>
<p>
The issuer converts this claimset into the SD-JWT payload, and encodes the token, for example:
The issuer converts this JWT Claims Set into the SD-JWT payload, and encodes the token, for example:
</p>
<pre class="example">
eyJhbGciOiAiRVMyNTYifQ.eyJpc3MiOiAiaHR0cHM6Ly9leGFtcGxlLmNvbS9pc3N1Z
Expand Down Expand Up @@ -1336,7 +1333,7 @@ <h3>Selective Disclosure</h3>
</pre>
<p>
Notice that, in the case of sd-jwt, the decoded payload
is different from the input claimset:
is different from the input JWT Claims Set:
</p>
<pre class="example">
{
Expand Down