From 09103b24a056acba929075647a5aaad7f1558278 Mon Sep 17 00:00:00 2001 From: mprorock Date: Fri, 2 Jun 2023 13:06:31 -0600 Subject: [PATCH 01/32] chore: add context integrity capabilities --- index.html | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/index.html b/index.html index 1ac014505..f15925bc1 100644 --- a/index.html +++ b/index.html @@ -2595,6 +2595,74 @@

Data Schemas

+
+

Context Integrity

+

+ In some cases it is desirable to know that the contents of the + context(s) utilized in the verifiable credential are the same as + used by both the issuer and verifier. +

+

+ To validate that a context included in a Verifiable Credential is + the same at verification time as at issuing time an implementer + MAY include a property named contextIntegrity that + stores an array of objects that describe additional integrity + metadata about each context used by the VC. If + contextIntegrity + is present there MUST be an object in the array for each remote + context. +

+

+ Each object in the + contextIntegrity array MUST contain the following: + the URL to the context named context, a + timestamp + that indicates the time at which the hash was computed, the + hash + of the context, and the method which indicates what + hashing algorithm was used as listed as the 'Hash Name String' + property from the IANA + Named Information Hash Algorithm Registry. + The timestamp property MUST be a string value of an + [[XMLSCHEMA11-2]] combined date-time string. An implementer may + include other fields in each object. +

+

+ Implementers should consult appropriate sources, such as the IANA + Named Information Hash Algorithm Registry to ensure that they + are chosing a current and reliable hash algorithm. At the time of + this writing `sha-256` should be considered the minimum strength + hash algorithm for use by implemnters. +

+

+ If at a later date subresource integrity as defined in [[SRI]] is + adopted into the [[JSON-LD]] specification as noted in that + specifications current security + considerations 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. +

+

+

+

+
+

Refreshing

From 71960a5960eef13f4cd3724c31dcad2610a14813 Mon Sep 17 00:00:00 2001 From: Mike Prorock Date: Fri, 2 Jun 2023 15:28:01 -0400 Subject: [PATCH 02/32] correct issue Co-authored-by: Orie Steele --- index.html | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index f15925bc1..81309772d 100644 --- a/index.html +++ b/index.html @@ -2653,7 +2653,10 @@

Context Integrity

An example of a context integrity object

               "contextIntegrity": [{
-                "context":"https://example.org/v1/context", 
+                "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2"
+  ],
                 "timestamp": "2020-01-01T19:23:24Z", 
                 "hash": "0c63a75b845e4f7d01107d852e4c2485c51a50aaaa94fc61995e71bbee983a2ac3713831264adb47fb6bd1e058d5f004", 
                 "method": "sha3-384"  

From 4d8bbde5eff747cb3a0eef0c66be1a93881ddf76 Mon Sep 17 00:00:00 2001
From: Mike Prorock 
Date: Fri, 2 Jun 2023 16:41:20 -0400
Subject: [PATCH 03/32] Update index.html

---
 index.html | 1 -
 1 file changed, 1 deletion(-)

diff --git a/index.html b/index.html
index 81309772d..57471a54f 100644
--- a/index.html
+++ b/index.html
@@ -2655,7 +2655,6 @@ 
Context Integrity

               "contextIntegrity": [{
                 "@context": [
     "https://www.w3.org/ns/credentials/v2",
-    "https://www.w3.org/ns/credentials/examples/v2"
   ],
                 "timestamp": "2020-01-01T19:23:24Z", 
                 "hash": "0c63a75b845e4f7d01107d852e4c2485c51a50aaaa94fc61995e71bbee983a2ac3713831264adb47fb6bd1e058d5f004", 

From c361bf7b05ec4194082d794fa68c9221b0194f41 Mon Sep 17 00:00:00 2001
From: Mike Prorock 
Date: Sat, 3 Jun 2023 11:59:10 -0400
Subject: [PATCH 04/32] incorporate a better example

thanks @or13

Co-authored-by: Orie Steele 
---
 index.html | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/index.html b/index.html
index 57471a54f..022d6cd5c 100644
--- a/index.html
+++ b/index.html
@@ -2653,12 +2653,15 @@ 
Context Integrity

             
An example of a context integrity object

             
               "contextIntegrity": [{
-                "@context": [
-    "https://www.w3.org/ns/credentials/v2",
-  ],
+                "@context": "https://www.w3.org/ns/credentials/v2",
                 "timestamp": "2020-01-01T19:23:24Z", 
                 "hash": "0c63a75b845e4f7d01107d852e4c2485c51a50aaaa94fc61995e71bbee983a2ac3713831264adb47fb6bd1e058d5f004", 
                 "method": "sha3-384"  
+              },{
+                "@context": "https://www.w3.org/ns/credentials/examples/v2",
+                "timestamp": "2019-02-04T17:32:15Z", 
+                "hash": "ac996ae492f9a987c84f109f2118d3f6632e2259455d30c455a9ecd66c3c4959", 
+                "method": "sha2-256"  
               }]
             

           

From 94b5aa1ce43ae6394d82b2fb1149a70de46daf4b Mon Sep 17 00:00:00 2001
From: mprorock 
Date: Mon, 5 Jun 2023 06:19:46 -0600
Subject: [PATCH 05/32] chore: update to broaden context integrity to remote
 resources in general

---
 index.html | 56 ++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 40 insertions(+), 16 deletions(-)

diff --git a/index.html b/index.html
index 022d6cd5c..cc8b00955 100644
--- a/index.html
+++ b/index.html
@@ -2596,30 +2596,38 @@ 
Data Schemas
-

Context Integrity

+

External Resource Integrity

- In some cases it is desirable to know that the contents of the + When including a link to an external resource in a VC it is + desireable to know if the resource that is pointed to, is the + same at signing time, as at verification time. This applies to + both 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. +

+

+ It is also desirable to know that the contents of the context(s) utilized in the verifiable credential are the same as - used by both the issuer and verifier. + used by both the issuer and verifier.

- To validate that a context included in a Verifiable Credential is + To validate that a resource referenced by a Verifiable Credential is the same at verification time as at issuing time an implementer - MAY include a property named contextIntegrity that + MAY include a property named resourceIntegrity that stores an array of objects that describe additional integrity - metadata about each context used by the VC. If - contextIntegrity + metadata about each resource referenced by the VC. If + resourceIntegrity is present there MUST be an object in the array for each remote - context. + resource.

Each object in the - contextIntegrity array MUST contain the following: - the URL to the context named context, a + resourceIntegrity array MUST contain the following: + the URL to the resource named resource, a timestamp that indicates the time at which the hash was computed, the hash - of the context, and the method which indicates what + of the resource, and the method which indicates what hashing algorithm was used as listed as the 'Hash Name String' property from the IANA @@ -2648,17 +2656,17 @@

Context Integrity

+

+

+

From bab6c6f7167769c4f4f9ef85547cccb822b32d3a Mon Sep 17 00:00:00 2001 From: Mike Prorock Date: Wed, 7 Jun 2023 10:43:30 -0400 Subject: [PATCH 06/32] Apply suggestions from code review Co-authored-by: Ted Thibodeau Jr --- index.html | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/index.html b/index.html index cc8b00955..382a390d2 100644 --- a/index.html +++ b/index.html @@ -2598,26 +2598,26 @@

Data Schemas

External Resource Integrity

- When including a link to an external resource in a VC it is - desireable to know if the resource that is pointed to, is the - same at signing time, as at verification time. This applies to - both cases where there is an external resource that is - remotely retrieved, as well as to cases where the issuer and/or + When including a link to an external resource in a VC, it is + desirable to know whether the resource that is pointed to is the + same at signing time as 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.

It is also desirable to know that the contents of the - context(s) utilized in the verifiable credential are the same as + context(s) used in the verifiable credential are the same when used by both the issuer and verifier.

To validate that a resource referenced by a Verifiable Credential is - the same at verification time as at issuing time an implementer + the same at verification time as at issuing time, an implementer MAY include a property named resourceIntegrity that stores an array of objects that describe additional integrity metadata about each resource referenced by the VC. If resourceIntegrity - is present there MUST be an object in the array for each remote + is present, there MUST be an object in the array for each remote resource.

From b226e771c8a4a90b73b5bf14b44851006d035b7c Mon Sep 17 00:00:00 2001 From: Mike Prorock Date: Wed, 7 Jun 2023 10:58:08 -0400 Subject: [PATCH 07/32] update to clarify encoding of hash --- index.html | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/index.html b/index.html index 382a390d2..0d58d1faf 100644 --- a/index.html +++ b/index.html @@ -2632,6 +2632,8 @@

External Resource Integrity

property from the IANA Named Information Hash Algorithm Registry. + The hash property MUST be the base64url [[RFC 4648]] + encoded digest of the hash. The timestamp property MUST be a string value of an [[XMLSCHEMA11-2]] combined date-time string. An implementer may include other fields in each object. @@ -2662,13 +2664,13 @@

External Resource Integrity

               "resourceIntegrity": [{
                 "resource": "https://www.w3.org/ns/credentials/v2",
-                "timestamp": "2020-01-01T19:23:24Z", 
-                "hash": "0c63a75b845e4f7d01107d852e4c2485c51a50aaaa94fc61995e71bbee983a2ac3713831264adb47fb6bd1e058d5f004", 
+                "timestamp": "2023-06-07T19:23:24Z", 
+                "hash": "zMxXZRc9wGRgtsdFaCaqluKtZbyEz-emTp4Y1k1wBvgKNYguD7qTACwjWOTUgB-A", 
                 "method": "sha3-384"  
               },{
                 "resource": "https://www.w3.org/ns/credentials/examples/v2",
-                "timestamp": "2019-02-04T17:32:15Z", 
-                "hash": "ac996ae492f9a987c84f109f2118d3f6632e2259455d30c455a9ecd66c3c4959", 
+                "timestamp": "2023-06-07T17:32:15Z", 
+                "hash": "STCt_TVvy-QH6PCA8IDH7tw0dsBsgkewEl9VjCDwvUCVPz5M10dUhrMG9f2Q82MA", 
                 "method": "sha2-256"  
               }]
@@ -2684,7 +2686,7 @@

External Resource Integrity

"resourceIntegrity": [{ "resource": "https://www.w3.org/Icons/w3c_home.png", "timestamp": "2023-06-05T19:23:24Z", - "hash": "d727ecbc780ef52b029e0013677afa36c14e0f31b30dfb6d946739800dd0926ff4f3225be1f7a94d76c02ba2116760be", + "hash": "1yfsvHgO9SsCngATZ3r6NsFODzGzDfttlGc5gA3Qkm_08yJb4fepTXbAK6IRZ2C-", "method": "sha3-384" }] From 67e936cc837485112e3efce86ad4eee9dd6e7d6d Mon Sep 17 00:00:00 2001 From: mprorock Date: Mon, 12 Jun 2023 14:59:15 -0600 Subject: [PATCH 08/32] chore: add media types reference --- index.html | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/index.html b/index.html index 0d58d1faf..5630fec28 100644 --- a/index.html +++ b/index.html @@ -2638,6 +2638,20 @@

External Resource Integrity

[[XMLSCHEMA11-2]] combined date-time string. An implementer may include other fields in each object.

+

+ An object in the resourceIntegrity array MAY contain + a property named mediaType that indicates the + expected media type for the indicated resource. + If a mediaType is included it must be a valid + media type as listed in the + + IANA Media Types + registry. +

+

+ An object in the resourceIntegrity array MAY contain + additional properties. +

Implementers should consult appropriate sources, such as the IANA From 610b911a16a6910fe0fa2d3b32bd7480d5333183 Mon Sep 17 00:00:00 2001 From: Mike Prorock Date: Tue, 13 Jun 2023 12:51:13 -0400 Subject: [PATCH 09/32] Apply suggestions from code review Incorporating concrete feedback from dmitrizagidulin and or13 Co-authored-by: Orie Steele Co-authored-by: Dmitri Zagidulin --- index.html | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/index.html b/index.html index 5630fec28..921e0b399 100644 --- a/index.html +++ b/index.html @@ -2635,7 +2635,7 @@

External Resource Integrity

The hash property MUST be the base64url [[RFC 4648]] encoded digest of the hash. The timestamp property MUST be a string value of an - [[XMLSCHEMA11-2]] combined date-time string. An implementer may + [[XMLSCHEMA11-2]] combined date-time string. An implementer MAY include other fields in each object.

@@ -2653,15 +2653,15 @@

External Resource Integrity

additional properties.

- Implementers should consult appropriate sources, such as the IANA Named Information Hash Algorithm Registry to ensure that they are chosing a current and reliable hash algorithm. At the time of - this writing `sha-256` should be considered the minimum strength + this writing `sha-256` SHOULD be considered the minimum strength hash algorithm for use by implemnters.

-

- If at a later date subresource integrity as defined in [[SRI]] is +

+ The working group is discussing if we will adopt subresource integrity as defined in [[SRI]] is adopted into the [[JSON-LD]] specification as noted in that specifications current security @@ -2677,14 +2677,14 @@

External Resource Integrity

An example of a resource integrity object referencing contexts

               "resourceIntegrity": [{
-                "resource": "https://www.w3.org/ns/credentials/v2",
+                "id": "https://www.w3.org/ns/credentials/v2",
                 "timestamp": "2023-06-07T19:23:24Z", 
-                "hash": "zMxXZRc9wGRgtsdFaCaqluKtZbyEz-emTp4Y1k1wBvgKNYguD7qTACwjWOTUgB-A", 
+                "digest": "zMxXZRc9wGRgtsdFaCaqluKtZbyEz-emTp4Y1k1wBvgKNYguD7qTACwjWOTUgB-A", 
                 "method": "sha3-384"  
               },{
-                "resource": "https://www.w3.org/ns/credentials/examples/v2",
+                "id": "https://www.w3.org/ns/credentials/examples/v2",
                 "timestamp": "2023-06-07T17:32:15Z", 
-                "hash": "STCt_TVvy-QH6PCA8IDH7tw0dsBsgkewEl9VjCDwvUCVPz5M10dUhrMG9f2Q82MA", 
+                "digest": "STCt_TVvy-QH6PCA8IDH7tw0dsBsgkewEl9VjCDwvUCVPz5M10dUhrMG9f2Q82MA", 
                 "method": "sha2-256"  
               }]
@@ -2698,9 +2698,9 @@

External Resource Integrity

An example of a resource integrity object refering to an image

               "resourceIntegrity": [{
-                "resource": "https://www.w3.org/Icons/w3c_home.png",
+                "id": "https://www.w3.org/Icons/w3c_home.png",
                 "timestamp": "2023-06-05T19:23:24Z", 
-                "hash": "1yfsvHgO9SsCngATZ3r6NsFODzGzDfttlGc5gA3Qkm_08yJb4fepTXbAK6IRZ2C-", 
+                "digest": "1yfsvHgO9SsCngATZ3r6NsFODzGzDfttlGc5gA3Qkm_08yJb4fepTXbAK6IRZ2C-", 
                 "method": "sha3-384"  
               }]
From a53c272785f86a6b4d3bc4027cafe13ec91c6c4a Mon Sep 17 00:00:00 2001 From: Mike Prorock Date: Tue, 13 Jun 2023 12:54:50 -0400 Subject: [PATCH 10/32] Apply suggestions from code review updating normative language to match examples based on code review --- index.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.html b/index.html index 921e0b399..799587419 100644 --- a/index.html +++ b/index.html @@ -2623,16 +2623,16 @@

External Resource Integrity

Each object in the resourceIntegrity array MUST contain the following: - the URL to the resource named resource, a + the URL to the resource named id, a timestamp that indicates the time at which the hash was computed, the - hash + digest of the resource, and the method which indicates what hashing algorithm was used as listed as the 'Hash Name String' property from the IANA Named Information Hash Algorithm Registry. - The hash property MUST be the base64url [[RFC 4648]] + The digest property MUST be the base64url [[RFC 4648]] encoded digest of the hash. The timestamp property MUST be a string value of an [[XMLSCHEMA11-2]] combined date-time string. An implementer MAY From aaba294676deb1fa7e8e3e82494e5c103c2c61c2 Mon Sep 17 00:00:00 2001 From: Mike Prorock Date: Tue, 13 Jun 2023 14:12:40 -0400 Subject: [PATCH 11/32] clarify hash encoding around trailing characters --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 799587419..09a3c30fa 100644 --- a/index.html +++ b/index.html @@ -2633,7 +2633,7 @@

External Resource Integrity

href="https://www.iana.org/assignments/named-information/named-information.xhtml">IANA Named Information Hash Algorithm Registry. The digest property MUST be the base64url [[RFC 4648]] - encoded digest of the hash. + encoded digest of the hash with no trailing characters. The timestamp property MUST be a string value of an [[XMLSCHEMA11-2]] combined date-time string. An implementer MAY include other fields in each object. From 8c21cc8f83bf8a6ebac466288cdf2831094f654a Mon Sep 17 00:00:00 2001 From: mprorock Date: Wed, 14 Jun 2023 06:43:10 -0600 Subject: [PATCH 12/32] chore: re-rename id to resource. add clarifiation on multiple hashes --- index.html | 36 ++++++++++++++++++++++-------------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/index.html b/index.html index 09a3c30fa..20650cd89 100644 --- a/index.html +++ b/index.html @@ -2618,12 +2618,12 @@

External Resource Integrity

metadata about each resource referenced by the VC. If resourceIntegrity is present, there MUST be an object in the array for each remote - resource. + resource.

Each object in the resourceIntegrity array MUST contain the following: - the URL to the resource named id, a + the [[URL]] to the resource named resource, a timestamp that indicates the time at which the hash was computed, the digest @@ -2653,21 +2653,29 @@

External Resource Integrity

additional properties.

- Implementers SHOULD consult appropriate sources, such as the IANA + Implementers SHOULD consult appropriate sources, such as the + IANA Named Information Hash Algorithm Registry to ensure that they are chosing a current and reliable hash algorithm. At the time of this writing `sha-256` SHOULD be considered the minimum strength hash algorithm for use by implemnters.

+

+ If there is more than one object in resourceIntegrity + that refers to the same resource the method + MUST be different for each object. When performing integrity + checking the strongest hash algorithm available SHOULD be used + to confirm integrity of the resource. +

- The working group is discussing if we will adopt subresource integrity as defined in [[SRI]] is - adopted into the [[JSON-LD]] specification as noted in that - specifications current security - considerations 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. + The working group is discussing if we will adopt subresource + integrity as defined in [[SRI]] is adopted into the [[JSON-LD]] + specification as noted in that specifications current + security considerations 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.

@@ -2706,13 +2704,16 @@

External Resource Integrity

class="example" title="resource integrity over image" > -

An example of a resource integrity object refering to an image

+

An example of a resource integrity object in a credentialSubject refering to an image

-              "resourceIntegrity": [{
-                "resource": "https://www.w3.org/Icons/w3c_home.png",
-                "digest": "1yfsvHgO9SsCngATZ3r6NsFODzGzDfttlGc5gA3Qkm_08yJb4fepTXbAK6IRZ2C-", 
-                "method": "sha3-384"  
-              }]
+              "credentialSubject": {
+                "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+                "image": {
+                    "id": "https://university.example/images/58473",
+                    "integrity": "sha384-ZfAwuJmMgoX3s86L7x9XSPi3AEbiz6S/5SyGHJPCxWHs5NEth/c5S9QoS1zZft+J"
+                },
+                ...
+              }

From 84da94c185345b11db47b3b125a7cf36ad02a43f Mon Sep 17 00:00:00 2001 From: mprorock Date: Thu, 15 Jun 2023 13:45:36 -0600 Subject: [PATCH 16/32] chore: clean up some language --- index.html | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index 9357991cc..8d6078fb5 100644 --- a/index.html +++ b/index.html @@ -2630,8 +2630,11 @@

External Resource Integrity

Integrity.

- There may be only one object in the resourceIntegrity - per id. When performing integrity checking the + There MUST NOT be more than one object in the + resourceIntegrity per id. +

+

+ When performing integrity checking the strongest hash algorithm available SHOULD be used to confirm integrity of the resource.

From 1843865c12fe1c66e9eecc5575f8d6280cb604a4 Mon Sep 17 00:00:00 2001 From: mprorock Date: Thu, 15 Jun 2023 13:47:37 -0600 Subject: [PATCH 17/32] chore: add language around selective disclosure --- index.html | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index 8d6078fb5..8f68f7fd7 100644 --- a/index.html +++ b/index.html @@ -2666,6 +2666,11 @@

External Resource Integrity

information as specified above, with the [[URL]] in the id property.

+

+ Any objects for which selective disclosure is desired SHOULD NOT + be included as an object in the resourceIntegrity + array. +

Implementers SHOULD consult appropriate sources, such as the IANA @@ -2674,7 +2679,6 @@

External Resource Integrity

this writing `sha-256` SHOULD be considered the minimum strength hash algorithm for use by implemnters.

-

The working group is discussing if we will adopt subresource integrity as defined in [[SRI]] is adopted into the [[JSON-LD]] From 4b8ffbf7b4623c9be5474601470f9d358c75071a Mon Sep 17 00:00:00 2001 From: Mike Prorock Date: Fri, 16 Jun 2023 10:28:43 -0400 Subject: [PATCH 18/32] expand one example to include all optional properties --- index.html | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index 8f68f7fd7..6a7a2e28b 100644 --- a/index.html +++ b/index.html @@ -2717,7 +2717,9 @@

External Resource Integrity

"id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "image": { "id": "https://university.example/images/58473", - "integrity": "sha384-ZfAwuJmMgoX3s86L7x9XSPi3AEbiz6S/5SyGHJPCxWHs5NEth/c5S9QoS1zZft+J" + "integrity": "sha384-ZfAwuJmMgoX3s86L7x9XSPi3AEbiz6S/5SyGHJPCxWHs5NEth/c5S9QoS1zZft+J", + "mediaType": "application/svg+xml", + "timestamp": "2023-06-16T17:10:24Z" }, ... } From a15f29f42f30fc2ce4cb83f445ab6a82a543d0e1 Mon Sep 17 00:00:00 2001 From: Mike Prorock Date: Sun, 18 Jun 2023 13:09:21 -0400 Subject: [PATCH 19/32] Apply suggestions from code review from msporny improve normative language, grammar and links Co-authored-by: Manu Sporny --- index.html | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/index.html b/index.html index 6a7a2e28b..f778a0712 100644 --- a/index.html +++ b/index.html @@ -2598,24 +2598,24 @@

Data Schemas

External Resource Integrity

- When including a link to an external resource in a VC, it is + 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 at verification time. This applies + 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. + remotely retrieved as well as to cases where the issuer and/or + verifier may have local cached copies of a resource.

It is also desirable to know that the contents of the - context(s) used in the verifiable credential are the same when - used by both the issuer and verifier. + context(s) used in the verifiable credential are the same when + used by both the issuer and verifier.

- To validate that a resource referenced by a Verifiable Credential is - the same at verification time as at issuing time, an implementer + 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 resourceIntegrity that stores an array of objects that describe additional integrity - metadata about each resource referenced by the VC. If + metadata about each resource referenced by the verifiable credential. If resourceIntegrity is present, there MUST be an object in the array for each remote resource for each context used in the verifiable credential. @@ -2672,7 +2672,7 @@

External Resource Integrity

array.

- Implementers SHOULD consult appropriate sources, such as the + Implementers are urged to consult appropriate sources, such as the IANA Named Information Hash Algorithm Registry to ensure that they are chosing a current and reliable hash algorithm. At the time of @@ -2712,7 +2712,7 @@

External Resource Integrity

title="resource integrity over image" >

An example of a resource integrity object in a credentialSubject refering to an image

- 
+            
               "credentialSubject": {
                 "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
                 "image": {

From 07fd10d8b5ea0cfa092be8f46694f03e363dd046 Mon Sep 17 00:00:00 2001
From: Mike Prorock 
Date: Sun, 18 Jun 2023 13:18:36 -0400
Subject: [PATCH 20/32] remove an un-needed statement

Co-authored-by: Manu Sporny 
---
 index.html | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/index.html b/index.html
index f778a0712..385f2d903 100644
--- a/index.html
+++ b/index.html
@@ -2655,10 +2655,6 @@ 
External Resource Integrity

             IANA Media Types
            registry.
         

-        

-          An object in the resourceIntegrity array MAY contain
-          additional properties.
-        

         

           In any object in the credential.credentialSubject
           that contains a [[URL]], a property named

From 774d696d03d4f3f726437119115c5ee382accec0 Mon Sep 17 00:00:00 2001
From: Mike Prorock 
Date: Sun, 18 Jun 2023 13:22:15 -0400
Subject: [PATCH 21/32] change media type language from must to should

---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index 385f2d903..29dd8057c 100644
--- a/index.html
+++ b/index.html
@@ -2649,7 +2649,7 @@ 
External Resource Integrity

           An object in the resourceIntegrity array MAY contain
           a property named mediaType that indicates the 
           expected media type for the indicated resource.
-          If a mediaType is included it must be a valid
+          If a mediaType is included it SHOULD be a valid
           media type as listed in the 
           
             IANA Media Types

From 6c1ac58f1398bd043e24768ed708a472ba515e01 Mon Sep 17 00:00:00 2001
From: Mike Prorock 
Date: Tue, 27 Jun 2023 09:02:40 -0400
Subject: [PATCH 22/32] updated name to relatedResource based on feedback

Co-authored-by: Manu Sporny 
Co-authored-by: Ted Thibodeau Jr 
---
 index.html | 24 +++++++++++-------------
 1 file changed, 11 insertions(+), 13 deletions(-)

diff --git a/index.html b/index.html
index 29dd8057c..3fc6c3162 100644
--- a/index.html
+++ b/index.html
@@ -2596,7 +2596,7 @@ 
Data Schemas
-

External Resource Integrity

+

Integrity of Related Resources

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 @@ -2607,22 +2607,22 @@

External Resource Integrity

It is also desirable to know that the contents of the - context(s) used in the verifiable credential are the same when + JSON-LD context(s) used in the verifiable credential are the same when used by both the issuer and verifier.

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 resourceIntegrity that + MAY include a property named relatedResource that stores an array of objects that describe additional integrity metadata about each resource referenced by the verifiable credential. If - resourceIntegrity + relatedResource is present, there MUST be an object in the array for each remote resource for each context used in the verifiable credential.

Each object in the - resourceIntegrity array MUST contain the following: + relatedResource array MUST contain the following: the [[URL]] to the resource named id and the integrity information for the resource constructed using the method specified in External Resource Integrity integrity of the resource.

- An object in the resourceIntegrity array MAY + An object in the relatedResource array MAY contain a property named timestamp that indicates the time at which the hash was computed. The timestamp property if included MUST be a string value of an [[XMLSCHEMA11-2]] combined date-time string.

- An object in the resourceIntegrity array MAY contain + 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 it SHOULD be a valid @@ -2656,15 +2656,13 @@

External Resource Integrity

 registry.

- In any object in the credential.credentialSubject - that contains a [[URL]], a property named - integrity may be included with the integrity - information as specified above, with the [[URL]] in the - id property. + Any object in the verifiable credential + that contains an `id` [[URL]] property MAY be annotated with + integrity information as specified in this section.

Any objects for which selective disclosure is desired SHOULD NOT - be included as an object in the resourceIntegrity + be included as an object in the relatedResource array.

From 73f9490f88cf2822839435c2f98f6ce41cdb32c0 Mon Sep 17 00:00:00 2001 From: mprorock Date: Tue, 27 Jun 2023 07:05:34 -0600 Subject: [PATCH 23/32] remove timestamp from relatedResource --- index.html | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) diff --git a/index.html b/index.html index 3fc6c3162..61b119a1e 100644 --- a/index.html +++ b/index.html @@ -2631,19 +2631,7 @@

Integrity of Related Resources

There MUST NOT be more than one object in the - resourceIntegrity per id. -

-

- When performing integrity checking the - strongest hash algorithm available SHOULD be used to confirm - integrity of the resource. -

-

- An object in the relatedResource array MAY - contain a property named timestamp - that indicates the time at which the hash was computed. The - timestamp property if included MUST be a string - value of an [[XMLSCHEMA11-2]] combined date-time string. + relatedResource per id.

An object in the relatedResource array MAY contain @@ -2713,7 +2701,6 @@

Integrity of Related Resources

"id": "https://university.example/images/58473", "integrity": "sha384-ZfAwuJmMgoX3s86L7x9XSPi3AEbiz6S/5SyGHJPCxWHs5NEth/c5S9QoS1zZft+J", "mediaType": "application/svg+xml", - "timestamp": "2023-06-16T17:10:24Z" }, ... } From 1bd4309975d3d4dc10669d90242e18f52f4816b2 Mon Sep 17 00:00:00 2001 From: mprorock Date: Tue, 27 Jun 2023 07:16:50 -0600 Subject: [PATCH 24/32] chore: adjust to digestSRI --- index.html | 39 +++++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/index.html b/index.html index 61b119a1e..024e9b335 100644 --- a/index.html +++ b/index.html @@ -2624,7 +2624,7 @@

Integrity of Related Resources

Each object in the relatedResource array MUST contain the following: the [[URL]] to the resource named id and the - integrity information for the resource + digestSRI information for the resource constructed using the method specified in Subresource Integrity. @@ -2655,21 +2655,24 @@

Integrity of Related Resources

Implementers are urged to consult appropriate sources, such as the - IANA - Named Information Hash Algorithm Registry to ensure that they - are chosing a current and reliable hash algorithm. At the time of - this writing `sha-256` SHOULD be considered the minimum strength - hash algorithm for use by implemnters. + + FIPS 180-4 Secure Hash Standard and the + + Commercial National Security Algorithm Suite 2.0 + to ensure that they are 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 + implemnters.

- The working group is discussing if we will adopt subresource - integrity as defined in [[SRI]] is adopted into the [[JSON-LD]] - specification as noted in that specifications current - security considerations 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. + The working group is discussing if we will adopt more aspects + of subresource integrity as defined in [[SRI]] is adopted into + the [[JSON-LD]] specification as noted in that specifications + current + security considerations 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.

@@ -2698,8 +2701,8 @@

Integrity of Related Resources

"credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "image": { - "id": "https://university.example/images/58473", - "integrity": "sha384-ZfAwuJmMgoX3s86L7x9XSPi3AEbiz6S/5SyGHJPCxWHs5NEth/c5S9QoS1zZft+J", + "id": "https://university.example.org/images/58473", + "digestSRI": "sha384-ZfAwuJmMgoX3s86L7x9XSPi3AEbiz6S/5SyGHJPCxWHs5NEth/c5S9QoS1zZft+J", "mediaType": "application/svg+xml", }, ... From 90a43b8cdfd7f67b266fc37c5c8ee1ea89270308 Mon Sep 17 00:00:00 2001 From: mprorock Date: Tue, 27 Jun 2023 07:18:44 -0600 Subject: [PATCH 25/32] chore: adjust line wrapping and format --- index.html | 53 +++++++++++++++++++++++++++++------------------------ 1 file changed, 29 insertions(+), 24 deletions(-) diff --git a/index.html b/index.html index 024e9b335..9d18fb7b7 100644 --- a/index.html +++ b/index.html @@ -2598,24 +2598,26 @@

Data Schemas

Integrity of Related Resources

- 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 + 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.

- 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. + 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.

- 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 relatedResource that - stores an array of objects that describe additional integrity - metadata about each resource referenced by the verifiable credential. If + 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 + relatedResource 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. @@ -2634,11 +2636,11 @@

Integrity of Related Resources

relatedResource per id.

- 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 it SHOULD be a valid - media type as listed in the + 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 + it SHOULD be a valid media type as listed in the IANA Media Types registry. @@ -2649,12 +2651,13 @@

Integrity of Related Resources

integrity information as specified in this section.

- 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 is desired SHOULD + NOT be included as an object in the + relatedResource array.

- Implementers are urged to consult appropriate sources, such as the + Implementers are urged to consult appropriate sources, such as + the FIPS 180-4 Secure Hash Standard and the @@ -2679,7 +2682,8 @@

Integrity of Related Resources

class="example" title="resource integrity" > -

An example of a resource integrity object referencing contexts

+

An example of a resource integrity object referencing + contexts

               "resourceIntegrity": [{
                 "id": "https://www.w3.org/ns/credentials/v2",
@@ -2696,7 +2700,8 @@ 
Integrity of Related Resources

             class="example"
             title="resource integrity over image"
           >
-            
An example of a resource integrity object in a credentialSubject refering to an image

+            
An example of a resource integrity object in a
+            credentialSubject refering to an image

             
               "credentialSubject": {
                 "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",

From 3ecd1b840f67fbec2a706131b6e2e0193023f256 Mon Sep 17 00:00:00 2001
From: mprorock 
Date: Tue, 27 Jun 2023 07:20:23 -0600
Subject: [PATCH 26/32] chore: adjust titles in examples

---
 index.html | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/index.html b/index.html
index 9d18fb7b7..649402196 100644
--- a/index.html
+++ b/index.html
@@ -2680,9 +2680,9 @@ 
Integrity of Related Resources