From f8790712b2b2f622ef68707f2ff3b70d77322ac4 Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Sat, 27 Jul 2024 14:46:21 -0400 Subject: [PATCH] Clarify difference between input/un/secured document. --- index.html | 87 +++++++++++++++++++++++++++--------------------------- 1 file changed, 44 insertions(+), 43 deletions(-) diff --git a/index.html b/index.html index ddf72b8..008bc7e 100644 --- a/index.html +++ b/index.html @@ -509,8 +509,8 @@

Design Goals and Rationale

converted to a JSON document that follows the relevant normative requirements in -Sections [[[#proofs]]], [[[#proof-purposes]]], [[[#contexts-and-vocabularies]]], -and [[[#dataintegrityproof]]]. +Sections [[[#proofs]]], [[[#proof-purposes]]], [[[#resource-integrity]]], +[[[#contexts-and-vocabularies]]], and [[[#dataintegrityproof]]].

@@ -1040,7 +1040,7 @@

Proof Graphs

-The information contained in an unsecured document before a +The information contained in an input document before a [=data integrity proof=] is added to the document is expressed in one or more graphs. To ensure that information from different [=data integrity proofs=] is not accidentally co-mingled, the concept of a [=proof graph=] is used to encapsulate @@ -1744,8 +1744,8 @@

Cryptographic Suites

createProof
-An algorithm that takes an [=unsecured data document=] ([=map=] -|unsecuredDocument|) and proof options ([=map=] |options|) as input, and +An algorithm that takes an [=input document=] ([=map=] +|inputDocument|) and proof options ([=map=] |options|) as input, and produces a [=data integrity proof=] ([=map=]) or an error.
verifyProof
@@ -1885,12 +1885,13 @@

Algorithms

The algorithms defined below operate on documents represented as JSON objects. This specification follows the -[[[JSON-LD11-API]]] specification in representing a JSON object as an -[[[Infra]]] [=map=]. An unsecured data document is an -[[[Infra]]] [=map=] that has not yet had the current proof added to it, but it -MAY contain a proof value that was added to it by a previous process. A secured data document is a [=map=] that has had the current -proof(s) added to it. +[[[JSON-LD11-API]]] specification in representing a JSON object as an [=map=]. +An unsecured data document is a [=map=] that contains +no proof values. An input document is an [=map=] that has not yet had +the current proof added to it, but it MAY contain a proof value that was added +to it by a previous process. A secured data document +is a [=map=] that contains one or more proof value, one of which might be the +current proof(s) being generated to be added to it.

@@ -1964,19 +1965,19 @@

Processing Model

Add Proof

-The following algorithm specifies how a digital proof can be added to an -[=unsecured data document=], and can then be used to verify the output -document's authenticity and integrity. Required inputs are an unsecured data -document ([=map=] |unsecuredDocument|), a [=cryptosuite instance=] -([=struct=] |cryptosuite|), and a set of options ([=map=] |options|). Output is -a [=secured data document=] ([=map=]) or an error. Whenever this algorithm -encodes strings, it MUST use UTF-8 encoding. +The following algorithm specifies how a digital proof can be added to an [=input +document=], and can then be used to verify the output document's authenticity +and integrity. Required inputs are an [=input document=] ([=map=] +|inputDocument|), a [=cryptosuite instance=] ([=struct=] |cryptosuite|), and a +set of options ([=map=] |options|). Output is a [=secured data document=] +([=map=]) or an error. Whenever this algorithm encodes strings, it MUST use +UTF-8 encoding.

  1. Let |proof| be the result of calling the [=cryptosuite instance/createProof=] -algorithm specified in |cryptosuite|.|createProof| with |unsecuredDocument| +algorithm specified in |cryptosuite|.|createProof| with |inputDocument| and |options| passed as a parameters. If the algorithm produces an error, the error MUST be propagated and SHOULD convey the error type.
    2. @@ -1998,7 +1999,7 @@

    Add Proof

    PROOF_GENERATION_ERROR.
  2. -Let |securedDataDocument| be a copy of |unsecuredDocument|. +Let |securedDataDocument| be a copy of |inputDocument|.
  3. Set |securedDataDocument|.|proof| to the value of |proof|. @@ -2029,9 +2030,9 @@

    Add Proof Set/Chain

    is an object add a copy of that object to |allProofs|.
  4. -Let the |unsecuredDocument| be a copy of the |securedDocument| +Let the |inputDocument| be a copy of the |securedDocument| with the |proof| attribute removed. Let |output| be a copy of -the |unsecuredDocument|. +the |inputDocument|.
  5. Let |matchingProofs| be an empty list. @@ -2052,7 +2053,7 @@

    Add Proof Set/Chain

    PROOF_GENERATION_ERROR.
  6. -Set |unsecuredDocument|.|proof| to |matchingProofs|. +Set |inputDocument|.|proof| to |matchingProofs|.

    This step is critical, as it binds the previous proofs to the document prior to signing. The |proof| value for the document will be updated @@ -2061,7 +2062,7 @@

    Add Proof Set/Chain

  7. Run steps 1 through 6 of the algorithm in section [[[#add-proof]]], passing -|unsecuredDocument|, |suite|, and |options|. If no exceptions are raised, append +|inputDocument|, |suite|, and |options|. If no exceptions are raised, append the generated |proof| value to the |allProofs|; otherwise, raise the exception.
  8. @@ -2123,7 +2124,7 @@

    Verify Proof

    verifiedDocument
    Null, if [=verification result/verified=] is -`false`; otherwise, an [=unsecured data document=] +`false`; otherwise, an [=input document=]
    media type
    @@ -2255,12 +2256,12 @@

    Verify Proof Sets and Chains

    PROOF_VERIFICATION_ERROR.
  9. -Let |unsecuredDocument| be a copy of |securedDocument| with the proof value -removed and then set |unsecuredDocument|.|proof| to |matchingProofs|. +Let |inputDocument| be a copy of |securedDocument| with the proof value +removed and then set |inputDocument|.|proof| to |matchingProofs|.
  10. Run steps 4 through 8 of the algorithm in section [[[#verify-proof]]] on -|unsecuredDocument|; if no exceptions are raised, append |cryptosuiteVerificationResult| +|inputDocument|; if no exceptions are raised, append |cryptosuiteVerificationResult| to |verificationResults|.
@@ -3348,7 +3349,7 @@

Understanding Proof Sets and Proof Chains

When constructing a [=proof set=] where each of the signatories signs an -|unsecuredDataDocument| without concern, we construct a proof symbolically as: +|inputDocument| without concern, we construct a proof symbolically as: 

 {
@@ -3357,13 +3358,13 @@ 
Understanding Proof Sets and Proof Chains

   "created": "2023-03-05T19:23:24Z",
   "proofPurpose": "assertionMethod",
   "verificationMethod": publicCEO,
-  "proofValue": signature(secretCEO, unsecuredDataDocument)
+  "proofValue": signature(secretCEO, inputDocument)
 }

Where publicCEO is used as a placeholder for a reference that resolves to the CEO's public key and signature(`secretKey`, -`unsecuredDataDocument`) denotes the computation of a digital signature +`inputDocument`) denotes the computation of a digital signature by a particular data integrity cryptosuite using a particular secret key over a particular document. The `type`, `cryptosuite`, `created`, and `proofPurpose` attributes do not factor into our discussion so we will omit them. In @@ -3375,13 +3376,13 @@

Understanding Proof Sets and Proof Chains

// Remainder of secured data document not shown (above) "proof": [{ "verificationMethod": publicVPE, - "proofValue": signature(secretVPE, unsecuredDataDocument) + "proofValue": signature(secretVPE, inputDocument) }, { "verificationMethod": publicCFO, - "proofValue": signature(secretCFO, unsecuredDataDocument) + "proofValue": signature(secretCFO, inputDocument) }, { "verificationMethod": publicCEO, - "proofValue": signature(secretCEO, unsecuredDataDocument) + "proofValue": signature(secretCEO, inputDocument) }] } @@ -3402,10 +3403,10 @@

Understanding Proof Sets and Proof Chains

// Remainder of secured data document not shown (above) "proof": [{ "verificationMethod": publicCFO, - "proofValue": signature(secretCFO, unsecuredDataDocument) + "proofValue": signature(secretCFO, inputDocument) }, { "verificationMethod": publicCEO, - "proofValue": signature(secretCEO, unsecuredDataDocument) + "proofValue": signature(secretCEO, inputDocument) }] } @@ -3425,7 +3426,7 @@

Understanding Proof Sets and Proof Chains

and finally, based on both prior signatures and a review, the CEO signs off on the document. Since others will be referring to the VP of Engineering's signature, we need to add an `id` to the proof. First the VP of -Engineering signs the [=unsecured data document=]: +Engineering signs the [=input document=]: 

@@ -3434,7 +3435,7 @@ 
Understanding Proof Sets and Proof Chains

   "proof": {
     "id": "urn:proof-1",
     "verificationMethod": publicVPE,
-    "proofValue": signature(secretVPE, unsecuredDataDocument)
+    "proofValue": signature(secretVPE, inputDocument)
   }
 }
@@ -3454,12 +3455,12 @@

Understanding Proof Sets and Proof Chains

"proof": [{ "id": "urn:proof-1", "verificationMethod": publicVPE, - "proofValue": signature(secretVPE, unsecuredDataDocument) + "proofValue": signature(secretVPE, inputDocument) }, { "id": "urn:proof-2", "verificationMethod": publicCFO, "previousProof": "urn:proof-1", - "proofValue": signature(secretCFO, unsecuredDataDocumentWithProof1) + "proofValue": signature(secretCFO, inputDocumentWithProof1) }] } @@ -3485,17 +3486,17 @@

Understanding Proof Sets and Proof Chains

"proof": [{ "id": "urn:proof-1", "verificationMethod": publicVPE, - "proofValue": signature(secretVPE, unsecuredDataDocument) + "proofValue": signature(secretVPE, inputDocument) }, { "id": "urn:proof-2", "verificationMethod": publicCFO, "previousProof": "urn:proof-1", - "proofValue": signature(secretCFO, unsecuredDataDocumentWithProof1) + "proofValue": signature(secretCFO, inputDocumentWithProof1) }, { "id": "urn:proof-3", "verificationMethod": publicCEO, "previousProof": "urn:proof-2", - "proofValue": signature(secretCEO, unsecuredDataDocumentWithProof2) + "proofValue": signature(secretCEO, inputDocumentWithProof2) }] }