Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
May 27, 2024
Merged

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

Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
0480bf4
Rework content integrity section based on @jyasskin's feedback.
msporny May 5, 2024
522cb7b
Fix editorial nits in content integrity section.
msporny May 26, 2024
6d5ab3f
Remove "associated with" text from relatedResource requirements.
msporny May 26, 2024
eed1251
Allow more than one digest to be specified.
msporny May 26, 2024
b0896f2
Specify which resource should be retrieved when mediaType is used.
msporny May 26, 2024
ac98e17
Specify that non-matching media type responses should be rejected.
msporny May 26, 2024
f72d137
Specify how to annotate objects with `id` property.
msporny May 26, 2024
5ab5218
Refer to digest format issue by number.
msporny May 27, 2024
b1e5ed6
Remove duplicated text in trust model section.
msporny May 27, 2024
869ebeb
Remove normative text and examples related to digestMultibase.
msporny May 27, 2024
4e7d4b3
Clarify hash expression format for digestSRI.
msporny May 27, 2024
cc8b0e3
Remove text associated with removed resource integrity example.
msporny May 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 79 additions & 73 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3126,110 +3126,134 @@ <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.
When including a link to an external resource in a [=verifiable credential=], it
is desirable to know whether the resource has been modified since 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 locally 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 the [=verifier=] as
they were when used by the [=issuer=].
</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.">

<p class="issue" title="Mandatory listing of contexts in `relatedResource` is 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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are there any constraints on the allowable subject of the relatedResource property? If the constraints are based on the id of the value of that property, I think the current text requires implementations to recursively scan everything the issuer could be said to have "included" in order to find all uses of the property. That'd be easy for an RDF processor but probably not a JSON processor.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are there any constraints on the allowable subject of the relatedResource property?

No, there are no constraints. Any URL would do.

That'd be easy for an RDF processor but probably not a JSON processor.

Hmm, I don't understand why? Why wouldn't a "JSON processor" just look for "id" values?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What I think you have here is serialized as

{ "id": "vc://id",
  "type": "VerifiableCredential",
  "relatedResource": {
    "id": "the://resource",
    "mediaType": "media/type",
   "digestSRI": "sha384-hash"
  }
}

In RDF, that's

<the://resource> <https://schema.org/encodingFormat> "media/type" .
<the://resource> <https://www.w3.org/2018/credentials#digestSRI> "sha384-hash" .
<vc://id> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <vc://VerifiableCredential> .
<vc://id> <https://www.w3.org/ns/credentials/issuer-dependent#relatedResource> <the://resource> .

But I don't see any constraint in the text that the "relatedResource" property has to map from the VC to the constrained resource. The issuer could as easily "include the relatedResource property" as:

{ "id": "vc://id",
  "type": "VerifiableCredential",
  "foo": { "bar": { "baz": { "quux": {
    "relatedResource": {
     "id": "the://resource",
     "mediaType": "media/type",
     "digestSRI": "sha384-hash"
    }
  }}}}
}

A JSON processor then has to recursively scan all the objects to look for relatedResource properties. RDF APIs seem to have native queries for "find all the triples with a property of X", but that's not a natural operation on JSON.

</p>
<p class="issue" title="Unification of cryptographic hash expression formats are under discussion">

<dl>
<dt id="defn-relatedResource">relatedResource</dt>
<dd>
The value of the `relatedResource` property MUST be 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.
Comment on lines +3165 to +3166
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't this uniqueness just fall out of how JSON-LD works? Any two objects in a JSON-LD serialization with the same ID are just the same RDF object, right?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't this uniqueness just fall out of how JSON-LD works?

Yes.

Any two objects in a JSON-LD serialization with the same ID are just the same RDF object, right?

Correct.

However, there are people in the WG that don't want to do "full JSON-LD processing" and this language helps them avoid writing code that merges duplicates in the list.

We advise against going "full RDF" and creating multiple nodes with the same identifier in VCs; people that do that shouldn't expect to interoperate as well as if they would just avoid doing that.

I agree that the benefit of this language is debatable.

</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>
One or more cryptographic digests, as defined by the `hash-expression` ABNF
grammar defined in the [[[SRI]]] specification,
<a data-cite="SRI#the-integrity-attribute">Section 3.5: The `integrity`
attribute</a>.
</td>
</tr>
</tbody>
</table>
Each object associated with `relatedResource` MUST contain at least a
`digestSRI` value.
</dd>
</dl>

<p class="issue" data-number="1489">
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
identified by the `id` property 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.
reject the response if it includes a `Content-Type` HTTP Header with a different
media type.
</li>
</ul>

<p>
Any object in the [=verifiable credential=] that contains an `id` [[URL]]
property MAY be annotated with integrity information as specified in this
section by inclusion of `digestSRI`
in the object.
Any object in the [=verifiable credential=] that contains an `id`
property MAY be annotated with integrity information by adding the
`digestSRI` and `mediaType` properties.
</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.
Comment on lines +3229 to +3230
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this constraint only for objects that are the value of a relatedResource claim, or any subject of the mediaType or digestSRI claims?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Its for any subject of the digestSRI or digestMultibase claims. The previous sentence specifies that expectation.

</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":
Expand All @@ -3241,24 +3265,6 @@ <h2>Integrity of Related Resources</h2>
}]
</pre>

<p>
An example of an object in a `credentialSubject` that is refering to an
integrity protected image.
</p>

<pre class="example nohighlight"
title="An integrity-protected image that is associated with a credentialSubject">
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"image": {
"id": "https://university.example.org/images/58473",
"digestSRI":
"sha384-ZfAwuJmMgoX3s86L7x9XSPi3AEbiz6S/5SyGHJPCxWHs5NEth/c5S9QoS1zZft+J",
"mediaType": "application/svg+xml",
},
...
}
</pre>
</section>

<section>
Expand Down