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

Fix SD-JWT examples; add detail to the 'Securing Verifiable Credentials' section #304

Merged
merged 12 commits into from
Sep 27, 2024
Merged

Fix SD-JWT examples; add detail to the 'Securing Verifiable Credentials' section #304

Changes from 4 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
96d559e
fix sd-jwt examples
Sep 18, 2024
bc635de
securing text clarificaiton
Sep 18, 2024
2174a7e
formatting
Sep 18, 2024
c2ba43c
Update index.html
decentralgabe Sep 20, 2024
d28ab37
Merge remote-tracking branch 'origin/main' into issue-296
Sep 20, 2024
5d8785d
merge
Sep 20, 2024
9b57534
revert media types
Sep 20, 2024
6fd05b1
Apply suggestions from code review
decentralgabe Sep 24, 2024
236e87a
Merge remote-tracking branch 'origin/main' into issue-296
Sep 26, 2024
e009d5b
Update index.html
decentralgabe Sep 26, 2024
0090fac
Update index.html
decentralgabe Sep 26, 2024
6741e41
Apply suggestions from code review
decentralgabe Sep 26, 2024
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
364 changes: 117 additions & 247 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -237,58 +237,117 @@ <h2 id="conformance-classes">Conformance Classes</h2>
<a href="#secure-with-cose"></a>.
</p>
</section>
<section class="normative">
<h2 id="securing-verifiable-credentials">Securing Verifiable Credentials</h2>
<p>The <a data-cite="VC-DATA-MODEL-2.0#securing-mechanism-specifications"></a> describes
the approach taken by JSON Web 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-2.0#securing-mechanisms">Securing
Mechanisms</a> apply to securing
<code>application/vc-ld+jwt</code> and
<code>application/vp-ld+jwt</code>,
<code>application/vc-ld+sd-jwt</code> and
<code>application/vp-ld+sd-jwt</code>,
as well as
<code>application/vc-ld+cose</code> and
<code>application/vp-ld+cose</code>.
</p>
<p>
JSON Web Token implementers are advised to review <a data-cite="RFC7519#section-8">Implementation
Requirements</a>.
</p>
<p>
Issuers, Holders, and Verifiers MUST understand the
JSON Web Token header parameter setting
<code>"alg": "none"</code> when securing [[VC-DATA-MODEL-2.0]]
with JSON Web Tokens.
When content types from [[VC-DATA-MODEL-2.0]] are secured using
JSON Web Tokens, the header parameter setting <code>"alg": "none"</code>,
MUST be used to communicate that a JWT Claims Set that comprises a
Verifiable Credential or a Verifiable Presentation has no
integrity protection.
When a JWT Claims Set that comprises a Verifiable Credential or a
Verifiable Presentation contains
<code>proof</code>, and the JSON Web Token header contains
<code>"alg": "none"</code>, the JWT Claims Set MUST be considered to
have no integrity protection.
</p>
<p class="advisement">
Verifiable Credentials and Verifiable Presentations are not
required to be secured nor integrity protected, nor to contain a
<code>proof</code> member.
</p>
<p>
Issuers, Holders, and Verifiers of Verifiable Credentials and/or
Verifiable Presentations MUST ignore all, and MUST NOT produce any,
JWT Claims Sets that have no integrity protection.
</p>
<p>
The JWT Claim Names <code>vc</code> and <code>vp</code>
MUST NOT be present in any JWT Claims Set that comprises a
Verifiable Credential or a Verifiable Presentation.
</p>
</section>
<section class="normative">
<h2 id="securing-verifiable-credentials">Securing Verifiable Credentials</h2>
<p>
The <a data-cite="VC-DATA-MODEL-2.0#securing-mechanism-specifications"></a> describes
decentralgabe marked this conversation as resolved.
Show resolved Hide resolved
the approach taken by this specification to secure JSON and CBOR
claims by <i>applying an <code>enveloping proof</code></i>.
</p>
<p>
This specification defines how to secure different data structures
using various <code>enveloping proof</code> mechanisms:</p>
<dl>
<dt>JSON Web Tokens (JWTs):</dt>
<dd>JWTs secure JSON Web Token Claim Sets. These are JSON objects
containing claims about an entity (typically the subject of the JWT).</dd>
<dt>Selective Disclosure JWTs (SD-JWTs): </dt>
<dd>SD-JWTs secure JSON Claim Sets, similar to JWTs, but with added
selective disclosure capabilities. This allows for parts of the
claim set to be selectively revealed or withheld.</dd>
decentralgabe marked this conversation as resolved.
Show resolved Hide resolved

<dt>CBOR Object Signing and Encryption (COSE):</dt>
<dd>COSE secures CBOR (Concise Binary Object Representation) data
structures. CBOR is a binary data format that is more compact than
JSON and is designed for constrained environments.</dd>
</dl>

<p>In the context of Verifiable Credentials:</p>
<ul>
<li>When using JWTs, the Verifiable Credential or Presentation is
encoded as a JSON Web Token Claim Set.</li>
<li>When using SD-JWTs, the Verifiable Credential or Presentation
is encoded as a JSON Claim Set with selective disclosure features.</li>
decentralgabe marked this conversation as resolved.
Show resolved Hide resolved
<li>When using COSE, the Verifiable Credential or Presentation is
encoded as a CBOR data structure.</li>
</ul>
<p>
In all cases, the underlying data model of the Verifiable Credential
or Presentation remains consistent with the [[VC-DATA-MODEL-2.0]],
but the encoding and security mechanism differ.</p>
decentralgabe marked this conversation as resolved.
Show resolved Hide resolved
<p>
The normative statements in <a data-cite="VC-DATA-MODEL-2.0#securing-mechanisms">
Securing Mechanisms</a> apply to securing
<code>application/vc-ld+jwt</code> and
<code>application/vp-ld+jwt</code>,
<code>application/vc-ld+sd-jwt</code> and
<code>application/vp-ld+sd-jwt</code>,
<code>application/vc-ld+cose</code> and
<code>application/vp-ld+cose</code>.
</p>
<section>
<h2>JWT Format and Requirements</h2>
<p>
JSON Web Token implementers are advised to review <a data-cite="RFC7519#section-8">Implementation
Requirements</a>.
</p>
<p>
Accordingly, Issuers, Holders, and Verifiers MUST understand the
JSON Web Token header parameter
<code>"alg": "none"</code> when securing [[VC-DATA-MODEL-2.0]]
with JSON Web Tokens.
When content types from [[VC-DATA-MODEL-2.0]] are secured using
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.
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 JWT Claims Set MUST be considered to
have no integrity protection.
decentralgabe marked this conversation as resolved.
Show resolved Hide resolved
</p>
<p class="advisement">
Verifiable Credentials and Verifiable Presentations are not
required to be secured or integrity protected or to contain a
<code>proof</code> member.
</p>
decentralgabe marked this conversation as resolved.
Show resolved Hide resolved
<p>
Issuers, Holders, and Verifiers MUST ignore all JWT Claims Sets that
have no integrity protection.
</p>
<p>
The JWT Claim Names <code>vc</code> and <code>vp</code>
MUST NOT be present in any JWT Claims Set.
decentralgabe marked this conversation as resolved.
Show resolved Hide resolved
</p>
</section>
<section>
<h2>SD-JWT Format and Requirements</h2>
<p>
This specification uses Selective Disclosure for JWTs (SD-JWT) as
defined in the IETF draft [[SD-JWT]].
Implementers should refer to this draft for the full details of the
SD-JWT format and processing requirements.
</p>
<ul>
<li>An SD-JWT consists of three main parts: the
SD-JWT itself, optional disclosures, and an optional KB-JWT (Key
Binding JWT). These parts are separated by tilde (~) characters.</li>

<li>If the KB-JWT is not present, the SD-JWT must end
with a tilde (~) character. This is crucial for correct parsing and
processing of the SD-JWT.</li>

<li>Selective disclosure is achieved through the use of
disclosure objects. These are base64url-encoded JSON arrays
containing the digest of the disclosed claim, the claim name, and
the claim value.</li>

<li>Each disclosable claim is combined with a salt value
before hashing to prevent dictionary attacks.</li>
</ul>
</section>
</section>

</section>

Expand Down Expand Up @@ -1066,162 +1125,12 @@ <h3 id="using-controller-documents">Using Controller Documents</h3>
a <a data-cite="DID-CORE#dfn-did-documents">DID Document</a>.
</p>

<section id="conformance">
<section class="normative">
<h2 id="conformance-classes">Conformance Classes</h2>
<p>
A <dfn>conforming JWS document</dfn> is one that conforms to all of the
"MUST" statements in Section <a href="#secure-with-jose"></a>.
</p>
<p>
A <dfn>conforming JWS issuer implementation</dfn> produces
[=conforming JWS documents=] and MUST secure them as described in Section
<a href="#secure-with-jose"></a>.
<p>
A <dfn>conforming JWS verifier implementation</dfn> verifies
[=conforming JWS documents=] as described in Section
<a href="#secure-with-jose"></a>.
</p>
<p>
A <dfn>conforming SD-JWT document</dfn> is one that conforms to all of the
"MUST" statements in Section <a href="#secure-with-sd-jwt"></a>.
</p>
<p>
A <dfn>conforming SD-JWT issuer implementation</dfn> produces
[=conforming SD-JWT documents=] and MUST secure them as described in Section
<a href="#secure-with-sd-jwt"></a>.
<p>
A <dfn>conforming SD-JWT verifier implementation</dfn> verifies
[=conforming SD-JWT documents=] as described in Section
<a href="#secure-with-sd-jwt"></a>.
</p>
<p>
A <dfn>conforming COSE document</dfn> is one that conforms to all of the
"MUST" statements in Section <a href="#secure-with-cose"></a>.
</p>
<p>
A <dfn>conforming COSE issuer implementation</dfn> produces
[=conforming COSE documents=] and MUST secure them as described in Section
<a href="#secure-with-cose"></a>.
</p>
<p>
A <dfn>conforming COSE verifier implementation</dfn> verifies
[=conforming COSE documents=] as described in Section
<a href="#secure-with-cose"></a>.
</p>
</section>
<section class="normative">
<h2 id="securing-verifiable-credentials">Securing Verifiable Credentials</h2>
<p>
The <a data-cite="VC-DATA-MODEL-2.0#securing-mechanism-specifications"></a> describes
the approach taken by this specification to secure JSON and CBOR
claims by <i>applying an <code>enveloping proof</code></i>.
</p>
<p>
This specification defines how to secure different data structures
using various <code>enveloping proof</code> mechanisms:</p>
<dl>
<dt>JSON Web Tokens (JWTs):</dt>
<dd>JWTs secure JSON Web Token Claim Sets. These are JSON objects
containing claims about an entity (typically the subject of the JWT).</dd>
<dt>Selective Disclosure JWTs (SD-JWTs): </dt>
<dd>SD-JWTs secure JSON Claim Sets, similar to JWTs, but with added
selective disclosure capabilities. This allows for parts of the
claim set to be selectively revealed or withheld.</dd>

<dt>CBOR Object Signing and Encryption (COSE):</dt>
<dd>COSE secures CBOR (Concise Binary Object Representation) data
structures. CBOR is a binary data format that is more compact than
JSON and is designed for constrained environments.</dd>
</dl>

<p>In the context of Verifiable Credentials:</p>
<ul>
<li>When using JWTs, the Verifiable Credential or Presentation is
encoded as a JSON Web Token Claim Set.</li>
<li>When using SD-JWTs, the Verifiable Credential or Presentation
is encoded as a JSON Claim Set with selective disclosure features.</li>
<li>When using COSE, the Verifiable Credential or Presentation is
encoded as a CBOR data structure.</li>
</ul>
<p>
In all cases, the underlying data model of the Verifiable Credential
or Presentation remains consistent with the [[VC-DATA-MODEL-2.0]],
but the encoding and security mechanism differ.</p>
<p>
The normative statements in <a data-cite="VC-DATA-MODEL-2.0#securing-mechanisms">
Securing Mechanisms</a> apply to securing
<code>application/vc-ld+jwt</code> and
<code>application/vp-ld+jwt</code>,
<code>application/vc-ld+sd-jwt</code> and
<code>application/vp-ld+sd-jwt</code>,
as well as
<code>application/vc-ld+cose</code> and
<code>application/vp-ld+cose</code>.
</p>
<section>
<h2>JWT Format and Requirements</h2>
<p>
JSON Web Token implementers are advised to review <a data-cite="RFC7519#section-8">Implementation
Requirements</a>.
</p>
<p>
Accordingly, Issuers, Holders, and Verifiers MUST understand the
JSON Web Token header parameter
<code>"alg": "none"</code> when securing [[VC-DATA-MODEL-2.0]]
with JSON Web Tokens.
When content types from [[VC-DATA-MODEL-2.0]] are secured using
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.
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 JWT Claims Set MUST be considered to
have no integrity protection.
</p>
<p class="advisement">
Verifiable Credentials and Verifiable Presentations 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 JWT Claims Sets that
have no integrity protection.
</p>
<p>
The JWT Claim Names <code>vc</code> and <code>vp</code>
MUST NOT be present in any JWT Claims Set.
</p>
</section>
<section>
<h2>SD-JWT Format and Requirements</h2>
<p>
This specification uses Selective Disclosure for JWTs (SD-JWT) as
defined in the IETF draft [[SD-JWT]].
Implementers should refer to this draft for the full details of the
SD-JWT format and processing requirements.
</p>
<ul>
<li>An SD-JWT consists of three main parts: the
SD-JWT itself, optional disclosures, and an optional KB-JWT (Key
Binding JWT). These parts are separated by tilde (~) characters.</li>

<li>If the KB-JWT is not present, the SD-JWT must end
with a tilde (~) character. This is crucial for correct parsing and
processing of the SD-JWT.</li>

<li>Selective disclosure is achieved through the use of
disclosure objects. These are base64url-encoded JSON arrays
containing the digest of the disclosed claim, the claim name, and
the claim value.</li>

<li>Each disclosable claim is combined with a salt value
before hashing to prevent dictionary attacks.</li>
</ul>
</section>
</section>
<p>
When using [[URL]] identifiers, the <code>kid</code> is RECOMMENDED to be
an absolute [[URL]] that includes a JWK Thumbprint URI
as defined in [[RFC7638]]. For example:
<code>https://vendor.example/issuers/42/keys/urn:ietf:params:oauth:jwk-thumbprint:sha-256:NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs</code>
</p>

<pre class="example" title="An issuer identified by a controller document identifier">
{
Expand Down Expand Up @@ -1260,45 +1169,6 @@ <h2>SD-JWT Format and Requirements</h2>
}
</pre>
</section>
<section>
<h3 id="using-did-documents">Using DID Documents</h3>
<!-- DID URLS via "issuer" and "holder" -->
<p>
When <a href="#iss">iss</a> is absent and the <a data-cite="VC-DATA-MODEL-2.0#dfn-issuers">issuer</a>
is identified as a <a data-cite="DID-CORE#did-subject">DID Subject</a>,
the <a href="#kid">kid</a> MUST be an absolute <a data-cite="DID-CORE#relative-did-urls">DID URL</a>.
</p>
<pre class="example" title="An issuer identified by a DID">
{
"issuer": "did:example:123"
// ...
}
</pre>
<pre class="example" title="An absolute DID URL as a kid">
{
"alg": "ES384",
"kid": "did:example:123#key-456
}
</pre>
<p>
When <a href="#iss">iss</a> is absent, and the <a data-cite="VC-DATA-MODEL-2.0#dfn-holders">holder</a>
is identified as a <a data-cite="DID-CORE#did-subject">DID Subject</a>,
the <a href="#kid">kid</a> MUST be an absolute <a data-cite="DID-CORE#relative-did-urls">DID URL</a>.
</p>
<pre class="example" title="A holder identified by a DID">
{
"holder": "did:example:abc"
// ...
}
</pre>
<pre class="example" title="A kid as an absolute DID URL">
{
"alg": "ES384",
"kid": "did:example:abc#key-456
}
</pre>

</section>
</section>

<section class="normative">
Expand Down
Loading