Merge pull request decentralized-identity#35 from swcurran/whois-usecase

Move whois use case to Abstract

spec/abstract.md

@@ -95,16 +95,36 @@ The following is a `tl;dr` summary of the specification summarizing how
       keys (by reference) used by the DID currently, or in the past. This enables
       resolving both current and past DID URLs.
 7. `did:tdw` DID URLs with paths and `/whois` are resolved to documents
-  published by the DID Controller by default in the web location relative to the
-  `didlog.txt` file.
+  published by the DID Controller that are by default in the web location relative to the
+  `didlog.txt` file. See the [note below](#the-whois-use-case) about the
+   powerful capability enabled by the `/whois` DID URL path.
 8. Optionally, a DID Controller can generate and publish a `did:web` DIDDoc
   from the latest `did:tdw` DIDDoc by changing the `id` to the `did:web` DID,
   and adding an `alsoKnownAs` for the `did:tdw` (indicating to a resolver that
   they can verify the DIDDoc, if wanted).
+
   ::: warning
-    A resolver settling for just the `did:web` version of the DID
-    does not get the verifiability of the `did:tdw` log.
+    A resolver settling for just the `did:web` version of the DID does not get the **verifiability**
+    of the `did:tdw` log.
   :::
 
 An example of a `did:tdw` evolving through a series of versions can be seen in
 the [did:tdw Examples](#didtdw-example) of this specification.
+
+### The `/whois` Use Case
+
+This DID Method introduces what we hope will be a widely embraced convention for all DID Methods -- the `/whois` path. This feature harkens back to the `WHOIS` protocol that was created in the 1970s to provide a directory about people and entities in the early days of ARPANET. In the 80's, `whois` evolved into a [[spec-inform:rfc920]] that has expanded into the [global whois](https://en.wikipedia.org/wiki/WHOIS) feature we know today as [[spec-inform:rfc3912]]. Submit a `whois` request about a domain name, and get back the information published about that domain.
+
+We propose that the `/whois` path for a DID enable a comparable, decentralized, version of the `WHOIS` protocol for DIDs. Notably, when `<did>/whois` is resolved (using a standard DID `service` that follows the [[ref: Linked-VP]] specification), a [[ref: Verifiable Presentation]] (VP) may be returned (if published by the DID Controller) containing [[ref: Verifiable Credentials]] with the DID as the `credentialSubject`, and the VP signed by the DID. Given a DID, one can find out who controls that DID by calling `<did>/whois` and processing the returned VP. That's powerful -- a decentralized trust registry. For `did:tdw`, the approach is very simple -- transform the DID to its HTTPS equivalent, and `GET <https>/whois`. Need to know who issued the VCs in the VP? Get the issuer DIDs from the VCs, and resolve `<issuer did>/whois`. This is comparable to walking a CA (Certificate Authority) hierarchy, but self-managed by the DID Controllers -- and the issuers that attest to them.
+
+The following is a use case for the `/whois` capability. Consider an example of the `did:tdw` controller being a mining company that has exported a shipment and created a "Product Passport" Verifiable Credential with information about the shipment. A country importing the shipment (the Importer) might want to know more about the issuer of the VC, and hence, the details of the shipment. They resolve the `<did>/whois` of the entity and get back a Verifiable Presentation about that DID. It might contain:
+
+- A verifiable credential issued by the Legal Entity Registrar for the jurisdiction in which the mining company is headquartered.
+  - Since the Importer knows about the Legal Entity Registrar, they can automate this lookup to get more information about the company from the VC -- its legal name, when it was registered, contact information, etc.
+- A verifiable credential for a "Mining Permit" issued by the mining authority for the jurisdiction in which the company operates.
+  - Perhaps the Importer does not know about the mining authority for that jurisdiction. The Importer can repeat the `/whois` resolution process for the issuer of _that_ credential. The Importer might (for example), resolve and verify the `did:tdw` DID for the Authority, and then resolve the `/whois` DID URL to find a verifiable credential issued by the government of the jurisdiction. The Importer recognizes and trusts that government's authority, and so can decide to recognize and trust the mining permit authority.
+- A verifiable credential about the auditing of the mining practices of the mining company. Again, the Importer doesn't know about the issuer of the audit VC, so they resolve the `/whois` for the DID of the issuer, get its VP and find that it is accredited to audit mining companies by the [London Metal Exchange](https://www.lme.com/en/) according to one of its mining standards. As the Importer knows about both the London Metal Exchange and the standard, it can make a trust decision about the original Product Passport Verifiable Credential.
+
+Such checks can all be done with a handful of HTTPS requests and the processing of the DIDs and verifiable presentations. If the system cannot automatically make a trust decision, lots of information has been quickly collected that can be passed to a person to make such a decision.
+
+The result is an efficient, verifiable, credential-based, decentralized, multi-domain trust registry, empowering individuals and organizations to verify the authenticity and legitimacy of DIDs. The convention promotes a decentralized trust model where trust is established through cryptographic verification rather than reliance on centralized authorities. By enabling anyone to access and validate the information associated with a DID, the "/whois" path contributes to the overall security and integrity of decentralized networks.

spec/specification.md

@@ -490,10 +490,14 @@ publish about itself. The intention is that anyone interested in a particular
 `did:tdw` DID can resolve the a `<did>/whois` DID URL, and if returned, if it
 contains any useful (to the resolver) Verifiable Credentials that might help in
 learning more about who is the controller of the DID and if they should be
-trusted. It is up to the [[ref: DID Controller]] to decide to publish a `whois.vp`
+trusted. It is up to the [[ref: DID Controller]] to decide to publish a `whois`
 verifiable presentation and if so, which verifiable credentials to put into the
 verifiable presentation.
 
+See the [The `/whois` Use Case](#the-whois-use-case) in this specification for
+the background about why this capability is so useful, particularly for a
+web-based DID Method like `did:tdw`.
+
 `did:tdw` DIDs **automatically** supports a `#whois` service endpoint with the
 following definition based on the [[ref: Linked VP]] specification, with the `serviceEndpoint`
 matching the `did:tdw` DID-to-HTTPS DIDDoc transformation and `didlog.txt`
@@ -520,22 +524,6 @@ To resolve the DID URL `<did:tdw DID>/whois`, the resolver **MUST**:
    2. If the file at the defined `serviceEndpoint` is not found, return `Error 404: Not Found` **MUST** be returned.
 4. The web server handling the HTTPS get for the `/whois` endpoint **SHOULD** include an HTTP Header parameter with the MIME Type of the `whois` file.
 
-##### The `whois` Use Case
-
-This section is informative.
-
-The following is a use case for the `whois` capability. Consider an example of the `did:tdw` controller being an educational institution that issues "degree" verifiable credentials to its graduate students. A graduate from the school submits as part of their job application to a company a [[ref: Verifiable Presentation]] derived from the verifiable credential they received from the school. The company receiving the presentation can verify the cryptography of the presentation, but can they trust the the usefulness of a degree from the school that issued the verifiable credential? If the school issued the verifiable credential using its `did:tdw` DID, the company can resolve the DID. It can also resolve the DID's `/whois` DID URL Path where it might find VCs from issuers it trusts with the `did:tdw` DID as the subject. For example:
-
-- A verifiable credential issued by the Legal Entity Registrar for the jurisdiction in which the school is headquartered.
-  - Since the company knows about the Legal Entity Registrar, they can automate this lookup to get more information about the school from the verifiable credential -- its legal name, when it was registered, contact information, etc.
-- A verifiable credential issued by the "Association of Colleges and Universities" for the jurisdiction of the school.
-  - Perhaps the company does not know about the Association for that jurisdiction. The company can repeat the `whois` resolution process for the issuer of _that_ credential. The company might (for example), resolve and verify the `did:tdw` DID for the Association, and then resolve the `/whois` DID URL to find a verifiable credential issued by the government of the jurisdiction. The company recognizes and trusts that government's authority, and so can decide to recognize and trust the Association.
-- A verifiable credential issued by US News magazine about the school's placement on the [US News Rankings of Colleges and Universities].
-
-Such checks can all be done with a handful of HTTPS requests and the processing of the DIDs and verifiable presentations. The result is an efficient, verifiable, credential-based, decentralized, multi-domain trust registry.
-
-[US News Rankings of Colleges and Universities]: https://www.usnews.com/education/best-global-universities
-
 #### DID URL Path Resolution Service
 
 The automatic resolution of `did:tdw` DID URL paths follows the [[spec:DID-CORE]] `relativeRef` specification, as follows: