From 94b7826328b8c9800be48b98e334c9558024065e Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Sat, 6 Apr 2024 16:46:59 -0400 Subject: [PATCH] Ensure that status messages are committed to at issuance time. --- index.html | 296 +++++++++++++++++++++++++++++------------------------ 1 file changed, 162 insertions(+), 134 deletions(-) diff --git a/index.html b/index.html index e6c7be1..92f7e2b 100644 --- a/index.html +++ b/index.html @@ -465,6 +465,17 @@

BitstringStatusListEntry

conforming [=verifiable credential=] as defined in [[VC-DATA-MODEL-2.0]].

+

+The Working Group is currently seeking implementer feedback regarding the +utility of bitstring entries that have sizes greater than one. Supporting +such entries adds complexity to the solution, and it's not clear whether there +is enough of an implementation community to support the feature. The WG is +considering three options: (1) require conforming implementations to support +the feature; (2) allow implementations to optionally support the feature; or +(3) remove the feature. At present, the specification implements option (2). +

+ @@ -552,39 +563,150 @@

BitstringStatusListEntry

includes the `BitstringStatusListCredential` value. + + + + + + + + + + + +
statusSize +The `statusSize` indicates the size of the status entry in bits. `statusSize` +MAY be provided. If `statusSize` is not present as a property of the +`credentialStatus`, then `statusSize` MUST be processed as `1`. `statusSize` +MUST be an integer greater than zero. If `statusSize` is provided and is greater +than `1`, then the property `credentialStatus.statusMessage` MUST be present, +and the number of status messages must equal the number of possible values. +
statusMessage +The `statusMessage` property MUST be an array. If present, +the length of the array must equal the number of possible status states +indicated by `statusSize`. `statusMessages` MAY be present if +`statusSize` is `1`. `statusMessages` MUST be present if +`statusSize` is greater than `1`. If not present, the message value +associated with the bit value of `0` is "unset" and the bit +value of `1` is "set". +If present, elements in the `statusMessage` array MUST contain at +minimum two properties: +
    +
  • +`status`, a string representing the hexadecimal value of the status prefixed +with `0x` +
    • +
  • +`message`, a string used by software developers to assist with debugging +which SHOULD NOT be displayed to end users. +
    • +
+Implementers MAY add additional values to objects in the `statusMessage` array. +Implementers MAY use the string value of `undefined` in the value to indicate +that a corresponding status is not defined for the associated status value, but +that it may be defined in the future. Rules for how to handle various status +messages are outside the scope of normative requirements in this document, but +it is assumed that implementers will document rules for processing various +status codes. +
statusReference +The `statusReference` property provides a point for implementers to include a +[[URL]] to material related to the status. An implementer MAY include the +`statusReference` property, and if they do, the value MUST be a [[URL]] or an +array of URLs. Implementers using a `statusPurpose` of `status` are strongly +encouraged to provide a `statusReference`. +

+`statusReference` is especially important when interpretation of the status for +a credential may involve some understanding of the business case involved. +

+
- 
+
+        

+Status list entries can be used to associate a single status type,
+such as `revocation` or `suspension`, with a [=verifiable credential=] by using
+the `statusPurpose` property. The example below demonstrates the association
+of simple status list entries:
+        

+
+        
 {
   "@context": [
-    "https://www.w3.org/ns/credentials/v2"
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2"
   ],
   "id": "https://example.com/credentials/23894672394",
-  "type": ["VerifiableCredential"],
+  "type": ["VerifiableCredential", "EmployeeIdCredential"],
   "issuer": "did:example:12345",
-  "validFrom": "2021-04-05T14:27:42Z",
-  "credentialStatus": [
-    {
-      "id": "https://example.com/credentials/status/3#94567",
-      "type": "BitstringStatusListEntry",
-      "statusPurpose": "revocation",
-      "statusListIndex": "94567",
-      "statusListCredential": "https://example.com/credentials/status/3"
-    }, {
-      "id": "https://example.com/credentials/status/4#23452",
-      "type": "BitstringStatusListEntry",
-      "statusPurpose": "suspension",
-      "statusListIndex": "23452",
-      "statusListCredential": "https://example.com/credentials/status/4"
-    }
-  ],
+  "validFrom": "2024-04-05T14:27:42Z",
+  "credentialStatus": [{
+    "id": "https://example.com/credentials/status/3#94567",
+    "type": "BitstringStatusListEntry",
+    "statusPurpose": "revocation",
+    "statusListIndex": "94567",
+    "statusListCredential": "https://example.com/credentials/status/3"
+  }, {
+    "id": "https://example.com/credentials/status/4#23452",
+    "type": "BitstringStatusListEntry",
+    "statusPurpose": "suspension",
+    "statusListIndex": "23452",
+    "statusListCredential": "https://example.com/credentials/status/4"
+  }],
   "credentialSubject": {
     "id": "did:example:6789",
-    "type": "Person"
+    "type": "Person",
+    "employeeId": "A-123456"
   }
 }
         

+
+        

+Status list entries can be used to associate many status types with a
+[=verifiable credential=] by using the `message` status purpose. The set of
+messages associated with a particular entry is committed to by the [=issuer=]
+by using the `statusSize`, `statusMessage`, and optional `statusReference`
+properties. This commitment is done at the time of issuance to ensure that
+the [=holder=] knows what sort of information might be associated with a
+particular [=verifiable credential=] that is in their possession, and would
+then be discoverable by a [=verifier=] that receives that credential.
+        

+
+        
+{
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2"
+  ],
+  "id": "https://example.com/credentials/2947478373",
+  "type": ["VerifiableCredential", "BillOfLadingExampleCredential"],
+  "issuer": "did:example:12345",
+  "validFrom": "2024-04-05T03:52:31Z",
+  "credentialStatus": {
+    "id": "https://example.com/credentials/status/8#492847",
+    "type": "BitstringStatusListEntry",
+    "statusPurpose": "message",
+    "statusListIndex": "492847",
+    "statusSize": 2,
+    "statusListCredential": "https://example.com/credentials/status/8",
+    "statusMessage": [
+        {"status":"0x0", "message":"pending_review"},
+        {"status":"0x1", "message":"accepted"},
+        {"status":"0x2", "message":"rejected"},
+        ...
+    ],
+    "statusReference": "https://example.org/status-dictionary/"
+  },
+  "credentialSubject": {
+    "id": "did:example:6789",
+    "type": "BillOfLading",
+    ...
+  }
+}
+        

+
       
 
       

@@ -594,20 +716,29 @@ 
BitstringStatusListCredential

 When a status list [=verifiable credential=] is published, it MUST be a
 conforming document, as defined in [[VC-DATA-MODEL-2.0]], that expresses the
 data model in this section. The following section describes the format of
-the [=verifiable credential=] that encapsulates the status list:
+the [=verifiable credential=] that encapsulates the status list.
         

 
-        

-The Working Group is currently seeking implementer feedback regarding the
-utility of bitstring entries that have sizes greater than one. Supporting
-such entries adds complexity to the solution, and it's not clear whether there
-is enough of an implementation community to support the feature. The WG is
-considering three options: (1) require conforming implementations to support
-the feature; (2) allow implementations to optionally support the feature; or
-(3) remove the feature. At present, the specification implements option (2).
+        

+The status list is expressed inside a [=verifiable credential=] in order to
+enable a [=holder=] to provide it to a [=verifier=] directly. This mechanism,
+sometimes called "certificate stapling", increases privacy for the [=holder=] by
+ensuring that the [=verifier=] does not need to contact the [=issuer=] to
+retrieve the status list. Still, a [=verifier=] might choose to ignore the
+[=holder=]-provided status list, even when its authenticity is verifiable,
+if it desires a more recent version of a status list, for instance.
         

 
+        

+[=Issuers=] and [=verifiers=] are advised that the [=issuer=] of a
+[=verifiable credential=] and the [=issuer=] of an associated
+`BitstringStatusListCredential` might not be the same. There are technical,
+legal, institutional, and political reasons that might make it appropriate
+to separate the authority over the original credential from the authority to
+revoke such a credential. Therefore, the `issuer` value of a verifiable
+credential containing a `BitstringStatusListEntry` MAY be different from
+the `issuer` value of a `BitstringStatusListCredential`.
+        

 
         

 The Working Group is considering the removal of the `ttl` ("time to live")
@@ -746,62 +877,6 @@ 
BitstringStatusListCredential

 HTTP `Cache-Control` header, with the value in this field.
               
             
-            
-              credentialSubject.statusSize
-              
-The `statusSize` indicates the size of the status entry in bits. `statusSize`
-MAY be provided. If `statusSize` is not present as a property of the
-`credentialStatus`, then `statusSize` MUST be processed as `1`.  `statusSize`
-MUST be an integer greater than zero. If `statusSize` is provided and is greater
-than `1`, then the property `credentialStatus.statusMessage` MUST be present,
-and the number of status messages must equal the number of possible values.
-              
-            
-            
-              credentialSubject.statusMessage
-              
-The `statusMessage` property MUST be an array. If present,
-the length of the array must equal the number of possible status states
-indicated by `statusSize`. `statusMessages` MAY be present if
-`statusSize` is `1`. `statusMessages` MUST be present if
-`statusSize` is greater than `1`.  If not present, the message value
-associated with the bit value of `0` is "unset" and the bit
-value of `1` is "set".
-If present, elements in the `statusMessage` array MUST contain at
-minimum two properties:
-                
    
-                  
  • 
-`status`, a string representing the hexadecimal value of the status prefixed
-with `0x`
-                  
    • 
-                  
  • 
-`message`, a string used by software developers to assist with debugging
-which SHOULD NOT be displayed to end users.
-                  
    • 
-                

-Implementers MAY add additional values to objects in the `statusMessage` array.
-Implementers MAY use the string value of `undefined` in the value to indicate
-that a corresponding status is not defined for the associated status value, but
-that it may be defined in the future. Rules for how to handle various status
-messages are outside the scope of normative requirements in this document, but
-it is assumed that implementers will document rules for processing various
-status codes.
-              
-            
-            
-              credentialSubject.statusReference
-              
-The `statusReference` property provides a point for implementers to include a
-[[URL]] to material related to the status. An implementer MAY include the
-`statusReference` property, and if they do, the value MUST be a [[URL]] or an
-array of URLs. Implementers using a `statusPurpose` of `status` are strongly
-encouraged to provide a `statusReference`.
-                

-`statusReference` is especially important when interpretation of the status for
-a credential may involve some understanding of the business case involved.
-                

-              
-            
           
         
 
@@ -830,56 +905,9 @@ 
BitstringStatusListCredential

 }
-

-The status list is expressed inside a [=verifiable credential=] in order to -enable a [=holder=] to provide it to a [=verifier=] directly. This mechanism, -sometimes called "certificate stapling", increases privacy for the [=holder=] by -ensuring that the [=verifier=] does not need to contact the [=issuer=] to -retrieve the status list. Still, a [=verifier=] might choose to ignore the -[=holder=]-provided status list, even when its authenticity is verifiable, -if it desires a more recent version of a status list, for instance. -

- - 
-{
-  "@context": [
-    "https://www.w3.org/ns/credentials/v2"
-  ],
-  "id": "https://example.com/credentials/status/3",
-  "type": ["VerifiableCredential", "BitstringStatusListCredential"],
-  "issuer": "did:example:12345",
-  "validFrom": "2021-04-05T14:27:40Z",
-  "credentialSubject": {
-    "id": "https://example.com/status/3#list",
-    "type": "BitstringStatusList",
-    "ttl": 500,
-    "statusPurpose": "status",
-    "statusReference": "https://example.org/status-dictionary/",
-    "statusSize": 2,
-    "statusMessage": [
-        {"status":"0x0", "message":"valid"},
-        {"status":"0x1", "message":"invalid"},
-        {"status":"0x2", "message":"pending_review"},
-        ...
-    ],
-    "encodedList": "uH4sIAAAAAAAAA-3BMQEAAADAAAAAAAAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA"
-  }
-}
-
- -

-[=Issuers=] and [=verifiers=] are advised that the `issuer` of a -[=verifiable credential=] and the `issuer` of an associated -`BitstringStatusListCredential` might not be the same. There are technical, -legal, institutional, and political reasons that might make it appropriate -to separate the authority over the original credential from the authority to -revoke such a credential. Therefore, the `issuer` value of a verifiable -credential containing a `BitstringStatusListEntry` MAY be different from -the `issuer` value of a `BitstringStatusListCredential`. -

- +

Algorithms