Skip to content
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

Jump to bottom

Add cryptographic suite instantiation algorithm. #57

Merged
merged 10 commits into from
Feb 25, 2024
Merged

Add cryptographic suite instantiation algorithm. #57

Changes from 4 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
f61e06b
Add suite selection algorithm.
msporny Feb 11, 2024
b7da944
Align Create Proof and Verify Proof for ecdsa-rdfc-2019 with DI.
msporny Feb 16, 2024
69b6b45
Update Instantiate Cryptosuite algorithm.
msporny Feb 17, 2024
94fd162
Update link to "data integrity cryptographic suite instance".
msporny Feb 25, 2024
58cb3f2
Return an empty cryptosuite for invalid identifiers.
msporny Feb 25, 2024
68e36b2
Use `proofConfig` instead of `proof`.
msporny Feb 25, 2024
e399b31
Align ecdsa-jcs-2019 create proof algorithm to new interface.
msporny Feb 25, 2024
4d0bb8e
Align ecdsa-sd-2023 create proof algorithm to new interface.
msporny Feb 25, 2024
a994106
Align ecdsa-jcs-2019 verify proof algorithm to new interface.
msporny Feb 25, 2024
3ad673c
Align ecdsa-sd-2023 verify proof algorithm to new interface.
msporny Feb 25, 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
240 changes: 174 additions & 66 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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: [{
Expand Down Expand Up @@ -521,6 +519,72 @@ <h2>Algorithms</h2>
by default, and abort processing upon detection.
</p>

<section>
<h3>Instantiate Cryptosuite</h3>

<p>
This algorithm is used to configure a cryptographic suite to be used by the
<a data-cite="VC-DATA-INTEGRITY#add-proof">Add Proof</a> and
<a href="VC-DATA-INTEGRITY#verify-proof">Verify Proof</a>
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|).
</p>

<ol class="algorithm">
<li>
Initialize |cryptosuite| to an empty [=struct=].
</li>
<li>
If |options|.|type| does not equal `DataIntegrityProof`, an
`INVALID_PROOF_CONFIGURATION` error MUST be raised.
</li>
<li>
If |options|.|cryptosuite| is `ecdsa-rdfc-2019` then:
<ol class="algorithm">
<li>
Set |cryptosuite|.|createProof| to the algorithm in Section
<a href="#create-proof-ecdsa-rdfc-2019"></a>.
</li>
<li>
Set |cryptosuite|.|verifyProof| to the algorithm in Section
<a href="#proof-verification-ecdsa-rdfc-2019"></a>.
</li>
</ol>
</li>
<li>
If |options|.|cryptosuite| is `ecdsa-jcs-2019` then:
<ol class="algorithm">
<li>
Set |cryptosuite|.|createProof| to the algorithm in Section
<a href="#create-proof-ecdsa-jcs-2019"></a>.
</li>
<li>
Set |cryptosuite|.|verifyProof| to the algorithm in Section
<a href="#proof-verification-ecdsa-jcs-2019"></a>.
</li>
</ol>
</li>
<li>
If |options|.|cryptosuite| is `ecdsa-sd-2023` then:
<ol class="algorithm">
<li>
Set |cryptosuite|.|createProof| to the algorithm in Section
<a href="#create-base-proof-ecdsa-sd-2023"></a>.
</li>
<li>
Set |cryptosuite|.|verifyProof| to the algorithm in Section
<a href="#verify-derived-proof-ecdsa-sd-2023"></a>.
</li>
</ol>
</li>
<li>
Return |cryptosuite|.
Copy link
Member

Choose a reason for hiding this comment

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

Note that https://w3c.github.io/vc-data-integrity/#dfn-suite-selection-algorithm expects this to return "failure" for values it can't handle, rather than an empty suite.

Copy link
Member Author

Choose a reason for hiding this comment

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

The algorithm was updated to never return a failure. It either returns an empty cryptosuite instance (which doesn't have the functions set) or one that does. The error handling bits were removed to be out of scope in VC-DATA-INTEGRITY as well. This was largely done to simplify the algorithms. The algorithms in VC-DATA-INTEGRITY presume that they're handed a valid cryptosuite instance... if they're not, errors will be thrown. It's up to the implementations to decide how they handle empty cryptosuite instances.

IOW, this feels like implementation-specific stuff that we shouldn't have to spell out to implementers. Unless I'm missing something, I don't think we lose much if we don't return an error here. If you feel strongly about this, we can rework it so it generates an error.

Copy link
Member

Choose a reason for hiding this comment

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

I don't think you'll cause implementation divergence with this or make it significantly more difficult to read the spec, so it doesn't matter a lot, but pedantically, https://w3c.github.io/vc-data-integrity/#dfn-data-integrity-cryptographic-suite-instance doesn't admit the possibility that it could be empty. Both items are just "an algorithm that ..." rather than "null or an algorithm that ...". I think that's the right choice there, so to make the types work here, it'd be better to have this algorithm return a sentinel value instead of an "empty" cryptosuite. I used "failure", matching places like https://url.spec.whatwg.org/#concept-url-parser, but "null" would also work perfectly well. But again, this isn't super important.

</li>
</ol>

</section>

<section>
<h3>ecdsa-rdfc-2019</h3>

Expand All @@ -533,45 +597,119 @@ <h3>ecdsa-rdfc-2019</h3>
</p>

<section>
<h4>Add Proof (ecdsa-rdfc-2019)</h4>
<h4>Create Proof (ecdsa-rdfc-2019)</h4>

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

<ol class="algorithm">
<li>
Let |proof| be an empty [=map=].
msporny marked this conversation as resolved.
Show resolved Hide resolved
</li>
<li>
Let |proof| be the result of running the algorithm in
msporny marked this conversation as resolved.
Show resolved Hide resolved
Section <a href="#proof-configuration-ecdsa-rdfc-2019"></a> with
|options| passed as a parameter.
</li>
<li>
Let |transformedData| be the result of running the algorithm in Section <a
href="#transformation-ecdsa-rdfc-2019"></a> with |unsecuredDocument| and
|options| passed as parameters.
msporny marked this conversation as resolved.
Show resolved Hide resolved
</li>
<li>
Let |hashData| be the result of running the algorithm in Section
<a href="#hashing-ecdsa-rdfc-2019"></a> with |transformedData| and |proofConfig|
passed as a parameters.
</li>
<li>
Let |proofBytes| be the result of running the algorithm in Section
<a href="#proof-serialization-ecdsa-rdfc-2019"></a> with |hashData| and
|options| passed as parameters.
</li>
<li>
Let |proof|.|proofValue| be a <a data-cite="VC-DATA-INTEGRITY#multibase-0">
base58-btc-encoded Multibase value</a> of the |proofBytes|.
</li>
<li>
Return |proof| as the [=data integrity proof=].
</li>
</ol>

<p>
To generate a proof, the algorithm in
<a href="https://www.w3.org/TR/vc-data-integrity/#add-proof">
Section 4.1: Add Proof</a> in the Data Integrity
[[VC-DATA-INTEGRITY]] specification MUST be executed.
For that algorithm, the cryptographic suite specific
<a href="https://www.w3.org/TR/vc-data-integrity/#dfn-transformation-algorithm">
transformation algorithm</a> is defined in Section
<a href="#transformation-ecdsa-rdfc-2019"></a>, the
<a href="https://www.w3.org/TR/vc-data-integrity/#dfn-hashing-algorithm">
hashing algorithm</a> is defined in Section <a href="#hashing-ecdsa-rdfc-2019"></a>,
and the
<a href="https://www.w3.org/TR/vc-data-integrity/#dfn-proof-serialization-algorithm">
proof serialization algorithm</a> is defined in Section
<a href="#proof-serialization-ecdsa-rdfc-2019"></a>.
</p>
</section>

<section>
<h4>Verify Proof (ecdsa-rdfc-2019)</h4>


<p>
To verify a proof, the algorithm in
<a href="https://www.w3.org/TR/vc-data-integrity/#verify-proof">
Section 4.2: Verify Proof</a> in the Data Integrity
[[VC-DATA-INTEGRITY]] specification MUST be executed.
For that algorithm, the cryptographic suite specific
<a href="https://www.w3.org/TR/vc-data-integrity/#dfn-transformation-algorithm">
transformation algorithm</a> is defined in Section
<a href="#transformation-ecdsa-rdfc-2019"></a>, the
<a href="https://www.w3.org/TR/vc-data-integrity/#dfn-hashing-algorithm">
hashing algorithm</a> is defined in Section <a href="#hashing-ecdsa-rdfc-2019"></a>,
and the
<a href="https://www.w3.org/TR/vc-data-integrity/#dfn-proof-serialization-algorithm">
proof verification algorithm</a> is defined in Section
<a href="#proof-verification-ecdsa-rdfc-2019"></a>.
The following algorithm specifies how to verify a [=data integrity proof=] given
an <a>secured data document</a>. Required inputs are an
<a>secured data document</a> ([=map=] |securedDocument|). This algorithm returns
a <dfn>verification result</dfn>, which is a [=struct=] whose
[=struct/items=] are:
</p>
<dl>
<dt><dfn data-dfn-for="verification result">verified</dfn></dt>
<dd>`true` or `false`</dd>
<dt><dfn data-dfn-for="verification result">verifiedDocument</dfn></dt>
<dd>
<a data-cite="INFRA#nulls">Null</a>, if [=verification result/verified=] is
`false`; otherwise, an [=unsecured data document=]
</dd>
</dl>

<ol class="algorithm">
<li>
Let |unsecuredDocument| be a copy of |securedDocument| with
the `proof` value removed.
</li>
<li>
Let |proofConfig| be a copy of |securedDocument|.|proof| with `proofValue`
removed.
</li>
<li>
Let |proofBytes| be the
<a data-cite="VC-DATA-INTEGRITY#multibase-0">Multibase decoded base58-btc
value</a> in |securedDocument|.|proof|.|proofValue|.
</li>
<li>
Let |transformedData| be the result of running the algorithm in Section <a
href="#transformation-ecdsa-rdfc-2019"></a> with |unsecuredDocument| and
|proofConfig| passed as parameters.
</li>
<li>
Let |hashData| be the result of running the algorithm in Section
<a href="#hashing-ecdsa-rdfc-2019"></a> with |transformedData| and |proofConfig|
passed as a parameters.
</li>
<li>
Let |verified:boolean| be the result of running the algorithm in Section
<a href="#proof-verification-ecdsa-rdfc-2019"></a> algorithm on |hashData|,
|proofBytes|, and |proofConfig|.
</li>
<li>
If |proof|.|created| does not [=map/exist=],
an error MUST be raised and SHOULD convey an error type of
<a data-cite="VC-DATA-INTEGRITY#MALFORMED_PROOF_ERROR">
MALFORMED_PROOF_ERROR</a>.
</li>
<li>
Return a [=verification result=] with [=struct/items=]:
<dl data-link-for="verification result">
<dt>[=verified=]</dt>
<dd>|verified|</dd>
<dt>[=verifiedDocument=]</dt>
<dd>
|unsecuredDocument| if |verified| is `true`, otherwise <a data-cite="INFRA#nulls">Null</a></dd>
</dl>
</li>
</ol>

</section>

<section>
Expand Down Expand Up @@ -804,23 +942,13 @@ <h3>ecdsa-jcs-2019</h3>
</p>

<section>
<h4>Add Proof (ecdsa-jcs-2019)</h4>
<h4>Create Proof (ecdsa-jcs-2019)</h4>

<p>
To generate a proof, the algorithm in
<a href="https://www.w3.org/TR/vc-data-integrity/#add-proof">
Section 4.1: Add Proof</a> of the Data Integrity
[[VC-DATA-INTEGRITY]] specification MUST be executed.
For that algorithm, the cryptographic suite-specific
<a href="https://www.w3.org/TR/vc-data-integrity/#dfn-transformation-algorithm">
transformation algorithm</a> is defined in Section
<a href="#transformation-ecdsa-jcs-2019"></a>, the
<a href="https://www.w3.org/TR/vc-data-integrity/#dfn-hashing-algorithm">
hashing algorithm</a> is defined in Section <a href="#hashing-ecdsa-jcs-2019"></a>,
and the
<a href="https://www.w3.org/TR/vc-data-integrity/#dfn-proof-serialization-algorithm">
proof serialization algorithm</a> is defined in Section
<a href="#proof-serialization-ecdsa-jcs-2019"></a>.
</p>
</section>

Expand All @@ -832,16 +960,6 @@ <h4>Verify Proof (ecdsa-jcs-2019)</h4>
<a href="https://www.w3.org/TR/vc-data-integrity/#verify-proof">
Section 4.2: Verify Proof</a> of the Data Integrity
[[VC-DATA-INTEGRITY]] specification MUST be executed.
For that algorithm, the cryptographic suite-specific
<a href="https://www.w3.org/TR/vc-data-integrity/#dfn-transformation-algorithm">
transformation algorithm</a> is defined in Section
<a href="#transformation-ecdsa-jcs-2019"></a>, the
<a href="https://www.w3.org/TR/vc-data-integrity/#dfn-hashing-algorithm">
hashing algorithm</a> is defined in Section <a href="#hashing-ecdsa-jcs-2019"></a>,
and the
<a href="https://www.w3.org/TR/vc-data-integrity/#dfn-proof-serialization-algorithm">
proof verification algorithm</a> is defined in Section
<a href="#proof-verification-ecdsa-jcs-2019"></a>.
</p>
</section>

Expand Down Expand Up @@ -2399,23 +2517,13 @@ <h3>ecdsa-sd-2023</h3>
</p>

<section>
<h4>Add Base Proof (ecdsa-sd-2023)</h4>
<h4>Create Base Proof (ecdsa-sd-2023)</h4>

<p>
To generate a base proof, the algorithm in
<a href="https://www.w3.org/TR/vc-data-integrity/#add-proof">
Section 4.1: Add Proof</a> in the Data Integrity
[[VC-DATA-INTEGRITY]] specification MUST be executed.
For that algorithm, the cryptographic suite specific
<a href="https://www.w3.org/TR/vc-data-integrity/#dfn-transformation-algorithm">
transformation algorithm</a> is defined in Section
<a href="#base-proof-transformation-ecdsa-sd-2023"></a>, the
<a href="https://www.w3.org/TR/vc-data-integrity/#dfn-hashing-algorithm">
hashing algorithm</a> is defined in Section <a href="#base-proof-hashing-ecdsa-sd-2023"></a>,
and the
<a href="https://www.w3.org/TR/vc-data-integrity/#dfn-proof-serialization-algorithm">
proof serialization algorithm</a> is defined in Section
<a href="#base-proof-serialization-ecdsa-sd-2023"></a>.
</p>
</section>

Expand Down
Loading