Rework content integrity section based on @jyasskin's feedback.

Author: msporny

index.html

@@ -3126,110 +3126,136 @@ <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 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.
+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=].
         </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>
-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>.
+To extend integrity protection to a related resource, an [=issuer=] of a
+[=verifiable credential=] MAY include the `relatedResource` property:
         </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>
-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:
+If a `mediaType` is listed, implementations that retrieve the resource
+using [[[?RFC9110]]] SHOULD:
         </p>
         <ul>
           <li>
-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
+use the media type in the `Accept` HTTP Header, and
           </li>
           <li>
-match the retrieved content media type, such as via the `Content-Type` HTTP
-Header.
+use the media type in the `Content-Type` HTTP Header.
           </li>
         </ul>
 
         <p>
-Any object in the [=verifiable credential=] that contains an `id` [[URL]]
+Any object in the [=verifiable credential=] that contains an `id`
 property MAY be annotated with integrity information as specified in this
-section by inclusion of `digestSRI`
-in the object.
+section.
         </p>
+
         <p>
-Any objects for which selective disclosure is desired SHOULD NOT be included as
-an object in the `relatedResource` array.
+Any objects for which selective disclosure or unlinkable 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 has the
-expected media type and its bytes hash to the expected digest.
+specification MUST produce a validation error unless the resource matches the
+expected media type and cryptographic 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
-chosing a current and reliable hash algorithm. At the time of this writing
+choosing 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, 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.
+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.
         </p>
         <p>
 An example of a related resource integrity object referencing JSON-LD contexts.
         </p>
 
         <pre class="example nohighlight"
-          title="Usage of the relatedResource property">
+          title="Usage of the relatedResource and digestSRI property">
 "relatedResource": [{
   "id": "https://www.w3.org/ns/credentials/v2",
   "digestSRI":
@@ -3252,9 +3278,8 @@ <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"
   },
   ...
 }