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

Author: msporny

index.html

@@ -1248,7 +1248,7 @@ <h3>Identifiers</h3>
 <a href="#identifier-based-correlation"></a> carefully when considering such
 scenarios. There are also other types of access and correlation mechanisms documented
 in Section <a href="#privacy-considerations"></a> that create privacy concerns.
-Where privacy is a strong consideration, it is permissible to omit the 
+Where privacy is a strong consideration, it is permissible to omit the
 `id` [=property=]. Some use cases do not need, or explicitly need to omit,
 the `id` [=property=]. Similarly, special attention is to be given to the choice between
 publicly resolvable URLs and other forms of identifiers. Publicly resolvable URLs can
@@ -2733,7 +2733,7 @@ <h3>Trust Model</h3>
 either of the following:
             <ul>
               <li>
-An [=issuer=] is expected to secure a [=credential=] with a 
+An [=issuer=] is expected to secure a [=credential=] with a
 <a href="#securing-mechanisms">securing mechanism</a> which establishes
 that the [=issuer=] generated the [=credential=]. (In other words, an
 [=issuer=] is expected to [=issue=] a [=verifiable credential=].)
@@ -3040,110 +3040,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
+use the media type in the `Accept` HTTP Header, and
           </li>
           <li>
-be used when retrieving the content, such as via the `Accept` HTTP Header
-          </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":
@@ -3166,9 +3192,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"
   },
   ...
 }
@@ -5578,7 +5603,7 @@ <h3>Data Theft</h3>
 [=verifiable presentations=] are valuable since they contain authentic
 statements made by trusted third parties, such as [=issuers=], or
 individuals, such as [=holders=] and [=subjects=]. The storage and
-acessibility of this data can inadvertently create honeypots of 
+acessibility of this data can inadvertently create honeypots of
 sensitive data for malicious actors. These adversaries often seek to
 exploit such resevoirs of sensitive information, aiming to
 acquire and exchange that data for financial gain.
@@ -5589,9 +5614,9 @@ <h3>Data Theft</h3>
 manage the status and revocation of those credentials. Similarly,
 [=issuers=] are advised to avoid the practice of creating publicly
 resolvable credentials that include personally identifiable information
-(PII) or other sensitive data. Software implementers are advised 
-to safeguarded [=verifiable credentials=] using robust consent 
-and access control measures, ensuring that they remain 
+(PII) or other sensitive data. Software implementers are advised
+to safeguarded [=verifiable credentials=] using robust consent
+and access control measures, ensuring that they remain
 inaccessible to unauthorized entities.
         </p>
         <p>
@@ -6123,7 +6148,7 @@ <h3>Code Injection</h3>
 Despite the ability to encode information as HTML, implementers are strongly
 discouraged from doing so, for the following reasons:
         </p>
-        
+
         <ul>
           <li>
 It requires some version of an HTML processor, which increases the burden of