Skip to content

Commit

Permalink
merge
Browse files Browse the repository at this point in the history
  • Loading branch information
gabe committed Sep 20, 2024
1 parent d28ab37 commit 5d8785d
Showing 1 changed file with 112 additions and 164 deletions.
276 changes: 112 additions & 164 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -237,58 +237,118 @@ <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
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+jwt</code> and
<code>application/vp+jwt</code>,
<code>application/vc+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>

</section>

Expand Down Expand Up @@ -1110,118 +1170,6 @@ <h3 id="using-controller-documents">Using Controller Documents</h3>
}
</pre>
</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+jwt</code> and
<code>application/vp+jwt</code>,
<code>application/vc+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>
</section>

<section class="normative">
Expand Down

0 comments on commit 5d8785d

Please sign in to comment.