Skip to content

Commit 4c11510

Browse files
committed
Fix grammar and flow in Verify algorithms.
1 parent a0b9ba9 commit 4c11510

File tree

1 file changed

+47
-51
lines changed

1 file changed

+47
-51
lines changed

index.html

Lines changed: 47 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1826,17 +1826,17 @@ <h2>Algorithms</h2>
18261826
no proof values. An <dfn>input document</dfn> is an [=map=] that has not yet had
18271827
the current proof added to it, but it MAY contain a proof value that was added
18281828
to it by a previous process. A <dfn class="export">secured data document</dfn>
1829-
is a [=map=] that contains one or more proof value, one of which might be the
1830-
current proof(s) being generated to be added to it.
1829+
is a [=map=] that contains one or more proof values.
18311830
</p>
18321831

18331832
<p>
18341833
Implementers MAY implement reasonable defaults and safeguards in addition to the
18351834
algorithms below, to help mitigate developer error, excessive resource
18361835
consumption, newly discovered attack models against which there is a particular
1837-
protection, etc. The algorithms provided below are the minimum requirements for
1838-
an interoperable implementation, and developers are urged to include additional
1839-
measures that could contribute to a safer and more efficient ecosystem.
1836+
protection, and other improvements. The algorithms provided below are the
1837+
minimum requirements for an interoperable implementation, and developers are
1838+
urged to include additional measures that could contribute to a safer and more
1839+
efficient ecosystem.
18401840
</p>
18411841

18421842
<section class="normative">
@@ -1951,11 +1951,11 @@ <h3>Add Proof Set/Chain</h3>
19511951
<p>
19521952
The following algorithm specifies how to incrementally add a proof to a proof
19531953
set or proof chain starting with a secured document containing either a proof or
1954-
proof set/chain. Required inputs are a [=secured data document=]
1955-
([=map=] |securedDocument|), a [=cryptographic suite=]
1956-
(|suite:cryptosuite instance|), and a set of options ([=map=] |options|). Output
1957-
is a new [=secured data document=] ([=map=]). Whenever this algorithm
1958-
encodes strings, it MUST use UTF-8 encoding.
1954+
proof set/chain. Required inputs are a [=secured data document=] ([=map=]
1955+
|securedDocument|), a [=cryptographic suite=] ([=cryptosuite
1956+
instance=] |suite|), and a set of options ([=map=] |options|). Output is a new
1957+
[=secured data document=] ([=map=]). Whenever this algorithm encodes strings, it
1958+
MUST use UTF-8 encoding.
19591959
</p>
19601960

19611961
<ol class="algorithm">
@@ -1990,15 +1990,13 @@ <h3>Add Proof Set/Chain</h3>
19901990
</li>
19911991
<li>
19921992
Set |inputDocument|.|proof| to |matchingProofs|.
1993-
<div class="note">
1993+
<div class="note" title="This step protects the document and existing proofs">
19941994
<p>
1995-
This step adds references to the graph names, as well as adding a copy
1996-
of <em>all</em> the claims contained in the proof graphs.
1997-
</p>
1998-
<p>
1999-
The step is critical, as it <q>binds</q> any matching proofs to the document prior
2000-
to applying the current signature. The |proof| value for the document will be updated
2001-
in a later step of this algorithm.
1995+
This step adds references to the [=named graphs=], as well as adding a copy of
1996+
<em>all</em> the claims contained in the [=proof graphs=]. The step is critical,
1997+
as it <q>binds</q> any matching proofs to the document prior to applying the
1998+
current proof. The |proof| value for the document will be updated in a later
1999+
step of this algorithm.
20022000
</p>
20032001
</div>
20042002
</li>
@@ -2068,26 +2066,26 @@ <h3>Verify Proof</h3>
20682066
<a data-cite="INFRA#nulls">Null</a>, if [=verification result/verified=] is
20692067
`false`; otherwise, an [=input document=]
20702068
</dd>
2071-
<dt><dfn data-dfn-for="verification result">media type</dfn></dt>
2069+
<dt><dfn data-dfn-for="verification result">mediaType</dfn></dt>
20722070
<dd>
20732071
<a data-cite="INFRA#nulls">Null</a>, if [=verification result/verified=] is
20742072
`false`; otherwise, a [=MIME type|media type=], which MAY include [=MIME
20752073
type/parameters=]
20762074
</dd>
20772075
<dt><dfn data-dfn-for="verification result" class="lint-ignore">warnings</dfn></dt>
20782076
<dd>
2079-
a [=list=] of
2080-
<dfn data-cite="VC-DATA-MODEL-2.0#dfn-problemdetails">ProblemDetails</dfn>,
2081-
which defaults to an empty [=list=]</dd>
2077+
a [=list=] of [=ProblemDetails=], which defaults to an empty [=list=]
2078+
</dd>
20822079
<dt><dfn data-dfn-for="verification result">errors</dfn></dt>
20832080
<dd>
2084-
a [=list=] of [=ProblemDetails=], which defaults to an empty [=list=]</dd>
2081+
a [=list=] of [=ProblemDetails=], which defaults to an empty [=list=]
2082+
</dd>
20852083
</dl>
20862084

20872085
<p>
20882086
When a step says "an error MUST be raised", it means that a [=verification
2089-
result=] MUST be returned with a [=verification result/verified=] of `false`
2090-
and a non-empty [=verification result/errors=] list.
2087+
result=] MUST be returned with a [=verification result/verified=] value of
2088+
`false` and a non-empty [=verification result/errors=] list.
20912089
</p>
20922090

20932091
<ol class="algorithm">
@@ -2141,7 +2139,7 @@ <h3>Verify Proof</h3>
21412139
<dd>|cryptosuiteVerificationResult|.|verified|</dd>
21422140
<dt>[=verifiedDocument=]</dt>
21432141
<dd>|cryptosuiteVerificationResult|.|verifiedDocument|</dd>
2144-
<dt>[=media type=]</dt>
2142+
<dt>[=mediaType=]</dt>
21452143
<dd>|mediaType|</dd>
21462144
</dl>
21472145
</li>
@@ -2151,21 +2149,18 @@ <h3>Verify Proof</h3>
21512149
<section>
21522150
<h3>Verify Proof Sets and Chains</h3>
21532151
<p>
2154-
In a proof set or proof chain, a [=secured data document=] has a
2155-
`proof` attribute which contains a list of proofs
2156-
(|allProofs|).
2157-
The following algorithm provides one method of checking the authenticity and
2158-
integrity of a [=secured data document=], achieved by verifying every
2159-
proof in |allProofs|. Other approaches are possible, particularly if
2160-
it is only desired to verify a subset of the proofs contained in
2161-
|allProofs|. If another approach is taken to verify only a subset of the
2162-
proofs, then it is important to note that any proof in that subset with a
2163-
`previousProof` can only be considered verified if the proofs it
2164-
references are also considered verified.
2165-
</p>
2166-
<p>
2167-
Required input is a
2168-
[=secured data document=] (|securedDocument|). A list of
2152+
In a [=proof set=] or [=proof chain=], a [=secured data document=] has a `proof`
2153+
attribute which contains a list of [=proofs=] (|allProofs|). The following
2154+
algorithm provides one method of checking the authenticity and integrity of a
2155+
[=secured data document=], achieved by verifying every proof in |allProofs|.
2156+
Other approaches are possible, particularly if it is only desired to verify a
2157+
subset of the proofs contained in |allProofs|. If another approach is taken to
2158+
verify only a subset of the proofs, then it is important to note that any proof
2159+
in that subset with a `previousProof` can only be considered verified if the
2160+
proofs it references are also considered verified.
2161+
</p>
2162+
<p>
2163+
Required input is a [=secured data document=] (|securedDocument|). A list of
21692164
[=verification results=] corresponding to each proof in |allProofs| is
21702165
generated, and a single combined [=verification result=] is returned as output.
21712166
Implementations MAY return any of the other [=verification result=]s and/or any
@@ -2185,13 +2180,13 @@ <h3>Verify Proof Sets and Chains</h3>
21852180
Let |matchingProofs| be an empty list.
21862181
</li>
21872182
<li>
2188-
If |proof| contains a `previousProof` attribute and that attribute is a string,
2189-
add the element from |allProofs| with an `id` attribute matching `previousProof`
2190-
to `matchingProofs`. If a proof with `id` does not exist in |allProofs|, an
2191-
error MUST be raised and SHOULD convey an error type of
2183+
If |proof| contains a `previousProof` attribute and that attribute is a
2184+
[=string=], add the element from |allProofs| with an `id` attribute matching
2185+
`previousProof` to `matchingProofs`. If a proof with `id` does not exist in
2186+
|allProofs|, an error MUST be raised and SHOULD convey an error type of
21922187
<a href="#PROOF_VERIFICATION_ERROR">PROOF_VERIFICATION_ERROR</a>. If the
2193-
`previousProof` attribute is an array, add each element from |allProofs| with an
2194-
`id` attribute that matches an element of that array. If any element of
2188+
`previousProof` attribute is a [=list=], add each element from |allProofs| with an
2189+
`id` attribute that matches an element of that [=list=]. If any element of
21952190
`previousProof` [=list=] has an `id` attribute that does not match the `id`
21962191
attribute of any element of |allProofs|, an error MUST be raised and SHOULD
21972192
convey an error type of
@@ -2201,9 +2196,9 @@ <h3>Verify Proof Sets and Chains</h3>
22012196
Let |inputDocument| be a copy of |securedDocument| with the proof value
22022197
removed and then set |inputDocument|.|proof| to |matchingProofs|.
22032198

2204-
<p class="note">
2205-
See the note in <a href="#add-proof-set-chain"></a> to learn what
2206-
claims this step entails.
2199+
<p class="note" title="Secure document and previous proofs">
2200+
See the note in Step 6 of Section [[[#add-proof-set-chain]]] to learn about
2201+
what document properties and previous proofs this step secures.
22072202
</p>
22082203
</li>
22092204
<li>
@@ -2339,7 +2334,8 @@ <h3>Processing Errors</h3>
23392334

23402335
<p>
23412336
When exposing these errors through an HTTP interface, implementers SHOULD use
2342-
[[RFC9457]] to encode the error data structure. If [[RFC9457]] is used:
2337+
[[RFC9457]] to encode the error data structure as a <dfn>ProblemDetails</dfn>
2338+
[=map=]. If [[RFC9457]] is used:
23432339
</p>
23442340

23452341
<ul>

0 commit comments

Comments
 (0)