updated introduction to focus on verification of proofs #102

jandrieu · 2024-10-12T17:11:30Z

Just an update to the introduction.

jandrieu · 2024-10-12T17:24:45Z

Addresses issue w3c/vc-data-integrity#75

index.html

msporny

Can we get the first sentence to say that controller documents are about keys and services? The whole paragraph ends up saying the right thing, but it might be better for the first sentence to capture what controller documents are about in a single sentence. Something like:

Controller documents enable an entity to interact with services and verify proofs created by the controller of an identifier.

While that's imperfect and needs more word smithing, I hope it conveys the desired language.

dlongley

This is a great improvement, IMO. Approving with a suggestion and assuming that Manu's suggestions will get incorporated as well.

index.html

David-Chadwick

Subject to minor editorial

David-Chadwick · 2024-10-12T20:26:03Z

index.html

+        services related to the identifier, for example to request
+        additional information for verification. In other words, the
+        controller document contains the necessary information for proving
+        cryptographically that specific actions were taken by the


Suggested change

cryptographically that specific actions were taken by the

cryptographically that either specific actions were taken by,

It is not always that specific actions were taken by the controller. It might be that someone wants to contact the controller of an identifier.

@David-Chadwick Happy to take your changes. They got clobbered by some cleanup I accepted from Manu.

If you could recomment, I'll adopt.

Edit incoming.

David-Chadwick · 2024-10-12T20:30:13Z

index.html

+        additional information for verification. In other words, the
+        controller document contains the necessary information for proving
+        cryptographically that specific actions were taken by the
+        controller of an identifier, including cryptographic material for


Suggested change

controller of an identifier, including cryptographic material for

or for communicating with, the controller of an identifier, including cryptographic material for

Co-authored-by: Manu Sporny <[email protected]>

jandrieu · 2024-10-12T23:42:28Z

Ok. I've made some changes, trying to be responsive to @msporny @dlongley and @David-Chadwick's requests.

jandrieu · 2024-10-12T23:44:29Z

FWIW, I'm also working on edits to the rest of the document (in a separate PR) to align with this introduction, including a replacement definition for the "controller" property. That will let us address w3c/vc-data-integrity#33 in full.

But first, let's make sure there's a version of this language the works for most.

msporny · 2024-10-13T12:37:19Z

FWIW, I'm also working on edits to the rest of the document (in a separate PR) to align with this introduction, including a replacement definition for the "controller" property.

I'll update my PRs to your language once we get consensus. I had to fiddle around w/ the intro because both PING and TAG asked for more elaboration about what this document is about and that ended up touching parts of the introduction, which is still quite slim on details.

index.html

msporny

I really like the updates, thank you. I'll incorporate them into PR #103 which will go in after this PR.

The intro feels a bit repetitive once you get to the final paragraph, don't know if we can tighten that language up, though that might just be a side effect of reading the abstract and then reading the intro back-to-back. It's not a big deal, we can wordsmith further in future PRs or direct edits.

LGTM to merge.

index.html

David-Chadwick · 2024-10-13T16:03:38Z

If you allow me to re-review it, then I can comment on the revised wording. Thanks.

Co-authored-by: Manu Sporny <[email protected]>

jandrieu · 2024-10-13T17:11:02Z

a bit repetitive

Agreed. Part of that was just editorial fatigue.

Open to suggestions and will aim to keep an eye on this as we move forward. I think the edits for w3c/vc-data-integrity#75 might also affect readability, so I'll review again in the PR for that.

index.html

Co-authored-by: Dave Longley <[email protected]>

Co-authored-by: Manu Sporny <[email protected]>

iherman · 2024-10-14T08:14:18Z

I like the new text, but I have two comments here.

The "controller" concept and term plays a central role here. And that is fine, but this specification uses the same terms for two different purposes:
- The controller of the, well, controller document, as defined in §2.1
- The controller of an individual verification method, as defined in §2.2
If we are talking about, essentially, the same concept (which I believe is the case), then the term "controller document" becomes a bit fuzzy to me, and maybe this should be addressed, somehow, in the introduction.
A controller is optional. Which begs the question: what does all this mean if there is no controller? And while one might be tempted to say that then the value of id takes the same role, but id property is not required either or, more exactly, it may be implicit and be a blank node. What is the interpretation, then?

This is actually the case for all occurrences of the proof in the DI spec. They are all controller documents identified by a blank node, and none of the examples in the spec have a "controller" set...

David-Chadwick · 2024-10-14T08:55:34Z

index.html

@@ -329,8 +329,8 @@ <h2>Introduction</h2>
      <p> 
 In other words, the
 controller document contains the necessary information for proving
-cryptographically that specific actions were taken by the
-controller of an identifier, including material for
+that specific actions were taken by the controller of an identifier,


that either specific actions were taken by, or for communicating with, the controller of an identifier

David-Chadwick · 2024-10-14T09:26:18Z

@iherman So how about changing the title of the document to "Cryptographic Information Document (CID)". The first sentence of the Introduction will then read "A Cryptographic Information Document (CID) contains cryptographic material and service endpoints for the purposes of verifying proofs from, and interacting with, the controller of an identifier.

And the abbreviation CID can then be used everywhere that Controller Document is currently used.

iherman · 2024-10-15T15:27:31Z

@iherman So how about changing the title of the document to "Cryptographic Information Document (CID)". The first sentence of the Introduction will then read "A Cryptographic Information Document (CID) contains cryptographic material and service endpoints for the purposes of verifying proofs from, and interacting with, the controller of an identifier.

And the abbreviation CID can then be used everywhere that Controller Document is currently used.

I have created a reference to your comment in w3c/vc-data-integrity#100. That is the issue discussing the (possible) document name change.

However, I do not think the name change would answer my issues in #102 (comment). Or maybe that was not your intention?

msporny · 2024-10-15T16:33:16Z

@iherman wrote:

However, I do not think the name change would answer my issues in w3c/vc-data-integrity#102 (comment). Or maybe that was not your intention?

It wasn't my intention, but since you mentioned it, I'll take a shot at trying to answer your questions below (I do think we'll need some new spec text to address your concerns, but don't quite know what to say yet).

If we are talking about, essentially, the same concept (which I believe is the case), then the term "controller document" becomes a bit fuzzy to me, and maybe this should be addressed, somehow, in the introduction.

Yes, we're essentially talking about the same concept. A controller is capable of demonstrating that they "are in control of" something. That might mean they can demonstrate that they can modify a controller document, or it might mean that they can demonstrate that they can generate a digital signature with a private key that's paired to a public key.

A controller is optional.

controller is optional for controller documents.

https://w3c.github.io/controller-document/#controllers

controller is NOT optional for verification methods.

https://w3c.github.io/controller-document/#verification-methods

... though, I admit that is not clear unless you're reading the spec very closely.

Which begs the question: what does all this mean if there is no controller?

It means that the subject is the controller.

And while one might be tempted to say that then the value of id takes the same role, but id property is not required either or, more exactly, it may be implicit and be a blank node. What is the interpretation, then?

The id property is required for controller documents. :)

https://w3c.github.io/controller-document/#subjects

This is actually the case for all occurrences of the proof in the DI spec. They are all controller documents identified by a blank node, and none of the examples in the spec have a "controller" set...

I don't quite know what you're saying above. Are you saying that proofs are controller documents?

index.html

iherman · 2024-10-16T10:22:52Z

@msporny wrote in #102 (comment)

If we are talking about, essentially, the same concept (which I believe is the case), then the term "controller document" becomes a bit fuzzy to me, and maybe this should be addressed, somehow, in the introduction.

Yes, we're essentially talking about the same concept. A controller is capable of demonstrating that they "are in control of" something. That might mean they can demonstrate that they can modify a controller document, or it might mean that they can demonstrate that they can generate a digital signature with a private key that's paired to a public key.

I must admit I was always bothered that this term is specified twice: once for the controller itself, and once for the verification method. It may be better to define this property formally once (it is, after all, central to the document, so it should deserve attention) and then make it clear that it can be used for those two concepts.

The terminology section, though normative, may not be the right place. I wonder whether a new, top level section on controllers is not necessary (for a document whose title is 'controller document':-)

A controller is optional.

controller is optional for controller documents.

[…]

The id property is required for controller documents. :)

https://w3c.github.io/controller-document/#subjects

Ok, I missed these, so you are right, there is no ambiguity neither for controller documents nor for verification methods. But, as you say, it may have to be made more obvious. After some closer look, we have

Controller Documents and Verification Methods must have an explicit id values (i.e., those resources cannot be blank nodes)
The controller property is a MUST for verification methods and OPTIONAL for controller documents
In the case of a missing controller method, the id takes over as for the role of controller.

However: where does the last statement appear in the spec? I may have missed it, but it should be obvious. If we have a separate section on controllers, this may be elaborated there.

... Are you saying that proofs are controller documents?

I was actually wondering about that. And it indeed would not make sense if this was the case. What is, however, misleading at a cursory read is the fact that both proof and a controller document make use of the verificationMethod property (in https://www.w3.org/TR/vc-data-integrity/#proofs and in https://www.w3.org/TR/controller-document/#controller-documents, respectively). From a pure RDF point of view it is actually fine, because the vocabulary item does not specify a domain (i.e., using the term does not yield a class relationship for proof), but it is still a bit misleading (I had to give myself some time to realize that things are all right). I think it would be worth making this somehow clear to the reader (without using the RDF mumbo jumbo).

Actually, the DI specification does not make it clear that the 'value' of verificationMethod is an instance of a Verification Method in the controller document sense. This may be important, because in all the DI examples the value of a property is a URL which cannot be dereferenced, so reading the DI spec does not help...

B.t.w., see also #128

I'm keeping the duplicate from the abstract, but updating as requested. I agree that duplicating the abstract is a bit painful, but without it, the opening felt out of context. Co-authored-by: Ted Thibodeau Jr <[email protected]>

jandrieu · 2024-10-21T19:25:35Z

@manu wrote:

Which begs the question: what does all this mean if there is no controller?

It means that the subject is the controller.

Unfortunately, this is simply not true.

Clearly we need language to make this explicit.

The controller property is optional. If it is not there, then nothing can be presumed about the controller. The controller might be using the DID in reference to themselves or they might use it for other entities. I can create a DID today that refers to Manu Sporny and I can leave the controller property blank. I can then make a VC that uses that DID as a subject id. None of that transforms the controller of the DID into Manu Sporny, even though he is the subject of the DID I created.

If the controller property is missing, as it will be in did:btc1, it will be because it is not possible to represent the literal controller of the DID in a URL form.

You CANNOT presume that the subject of an identifier is it's controller. This is a huge security disconnect and we need to stop asserting that this is a thing.

dlongley · 2024-10-21T21:02:07Z

@jandrieu,

You CANNOT presume that the subject of an identifier is it's controller.

There's a subtlety here that I'm not quite sure how to capture. While I agree that this presumption can be wrong, it is an anti-pattern for a verifiable data registry to both:

accept proofs as a means of updating controller documents, and
to deny an update that includes a proof that verifies using an appropriate verification method present in the controller document (when no controller is present).

It is possible for this to happen, though. Perhaps the way to say this is to highlight that control over the content of a controller document flows from the "verifiable data registry". It may or may not allow a controller property to be listed in the document. It may or may not allow proofs to be used to perform updates to the controller document (i.e., if not, it may either have immutable controller documents or have some other mechanism for doing updates).

Regardless, there is an expectation, but not a requirement, that a verifiable data registry that does accept proofs for performing updates will accept them from either a listed controller or if they will verify using an appropriate verification method listed in the controller document.

But, the ultimately root of authority for the content of the document is the verifiable data registry -- and for HTTPS-based documents -- the root of authority is the Web origin + DNS infrastructure. The registry is for DID documents is based on the DID method.

In the end, most applications using this spec just want to be able to mark their resources as being under the control of something identified by identifier X, and to know what proofs ought to be accepted as authoritative for that identifier. The answer is: any proofs that verify using a verification method (with the appropriate verification relationship) in the controller document with id=X. That's it. This seems to be what's most important for this spec.

Note that it is only when this gets "meta" that we need to consider the controller property. Consider a "verifiable data registry updater" application. It is still such an application as above, but its resources are controller documents. In this case, these resources are "marked as being under the control of some entity" (somehow). One way to do it is with the controller property. Another way to potentially do it is via the id property (or to fallback to this if controller is not listed). Most importantly, if this application accepts proofs to perform updates, it should accept them from the controller (whatever it may be) of the controller document.

jandrieu · 2024-10-23T15:10:09Z

Regardless, there is an expectation, but not a requirement, that a verifiable data registry that does accept proofs for performing updates will accept them from either a listed controller or if they will verify using an appropriate verification method listed in the controller document.

We don't have this expectation in any of the BTC methods. It simply isn't possible. The fact that you have a different expectation is the root disconnect that has created the confusion about whether or not a subject has any control. They do not.

Frankly, I'm with Ivan, I think the controller term in a controller document is sufficiently different from the meaning of that term in a verification method that they are effectively two different terms.

That doesn't solve the confusion problem about subjects, but it does suggest that however resolve that question, we need to use that new language in the introduction of the controller document and redefinition of the controller property.

filip26 · 2024-10-23T15:33:55Z

I think the controller term in a controller document is sufficiently different from the meaning of that term in a verification method that they are effectively two different terms.

I'm sorry, perhaps I'm missing something, but this confuses me. An interpretation based on a context is possible but it pushes processing complexity to the next level.

Why does the term controller have two different meanings?

If used on a verification method it should point to a controller document, if it's present on a controller document then it also points to a controller document, otherwise, if it's not present, "the control" is handled differently, is not directly specified. Is that correct?

dlongley · 2024-10-23T16:02:40Z

@jandrieu,

We don't have this expectation in any of the BTC methods. It simply isn't possible.

The language I used may be a bit tricky, but what I said was this:

... a verifiable data registry that does accept proofs for performing updates ...

And you've said here that the BTC VDR doesn't allow this -- so that's fine and doesn't contradict what I've said. If that VDR did allow this capability, I believe it would be very awkward and unexpected (but perhaps not non-conformant) to not honor proofs from a listed controller. That is all. So I don't think we're in disagreement.

iherman · 2024-10-23T16:13:23Z

The issue was discussed in a meeting on 2024-10-23

no resolutions were taken

View the transcript

5.1. updated introduction to focus on verification of proofs (pr controller-document#102)

See github pull request controller-document#102.

Brent Zundel: Updated introduction to focus on verification of proofs. Request for changes from Ted. It looks like requests for changes from David Chadwick or some suggestions that have been resolved.
… If folks have comments here -- Ted have your requests been addressed?
… It looks like they've all been incorporated from a quick glance. If that's the case, nothing standing in the way.

Manu Sporny: That would be great with true. I thought I saw some misalignment between Joe and Dave Longley who is scribing -- that just needs to be resolved.
… I don't think we can do the CR without resolving this.

Dave Longley: Taking a quick look, I was being responsive to a point that DavidC was making in comments. I don't think I had changes in the PR that I requested.
… I don't think I'm blocking the PR with my comments.

Ted Thibodeau Jr.: I don't need to speak; my changes appear to have been applied, modulo addressing that the "abstract" is entirely reproduced as the first paragraph of the "introduction", which doesn't seem to bother others as much as me.

Joe Andrieu: Yes, this is just the introduction section, I think Dave and I are discussing something else. I don't think the language addresses the confusion around subject not being the controller.
… Whether or not the controller property is semantically different when it's in a verification method or in the root of the controller document; I don't think we need to resolve that argument to resolve this PR so we can move forward.

Ivan Herman: +1 to joe.

Brent Zundel: No one else is on the queue, but I would recommend to filip that he raise his concerns as a separate issue.
… I can make a comment in the PR recommending that filip open an issue to track his concerns. Ted, if you can do a re-review and make sure your changes have been made to your satisfaction then this PR can be merged.

Ted Thibodeau Jr.: My changes have all been applied, with one exception that I can live with.
… About the abstract and intro being duplicated that doesn't seem to bother anyone else.

msporny · 2024-10-28T00:50:18Z

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

Merged via PR w3c/vc-data-integrity#114 (which fixed the merge conflicts in this PR).

updated introduction to focus on verification of proofs

b08b4a8

jandrieu requested review from msporny and selfissued as code owners October 12, 2024 17:11

msporny requested review from davidlehn, dlongley, iherman, TallTed, David-Chadwick, decentralgabe, KDean-Dolphin, brentzundel and PatStLouis October 12, 2024 19:05

msporny reviewed Oct 12, 2024

View reviewed changes

index.html Outdated Show resolved Hide resolved

msporny approved these changes Oct 12, 2024

View reviewed changes

dlongley approved these changes Oct 12, 2024

View reviewed changes

index.html Outdated Show resolved Hide resolved

selfissued approved these changes Oct 12, 2024

View reviewed changes

David-Chadwick approved these changes Oct 12, 2024

View reviewed changes

msporny mentioned this pull request Oct 12, 2024

PING review for v1.0 #93

Closed

dlongley mentioned this pull request Oct 12, 2024

Add Use Cases and Requirements #103

Merged

jandrieu and others added 2 commits October 12, 2024 14:11

removed leading spaces in index.html

8eeec77

Co-authored-by: Manu Sporny <[email protected]>

incorporated suggestions from @dlongley, @msporny, and @David-Chadwick

16db68e

msporny reviewed Oct 13, 2024

View reviewed changes

index.html Outdated Show resolved Hide resolved

msporny reviewed Oct 13, 2024

View reviewed changes

index.html Outdated Show resolved Hide resolved

msporny approved these changes Oct 13, 2024

View reviewed changes

msporny reviewed Oct 13, 2024

View reviewed changes

index.html Outdated Show resolved Hide resolved

Update index.html

294e5e5

Co-authored-by: Manu Sporny <[email protected]>

dlongley reviewed Oct 13, 2024

View reviewed changes

index.html Outdated Show resolved Hide resolved

dlongley reviewed Oct 13, 2024

View reviewed changes

index.html Outdated Show resolved Hide resolved

dlongley mentioned this pull request Oct 13, 2024

Find a better name for the specification #100

Open

jandrieu and others added 3 commits October 13, 2024 14:02

add key agreement (instead of just encryption)

eff2a43

Co-authored-by: Dave Longley <[email protected]>

Update index.html

2fe726b

Co-authored-by: Dave Longley <[email protected]>

Update index.html

26858f6

Co-authored-by: Manu Sporny <[email protected]>

David-Chadwick reviewed Oct 14, 2024

View reviewed changes

TallTed requested changes Oct 15, 2024

View reviewed changes

index.html Outdated Show resolved Hide resolved

index.html Outdated Show resolved Hide resolved

index.html Outdated Show resolved Hide resolved

index.html Outdated Show resolved Hide resolved

index.html Outdated Show resolved Hide resolved

msporny mentioned this pull request Oct 16, 2024

What is the role of the subject when the controller property is present? #33

Closed

Apply suggestions from @TallTed's code review

a87dc88

I'm keeping the duplicate from the abstract, but updating as requested. I agree that duplicating the abstract is a bit painful, but without it, the opening felt out of context. Co-authored-by: Ted Thibodeau Jr <[email protected]>

msporny mentioned this pull request Oct 28, 2024

Fix merge conflicts in PR #102 #114

Merged

msporny closed this Oct 28, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

updated introduction to focus on verification of proofs #102

updated introduction to focus on verification of proofs #102

jandrieu commented Oct 12, 2024 •

edited by pr-preview bot

Loading

jandrieu commented Oct 12, 2024

msporny left a comment •

edited

Loading

dlongley left a comment •

edited

Loading

David-Chadwick left a comment

David-Chadwick Oct 12, 2024

jandrieu Oct 12, 2024

jandrieu Oct 12, 2024

David-Chadwick Oct 12, 2024

jandrieu commented Oct 12, 2024

jandrieu commented Oct 12, 2024

msporny commented Oct 13, 2024

msporny left a comment

David-Chadwick commented Oct 13, 2024

jandrieu commented Oct 13, 2024

iherman commented Oct 14, 2024

David-Chadwick Oct 14, 2024 •

edited

Loading

David-Chadwick commented Oct 14, 2024 •

edited

Loading

iherman commented Oct 15, 2024

msporny commented Oct 15, 2024

iherman commented Oct 16, 2024

jandrieu commented Oct 21, 2024

dlongley commented Oct 21, 2024 •

edited

Loading

jandrieu commented Oct 23, 2024

filip26 commented Oct 23, 2024

dlongley commented Oct 23, 2024 •

edited

Loading

iherman commented Oct 23, 2024

5.1. updated introduction to focus on verification of proofs (pr controller-document#102)

msporny commented Oct 28, 2024

	cryptographically that specific actions were taken by the
	cryptographically that either specific actions were taken by,

	controller of an identifier, including cryptographic material for
	or for communicating with, the controller of an identifier, including cryptographic material for

updated introduction to focus on verification of proofs #102

updated introduction to focus on verification of proofs #102

Conversation

jandrieu commented Oct 12, 2024 • edited by pr-preview bot Loading

jandrieu commented Oct 12, 2024

msporny left a comment • edited Loading

Choose a reason for hiding this comment

dlongley left a comment • edited Loading

Choose a reason for hiding this comment

David-Chadwick left a comment

Choose a reason for hiding this comment

David-Chadwick Oct 12, 2024

Choose a reason for hiding this comment

jandrieu Oct 12, 2024

Choose a reason for hiding this comment

jandrieu Oct 12, 2024

Choose a reason for hiding this comment

David-Chadwick Oct 12, 2024

Choose a reason for hiding this comment

jandrieu commented Oct 12, 2024

jandrieu commented Oct 12, 2024

msporny commented Oct 13, 2024

msporny left a comment

Choose a reason for hiding this comment

David-Chadwick commented Oct 13, 2024

jandrieu commented Oct 13, 2024

iherman commented Oct 14, 2024

David-Chadwick Oct 14, 2024 • edited Loading

Choose a reason for hiding this comment

David-Chadwick commented Oct 14, 2024 • edited Loading

iherman commented Oct 15, 2024

msporny commented Oct 15, 2024

iherman commented Oct 16, 2024

jandrieu commented Oct 21, 2024

dlongley commented Oct 21, 2024 • edited Loading

jandrieu commented Oct 23, 2024

filip26 commented Oct 23, 2024

dlongley commented Oct 23, 2024 • edited Loading

iherman commented Oct 23, 2024

5.1. updated introduction to focus on verification of proofs (pr controller-document#102)

msporny commented Oct 28, 2024

jandrieu commented Oct 12, 2024 •

edited by pr-preview bot

Loading

msporny left a comment •

edited

Loading

dlongley left a comment •

edited

Loading

David-Chadwick Oct 14, 2024 •

edited

Loading

David-Chadwick commented Oct 14, 2024 •

edited

Loading

dlongley commented Oct 21, 2024 •

edited

Loading

dlongley commented Oct 23, 2024 •

edited

Loading