Skip to content

Commit 2f8eabc

Browse files
mprorockOR13TallTeddmitrizagidulinmsporny
authored
Add context integrity capabilities.
Co-authored-by: Orie Steele <[email protected]> Co-authored-by: Ted Thibodeau Jr <[email protected]> Co-authored-by: Dmitri Zagidulin <[email protected]> Co-authored-by: Manu Sporny <[email protected]> Co-authored-by: David I. Lehn <[email protected]>
1 parent 329d6f8 commit 2f8eabc

File tree

1 file changed

+128
-0
lines changed

1 file changed

+128
-0
lines changed

‎index.html

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2599,6 +2599,134 @@ <h3>Data Schemas</h3>
25992599

26002600
</section>
26012601

2602+
<section>
2603+
<h2>Integrity of Related Resources</h2>
2604+
<p>
2605+
When including a link to an external resource in a
2606+
<a>verifiable credential</a>, it is desirable to know whether
2607+
the resource that is pointed to is the same at signing time as
2608+
it is at verification time. This applies to cases where there
2609+
is an external resource that is remotely retrieved as well as
2610+
to cases where the <a>issuer</a> and/or
2611+
<a>verifier</a> may have local cached copies of a resource.
2612+
</p>
2613+
<p>
2614+
It is also desirable to know that the contents of the JSON-LD
2615+
context(s) used in the <a>verifiable credential</a> are the
2616+
same when used by both the <a>issuer</a> and <a>verifier</a>.
2617+
</p>
2618+
<p>
2619+
To validate that a resource referenced by a <a>verifiable
2620+
credential</a> is the same at verification time as it is at
2621+
issuing time, an implementer MAY include a property named
2622+
<code>relatedResource</code> that stores an array of objects
2623+
that describe additional integrity metadata about each
2624+
resource referenced by the <a>verifiable credential</a>. If
2625+
<code>relatedResource</code>
2626+
is present, there MUST be an object in the array for each remote
2627+
resource for each context used in the verifiable credential.
2628+
</p>
2629+
<p class="issue" title="Mandatory listing of contexts in relatedResouce are under debate.">
2630+
The requirement that contexts be listed in `relatedResource` is currently being debated in the VCWG. This requirement might be removed in future iterations of the specification.
2631+
</p>
2632+
<p>
2633+
Each object in the
2634+
<code>relatedResource</code> array MUST contain the following:
2635+
the [[URL]] to the resource named <code>id</code> and the
2636+
<code>digestSRI</code> information for the resource
2637+
constructed using the method specified in <a
2638+
href="https://www.w3.org/TR/SRI/#integrity-metadata">Subresource
2639+
Integrity</a>.
2640+
</p>
2641+
<p class="issue" title="Unification of cryptographic hash expression formats are under discussion">
2642+
The Working Group is currently attempting to determine if cryptographic hash expression formats can be unified across all of the VCWG core specifications. Candidates for this mechanism include `digestSRI` and `digestMultibase`. There are arguments for and against unification that the WG is currently debating.
2643+
</p>
2644+
There MUST NOT be more than one object in the
2645+
<code>relatedResource</code> per <code>id</code>.
2646+
</p>
2647+
<p>
2648+
An object in the <code>relatedResource</code> array MAY
2649+
contain a property named <code>mediaType</code> that indicates
2650+
the expected media type for the indicated
2651+
<code>resource</code>. If a <code>mediaType</code> is included
2652+
it SHOULD be a valid media type as listed in the
2653+
<a href="https://www.iana.org/assignments/media-types/media-types.xhtml">
2654+
IANA Media Types
2655+
</a> registry.
2656+
</p>
2657+
<p>
2658+
Any object in the <a>verifiable credential</a>
2659+
that contains an `id` [[URL]] property MAY be annotated with
2660+
integrity information as specified in this section by inclusion
2661+
of <code>digestSRI</code> in the object.
2662+
</p>
2663+
<p>
2664+
Any objects for which selective disclosure is desired SHOULD
2665+
NOT be included as an object in the
2666+
<code>relatedResource</code> array.
2667+
</p>
2668+
<p>
2669+
Implementers are urged to consult appropriate sources, such as
2670+
the
2671+
<a href="https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf">
2672+
FIPS 180-4 Secure Hash Standard</a> and the
2673+
<a href="https://media.defense.gov/2022/Sep/07/2003071834/-1/-1/0/CSA_CNSA_2.0_ALGORITHMS_.PDF">
2674+
Commercial National Security Algorithm Suite 2.0</a>
2675+
to ensure that they are chosing a current and reliable hash
2676+
algorithm. At the time of this writing `sha384` SHOULD be
2677+
considered the minimum strength hash algorithm for use by
2678+
implementers.
2679+
</p>
2680+
<p class="issue">
2681+
The working group is discussing if we will adopt more aspects
2682+
of subresource integrity as defined in [[SRI]] is adopted into
2683+
the [[JSON-LD]] specification as noted in that specifications
2684+
<a href="https://www.w3.org/TR/json-ld11/#security">current
2685+
security considerations</a> of that specification, this hash
2686+
in the VC can serve as an additional check towards ensuring
2687+
that a cached context used when issuing the VC matches the
2688+
remote resource.
2689+
</p>
2690+
<p>
2691+
<aside
2692+
class="example"
2693+
title="related resource integrity"
2694+
>
2695+
<p>An example of related resource integrity object referencing
2696+
contexts</p>
2697+
<pre>
2698+
"relatedResource": [{
2699+
"id": "https://www.w3.org/ns/credentials/v2",
2700+
"digestSRI": "sha384-lHKDHh0msc6pRx8PhDOMkNtSI8bOfsp4giNbUrw71nXXLf13nTqNJoRp3Nx+ArVK",
2701+
},{
2702+
"id": "https://www.w3.org/ns/credentials/examples/v2",
2703+
"digestSRI": "sha384-zNNbQTWCSUSi0bbz7dbua+RcENv7C6FvlmYJ1Y+I727HsPOHdzwELMYO9Mz68M26",
2704+
}]
2705+
</pre>
2706+
</aside>
2707+
</p>
2708+
<p>
2709+
<aside
2710+
class="example"
2711+
title="related resource integrity over image"
2712+
>
2713+
<p>An example of a related resource integrity object in a
2714+
credentialSubject refering to an image</p>
2715+
<pre class="example" title="An integrity-protected image that is associated with a credentialSubject">
2716+
"credentialSubject": {
2717+
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
2718+
"image": {
2719+
"id": "https://university.example.org/images/58473",
2720+
"digestSRI": "sha384-ZfAwuJmMgoX3s86L7x9XSPi3AEbiz6S/5SyGHJPCxWHs5NEth/c5S9QoS1zZft+J",
2721+
"mediaType": "application/svg+xml",
2722+
},
2723+
...
2724+
}
2725+
</pre>
2726+
</aside>
2727+
</p>
2728+
</section>
2729+
26022730
<section>
26032731
<h3>Refreshing</h3>
26042732

0 commit comments

Comments
 (0)