diff --git a/index.html b/index.html index f6780ba..5d686a2 100644 --- a/index.html +++ b/index.html @@ -103,7 +103,6 @@ /*preProcess: [ webpayments.preProcess ], alternateFormats: [ {uri: "diff-20111214.html", label: "diff to previous version"} ], */ - xref: ["INFRA", "VC-DATA-INTEGRITY", "VC-DATA-MODEL-2.0"], localBiblio: { MULTIBASE: { title: "Multibase", @@ -139,8 +138,7 @@ href: "https://doi.org/10.6028/NIST.SP.800-57pt1r5" } }, - lint: {"no-unused-dfns": false}, - postProcess: [], + xref: ["INFRA", "VC-DATA-MODEL-2.0", "VC-DATA-INTEGRITY"], otherLinks: [{ key: "Related Specifications", data: [{ @@ -521,6 +519,71 @@

Algorithms

by default, and abort processing upon detection.

+
+

Instantiate Cryptosuite

+ +

+This algorithm is used to configure a cryptographic suite to be used by the +Add Proof and +Verify Proof +functions in [[[VC-DATA-INTEGRITY]]]. The algorithm takes an options object +([=map=] |options|) as input and returns a [=data integrity cryptographic suite +instance|cryptosuite instance=] ([=struct=] |cryptosuite|). +

+ +
    +
  1. +Initialize |cryptosuite| to an empty [=struct=]. +
    2. +
  2. +If |options|.|type| does not equal `DataIntegrityProof`, return |cryptosuite|. +
    3. +
  3. +If |options|.|cryptosuite| is `ecdsa-rdfc-2019` then: +
      +
    1. +Set |cryptosuite|.|createProof| to the algorithm in Section +. +
      2. +
    2. +Set |cryptosuite|.|verifyProof| to the algorithm in Section +. +
      3. +
    +
    4. +
  4. +If |options|.|cryptosuite| is `ecdsa-jcs-2019` then: +
      +
    1. +Set |cryptosuite|.|createProof| to the algorithm in Section +. +
      2. +
    2. +Set |cryptosuite|.|verifyProof| to the algorithm in Section +. +
      3. +
    +
    5. +
  5. +If |options|.|cryptosuite| is `ecdsa-sd-2023` then: +
      +
    1. +Set |cryptosuite|.|createProof| to the algorithm in Section +. +
      2. +
    2. +Set |cryptosuite|.|verifyProof| to the algorithm in Section +. +
      3. +
    +
    6. +
  6. +Return |cryptosuite|. +
    7. +
+ +
+

ecdsa-rdfc-2019

@@ -533,45 +596,118 @@

ecdsa-rdfc-2019

-

Add Proof (ecdsa-rdfc-2019)

- -

-To generate a proof, the algorithm in - -Section 4.1: Add Proof in the Data Integrity -[[VC-DATA-INTEGRITY]] specification MUST be executed. -For that algorithm, the cryptographic suite specific - -transformation algorithm is defined in Section -, the - -hashing algorithm is defined in Section , -and the - -proof serialization algorithm is defined in Section -. +

Create Proof (ecdsa-rdfc-2019)

+ +

+The following algorithm specifies how to create a [=data integrity proof=] given +an unsecured data document. Required inputs are an +unsecured data document ([=map=] |unsecuredDocument|), and a set of proof +options ([=map=] |options|). A [=data integrity proof=] ([=map=]), or an error, +is produced as output.

+ +
    +
  1. +Let |proof| be a clone of the proof options, |options|. +
    2. +
  2. +Let |proofConfig| be the result of running the algorithm in +Section with +|options| passed as a parameter. +
    3. +
  3. +Let |transformedData| be the result of running the algorithm in Section with |unsecuredDocument|, +|proofConfig|, and |options| passed as parameters. +
    4. +
  4. +Let |hashData| be the result of running the algorithm in Section + with |transformedData| and |proofConfig| +passed as a parameters. +
    5. +
  5. +Let |proofBytes| be the result of running the algorithm in Section + with |hashData| and +|options| passed as parameters. +
    6. +
  6. +Let |proof|.|proofValue| be a +base58-btc-encoded Multibase value of the |proofBytes|. +
    7. +
  7. +Return |proof| as the [=data integrity proof=]. +
    8. +
+

Verify Proof (ecdsa-rdfc-2019)

-To verify a proof, the algorithm in - -Section 4.2: Verify Proof in the Data Integrity -[[VC-DATA-INTEGRITY]] specification MUST be executed. -For that algorithm, the cryptographic suite specific - -transformation algorithm is defined in Section -, the - -hashing algorithm is defined in Section , -and the - -proof verification algorithm is defined in Section -. +The following algorithm specifies how to verify a [=data integrity proof=] given +an secured data document. Required inputs are an +secured data document ([=map=] |securedDocument|). This algorithm returns +a verification result, which is a [=struct=] whose +[=struct/items=] are:

+
+
verified
+
`true` or `false`
+
verifiedDocument
+
+Null, if [=verification result/verified=] is +`false`; otherwise, an [=unsecured data document=] +
+
+ +
    +
  1. +Let |unsecuredDocument| be a copy of |securedDocument| with +the `proof` value removed. +
    2. +
  2. +Let |proofConfig| be a copy of |securedDocument|.|proof| with `proofValue` +removed. +
    3. +
  3. +Let |proofBytes| be the +Multibase decoded base58-btc +value in |securedDocument|.|proof|.|proofValue|. +
    4. +
  4. +Let |transformedData| be the result of running the algorithm in Section with |unsecuredDocument| and +|proofConfig| passed as parameters. +
    5. +
  5. +Let |hashData| be the result of running the algorithm in Section + with |transformedData| and |proofConfig| +passed as a parameters. +
    6. +
  6. +Let |verified:boolean| be the result of running the algorithm in Section + algorithm on |hashData|, +|proofBytes|, and |proofConfig|. +
    7. +
  7. +If |proof|.|created| does not [=map/exist=], +an error MUST be raised and SHOULD convey an error type of + +MALFORMED_PROOF_ERROR. +
    8. +
  8. +Return a [=verification result=] with [=struct/items=]: +
    +
    [=verified=]
    +
    |verified|
    +
    [=verifiedDocument=]
    +
    +|unsecuredDocument| if |verified| is `true`, otherwise Null
    +
    +
    9. +
+
@@ -804,45 +940,108 @@

ecdsa-jcs-2019

-

Add Proof (ecdsa-jcs-2019)

- -

-To generate a proof, the algorithm in - -Section 4.1: Add Proof of the Data Integrity -[[VC-DATA-INTEGRITY]] specification MUST be executed. -For that algorithm, the cryptographic suite-specific - -transformation algorithm is defined in Section -, the - -hashing algorithm is defined in Section , -and the - -proof serialization algorithm is defined in Section -. +

Create Proof (ecdsa-jcs-2019)

+ + +

+The following algorithm specifies how to create a [=data integrity proof=] given +an unsecured data document. Required inputs are an +unsecured data document ([=map=] |unsecuredDocument|), and a set of proof +options ([=map=] |options|). A [=data integrity proof=] ([=map=]), or an error, +is produced as output.

+ +
    +
  1. +Let |proof| be a clone of the proof options, |options|. +
    2. +
  2. +Let |proofConfig| be the result of running the algorithm in +Section with +|options| passed as a parameter. +
    3. +
  3. +Let |transformedData| be the result of running the algorithm in Section with |unsecuredDocument|, +|proofConfig|, and |options| passed as parameters. +
    4. +
  4. +Let |hashData| be the result of running the algorithm in Section + with |transformedData| and |proofConfig| +passed as a parameters. +
    5. +
  5. +Let |proofBytes| be the result of running the algorithm in Section + with |hashData| and +|options| passed as parameters. +
    6. +
  6. +Let |proof|.|proofValue| be a +base58-btc-encoded Multibase value of the |proofBytes|. +
    7. +
  7. +Return |proof| as the [=data integrity proof=]. +
    8. +

Verify Proof (ecdsa-jcs-2019)

-To verify a proof, the algorithm in - -Section 4.2: Verify Proof of the Data Integrity -[[VC-DATA-INTEGRITY]] specification MUST be executed. -For that algorithm, the cryptographic suite-specific - -transformation algorithm is defined in Section -, the - -hashing algorithm is defined in Section , -and the - -proof verification algorithm is defined in Section -. +The following algorithm specifies how to verify a [=data integrity proof=] given +an secured data document. Required inputs are an +secured data document ([=map=] |securedDocument|). This algorithm returns +a [=verification result=]:

+ +
    +
  1. +Let |unsecuredDocument| be a copy of |securedDocument| with +the `proof` value removed. +
    2. +
  2. +Let |proofConfig| be a copy of |securedDocument|.|proof| with `proofValue` +removed. +
    3. +
  3. +Let |proofBytes| be the +Multibase decoded base58-btc +value in |securedDocument|.|proof|.|proofValue|. +
    4. +
  4. +Let |transformedData| be the result of running the algorithm in Section with |unsecuredDocument| and +|proofConfig| passed as parameters. +
    5. +
  5. +Let |hashData| be the result of running the algorithm in Section + with |transformedData| and |proofConfig| +passed as a parameters. +
    6. +
  6. +Let |verified:boolean| be the result of running the algorithm in Section + algorithm on |hashData|, +|proofBytes|, and |proofConfig|. +
    7. +
  7. +If |proof|.|created| does not [=map/exist=], +an error MUST be raised and SHOULD convey an error type of + +MALFORMED_PROOF_ERROR. +
    8. +
  8. +Return a [=verification result=] with [=struct/items=]: +
    +
    [=verified=]
    +
    |verified|
    +
    [=verifiedDocument=]
    +
    +|unsecuredDocument| if |verified| is `true`, otherwise Null
    +
    +
    9. +
+
@@ -2399,24 +2598,49 @@

ecdsa-sd-2023

-

Add Base Proof (ecdsa-sd-2023)

- -

-To generate a base proof, the algorithm in - -Section 4.1: Add Proof in the Data Integrity -[[VC-DATA-INTEGRITY]] specification MUST be executed. -For that algorithm, the cryptographic suite specific - -transformation algorithm is defined in Section -, the - -hashing algorithm is defined in Section , -and the - -proof serialization algorithm is defined in Section -. +

Create Base Proof (ecdsa-sd-2023)

+ + +

+The following algorithm specifies how to create a [=data integrity proof=] given +an unsecured data document. Required inputs are an +unsecured data document ([=map=] |unsecuredDocument|), and a set of proof +options ([=map=] |options|). A [=data integrity proof=] ([=map=]), or an error, +is produced as output.

+ +
    +
  1. +Let |proof| be a clone of the proof options, |options|. +
    2. +
  2. +Let |proofConfig| be the result of running the algorithm in +Section with +|options| passed as a parameter. +
    3. +
  3. +Let |transformedData| be the result of running the algorithm in Section with |unsecuredDocument|, +|proofConfig|, and |options| passed as parameters. +
    4. +
  4. +Let |hashData| be the result of running the algorithm in Section + with |transformedData| and |proofConfig| +passed as a parameters. +
    5. +
  5. +Let |proofBytes| be the result of running the algorithm in Section + with |hashData| and +|options| passed as parameters. +
    6. +
  6. +Let |proof|.|proofValue| be a +base64-url-encoded Multibase value of the |proofBytes|. +
    7. +
  7. +Return |proof| as the [=data integrity proof=]. +
    8. +
@@ -2700,12 +2924,15 @@

Verify Derived Proof (ecdsa-sd-2023)

proof. This algorithm is called by a verifier of an ECDSA-SD-protected [=verifiable credential=]. The inputs include a JSON-LD document (document), an ECDSA-SD disclosure proof (proof), and any -custom JSON-LD API options, such as a document loader. A single boolean -verification result value is produced as output. +custom JSON-LD API options, such as a document loader. This algorithm returns +a [=verification result=]:

  1. +Let `unsecuredDocument` be a copy of `document` with the `proof` value removed. +
    2. +
  2. Initialize `baseSignature`, `proofHash`, `publicKey`, `signatures`, `nonMandatory`, and `mandatoryHash` to the values associated with their property names in the object returned when calling the algorithm in Section @@ -2728,30 +2955,42 @@

    Verify Derived Proof (ecdsa-sd-2023)

    `mandatoryHash`.
  3. -Initialize `verificationResult` be the result of applying the verification +Initialize `verified` to true. +
    4. +
  4. +Initialize `verificationCheck` be the result of applying the verification algorithm of the Elliptic Curve Digital Signature Algorithm (ECDSA) [FIPS-186-5], with `toVerify` as the data to be verified against the `baseSignature` using -the public key specified by `publicKeyBytes`. If `verificationResult` is -`false`, return `false`. +the public key specified by `publicKeyBytes`. If `verificationCheck` is +`false`, set `verified` to false.
  5. For every entry (`index`, `signature`) in `signatures`, verify every signature for every selectively disclosed (non-mandatory) statement:
    1. -Initialize `verificationResult` to the result of applying the verification +Initialize `verificationCheck` to the result of applying the verification algorithm Elliptic Curve Digital Signature Algorithm (ECDSA) [FIPS-186-5], with the UTF-8 representation of the value at `index` of `nonMandatory` as the data to be verified against `signature` using the public key specified by `publicKeyBytes`.
    2. -If `verificationResult` is `false`, return `false`. +If `verificationCheck` is `false`, set `verified` to false.
  6. -Return `verificationResult` as verification result. +Return a [=verification result=] with [=struct/items=]: +
    +
    [=verified=]
    +
    The value of `verified`
    +
    [=verifiedDocument=]
    +
    +`unsecuredDocument` if `verified` is `true`, otherwise Null +
    +