Clarify how issuer validation occurs. #1393

msporny · 2023-12-17T22:28:01Z

This PR is an attempt to address issue #1386 by clarifying how issuer validation could occur. It establishes an interface between the VCDM and securing specifications for the securing mechanism verification algorithms. It also adds more detail to the issuer validation section in the specification.

NOTE: The algorithms haven't been updated to use the new interface (that will be done in a separate PR). What's important in this PR is that the controller and controller document is being returned by the securing mechanism verification algorithm such that a check between the issuer property and the controller is possible.

/cc @jyasskin (this PR starts to define the interface between the Securing Mechanisms and the VCDM)

Preview | Diff

msporny · 2023-12-18T02:08:50Z

index.html

-          <li>
-MUST document normative algorithms that provide content integrity protection
-for <a>conforming documents</a>. The algorithms MAY be general in nature and
-MAY be used to secure data other than <a>conforming documents</a>.
-          </li>
-          <li>
-MUST provide a verification mechanism that returns only the information in the
-<a>conforming document</a> that has been secured. It MAY provide an
-additional mechanism to receive other information that might be helpful
-during validation or for debugging purposes. The concrete interface that is
-expected to be provided is detailed in the
-<a href="#verify-securing-mechanism">securing mechanism verification
-algorithm</a> section.
-          </li>
-          <li>
-MUST document post-processing considerations for data returned from verification
-processes. This includes, but is not limited to, what information can and cannot
-be used for decision making, for what period of time after verification, when
-additional information is required, and when care is necessary even when the
-returned data was properly secured.
-          </li>
-          <li>
-SHOULD provide integrity protection for any information referenced by a URL that
-is critical to validation. Mechanisms that can achieve this protection are
-discussed in Section <a href="#integrity-of-related-resources"></a> and Section


The text above hasn't been deleted, but has instead been rewritten below in non-list form.

dlongley · 2023-12-18T03:14:48Z

index.html

+that might be helpful during validation or for debugging purposes. A securing
+mechanism's verification algorithm MUST provide an interface that
+receives an sequence of bytes ([=byte sequence=] |inputBytes|) and a media type
+([=string=] |inputMediaType|) as inputs and returns a verification result with


I think it must be also possible for securing mechanisms to be valid if they accept a JSON document / parsed JSON document (Map/dictionary?) instead of bytes and an input media type. Many implementations will be written that way for embedded securing mechanisms (and already are), based on common software pipeline practices that will have JSON already being parsed into a document / object before it hits this API.

We should allow for either of these approaches to be used, especially if we are requiring these algorithms to be normative in the securing mechanism specifications.

Fixed in 02c3744.

selfissued · 2023-12-18T23:54:40Z

index.html

+Securing mechanism specifications MUST provide a verification mechanism that
+returns only the information in the <a>conforming document</a> that has been
+secured. It MAY provide an additional mechanism to receive other information


How does this sentence apply when Data Integrity is used? Does it mean that the "proof" member must not be returned in the secured information? That would be my interpretation but this could be clearer.

All current Data Integrity specifications secure all the information in the proof value. There is no such thing as "unprotected" in the Data Integrity cryptosuites that exist today.

That said, we defer what to do to the securing mechanism specifications. It is their remit wrt. what is returned. For example, vc-jose-cose might choose to strip out proof values that were not verified during the securing process (but by doing that, it'll make it impossible for upstream processors to verify those proofs). So, there will need to be work done in vc-jose-cose to determine what to do there.

For Data Integrity, I expect all the current cryptosuites we have to return proof in the returned data because all information in the proof values ARE protected and verified as a part of the securing mechanism verification process.

In DI, all verified proofs are secured -- so DI securing mechanisms can return all proofs there were verified using the verifier's accepted cryptosuites from the base verification algorithm.

The plain meaning of the text above implies that proof is used to secure the secured data and is not in the secured data. Please be clear that proof, if present, must be removed by this algorithm.

@selfissued fixed in 8c16fec.

selfissued

I will approve this PR after my suggestion about not returning proof as part of the secured data is accepted.

iherman · 2023-12-20T07:36:35Z

The issue was discussed in a meeting on 2023-12-19

no resolutions were taken

View the transcript

2.4. Clarify how issuer validation occurs. (pr vc-data-model#1393)

See github pull request vc-data-model#1393.

Brent Zundel: "Clarify how issuer validation occurs".

Manu Sporny: This PR is an attempt at addressing Oliver's concern where Oliver is saying that the spec needs to be clear about how you verify that a VC came from a particular issuer.
… Some people in the group would argue that's validation.
… And that we don't do that and don't normatively specify that. So what I tried to do is ... we're now specifying an interface between the securing mechanisms and the VCDM verify algorithm -- and it now returns the controller and controller document. That gives you info you could use to check against the issuer.
… However, that's not the only way to do validation, you could also have a trust list with some keys and you could just trust that -- including the statements in the VC, including the issuer field.
… In that case the issuer isn't directly tied to the verification method and controller, etc. -- so I tried to address Oliver's concern to ensure the information is available if the issuer validation works one way.
… I added some non-normative language as well to help address Oliver's concerns. I don't know if these changes together address his concerns.

Brent Zundel: Any comments on this PR?
… If all of these, if it's possible to find consensus, if the language needs tweaks or not, that is our goal. If you have comments to make please do or say the PR is great, etc. Let us know what we need to change for you if you need it.

TallTed · 2023-12-20T18:19:59Z

index.html

+Relevant metadata that is related to the <code>issuer</code> <a>property</a>
+is available to the <a>verifier</a> through the
+<a href="#verify-securing-mechanism">securing mechanism verification
+algorithm</a> as defined in Section <a href="#securing-mechanisms"></a>. This
+information includes the controller, which is typically the `issuer`, of the
+verification method used by the securing mechanism to secure each <a>verifiable
+credential</a>. When verifying a <a>verifiable presentation</a>, the controller
+of the verification method is typically the `holder`.


I hope this edit makes this (single) paragraph somewhat clearer.

I wonder whether the first sentence of this paragraph should discuss metadata related to the `holder` property in addition to metadata related to the `issuer` property.

It might be better to cover verifiable credentials (and issuers) in one paragraph, and verifiable presentations (and holders) in another.

Suggested change

Relevant metadata that is related to the <code>issuer</code> <a>property</a>

is available to the <a>verifier</a> through the

<a href="#verify-securing-mechanism">securing mechanism verification

algorithm</a> as defined in Section <a href="#securing-mechanisms"></a>. This

information includes the controller, which is typically the `issuer`, of the

verification method used by the securing mechanism to secure each <a>verifiable

credential</a>. When verifying a <a>verifiable presentation</a>, the controller

of the verification method is typically the `holder`.

Metadata related to the `issuer` <a>property</a>

is available to the <a>verifier</a> through the

<a href="#verify-securing-mechanism">verification algorithm of the securing

mechanism</a> as defined in Section <a href="#securing-mechanisms"></a>.

This metadata includes identification of the controller of the verification

method used by the securing mechanism to secure each <a>verifiable credential</a>

or <a>verifiable presentation</a>, of which the controller is typically the

respective `issuer` or `holder`.

Applied in af27128.

awoie

I assume the securing mechanism verifies the returned controller is the controller of the securing mechanism?

index.html

msporny · 2023-12-21T18:36:24Z

@awoie, @selfissued, and @TallTed, I have applied each of your requested changes, requesting re-review from each of you.

index.html

Co-authored-by: Oliver Terbu <43441584+awoie@users.noreply.github.com>

Co-authored-by: Dave Longley <dlongley@digitalbazaar.com>

msporny · 2023-12-26T16:18:46Z

Normative, multiple reviews, changes requested and made, no objections, merging.

msporny requested a review from dlongley December 17, 2023 22:28

msporny changed the base branch from main to msporny-safe-processing December 18, 2023 01:09

msporny force-pushed the msporny-issuer-validation branch from 42d9db2 to 68f3fa2 Compare December 18, 2023 01:44

msporny marked this pull request as ready for review December 18, 2023 02:03

msporny requested review from iherman, selfissued and decentralgabe as code owners December 18, 2023 02:03

msporny requested review from brentzundel, awoie and TallTed December 18, 2023 02:07

msporny commented Dec 18, 2023

View reviewed changes

msporny mentioned this pull request Dec 18, 2023

Specify that it is important to validate the issuer value #1386

Closed

msporny added the before-CR label Dec 18, 2023

msporny mentioned this pull request Dec 18, 2023

Rewrite verification algorithm in a way that does not cause layer violations #1377

Closed

dlongley reviewed Dec 18, 2023

View reviewed changes

msporny force-pushed the msporny-issuer-validation branch from 719c826 to 6d6dd20 Compare December 18, 2023 16:55

selfissued reviewed Dec 18, 2023

View reviewed changes

msporny mentioned this pull request Dec 19, 2023

Update references to controller document #1396

Merged

selfissued requested changes Dec 20, 2023

View reviewed changes

TallTed reviewed Dec 20, 2023

View reviewed changes

selfissued mentioned this pull request Dec 20, 2023

Verifying a VC should return the same credential regardless of the verification method #1399

Closed

awoie suggested changes Dec 21, 2023

View reviewed changes

index.html Outdated Show resolved Hide resolved

msporny requested review from selfissued, awoie and TallTed December 21, 2023 18:36

dlongley approved these changes Dec 22, 2023

View reviewed changes

index.html Outdated Show resolved Hide resolved

msporny mentioned this pull request Dec 22, 2023

Correct layering violations related to the proof property #1397

Merged

msporny force-pushed the msporny-safe-processing branch from 4668f2d to 9561353 Compare December 26, 2023 15:55

msporny force-pushed the msporny-issuer-validation branch from 1c3a93c to d9b3915 Compare December 26, 2023 16:05

msporny changed the base branch from msporny-safe-processing to main December 26, 2023 16:06

msporny added 2 commits December 26, 2023 11:06

Refine section on Issuer Validation to include controllers.

edc3760

Add required interface for securing verification algorithms.

79a2502

msporny force-pushed the msporny-issuer-validation branch from d9b3915 to 57ce60b Compare December 26, 2023 16:11

msporny and others added 8 commits December 26, 2023 11:16

Rework Securing Mechanisms section to include verification result.

dc34d00

Remove redefinition of securing mechanism interface.

e6cfe10

Specify where verification interface is defined.

a68135c

Clarify that returned controller information is verified.

5caf584

Co-authored-by: Oliver Terbu <43441584+awoie@users.noreply.github.com>

Clarify related metadata section in issuer validation section.

b56f2c6

Note that securing metadata must not be returned by default.

9522d30

Add ability to pass in inputBytes or inputDocument.

512ea3a

Clarify that verification data usage text is an example.

a59c20b

Co-authored-by: Dave Longley <dlongley@digitalbazaar.com>

msporny force-pushed the msporny-issuer-validation branch from 57ce60b to a59c20b Compare December 26, 2023 16:16

msporny merged commit 8d81752 into main Dec 26, 2023
1 check passed

msporny deleted the msporny-issuer-validation branch December 26, 2023 16:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Clarify how issuer validation occurs. #1393

Clarify how issuer validation occurs. #1393

msporny commented Dec 17, 2023 •

edited by pr-preview bot

Loading

msporny Dec 18, 2023 •

edited

Loading

dlongley Dec 18, 2023

msporny Dec 21, 2023

selfissued Dec 18, 2023

msporny Dec 19, 2023 •

edited

Loading

dlongley Dec 19, 2023

selfissued Dec 20, 2023

msporny Dec 21, 2023

selfissued left a comment

iherman commented Dec 20, 2023

2.4. Clarify how issuer validation occurs. (pr vc-data-model#1393)

TallTed Dec 20, 2023

msporny Dec 21, 2023

awoie left a comment

msporny commented Dec 21, 2023 •

edited

Loading

msporny commented Dec 26, 2023

Clarify how issuer validation occurs. #1393

Clarify how issuer validation occurs. #1393

Conversation

msporny commented Dec 17, 2023 • edited by pr-preview bot Loading

msporny Dec 18, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

msporny Dec 19, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

selfissued left a comment

Choose a reason for hiding this comment

iherman commented Dec 20, 2023

2.4. Clarify how issuer validation occurs. (pr vc-data-model#1393)

Choose a reason for hiding this comment

Choose a reason for hiding this comment

awoie left a comment

Choose a reason for hiding this comment

msporny commented Dec 21, 2023 • edited Loading

msporny commented Dec 26, 2023

msporny commented Dec 17, 2023 •

edited by pr-preview bot

Loading

msporny Dec 18, 2023 •

edited

Loading

msporny Dec 19, 2023 •

edited

Loading

msporny commented Dec 21, 2023 •

edited

Loading