Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updates re controller property #116

Merged
merged 34 commits into from
Nov 23, 2024
Merged

Updates re controller property #116

Changes from 27 commits
Commits
Show all changes
34 commits
Select commit Hold shift + click to select a range
a9f97a5
revised language describing the controller property
jandrieu Oct 12, 2024
eadc13c
removed extra spaces
jandrieu Oct 12, 2024
44a9c9d
incomplete edits. need to base on new intro opening
jandrieu Oct 12, 2024
76ce24f
revised language describing the controller property
jandrieu Oct 12, 2024
dcfc7ac
removed extra spaces
jandrieu Oct 12, 2024
e92d99e
minor merge edits
jandrieu Oct 31, 2024
7f54c71
clarified controller property language and discussed subject/controll…
jandrieu Oct 31, 2024
909f01d
Apply suggestions from code review
jandrieu Nov 12, 2024
1f32576
Update index.html
jandrieu Nov 12, 2024
7b8b533
Update index.html
jandrieu Nov 12, 2024
b085d30
Update index.html
jandrieu Nov 12, 2024
c02cf58
Update index.html
jandrieu Nov 12, 2024
229d7a1
Update index.html
jandrieu Nov 12, 2024
79227a6
Update index.html
jandrieu Nov 12, 2024
8db5053
Update index.html
jandrieu Nov 12, 2024
bd6dfd1
Update index.html
jandrieu Nov 12, 2024
f8ec6f2
Update index.html
jandrieu Nov 12, 2024
48fa8d4
Update index.html
jandrieu Nov 13, 2024
fb4aa43
Update index.html
jandrieu Nov 13, 2024
3e40b39
Update index.html
jandrieu Nov 13, 2024
9c1e39b
merge from upstream
jandrieu Nov 19, 2024
2d6248f
Added definitions for canonical URL and base identifier.
jandrieu Nov 19, 2024
303da6b
Update index.html
jandrieu Nov 19, 2024
c4338da
Update index.html
jandrieu Nov 20, 2024
124697a
Update index.html
jandrieu Nov 20, 2024
982605e
Update index.html
jandrieu Nov 20, 2024
515631c
Update index.html
jandrieu Nov 20, 2024
ec440ee
Update index.html
jandrieu Nov 22, 2024
17f99f2
Update index.html
jandrieu Nov 22, 2024
13696a2
Update index.html
jandrieu Nov 22, 2024
535f07e
Apply suggestions from code review
jandrieu Nov 23, 2024
7d450be
Update index.html
jandrieu Nov 23, 2024
98f1a59
Update index.html
jandrieu Nov 23, 2024
3e69af1
Update index.html
jandrieu Nov 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
264 changes: 213 additions & 51 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -300,9 +300,9 @@
<body>
<section id='abstract'>
<p>
A [=controller document=] contains cryptographic material and identifies
service endpoints that can be used to verify proofs from, and interact
with, the [=controller=] of an identifier.
A [=controller document=] contains cryptographic material and lists
service endpoints for the purposes of verifying proofs from, and interacting
with, the controller of an identifier.
</p>
</section>

Expand All @@ -319,9 +319,9 @@ <h2>Introduction</h2>
public cryptographic material, such as public keys, for verifying proofs created
by the controller of the identifier for specific purposes, such as
authentication, attestation, key agreement (for encryption), and capability
invocation and delegation. [=Controller documents=] also provide [=services=]
related to the identifier, for example to request additional information for
verification.
invocation and delegation. [=Controller documents=] also list [=services=]
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
related to the identifier, for example; from which to request additional
information for verification.
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
</p>

<p>
Expand All @@ -330,12 +330,21 @@ <h2>Introduction</h2>
controller of an identifier, including material for cryptographic proofs and
service endpoints for additional communications.
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
</p>

<p>
It is expected that other specifications, such as [[[?DID-CORE]]], will profile
A [=controller document=] specifies
[=verification relationships=] and [=service endpoints=] for a single
identifier, for which the current controller document is taken as authoritative.
Every controller document is stored and retrieved according to the [[=canonical url=]] of the
document, which MUST also be the [[=base identifier=]] of the document.
</p>
<p>
It is expected that other specifications will profile
the features that are defined in this specification, requiring and/or
recommending the use of some and prohibiting and/or deprecating the use of
others.
others. For example, [[[?DID-CORE]]] is expected to define DID documents as a
profile of controller documents, where the DID is the identifier, DID documents
are controller documents, and resolution is the process of retrieving the
canonical DID document for a DID.
</p>

<section>
Expand Down Expand Up @@ -557,24 +566,54 @@ <h3>Terminology</h3>

<dt><dfn class="export" data-lt="controller(s)|Controllers">controller</dfn></dt>
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
<dd>
An entity that is [=authorized=] to perform an action with a specific resource,
such as update a [=controller document=] or use a cryptographic key to generate
a digital signature.
<p>
An entity that is capable of performing an action with a specific resource,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
An entity that is capable of performing an action with a specific resource,
An entity that is capable of performing an action with a

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This suggestion would leave a broken sentence.

Can you try a new suggestion that addresses the flow of the remaining sentence?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure what happened to my original proposal, but here is the revised one from PR#126

An entity that is [=authorized=] to perform any action on the associated resource such as updating the associated [=controller document=] or updating the associated [=verification method=].

such as updating a [=controller document=] or generating a [=proof=] using a [=verification method=].
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
</p>
</dd>

<dt><dfn class="export">controller document</dfn></dt>
<dd>
A set of data that specifies one or more relationships between a
[=controller=] and a set of data, such as a set of public cryptographic keys.
<p>
A document that contains cryptographic material and lists service
endpoints that can be used for verifying proofs from, and interacting
with, the [=controller=] of an identifier.
</p>
</dd>

<dt><dfn data-lt="subjects">subject</dfn></dt>
<dd>
The entity identified by the `id` property in a [=controller document=].
Anything can be a subject: person, group, organization, physical thing, digital
thing, logical thing, etc.
<p>
An entity that is referred to by the `id` property in a [=controller document=]
when it is used as a subject in other contexts, such as authentication or
attestations, e.g., Verifiable Credentials. Anything can be a subject:
person, group, organization, physical thing, digital thing, logical thing, etc.
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
</p>
<div class="note">
<p>
It is expected that the [=subject=] referred to by the `id` of a
[=controller document=] will be consistent over time, so that a set of
proofs with the same [=identifier=] as [=subject=] can be interpreted
as referring to the same entity. For example, it is preferred that
credential issuers require that [=subjects=] demonstrate proof of
control over their [=identifier=] before issuing a credential with that
[=identifier=] as subject, creating assurance that the same entity was
involved in the issuance of each credential with that [=identifier=]
as [=subject=].
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
</p>
<p>
However, there are valid cases where that practice is either impossible or
unreasonable; for example, when a parent requests a Verifiable Credential
for their child. There are also cases where an issuer simply makes a mistake
or intentionally issues a false statement. All of these possibilities should
be considered when evaluating the security impacts of reliance on a given
[=identifier=] for any given purpose. See the section on Identifier Ambiguity
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
in Security Considerations.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs a citation/link to that Identifier Ambiguity in Security Considerations section.

</p>
</div>
</dd>


<dt><dfn class="export">verification method</dfn></dt>
<dd>
<p>
Expand All @@ -596,12 +635,33 @@ <h3>Terminology</h3>
<dt><dfn class="export">verification relationship</dfn></dt>
<dd>
<p>
An expression of the relationship between a [=subject=] and a
An expression of the relationship between an [=identifier=] and a
[=verification method=]. One example of a verification relationship is
Comment on lines +639 to 640
Copy link
Contributor

@dlongley dlongley Nov 20, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't seem quite right to me. An identifier is just a string / symbol. These relationships are between the subject (as identified by the base identifier) and the verification method. What is being said by verification relationship, R, is that the associated verification method, VM, can be used to verify a proof for a particular purpose on behalf of the subject when it is identified by the base identifier, X.

Also note the change from "the relationship" to "a relationship" since there can be more than one relationship for the same verification method. I'd prefer to just keep "a [=subject=]" because the wording was simple enough for me, but if this more wordy expression gets to consensus I'm ok with it (or something like it):

Suggested change
An expression of the relationship between an [=identifier=] and a
[=verification method=]. One example of a verification relationship is
An expression of a relationship between a [=subject=], when
identified by the [=base identifier=], and a [=verification method=].
One example of a verification relationship is

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I disagree with this characterization, but I want to acknowledge it's a difference of worldview that has some irreducible impedence mismatch. Which is to say I understand where Dave is coming from, but I disagree that that perspective is helping us.

We cannot know for certain who the subject referred to by the identifier is. Determining the subject referred to by an identifier is an output after the verification and validation of claims made in reference to that identiifier. As such, it is a mistake to START with the presumption that the verification method applies to the subject. It might. It might not.

What we do know is that particular verification methods are declared as suitable for verifying proofs from the controller of the identifier. Whoever that controller happens to be, these verification methods can be applied to have cryptographic confidence that the proof was created by the controller.

The subject may not be involved at all.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We cannot know for certain who the subject referred to by the identifier is.

What matters is which subject it is. And the ID is what allows there to be no confusion about which one. The fact that the ID is "controllable" is what allows there to be no confusion about whether certain proofs are verifiable by verification methods actually authorized by the controller to be used behalf of this subject. These are the only elements that matter about the subject at this layer. Talking about "who" or "what" the subject is here (e.g., "who is the subject?", "what real world thing is it?"), in my view, continues to be wholly irrelevant and is what I think creates this confusion.

Just because we say "this subject has these authorized verification methods" doesn't mean we also then have to debate whether the subject is a human being who likes rainy days. It also doesn't mean that if we can't decide whether that's true or not that we have to say that it's really the ID that has the verification methods, not the subject. It just doesn't follow. The ID just lets me know which subject -- and then I can use that information to figure out which verification methods are authorized for what (or which services I can use to interact with the subject).

The subject may not be involved at all.

I think we disagree what a "subject" is. Your comments imply to me that your mental model includes more in its definition than is necessary and more than I believe the spec says. Again, as an example, I see no reason whatsoever at this layer to ask: "but what real world thing is the subject?"

In my view of a "subject", it is the centerpiece of this technology. The whole point of a controller document is to enable a controller to logically establish "a thing" (a subject) that can act, interact, etc. with other things -- and to provide a mechanism for others to be able to verify information about those actions/interacts and that they were authorized by the controller. The ID is what allows there to be no confusion about which subject that is (out of all possible subjects) and the fact that it is "controllable" is what allows there to be no confusion about whether proofs were made by authorized verification methods.

When I speak of a "subject" that's it, it's just a logical construct used to distinguish it from "other things". All that matters is that we're "referring to the same 'thing'" when we use the same ID and that we can get some information to interact with it or verify some stuff supposedly done on its behalf.

All other debates about whether that "same thing" has horns, is a good idea or a bad one, wears blue pants, or likes to jump are not relevant here.

[[[#authentication]]].
</p>
</dd>

<dt><dfn class="export">base identifier</dfn></dt>
<dd>
<p>
The value of the `id` property of the root object in the [=controller document=]
MUST be set to the [[=canonical url=]] for this [=controller document=].
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
</p>
</dd>
<dt><dfn class="export">canonical url</dfn></dt>
<dd>
<p>
The URL for retrieving the current, authoritative controller
document for a given identifier. Dereferencing the canonical
URL MUST return the current authoritative controller
document. The returned document's [[=base identifier=]] MUST
be the same as the canonical URL; if it is anything else,
then the returned document is *not* an authoritative
controller document and the identifier SHOULD be treated as
invalid.
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
</p>
</dd>

</dl>

</section>
Expand All @@ -611,9 +671,9 @@ <h3>Terminology</h3>
<h3>Data Model</h3>

<p>
A [=controller document=] is a set of data that specifies one or more
relationships between a [=controller=] and a set of data, such as a set of
public cryptographic keys. The [=controller document=] SHOULD
A [=controller document=] specifies one or more relationships between
an [=identifier=] and a set of verification methods and/or service
endpoints. The [=controller document=] SHOULD
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
contain [=verification relationships=] that explicitly permit the use of
certain [=verification methods=] for specific purposes.
</p>
Expand Down Expand Up @@ -828,33 +888,66 @@ <h3>Subjects</h3>
<h3>Controllers</h3>

<p>
A [=controller=] is an entity that is authorized to make changes to a
[=controller document=].
A [=controller=] is any entity capable of making changes to a
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
[=controller document=]. Whoever can update
the content of the resource returned from dereferencing the controller
document's canonical URL is, by definition, a controller of the
document and its canonical identifier. Proofs that satisfy a
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have a problem with the controller being able to change the canonical identifier. Strictly speaking, changing the canonical identifier means changing the document altogether; put it another way, it means the creation of a new controller document. I would prefer to remove the reference to the identifier, it is not necessary here imho.

Suggested change
document and its canonical identifier. Proofs that satisfy a
document. Proofs that satisfy a

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That language doesn't say you can change a canonical identifier.

It says you establish control of the identifier by creating proofs.

Whoever can update
the content of the resource returned from dereferencing the controller
document's canonical URL is, by definition, a controller of the
document and its canonical identifier.

This is correct. If you can update the content of the canonical resource, you are a controller of the document's canonical identifier.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, again from my RDF-tainted view, I am not sure what it means to "control the identifier". Control means an ability to change; but changing the identifier means, strictly speaking, to replace the document because a document and its identifier are intimately bound. (An RDF Resource is specified by its URL. Changing a URL means to introduce a different resource.)

But I acknowledge that this is very much an RDF view of things, so I won't lie down the road over this.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@iherman

am not sure what it means to "control the identifier"

Yes. This update is describing that it means to control the identifier.

controller document's verification methods are taken as cryptographic
assurance that the controller of the identifier created those proofs.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
assurance that the controller of the identifier created those proofs.
assurance that the controller of the document created those proofs.

Strictly speaking, I believe that the controller controls the document and not necessarily the identifier. As an analogy, I may have the right to modify a google document, but I do not control its identifier (which is provided by the google doc system itself.)

Copy link
Contributor Author

@jandrieu jandrieu Nov 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From the new abstract:

A controller document contains cryptographic material and identifies service endpoints that can be used to verify proofs from, and interact with, the controller of an identifier.

The point is to demonstrate proof of control of the identifier.

Changing the controller document is simply the most fundamental way to do that. You can also use verification methods. Control of the document lets us deduce control of the identifier. That's the magic. Simply changing a resource is as old as the web. Proving control over an identifier is what DIDs (and now controlled/controllable identifiers) add to the game.

jandrieu marked this conversation as resolved.
Show resolved Hide resolved
</p>
<p class="note" title="Identifier Controller versus Document Controller">
The controller of the controller document is taken to be the
controller of the document's canonical identifier, also known as its
URL. That is, whoever can update the controller document is both
the document controller and the identifier controller. Updating the
document is how you control the identifier. These terms can be used
interchangeably. Controlling the canonical controller document for
an identifier is the same as controlling the identifier.
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
</p>

<dl>
<dt>controller</dt>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

-1 to document controller.

<dd>
The `controller` property is OPTIONAL. If present, its value MUST be a
The `controller` property is OPTIONAL. If it is possible to represent
Copy link
Member

@msporny msporny Nov 16, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

-1 to this change, it creates backwards-breaking changes that makes this document incompatible with DID Core and will make it impossible for DID Core to build on top of this specification (forced class 4 changes in DID WG, which is not authorized to make class 4 changes).

the legitimate controllers of the document as URLs, the document SHOULD
list URLs identifying those controllers.

<p class="note" title="Presumed Control">
It is possible to list a verification method which is
functionally under the control of someone other than the controller
of the controller document. For example, a document controller could
set a public key under another party's control as an authentication
verification method. This would enable the other party to authenticate
on behalf of this identifier (because their public key is listed in
an authentication verification method) <em>without</em> enabling that party
to update the controller document. However, since the document
controller explicitly listed that key for authentication, the
proof in question is taken as created by the document controller, as
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
proof in question is taken as created by the document controller, as
proof in question is assumed to be created by the document controller, as

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not an assumption. It is a constructive formulation. The proof is, by definition, created by the document controller (through the verification method specified by the controller).

jandrieu marked this conversation as resolved.
Show resolved Hide resolved
it was created by their explicit assignee. This is especially useful
when the "other party" is a device under the control of the document
controller, but with a distinct cryptographic authority, i.e., it
has its own keystore and can generate proofs. That pattern enables
different devices, each using their own cryptographic material, to
generate verifiable proofs that are taken as proofs created by
controller of the identifier.
</p>
If present, its value MUST be a
<a data-cite="INFRA#string">string</a> or a
<a data-cite="INFRA#ordered-set">set</a> of
<a data-cite="INFRA#string">strings</a>, each of which conforms to the rules
in the [[[URL]]]. The corresponding [=controller document=](s) SHOULD contain
[=verification relationships=] that explicitly permit the use of certain
[=verification methods=] for specific purposes. If the `controller` property is
not present, the value expressed by the `id` property MUST be treated as if it
were also set as the value of the `controller` property.
<a data-cite="INFRA#string">strings</a>,
each of which conforms to the rules in the [[[URL]]].

Each entry in the `controller` property MUST identify
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

-1 for the reasons stated here: https://github.com/w3c/controller-document/pull/116/files#r1839014775

an entity capable of updating the canonical version
of the [=controller document=].
Subsequent requests for this [=controller document=] through its
canonical location will always receive the latest version.

If the `controller` property is not present, then control of the document
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

-1 for the reasons stated here: https://github.com/w3c/controller-document/pull/116/files#r1839014775

jandrieu marked this conversation as resolved.
Show resolved Hide resolved
is determined entirely by its storage location.
</dd>
</dl>

<p>
When a `controller` property is present in a [=controller document=], its value
expresses one or more identifiers. Any [=verification methods=] contained in the
[=controller documents=] for those identifiers SHOULD be accepted as
authoritative, such that proofs that satisfy those [=verification methods=] are
considered equivalent to proofs provided by the [=subject=].
</p>

<pre class="example nohighlight"
title="Controller document with a controller property">
{
Expand All @@ -868,7 +961,7 @@ <h3>Controllers</h3>
While the identifier used for a [=controller=] is unambiguous, this does not
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
imply that a single entity is always the controller, nor that a controller
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
only has a single identifier. A [=controller=] might be a single entity, or a
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
collection of entities, such as a corporation. A [=controller=] might also use
collection of entities, such as a partnership. A [=controller=] might also use
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
multiple identifiers to refer to itself, for purposes such as privacy or
delineating operational boundaries within an organization. Similarly, a
[=controller=] might control many [=verification methods=]. For these reasons,
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
Expand All @@ -879,7 +972,7 @@ <h3>Controllers</h3>
<p class="note" title="Authentication versus Authorization">
Note that the definition of [=authentication=] is different from the definition
of [=authorization=]. Generally speaking, [=authentication=] answers the
question of "Who is this?" while [=authorization=] answers the question of "Are
question of "Do we know who this is?" while [=authorization=] answers the question of "Are
they allowed to perform this action?". The `authentication` property in this
Comment on lines +976 to 977
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
question of "Do we know who this is?" while [=authorization=] answers the question of "Are
they allowed to perform this action?". The `authentication` property in this
question of "Do we know who this is?" while [=authorization=] answers the question of "Do we know whether
they are allowed to perform this action?". The `authentication` property in this

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this case, I don't think the question is "do we know" but rather "are they ACTUALLY allowed".

To wit: the verifier may not know before doing the analysis, especially in cases of object capabilities and bearer tokens.

So, it isn't "answers the question of 'Do we know...?'" but rather "answers the question of 'can we determine if they are allowed'", which to me is just a wordier way to say "answers the question of 'are they allowed...?'"

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The question of "are they ACTUALLY allowed" cannot be answered, unless we have some affirmative (or negative) statement to that effect. If we have no specific statement, then the Open World assumption means we can only say, "we don't know".

specification is used to, unsurprisingly, perform [=authentication=] while the
other [=verification relationships=] such as `capabilityDelegation` and
Expand Down Expand Up @@ -944,8 +1037,9 @@ <h2>Services</h2>

<p>
[=Services=] are used in [=controller documents=] to express ways of
communicating with the [=subject=] or associated entities. A [=service=] can be
any type of service the [=subject=] wants to advertise for further discovery,
communicating with the [=controller=], or associated entities, in relation to
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
the controlled identifier. A [=service=] can be
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
any type of service the [=controller=] wants to advertise for further discovery,
authentication, authorization, or interaction.
</p>

Expand Down Expand Up @@ -1145,9 +1239,15 @@ <h2>Verification Methods</h2>
The `controller` property is used by [=controller documents=], as described in
Section [[[#controller-documents]]], and by [=verification methods=], as
described in Section [[[#verification-methods]]]. When it is used in either
place, its purpose is the same; that is, it expresses one or more entities that
are authorized to perform certain actions associated with the resource with
which it is associated. To ensure explicit security guarantees, the
place, its purpose is essentially the same; that is, it expresses one or more
entities that are authorized to perform certain actions associated with the
resource with which it is associated.

In the case of the controller of a controller document, the controller can
update the content of the document. In the case of the controller of a
verification method, the controller can generate proofs that satisfy the method.
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
jandrieu marked this conversation as resolved.
Show resolved Hide resolved

jandrieu marked this conversation as resolved.
Show resolved Hide resolved
To ensure explicit security guarantees, the
[=controller=] of a [=verification method=] cannot be inferred from the
[=controller document=]. It is necessary to explicitly express the identifier of
the controller of the key because the value of `controller` for a [=verification
Expand Down Expand Up @@ -1680,11 +1780,8 @@ <h2>Authentication</h2>
<p>
Note that the [=verification method=] indicated by the
`authentication` property of a [=controller document=] can
only be used to [=authenticate=] the [=controller=]. To
[=authenticate=] a different [=controller=], the entity associated with
the value of `controller` needs to [=authenticate=] with its
<em>own</em> [=controller document=] and associated
`authentication` [=verification relationship=].
only be used to [=authenticate=] on behalf
of the controller document's base identifier.
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
</p>
</section>

Expand Down Expand Up @@ -2884,7 +2981,72 @@ <h3>Binding to Physical Identity</h3>
</p>
</section>
</section>
<section>
<h2>Identifier Ambiguity</h2>
<p>Even in cases where the subject of the identifier proves control, the interpretation of the subject remains contextual and potentially ambiguous.
</p><p>
For example, a school might issue a credential about the
teacher of _Intro to Computer Science_, using `did:example:abc` as a subject identifier, saying in effect "did:example:abc is the teacher of
_Intro to Computer Science_" and "did:example:abc controls access
to the school's computer lab. See them to request access".
</p><p>
From this usage it is ambgious as to whether or not `did:example:abc`
refers to a specific teacher or to whomever is the current teacher.
</p><p>
Only with further statements might we be able to discern the difference.
</p><p>
But it's still tricky. For example the subject in the following statement
```turtle
did:example:abc foaf:name "Bob Smith" .
```
remains ambiguous. If `did:example:abc` refers to a specific human
being, then the statement is taken as an attestation about that
particular human's name. However, if `did:example:abc` is used to
refer to the _current_ teacher, it is also valid as the current
teacher does have that name. In this case the ambiguity is
immaterial.
</p><p>
However, in a statement like
```turtle
did:example:abc http://law.example/convicted http://calaw.example/PenalCode647b .
```
The difference becomes vital. The statement in English could be
"the person referred to by did:example:abc has been convicted of
California Penal Code 647b." But which person(s) did we mean? Did we
mean to say one, some, or all of the teachers of computer science at
the school have been convicted of violating Pen647b? Or is it meant to
say that a particular individual teacher, perhaps the one named "Bob
Smith", has been convicted of said crime?
</p>
<p>
The challenge is particularly difficult in situations where the
subject is fundamentally uninvolved in the issuance of the
credential. For example, an identifier might be used by a school to
refer to a teacher, and students and or parents may use that
identifier to make statements about the teacher, with neither the
teacher nor the school involved. In these cases, it is easy to
imagine that the subtle nuance of the school's intended meaning, e.g., "any current teacher of the computer science class", gets lost
and the identifier misused by parents and
students to refer to a specific teacher, quite likely in contexts
where neither the school nor the teacher is aware of the
conversation.
</p>
<p>
In natural language, these ambiguities are often easily ignored or
corrected. In digital media, it's vital that context be evaluated to
establish the intended referent, especially when identifiers are
used in different contexts by different issuers, e.g.: on a school
website by the school, but in a social networking app by parents and
students.
</p>
<p>
In short, the context in which identifiers are created and used
must be considered when relying on any particular interpretation
of the subject of any particular identifier.
</p>


jandrieu marked this conversation as resolved.
Show resolved Hide resolved
</section>
<section>
<h2>Key and Signature Expiration</h2>

Expand Down