w3c · msporny · Nov 23, 2024 · Oct 12, 2024 · Oct 12, 2024 · Oct 12, 2024
@@ -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>
 
@@ -319,7 +319,7 @@ <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=]
+invocation and delegation. [=Controller documents=] also list [=services=]
 related to the identifier, for example to request additional information for
 verification.
       </p>
@@ -330,12 +330,21 @@ <h2>Introduction</h2>
 controller of an identifier, including material for cryptographic proofs and
 service endpoints for additional communications.
       </p>
-
       <p>
-It is expected that other specifications, such as [[[?DID-CORE]]], will profile
+A [=controller document=] specifies one or more
+[=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 URL of the 
+document, which is also the canonical identifier of the document.
-identifier, for which the current controller document is taken as authoritative. 
-Every controller document is stored and retrieved according to the URL of the 
-document, which is also the canonical identifier of the document.
+identifier, about which relationships the current controller document is taken
+as authoritative. Every controller document is stored and retrieved according to
+the URL of the document, which is also the canonical identifier of the document.
-identifier, for which the current controller document is taken as authoritative. 
-Every controller document is stored and retrieved according to the URL of the 
-document, which is also the canonical identifier of the document.
+identifier, about which relationships the current controller document is taken
+as authoritative. Every controller document is stored and retrieved according to
+the URL of the document, which is also the canonical 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>
@@ -557,24 +566,66 @@ <h3>Terminology</h3>
 
           <dt><dfn class="export" data-lt="controller(s)|Controllers">controller</dfn></dt>
           <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,
-An entity that is capable of performing an action with a specific resource,
+An entity that is capable of performing an action with a
-An entity that is capable of performing an action with a specific resource,
+An entity that is capable of performing an action with a
+such as updating a [=controller document=] or generating a [=proof=] using a [=verification method=].
+            </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. 
+            </p>
+            <p class="note">
+It is expected that the subject referred to by the id of a controller document 
+be consistent over time, so that a set of credentials with a given identifer as 
+subject can be taken to be about the same entity. However, it <em>is</em> possible to 
+issue credentials with a subject identifier <em>without</em> the subject even being 
+aware of it.
+
+It is expected that credential issuers will ask the subject for identifiers 
+and that those subjects would demonstrate proof of control before the issuer
+issues the credential. However, there are valid cases where issuers will 
+use identifiers that are not provably under the control of the subject. 
-use identifiers that are not provably under the control of the subject. 
+use identifiers that are not provably under the control of the subject, for example,
+when a parent requests a verifiable credential for their child.
-use identifiers that are not provably under the control of the subject. 
+use identifiers that are not provably under the control of the subject, for example,
+when a parent requests a verifiable credential for their child.
+
+However, even in cases
-However, even in cases
-However, even in cases
+where the subject of the ID does prove control, the interpretation of the subject
-where the subject of the ID does prove control, the interpretation of the subject
-where the subject of the ID does prove control, the interpretation of the subject
+remains contextual and potentially ambiguous.
-It is expected that credential issuers will ask the subject for identifiers 
-and that those subjects would demonstrate proof of control before the issuer
-issues the credential. However, there are valid cases where issuers will 
-use identifiers that are not provably under the control of the subject. 
-
-However, even in cases
-where the subject of the ID does prove control, the interpretation of the subject
-remains contextual and potentially ambiguous.
+It is expected that credential issuers will ask the controller for identifiers 
+and that those controllers would demonstrate proof of control before the issuer
+issues the credential. However, there are valid cases where issuers will 
+use identifiers that are not provably under the control of the controller.
+
+However, even in cases
+where the controller of the ID does prove control, the interpretation of the subject
+remains contextual and potentially ambiguous.
-remains contextual and potentially ambiguous.
-It is expected that credential issuers will ask the subject for identifiers 
-and that those subjects would demonstrate proof of control before the issuer
-issues the credential. However, there are valid cases where issuers will 
-use identifiers that are not provably under the control of the subject. 
-
-However, even in cases
-where the subject of the ID does prove control, the interpretation of the subject
-remains contextual and potentially ambiguous.
+It is expected that credential issuers will ask the controller for identifiers 
+and that those controllers would demonstrate proof of control before the issuer
+issues the credential. However, there are valid cases where issuers will 
+use identifiers that are not provably under the control of the controller.
+
+However, even in cases
+where the controller of the ID does prove control, the interpretation of the subject
+remains contextual and potentially ambiguous.
-remains contextual and potentially ambiguous.
+
+For example, the White House might issue a credential about the president of the United States 
+using `did:example:abc` as a subject identifier, saying in effect "The President 
+likes fried chicken." Then, the US National Parks Service might issue their own 
+credential about the president, using the same identifier, saying "The President authorizes
+the creation of new National Parks." 
+
+However, the White House meant "President Joe Biden", who is a physical person who 
+happened to be in office at the time the credential was issued. In contrast, 
+the park service meant "the current president, aka POTUS, whoever he is"; this second VC is not 
+about the Joe Biden as a human individual, it's about the role of President of
+the United States. 
+
+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.
+            </p>
+
           </dd>
 
+
           <dt><dfn class="export">verification method</dfn></dt>
           <dd>
             <p>
@@ -596,7 +647,7 @@ <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
-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
-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
 [[[#authentication]]].
             </p>
@@ -611,9 +662,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 service 
+endpoints. The [=controller document=] SHOULD
 contain [=verification relationships=] that explicitly permit the use of
 certain [=verification methods=] for specific purposes.
         </p>
@@ -828,33 +879,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
+[=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
-document and its canonical identifier. Proofs that satisfy a
+document. Proofs that satisfy a
-document and its canonical identifier. Proofs that satisfy a
+document. Proofs that satisfy a
+controller document's verification methods are taken as cryptographic
+assurance that the controller of the identifier created those proofs.
-assurance that the controller of the identifier created those proofs.
+assurance that the controller of the document created those proofs.
-assurance that the controller of the identifier created those proofs.
+assurance that the controller of the document created those proofs.
+            </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.
             </p>
-
             <dl>
               <dt>controller</dt>
               <dd>
-The `controller` property is OPTIONAL. If present, its value MUST be a
+The `controller` property is OPTIONAL. If it is possible to represent
+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
-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
-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
+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
+an entity capable of updating the canonical version
+of the [=controller document=].
+This means that subsequent requests for this controller document, 
+through its canonical location, would always contain the latest version.
+
+If the `controller` property is not present, then control of the document
+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">
 {
@@ -868,7 +952,7 @@ <h3>Controllers</h3>
 While the identifier used for a [=controller=] is unambiguous, this does not
 imply that a single entity is always the controller, nor that a controller
 only has a single identifier. A [=controller=] might be a single entity, or a
-collection of entities, such as a corporation. A [=controller=] might also use
+collection of entities, such as a partnership. A [=controller=] might also use
 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,
@@ -879,7 +963,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
-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
-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
 specification is used to, unsurprisingly, perform [=authentication=] while the
 other [=verification relationships=] such as `capabilityDelegation` and
@@ -944,8 +1028,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 
+the controlled identifier. A [=service=] can be
+any type of service the [=controller=] wants to advertise for further discovery,
 authentication, authorization, or interaction.
             </p>
 
@@ -1145,9 +1230,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.
+
+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
@@ -1680,11 +1771,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=] interactive sessions on behalf 
+of the controller document's base identifier. 
             </p>
           </section>