Skip to content

Commit

Permalink
Revert all changes to Section 5.3: Integrity of Related Resources.
Browse files Browse the repository at this point in the history
  • Loading branch information
@msporny
msporny committed May 5, 2024
1 parent 49e3875 commit af4ff9f
Showing 1 changed file with 54 additions and 79 deletions.
133 changes: 54 additions & 79 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3090,136 +3090,110 @@ <h4>Semantic Interoperability</h4>
<section>
<h2>Integrity of Related Resources</h2>
<p>
When including a link to an external resource in a [=verifiable credential=], it
is desirable to know whether the resource has been modified after the
[=verifiable credential=] was issued. This applies to cases where there is an
external resource that is remotely retrieved, as well as to cases where the
[=issuer=] and/or [=verifier=] might have local cached copies of a resource. It
is also desirable to know that the contents of the JSON-LD context(s) used in
the [=verifiable credential=] are the same when used by both the [=issuer=] and
[=verifier=].
When including a link to an external resource in a [=verifiable credential=],
it is desirable to know whether the resource that is pointed to is the same at
signing time as it is at verification time. This applies to cases where there is
an external resource that is remotely retrieved as well as to cases where the
[=issuer=] and/or [=verifier=] may have local cached copies of a resource.
</p>
<p>
It is also desirable to know that the contents of the JSON-LD context(s) used in
the [=verifiable credential=] are the same when used by both the
[=issuer=] and [=verifier=].
</p>
<p>
To validate that a resource referenced by a [=verifiable credential=] is the
same at verification time as it is at issuing time, an implementer MAY include a
property named <code id="defn-relatedResource">relatedResource</code> that
stores an array of objects that describe additional integrity metadata about
each resource referenced by the [=verifiable credential=]. If
`relatedResource` is present, there MUST be an object in the array
for each remote resource for each context used in the verifiable credential.
</p>

<p class="issue" title="Mandatory listing of contexts in relatedResouce are under debate.">
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.
</p>

<p>
To extend integrity protection to a related resource, an [=issuer=] of a
[=verifiable credential=] MAY include the `relatedResource` property:
Each object in the `relatedResource` array MUST contain the
following: the [[URL]] to the resource named `id` and the
<code id="defn-digestSRI">digestSRI</code> information for the resource
constructed using the method specified in
<a href="https://www.w3.org/TR/SRI/#integrity-metadata">Subresource Integrity</a>.
</p>

<dl>
<dt id="defn-relatedResource">relatedResource</dt>
<dd>
The value of the `relatedResource` property MUST be associated with one or
more objects of the following form:
<table class="simple">
<thead>
<th>Property</th>
<th>Description</th>
</thead>
<tbody>
<tr>
<td>`id`</td>
<td>
The identifier for the resource is REQUIRED and conforms to the format defined
in Section [[[#identifiers]]]. The value MUST be unique among the list of
related resource objects.
</td>
</tr>
<tr>
<td>`mediaType`</td>
<td>
An OPTIONAL valid media type as listed in the
<a href="https://www.iana.org/assignments/media-types/media-types.xhtml">
IANA Media Types</a> registry.
</td>
</tr>
<tr>
<td>`digestSRI`</td>
<td>
A cryptographic digest, as defined in [[[SRI]]].
</td>
</tr>
<tr>
<td>`digestMultibase`</td>
<td>
A cryptographic digest, as defined in [[[VC-DATA-INTEGRITY]]].
</td>
</tr>
</tbody>
</table>
Each object associated with `relatedResource` MUST contain at least a
`digestSRI` or `digestMultibase` value.
</dd>
</dl>

<p class="issue" title="Unification of cryptographic hash expression formats are under discussion">
The Working Group is currently attempting to determine whether 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.
</p>

<p>
If a `mediaType` is listed, implementations that retrieve the resource
using [[[?RFC9110]]] SHOULD:
There MUST NOT be more than one object in the `relatedResource` per
`id`.
</p>
<p>
An object in the `relatedResource` array MAY contain a property named
`mediaType` that indicates the expected media type for the indicated
`resource`. If a `mediaType` is included, its value
SHOULD:
</p>
<ul>
<li>
use the media type in the `Accept` HTTP Header, and
be a valid media type as listed in the
<a href="https://www.iana.org/assignments/media-types/media-types.xhtml">
IANA Media Types</a> registry
</li>
<li>
be used when retrieving the content, such as via the `Accept` HTTP Header
</li>
<li>
use the media type in the `Content-Type` HTTP Header.
match the retrieved content media type, such as via the `Content-Type` HTTP
Header.
</li>
</ul>

<p>
Any object in the [=verifiable credential=] that contains an `id`
Any object in the [=verifiable credential=] that contains an `id` [[URL]]
property MAY be annotated with integrity information as specified in this
section.
section by inclusion of `digestSRI`
in the object.
</p>

<p>
Any objects for which selective disclosure or unlinkable disclosure is desired
SHOULD NOT be included as an object in the `relatedResource` array.
Any objects for which selective disclosure is desired SHOULD NOT be included as
an object in the `relatedResource` array.
</p>

<p>
Specification authors that write algorithms that fetch a resource based on the
`id` of an object inside a [=conforming document=] need to consider whether
that resource's content is vital to the validity of that document. If it is, the
specification MUST produce a validation error unless the resource matches the
expected media type and cryptographic digest.
specification MUST produce a validation error unless the resource has the
expected media type and its bytes hash to the expected digest.
</p>
<p>
Implementers are urged to consult appropriate sources, such as the
<a href="https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf">
FIPS 180-4 Secure Hash Standard</a> and the
<a href="https://media.defense.gov/2022/Sep/07/2003071834/-1/-1/0/CSA_CNSA_2.0_ALGORITHMS_.PDF">
Commercial National Security Algorithm Suite 2.0</a> to ensure that they are
choosing a current and reliable hash algorithm. At the time of this writing
chosing a current and reliable hash algorithm. At the time of this writing
`sha384` SHOULD be considered the minimum strength hash algorithm for use by
implementers.
</p>
<p class="issue">
The working group is discussing if we will adopt more aspects of subresource
integrity as defined in [[SRI]] is adopted into the [[JSON-LD11]] specification as
noted in that specifications <a href="https://www.w3.org/TR/json-ld11/#security">
current security considerations</a> of that specification, the
approach described in this section can serve as an additional check towards
ensuring that a cached context used when issuing
a [=verifiable credential=] matches the remote resource.
current security considerations</a> of that specification, this hash in the VC
can serve as an additional check towards ensuring that a cached context used
when issuing the VC matches the remote resource.
</p>
<p>
An example of a related resource integrity object referencing JSON-LD contexts.
</p>

<pre class="example nohighlight"
title="Usage of the relatedResource and digestSRI property">
title="Usage of the relatedResource property">
"relatedResource": [{
"id": "https://www.w3.org/ns/credentials/v2",
"digestSRI":
Expand All @@ -3242,8 +3216,9 @@ <h2>Integrity of Related Resources</h2>
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"image": {
"id": "https://university.example.org/images/58473",
"digestSRI":
"sha384-ZfAwuJmMgoX3s86L7x9XSPi3AEbiz6S/5SyGHJPCxWHs5NEth/c5S9QoS1zZft+J",
"mediaType": "application/svg+xml",
"digestMultibase": "zQmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n"
},
...
}
Expand Down

0 comments on commit af4ff9f

Please sign in to comment.