Properly define the semantics of all `controller` properties

[RieksJ]

The semantics of the term 'DID controller' seems clear enough from the spec. However, the semantics of the controller property in a verification method is not defined. Some might imagine what it could be from reading the note that discusses Verification method controller(s) and DID controller(s), but it isn't clear. In particular, readers that aren't deeply involved in the subject matter will lack the criteria to determine which of suggested meanings would be the intended one.

The note suggests to me a number of possible meanings. Using the terms

• 'controller' for a party that is referred to by (a DID in) a 'controller property' in a verification method section, and
• 'DID controller' for a party that is referred to by (a DID in) a controller property of the DID document itself;

I then find the following two (contradictory) statements plausible interpretations of the text in the aforementioned note:

• Since a DID controller can change the entire DID document, and the semantics of the controller property are the same when the subject of the relationship is the DID document as when the subject of the relationship is a verification method, it follows that any controller can also change the DID document.
• Since 'controlling something' seems to mean 'the ability to change that something', a controller seems to able to change the verification method in which it is mentioned.

[RieksJ]

@kdenhartog phased his understanding of 'controller' (issue #805) to be the entity that controls secret key material (that's not the same as controlling a section in a document that controls a verification method):

The Verification Method controller is the one who controls the secret key material to utilize the verification method in any way they choose. One example may be for the verification method to be used to update the DID Document, but it doesn't require it to be used in this way

Why would I want to know the controller DID if I can already recognize that controller by having it show me he possesses the secret key material it controls? It makes me wonder if there's another (still undocumented?) purpose for having it there. The aforementioned note seems to suggest there is, where it says:

Since a key can't control itself, and the key controller cannot be inferred from the DID document, it is necessary to explicitly express the identity of the controller of the key.

However, it doesn't explain this necessity.

[kdenhartog]

Hmm this could be a bit odd to define the semantics here since the semantics are realistically being set by the verification method suite which could be done in a variety of different ways. For example, the semantics of the controller property for the verifiable conditions suite is likely to mean something different than the semantics of a traditional public key base verification method suite.

[RieksJ]

I hope your are not saying: "this standard does not define semantics because every software suite that uses it chooses, and is at liberty to choose its own semantics"

[kdenhartog]

A bit more nuanced than that. What I'm trying to say is DID-Core should define the abstract semantics and it's up to the verification method suite to define the semantics for their particular verification method. A good analogy of how I see this is would be similar to if you were to treat DID-Core as an abstract interface in a programming language which defines the contract and then the verification method defines the implementation. Of course the verification method has to adhere to the function signature defined in the abstract interface, but all it's implementations don't necessarily have to be exact matches of each other.

[RieksJ]

That makes sense to me, that is to say I interpret this as that DID-Core could define the abstract semantics of every of its properties by adding a single line that does so. Perhaps something like this for DID Document properties:

Property	Required	Syntax	Semantics
id	yes	A string that conforms to the rules in § 3.1 DID Syntax.	This string identifies a specific entity (as decided by the DID controller), and can be resolved to the associated DID document.
controller	no	A string that conforms to the rules in § 3.1 DID Syntax.	This string identifies an entity that is allowed to change any content of this DID document

And might it look something like this for verification method properties?

Property	Required?	Syntax	Semantics
id	yes	A string that conforms to the rules in § 3.2 DID URL Syntax.	This string identifies the verification method.
controller	yes	A string that conforms to the rules in § 3.1 DID Syntax.	This string identifies the entity that is allowed to change this verification method.
type	yes	A string.	This string identifies the kind of verification method that the publicKey-material is intended to be used in.

If that's what is needed I'm looking forward to the texts that specify the 'semantics' column of the 'controller' properties.

[kdenhartog]

@RieksJ the didDocument.id property semantics you're proposing reintroduce the range 14 problem I believe. The DID only represents the subject as a URI not the DID Document resource. From the sounds of it you're saying that the URI represents the subject AND the DID Document resource which wouldn't be correct. If I am accurately representing the semantics included in section B.1 the DID Document resource is not identifiable it is only resolvable.

The rest of the semantics are correct.

[RieksJ]

@kdenhartog I've updated my earlier comment to better reflect my understanding of the id property of the DID doc. I think it's now in line with how it is intended to be. Regardless, I wouldn't want to rekindle any earlier problems.

I've also seen the changes you made in your PR. Your updates of the text for the id property in verificationMethod say "This value represents either the DID controller or DID delegate who possesses the secret cryptographic material used to authenticate the verification method ." To me, that's quite different from my text "This string identifies the entity that is allowed to change this verification method.", of which you said in your previous message that it is correct. Possession of secret key material (which you go for) does not imply authorization to use it for a specific purpose (which I go for).

If your description is correct, then why have the id property in the first place? What additional merit/benefit comes from having the DID up front as opposed to the situation where you do not yet are still able to ask any party that proves she has the private key material?

[RieksJ]

I noticed that this also came up (sort of) in #697, where @msporny stated that "If we didn't require the property, we open up a ton of potential attacks that we'd then have to figure out how to deal with". I'd love to see this documented in a place that people that are not heavily involved in authoring/contributing to the spec can easily find, and in a way that they can also easily understand (or did I miss that?)

In #802, @msporny stated that "the key material is bi-directionally associated with an entity", enabling verifiers to also check that the key material is being used by the proof-creator for the purpose (authentication, claim-signing, ...) it was intended for. That's understandable for authentication, but for other purposes, such as claim-signing, I'm not convinced this works, because the controller (proof-creator) can change his DID doc and remove the that specific key (verificationMethod). In that case, the verifier gets a proof that checks out, except for the fact that the relation with the proof-creator can no longer be established. If this means the verifier needs to reject the signed claims, changing such keys would effectively be a novel revocation mechanism (which I'm not sure is what we'd want). If this means the verifier can ignore the situation, there's no purpose in checking it in the first place.

[kdenhartog]

FYI @dlongley I think you're going to have opinions on this so want to make sure you're aware this thread is ongoing.

I've also seen the changes you made in your PR. Your updates of the text for the id property in verificationMethod say "This value represents either the DID controller or DID delegate who possesses the secret cryptographic material used to authenticate the verification method ." To me, that's quite different from my text "This string identifies the entity that is allowed to change this verification method.", of which you said in your previous message that it is correct. Possession of secret key material (which you go for) does not imply authorization to use it for a specific purpose (which I go for).

The problem is that with your proposed text that doesn't align with the behavior of how most DID Methods are defining how updates work. It's the DID Document controller not the verification method controller who gets to update the verification method. Re-reading my text though I think I got it slightly wrong as well since the DID-URL in the id property of the verification method actually represents a URL for the sub-resource being de-referenced in the DID Document. With that said I'm not sure what identifier is expected to be used for a verification method controller which is what my original text implied it was for.

If your description is correct, then why have the id property in the first place? What additional merit/benefit comes from having the DID up front as opposed to the situation where you do not yet are still able to ask any party that proves she has the private key material?

It's primary purpose is for being able to identify the specific verification method that's being used and de-referenced in practice so we should probably focus on that assumption and I should update my text to accurately reflect that.

In #802, @msporny stated that "the key material is bi-directionally associated with an entity", enabling verifiers to also check that the key material is being used by the proof-creator for the purpose (authentication, claim-signing, ...) it was intended for. That's understandable for authentication, but for other purposes, such as claim-signing, I'm not convinced this works, because the controller (proof-creator) can change his DID doc and remove the that specific key (verificationMethod). In that case, the verifier gets a proof that checks out, except for the fact that the relation with the proof-creator can no longer be established. If this means the verifier needs to reject the signed claims, changing such keys would effectively be a novel revocation mechanism (which I'm not sure is what we'd want). If this means the verifier can ignore the situation, there's no purpose in checking it in the first place.

Yes, that's a correct assessment of what's possible. In general that was considered a feature even though we were unable to standardize on a common revocation mechanisms and that was one of methods which was being considered.

[RieksJ]

@kdenhartog: Thanks for clarifying. At this point I'm primarily trying to understand how things are currently intended. This discussion, the issues I referred to and some private communications tell me such clarification is actually needed. And there's still #805, which basically calls for similar clarification texts for other properties.

A different thing is whether or not what is (then) specified is what we'd like/want/need. We could discuss that in this issue, too, or I could raise a separate issue for that. Is there any preferred way of doing that?

[kdenhartog]

I'm fine with keeping that discussion in this issue as well or for it to happen on the open PR as suggested text changes.

[RieksJ]

I'm struggling with git (I just know the very basics); so how do I best contribute to the open PR?

[iherman]

I'm struggling with git (I just know the very basics); so how do I best contribute to the open PR?

@RieksJ I am not sure how extensive your contribution would be. A very simple intro to github that I wrote some years ago:

https://iherman.github.io/misc-notes/docs/BasicGitHubContributionIntro

may help.

[kdenhartog]

Yeah for me just a review of the text on github is a great way to provide specific requests that I can take action on so we can find a text that makes sense for the both of us. Here's another guide from github on how to conduct a pull request review.

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request

[RieksJ]

Thank you both for trying to help out. I've spent quite some time trying to make my way through this pull request (learned a lot) but I find it too cumbersome and time consuming to actually contribute. As the clarifications, both in this issue and the additions by @kdenhartog work for me, I suggest we leave it as it is now.