Definition of Controller Property

[David-Chadwick]

From PR#116 comment by @jandrieu "This is the conflation/confusion with the controller property.

The controller of a controller document an update anything in the document. It doesn't not mean they can generate any particular proofs (but one would expect the controller to update the verification methods such that they can).

The controller of a verification method can create proofs that satisfy the method. It does not mean they can update the verification method.

To me, this makes these two terms fundamentally different, but that's a big normative change."

Comment by @David-Chadwick "I think it would be wise to have different terms for the controller of a controller document and the controller of a verification method. e.g. document controller and proof controller. In this way the reader can see that they are two different roles."

[iherman]

Copying my comment from PR#116 here:

I fundamentally agree with @David-Chadwick that we seem to conflate two different notions into one, which creates more problems than it solves. Ie, technically speaking, I would also prefer to separate them.

But @jandrieu may be right: it is unclear what this means for deployed implementation of DIDs and VCs.

---

Note that we can play an ugly trick. We can modify the JSON-LD @context so that the two uses of thecontroller term map to different URLs. That is what "scoped contexts" are for (see an Example in the JSON-LD spec). In plain text, this means the two usage of the same terms are formally defined as separate URLs and the rest is done behind the scenes doors. This may still create problems for those who rely on the purely RDF version of the terms, though it may be in the minority. But I find it an ugly hack nevertheless.

cc @msporny @dlongley

[TallTed]

Typos in initial comment here.

First paragraph should say (note live link) —

From PR #116

— instead of —

From PR#116

Second paragraph should read as below (emphasis mine), which I've also noted in the original thread —

The controller of a controller document can update anything in the document. It does not mean they can generate any particular proofs (but one would expect the controller to update the verification methods such that they can).

In conversations like this one, that go deep into the weeds, it's vital that such typos be avoided as much as possible, and corrected as quickly as possible when they do arise!

[dlongley]

Copying my comments from #116 (comment) and #116 (comment):

---

I'm definitely -1 to changing the data model in this way. The controller property is applicable to the entity/subject on which it appears (like any other property). We don't need multiple names for this (and shouldn't do it generally, e.g., we don't make a new id or type property for every possible subject on which it could appear, we just reuse them). Furthermore, this change would affect many long-lived implementations and create conflict with DID core.

However, I'm not opposed to more informative text that we believe can be helpful in this area.

---

I should also say that I think that whatever subtlety is trying to be addressed here by potentially splitting the property names would not be well understood by most developers -- and I would expect many of them to just question why the same name wasn't used, as they can mentally ignore the prefix before 'controller' given the context of where the property appears.

@iherman,

This sounds like the controller of a verification method can only generate proofs...

No, you don't know "who" or "what" (or "how many") can generate the proofs, you only know that the verification method "lives" in a controller document (which controls the verification method), and that the controller of that document has authorized such proofs for a specific purpose (through the verification relationship).

...but cannot change the verification method, e.g., change the expiration method or revoke the key. I would not think that is correct, is it?

Control "flows" in one direction and ultimately stems from some root of authority. Any party further up the chain has at least as much power as those down chain.

As stated above, a verification method "lives" (or is canonically/natively expressed) in a controller document and the verification method's controller value MUST match the controller document's identifier (see below for the reference), i.e., it is controlled by its controller document -- and, therefore, whomever controls the controller document always controls it. Whomever controls the verifiable data registry for the controller documents ultimately controls what gets expressed in that controller document (including its controller field, if present).

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

10. If the absolute URL value of verificationMethod.controller does not equal controllerDocumentUrl, an error MUST be raised and SHOULD convey an error type of INVALID_VERIFICATION_METHOD.

All of these control signals are useful to verifiers as they walk the flow of control until they reach something they trust.

[iherman]

As stated above, a verification method "lives" (or is canonically/natively expressed) in a controller document and the verification method's controller value MUST match the controller document's identifier (see below for the reference), i.e., it is controlled by its controller document -- and, therefore, whomever controls the controller document always controls it. Whomever controls the verifiable data registry for the controller documents ultimately controls what gets expressed in that controller document (including its controller field, if present).

Maybe this is where my uneasiness comes from. As I already expressed in w3c/vc-data-integrity#322:

The ControllerDocument concept is not used by the Data Integrity specification, only the VerificationMethod (by the way of the verificationMethod property).

A VC Proof is not a controller document, and there is nothing in the VC spec which requires that the verification method MUST be part of a controller document. In other words, seen from the VC spec, a verification method is a stand-alone concept, with its local controller that may not (necessarily) bound to any controller of a Controller Document. And the way I read the current text, the only known controller for a VC cannot even change the expiration dates, let alone the key data themselves.

Maybe this is part of a larger issue on how exactly does VC and the controller document relate (all the discussions so far concentrate on a controller document used as a DID document).

Generally, I do agree with:

The controller property is applicable to the entity/subject on which it appears (like any other property). We don't need multiple names for this (and shouldn't do it generally, e.g., we don't make a new id or type property for every possible subject on which it could appear, we just reuse them).

but when it comes to significant restrictions in usages, I do not think this is a good practice, and it would be cleaner to separate these at least on the vocabulary level. However, I also agree that the following may be true:

Furthermore, this change would affect many long-lived implementations

which should be taken in consideration (although I wonder whether the JSON-LD trick in #119 (comment) would mitigate the issue).

[dlongley]

A VC Proof is not a controller document, and there is nothing in the VC spec which requires that the verification method MUST be part of a controller document.

You have to go to some authoritative source to fetch the verification method or the trust doesn't work. There would be no way to trust the controller information expressed in an "embedded verification method" if the cryptographic signature comes from that same verification method. In fact, any claims could be made whatsoever. There was discussion on this point here:

#128

Hopefully this helps tie things together more clearly. Regarding your last comment -- I would still expect implementations to have to change if we had two different names, even if we did it in the vocabulary only. I also continue to think there's not a significant difference in the meaning of controller (given my comments here and above). So I still don't think a change is justified (on neither idealistic nor practical grounds).

[iherman]

A VC Proof is not a controller document, and there is nothing in the VC spec which requires that the verification method MUST be part of a controller document.

You have to go to some authoritative source to fetch the verification method or the trust doesn't work. There would be no way to trust the controller information expressed in an "embedded verification method" if the cryptographic signature comes from that same verification method. In fact, any claims could be made whatsoever. There was discussion on this point here:

w3c/controller-document#128 (comment)

Hopefully this helps tie things together more clearly.

Firstly, I expected this answer :-) and I do understand it (and agree). But we get to some editorial issue (cc @msporny, our fearless editor). I have followed some pointers and, at least for now, the relationship between the verification method and its controller document is not clearly stated, in my view. It very much sounds like tribal knowledge.

Following my nose, starting by w3c/controller-document#128 (comment), I get to §5.8, which says

going from the definition of the verification method to the controller document,

which is vague. Then, getting to the algorithm in this spec, one gets to:

• Let vmFragment be the result of parsing vmIdentifier according to the rules of the URL scheme and extracting the secondary resource identifier (the fragment identifier).
• Let controllerDocument be the result of dereferencing controllerDocumentUrl, according to the rules of the URL scheme and using the supplied options.

Which is again fairly vague to me. And it is an information hidden in an algorithm, which is not the first thing one would read, is it?

Let me be more positive. Shouldn't we add some text in the definition of the verification method, which makes it clear that there MUST be a documented way to get "back" to the controller document's identifier from the verification method? The verification method is its own resource; in theory, it could be a separate document somewhere on the Web, so it is not necessarily part of the same JSON document (which would not really make sense coming from an RDF world anyway). I could go as far as saying that we should have an extra optional property pointing back to the controller document, though I understand that some implementations may simply play with the identifiers, and their URL schemes, instead.

[David-Chadwick]

There has to be a trust chain from the root of trust to the verification method. The root of trust is the VDR. Do we state this anywhere?
So the VDR must point to the controller document and the controller document must point to the verification method. Crytographic proofs on the controller document and verification method verify the trust chain. So there do not need to be backwards pointers as @iherman suggests (though they might improve efficiency). Downwards pointers are sufficient to verify the trust chain.

[iherman]

There has to be a trust chain from the root of trust to the verification method. The root of trust is the VDR. Do we state this anywhere?

Not that I know of. The VDR is always mentioned as some sort of abstract entity, which has no trace in the official vocabulary of terms.

So the VDR must point to the controller document and the controller document must point to the verification method. Crytographic proofs on the controller document and verification method verify the trust chain. So there do not need to be backwards pointers as @iherman suggests (though they might improve efficiency). Downwards pointers are sufficient to verify the trust chain.

Provided there is a clear reference to the VDR. In a VC setting the "process" starts with the Verification Method, and there should be a pointer "back", so to say. Whether that pointer goes to the VDR or the CD is a bit of a detail.

I have made experimental implementations of DI in a purely RDF environment (no JSON document, "just" a set of resources and links) and, in such an environment, some reference "back" is necessary.

[dlongley]

@iherman,

In response to your comments, I'm generally supportive of some clarifying text (I'm not yet sure what that is) and don't think any normative changes are required (certainly none that would or should change implementations).

I agree that we could better highlight the things you mention that are either logical conclusions that perhaps require more thought from the reader than necessary (i.e., we should just come out and say more) or that are expressed in technical algorithmic steps that could also be elaborated upon with more informative prose.

[msporny]

+1 to creating some clarifying text, can @David-Chadwick or @iherman please propose the text or provide bullet items for what we need to clarify?

-1 to changing the properties, which will ripple into a class 4 change to DID Core, making it not possible to base DID Core on top of the controller document (and breaking every implementation of DIDs out there -- they'd all have to upgrade to the new language and we're over 14+ implementations in, just in the test suite alone).

In general, what it means to be a "controller" of something is based on the context (in the general English sense of the word). If you are a controller of a car, you can do things with the car, if you are the controller of a verification method, you can do things with the verification method, if you are the controller of a controller document, you can do things with the controller document. I don't think we need to have different terms for this, we just need to use more words to provide context and say what you can and cannot do within that context.

[David-Chadwick]

Here is a proposed update to the definition for Controller

Controller - An entity that is authorized to perform an action e.g. update, on a specific object e.g. a controller document or a verification method.

I think this makes it perfectly clear that the controller property is relative to the object that is being controlled. So this is the only edit that is needed to resolve this issue.

[msporny]

I think this makes it perfectly clear that the controller property is relative to the object that is being controlled.

Ok, thanks for the suggested text, I can raise a PR that does that (with some wordsmithing).

[iherman]

I am fine with the text referred to in #119 (comment), but that may cover part of the problem. As a more general issue, as I said in #119 (comment), the relationship between a verification method and a controller document is not properly defined/described in the spec, and it is not clear how I get from a verification method to the controller document in belongs to.

As a minimum I believe section §5.8 of the DI document should be copied (or moved?) to the Controller Document. And, I presume, that section should make it clearer that the exact way of getting to the CD from the VM depends on the… implementation? the URL Scheme? (Unclear to me.)

I understand that there is reluctance to add a new, optional property (from VM to CD) so late in the game, but I think that is the cleanest approach nevertheless. It is an optional property, hence it does not harm existing implementations. If I look at it from a non-JSON based RDF implementation, this seems to be fairly necessary...

[msporny]

And, I presume, that section should make it clearer that the exact way of getting to the CD from the VM depends on the… implementation? the URL Scheme? (Unclear to me.)

It depends on the URL Scheme.

In general, for HTTPS, the expectation is that the VM is identified using a fragment identifier, and the URL leads to the controller document. For example:

  "verificationMethod": "https://website.example/123#key-789"

For DIDs, the expectations is the same -- the VM is identified using a fragment identifier, and the URL leads to the controller document. For example:

  "verificationMethod": "did:example:123#key-789"

Now, it is possible for the VM to live somewhere other than the controller document, for example:

  "verificationMethod": "https://website.example/keys/789"

and the document dereferenced lists the keys controller property as https://website.example/123, and if that's the case, the algorithm provided in the document tells you how to properly ensure that https://w3c.github.io/vc-data-integrity/#verification-method-binding remains true.

I understand that there is reluctance to add a new, optional property (from VM to CD) so late in the game

You are describing the controller property on the VM... that already exists today, so I'm confused about what you are asking for?

[msporny]

PR #126 has been raised to address this issue. This issue will be closed once PR #126 has been merged.

[iherman]

I understand that there is reluctance to add a new, optional property (from VM to CD) so late in the game

You are describing the controller property on the VM... that already exists today, so I'm confused about what you are asking for?

In my understanding, the controller property refers to the entity that controls the document; without reproducing all the discussion here, it is, for example, the person who sets up the keys, for example.

But what I am talking about is a property referring to the controller document(s) that refer to this verification method. How can I deduce that from the URL of the VM?

See also my comment in #126 (comment)

[dlongley]

@iherman,

But what I am talking about is a property referring to the controller document(s) that refer to this verification method. How can I deduce that from the URL of the VM?

The VM controller isn't necessarily going to know or be able to express that kind of information in its controller document for every other party that might want to allow it to be used. Instead, the way that this sort of thing is presently done is with external properties, like dereferencing issuer with VCs. Business rules can be used to dereference an issuer URL to a controller document that lists an "external VM" that was used to sign the VC. This was mentioned here:

For a use case for this, consider a VC with an issuer with an ID value of did:a. This VC has a proof in it that is verifiable using a verification method with an ID of did:b#vm. To verify this proof, did:b#vm must be retrieved using the above algorithm, which will necessarily obtain (and validate) the VM information from the controller document did:b. This will allow the proof to be checked. Then business rules are run to check whether use of this verification method is acceptable for issuer did:a. This is a separate check -- and involves retrieving DID document, did:a, and seeing if it references did:b#vm as one of its assertionMethod verification methods.

#94 (comment)

[iherman]

@dlongley see my comment in #126 (comment)

Would we have to say that the exact approach taken to get from the VM to a CD is implementation dependent? Application dependent? I.e., should we have to say that, in a VC setting, the VM MUST be part of the same JSON-LD document as its CD, hence the usage of a fragment ID, otherwise this is up to the implementation?

I have absolutely no problems with your arguments; what I call "implementation dependent" is probably what you call "business rule". I guess the essence of what I am saying is that the reference to business rules is not in the specification (or at least I did not find it). At present, there is a chain of arguments with the (new) section in the PR, leading to https://pr-preview.s3.amazonaws.com/w3c/controller-document/pull/126.html#retrieve-verification-method, and the latter reads like a completely deterministic algorithm based on some vague URL scheme rules.

Note that the additional property I propose (linking the VM to the CD) is absolutely optional and does not contradict with what you say; you also talk in conditional. The only reason I think the property would be useful is because I presume it would simplify a number of business rules. But, again, if we decide it is too late for that, be it.

[dlongley]

Note that the additional property I propose (linking the VM to the CD) is absolutely optional and does not contradict with what you say; you also talk in conditional. The only reason I think the property would be useful is because I presume it would simplify a number of business rules. But, again, if we decide it is too late for that, be it.

Yeah, I do believe it's too late for that but it could perhaps be further debated/bikeshedded/sorted and tested in a future minor release. But it's not too late for us to add some non-normative text somewhere as needed.