Update note about controller value #371

rhiaro · 2020-08-11T09:20:29Z

following feedback from @dlongley and @jandrieu in #122

dlongley

I think this suggestion captures the intent of our discussion and removes the ambiguity/non-interoperability/squishiness that was in the spec previously around controller.

index.html

jandrieu · 2020-08-11T15:08:12Z

index.html

+changed is by consulting the relevant <a>DID method</a>. If no <a>verification
+methods</a> are present in the <a>DID Document</a>, then a
+<code><a>controller</a></code> property MUST be present, otherwise the
+the <a>DID document</a> can no longer be changed beyond whatever its present


This doesn't seem accurate, in that the DID Method can provide a means to update the did document without specifying a controller property. In particular, I believe BTCR defers all change properties to BTC, without regard to what is in the DID Document.

dlongley · 2020-08-11T15:54:46Z

index.html

+<code><a>controller</a></code> property MUST be present, otherwise the
+the <a>DID document</a> can no longer be changed beyond whatever its present
+value is.


@jandrieu -- would this address your concern?

Suggested change

<code><a>controller</a></code> property MUST be present, otherwise the

the <a>DID document</a> can no longer be changed beyond whatever its present

value is.

<code><a>controller</a></code> property MUST be present, otherwise it

is possible that the <a>DID document</a> can no longer be changed beyond

whatever its present value is. This can be determined by consulting the

applicable <a>DID method</a> specification.

It seems that the "MUST" is misplaced. If "MUST" is used, that's a normative requirement, which means the following phrase of "otherwise it is possible" is not actually possible with a conformant implementation.

Are you intending to say that, as a requirement,

DID Methods MUST return DID Documents that either have a verification method or a controller property.

DID Methods MUST respect the controller property

That's what this language suggests to me.

However, I don't believe BTCR does either of this today (I could be wrong), which makes me wonder if this particular use is actually in sync with a minimal set of capability for DIDs as envisioned to date.

I thought this while I was drafting it and then apparently completely forgot: we can't use normative language in a note block, so this MUST needs to come out anyway.

I'm fine if this is reworded to remove the "MUST" since it's in a note. The language I'm looking for here is an indication to DID-method agnostic consumers (such as verification software) such that it can understand the root of authority over what is expressed in the DID Document. This should either be the controller (if present) or the subject, IMO. Whether or not DID methods have implementation specific details for updating DID Documents is a separate matter to me. I want consuming software to be able to be structured/layered such that it only need to decide whether or not it trusts a given DID method/resolver for that method and then from there, once it has a DID Document, it can assume the root authority is as stated above (thereby allowing consistent verification code).

brentzundel · 2020-08-12T19:21:59Z

index.html

+If the <code><a>controller</a></code> property is present, its value expresses
+the root of authority for information expressed in the <a>DID Document.</a> If
+the <code><a>controller</a></code> property is not present, the value can be
+inferred to be the same as that of the <code><a>id</a></code> property of the
+<a>DID document</a>. The way to determine how the <a>DID Document</a> can be
+changed is by consulting the relevant <a>DID method</a>. If no <a>verification
+methods</a> are present in the <a>DID Document</a>, then a
+<code><a>controller</a></code> property MUST be present, otherwise the
+the <a>DID document</a> can no longer be changed beyond whatever its present
+value is.


Latest suggestion, as of 26 Aug 2020:

Suggested change

If the <code><a>controller</a></code> property is present, its value expresses

the root of authority for information expressed in the <a>DID Document.</a> If

the <code><a>controller</a></code> property is not present, the value can be

inferred to be the same as that of the <code><a>id</a></code> property of the

<a>DID document</a>. The way to determine how the <a>DID Document</a> can be

changed is by consulting the relevant <a>DID method</a>. If no <a>verification

methods</a> are present in the <a>DID Document</a>, then a

<code><a>controller</a></code> property MUST be present, otherwise the

the <a>DID document</a> can no longer be changed beyond whatever its present

value is.

A <a>DID method</a> may allow <a>DID Documents</a> to express a

<code><a>controller</a></code> property. When a

<code><a>controller</a></code> property is present in a

<a>DID Document</a>, its value expresses one or more <a>DIDs</a>. Any

<a>verification methods</a> contained in the <a>DID Documents</a> for those

<a>DIDs</a> SHOULD be accepted as authoritative, such that proofs that satisfy

those verification methods are to be considered equivalent to proofs provided by

the <a>DID Subject</a>.

@brentzundel -- How does one write DID-method agnostic verification software if we can't assume that the controller is the subject when controller is not present? It's one thing to say that it might not be clear who can further makes changes to the document (or not) when there's no controller and no verification methods present, but that's a matter left to DID methods. The problem, I believe, with your suggestion is that it affects DID Document consumers like DID-method agnostic verification software.

If there is no controller property and no verification methods, what should DID-method agnostic software assume about the DID Document?

@brentzundel, that the root of authority is the DID subject. Unless the software is for updating the DID Document, it doesn't care about whether or not the DID Document can be further changed (again, this can be DID method specific), it just cares about what is presently in the DID Document.

That makes sense, I have adjusted my suggestion accordingly.
I think it is cleaner if this note doesn't also attempt to address whether or not a DID Document can be further changed.

+1 to the above text. Thanks!

Thanks for working through this all! My only quibble is the normative language, as this is a note. I could just lowercase the SHOULD when I update the PR, or we could alter it to not say may and should at all - any preference?

Could we change it from a note to a regular paragraph?

+1 to the above text AND to change it from a not to a regular paragraph.

+1 to the text and to change it from a note to a regular paragraph.

agropper · 2020-08-12T19:47:33Z

Is my comment #373 (comment) relevant to this issue (#371) ?

…

On Wed, Aug 12, 2020 at 3:44 PM Dave Longley ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In index.html <#371 (comment)>: > +<code><a>controller</a></code> property MUST be present, otherwise the +the <a>DID document</a> can no longer be changed beyond whatever its present +value is. I'm fine if this is reworded to remove the "MUST" since it's in a note. The language I'm looking for here is an indication to DID-method agnostic consumers (such as verification software) such that it can understand the root of authority over what is expressed in the DID Document. This should either be the controller (if present) or the subject, IMO. Whether or not DID methods have implementation specific details for updating DID Documents is a separate matter to me. I want consuming software to be able to be structured such that it only need to decide whether or not it trusts a given DID method/resolver for that method and then from there, once it has a DID Document, it can assume the root authority is as stated above (thereby allowing consistent verification code). — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#371 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABB4YLEMYDKFT6YMJSOPUTSALWJRANCNFSM4P22OHJQ> .

dlongley · 2020-08-18T20:46:05Z

index.html

+If the <code><a>controller</a></code> property is present, its value expresses
+the root of authority for information expressed in the <a>DID Document.</a> If
+the <code><a>controller</a></code> property is not present, the value can be
+inferred to be the same as that of the <code><a>id</a></code> property of the
+<a>DID document</a>. The way to determine how the <a>DID Document</a> can be
+changed is by consulting the relevant <a>DID method</a>. If no <a>verification
+methods</a> are present in the <a>DID Document</a>, then a
+<code><a>controller</a></code> property MUST be present, otherwise the
+the <a>DID document</a> can no longer be changed beyond whatever its present
+value is.


@jandrieu and @brentzundel -- what about this? I'm trying to cover all of the concerns here at once: ensuring we're speaking clearly to what controller enables verifiers to consider in a DID-method-agnostic way and indicating that DID methods may say whatever they want about what a verifier actually needs to accept for a DID Document update.

Suggested change

If the <code><a>controller</a></code> property is present, its value expresses

the root of authority for information expressed in the <a>DID Document.</a> If

the <code><a>controller</a></code> property is not present, the value can be

inferred to be the same as that of the <code><a>id</a></code> property of the

<a>DID document</a>. The way to determine how the <a>DID Document</a> can be

changed is by consulting the relevant <a>DID method</a>. If no <a>verification

methods</a> are present in the <a>DID Document</a>, then a

<code><a>controller</a></code> property MUST be present, otherwise the

the <a>DID document</a> can no longer be changed beyond whatever its present

value is.

If the <code><a>controller</a></code> property is present, its value expresses

the root of authority for information expressed in the <a>DID Document</a>.

Expressing a <code><a>controller</a></code> property in a <a>DID Document</a>

enables <a>verifiers</a> to consider proofs generated by a

<a>DID controller</a> on behalf of a <a>DID subject</a>, even when the same

<a>DID Document</a> expresses no <a>verification methods</a>. Note that

whether any proofs will ultimately be accepted for some purpose is within the

purview of the <a>verifier</a>. DID methods, for example, may require

<a>verifiers</a> use a mechanism totally unrelated to <a>verification

methods</a> for validating DID Document updates.

This text is fine for me, except the last sentence. I keep trying to parse it and failing, so I'm not sure what you're trying to say there.

agropper · 2020-08-18T21:06:12Z

I'm not following all of the subtleties of this discussion, but I hope we end up with clarity, ideally an example, around a non-repudiable signature. In the prescription use-case, the DID subject is able to sign a prescription for a controlled substance under DEA regs. What does this mean: - the DID method will need to be "certified" by a federal agency or their delegate? - the DID document will need to be co-controlled by a federal agent? - changes to the DID document will need to be logged and audited? - the use of the DID by the doctor will need to be logged and audited? - all of the above? - Adrian

…

On Tue, Aug 18, 2020 at 4:46 PM Dave Longley ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In index.html <#371 (comment)>: > +If the <code><a>controller</a></code> property is present, its value expresses +the root of authority for information expressed in the <a>DID Document.</a> If +the <code><a>controller</a></code> property is not present, the value can be +inferred to be the same as that of the <code><a>id</a></code> property of the +<a>DID document</a>. The way to determine how the <a>DID Document</a> can be +changed is by consulting the relevant <a>DID method</a>. If no <a>verification +methods</a> are present in the <a>DID Document</a>, then a +<code><a>controller</a></code> property MUST be present, otherwise the +the <a>DID document</a> can no longer be changed beyond whatever its present +value is. @jandrieu <https://github.com/jandrieu> -- please see my tweak to your above below. Let me know what you think. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#371 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABB4YP2L5KWF6V5B7KA6Z3SBLSDFANCNFSM4P22OHJQ> .

jandrieu · 2020-08-19T16:27:20Z

I think it would make sense to concisely enumerate the options. The current text reads as if the controller property is required to verify proofs. I realize it doesn't say that, but opening with the statement that the controller allows XX, even when YY, doesn't clearly illuminate the fact that one may use either controller or verification methods (or both) to verify proofs and that for DID Documents with neither, a Requesting Party cannot rely upon the DID Document for proof verification.

To enable verification methods, a DID Document must include either a "controller" property, one or more verification methods, or both. If one or more verification methods are present, then Requesting Parties may verify proofs by checking the proof mechanisms whose verification purpose matches the proof's proof purpose. If a "controller" property is present in an initial DID Document, and the value of that property resolves to additional verification methods, such as from a secondary DID Document, then Requesting Parties MUST treat those additional verification methods as if they were present in the initial DID Document. If there are no verification methods specified: neither in the initial DID Document nor in any secondary sources referred to by a "controller" property, then Requesting Parties cannot rely on the DID Document to verify proofs.

We should probably also clarify whether or not Requesting Parties MUST also resolve all controller properties of secondary DID Documents. Namely, I'm fairly sure the "controller" property requires supporting arbitrary depth trees and should have language defining how to handle circular references.

dlongley · 2020-08-19T16:56:50Z

@jandrieu -- I approve of the direction, but things are a little inverted in the actual suggested language with respect to how proofs/verification methods are handled. I'll discuss with you offline a bit and see if we can resolve it.

dlongley · 2020-08-19T17:04:08Z

I'm looking, perhaps, for language that is more like:

Systems or protocols that make use of verification methods (which may or may not include DID methods) can use the "controller" property in DID Documents to consider proofs generated by a DID controller on behalf of a DID subject as valid.

msporny · 2020-08-24T01:31:17Z

We're still waiting for this conversation thread to converge on something. There remain a number of outstanding questions, IIUC. What do we need to move this PR forward?

msporny · 2020-08-30T16:34:04Z

Still waiting for this discussion to converge. I believe everyone is waiting on @rhiaro to note if she's ok with @brentzundel's text (but I may have my PRs confused).

@jandrieu

…and @jandrieu in #122

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

rhiaro · 2020-08-31T19:50:48Z

I have updated the section to use @brentzundel's wording here ... however (sorry!) I'm now not satisfied this answers my original question, which is basically what is a DID doc consumer expected to think/do/understand if there is no controller property?

(The answer I think was concluded to be "consult the DID method" but we seem to have lost that wording.)

It also duplicates to some extent, I think, text that is already in the definition of the controller property:

The value of the controller property MUST be a string or an ordered set of strings that conform to the rules in Section . The corresponding DID document(s) SHOULD contain verification relationships that explicitly permit the use of certain verification methods for specific purposes.

dlongley · 2020-09-01T00:39:06Z

@rhiaro,

I have updated the section to use @brentzundel's wording here ... however (sorry!) I'm now not satisfied this answers my original question, which is basically what is a DID doc consumer expected to think/do/understand if there is no controller property?

Well, we intentionally described what the presence of the controller property enables as opposed to talking about what happens when it isn't there. When it's not there, you just don't get the feature you get when it is there. I don't think there's anything more to it. So there's nothing special to think/do/understand for a DID doc consumer.

rhiaro · 2020-09-07T10:24:26Z

Okay, I'm fine to go with the most recent changes and close the issue.

msporny · 2020-09-07T18:56:06Z

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

rhiaro added the editorial Editors should update the spec then close label Aug 11, 2020

rhiaro requested review from dlongley and jandrieu August 11, 2020 09:20

dlongley requested changes Aug 11, 2020

View reviewed changes

index.html Outdated Show resolved Hide resolved

jandrieu reviewed Aug 11, 2020

View reviewed changes

dlongley reviewed Aug 11, 2020

View reviewed changes

brentzundel reviewed Aug 12, 2020

View reviewed changes

dlongley reviewed Aug 18, 2020

View reviewed changes

rhiaro and others added 3 commits August 31, 2020 18:50

Update note about controller value following feedback from @dlongley …

17d1e56

…and @jandrieu in #122

Improve wording about presence of verification methods

e28e55c

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

Update wording about controller property to suggestion by @brentzundel

330a828

rhiaro force-pushed the rhiaro-122-controller branch from 4645042 to 330a828 Compare August 31, 2020 18:46

brentzundel approved these changes Aug 31, 2020

View reviewed changes

dlongley approved these changes Sep 1, 2020

View reviewed changes

rhiaro mentioned this pull request Sep 1, 2020

When is a DID subject not a DID controller (if ever)? #122

Closed

msporny approved these changes Sep 7, 2020

View reviewed changes

msporny merged commit 001abab into master Sep 7, 2020

msporny deleted the rhiaro-122-controller branch November 8, 2020 17:17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update note about controller value #371

Update note about controller value #371

rhiaro commented Aug 11, 2020 •

edited by pr-preview bot

Loading

dlongley left a comment •

edited

Loading

jandrieu Aug 11, 2020

dlongley Aug 11, 2020

jandrieu Aug 12, 2020

rhiaro Aug 12, 2020

dlongley Aug 12, 2020 •

edited

Loading

brentzundel Aug 12, 2020 •

edited

Loading

dlongley Aug 12, 2020

brentzundel Aug 12, 2020

dlongley Aug 12, 2020 •

edited

Loading

brentzundel Aug 12, 2020

dlongley Aug 26, 2020

rhiaro Aug 26, 2020

brentzundel Aug 26, 2020

jandrieu Aug 27, 2020

dlongley Aug 27, 2020

agropper commented Aug 12, 2020 via email

dlongley Aug 18, 2020 •

edited

Loading

brentzundel Aug 20, 2020 •

edited

Loading

agropper commented Aug 18, 2020 via email

jandrieu commented Aug 19, 2020 •

edited

Loading

dlongley commented Aug 19, 2020

dlongley commented Aug 19, 2020 •

edited

Loading

msporny commented Aug 24, 2020

msporny commented Aug 30, 2020

rhiaro commented Aug 31, 2020

dlongley commented Sep 1, 2020

rhiaro commented Sep 7, 2020

msporny commented Sep 7, 2020

-<code><a>controller</a></code> property MUST be present, otherwise the
-the <a>DID document</a> can no longer be changed beyond whatever its present
-value is.
+<code><a>controller</a></code> property MUST be present, otherwise it
+is possible that the <a>DID document</a> can no longer be changed beyond
+whatever its present value is. This can be determined by consulting the
+applicable <a>DID method</a> specification.

Update note about controller value #371

Update note about controller value #371

Conversation

rhiaro commented Aug 11, 2020 • edited by pr-preview bot Loading

dlongley left a comment • 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

Choose a reason for hiding this comment

dlongley Aug 12, 2020 • edited Loading

Choose a reason for hiding this comment

brentzundel Aug 12, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dlongley Aug 12, 2020 • 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

agropper commented Aug 12, 2020 via email

dlongley Aug 18, 2020 • edited Loading

Choose a reason for hiding this comment

brentzundel Aug 20, 2020 • edited Loading

Choose a reason for hiding this comment

agropper commented Aug 18, 2020 via email

jandrieu commented Aug 19, 2020 • edited Loading

dlongley commented Aug 19, 2020

dlongley commented Aug 19, 2020 • edited Loading

msporny commented Aug 24, 2020

msporny commented Aug 30, 2020

rhiaro commented Aug 31, 2020

dlongley commented Sep 1, 2020

rhiaro commented Sep 7, 2020

msporny commented Sep 7, 2020

rhiaro commented Aug 11, 2020 •

edited by pr-preview bot

Loading

dlongley left a comment •

edited

Loading

dlongley Aug 12, 2020 •

edited

Loading

brentzundel Aug 12, 2020 •

edited

Loading

dlongley Aug 12, 2020 •

edited

Loading

dlongley Aug 18, 2020 •

edited

Loading

brentzundel Aug 20, 2020 •

edited

Loading

jandrieu commented Aug 19, 2020 •

edited

Loading

dlongley commented Aug 19, 2020 •

edited

Loading