From 24a87ee7310af5021327b60f8969703f0af414aa Mon Sep 17 00:00:00 2001 From: Stephen Curran Date: Tue, 9 Apr 2024 14:12:19 -0700 Subject: [PATCH 1/5] Move whois use case to Abstract Signed-off-by: Stephen Curran Signed-off-by: Brian Richter --- spec/abstract.md | 27 +++++++++++++++++++++++---- spec/specification.md | 22 +++++----------------- 2 files changed, 28 insertions(+), 21 deletions(-) diff --git a/spec/abstract.md b/spec/abstract.md index a0c45ba..344c0fd 100644 --- a/spec/abstract.md +++ b/spec/abstract.md @@ -95,16 +95,35 @@ 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, but decentralized version of the `WHOIS` protocol, but for DIDs. Notably, when `/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. So given a DID, one can find out who controls that DID by calling `/whois` and processing the returned VP. That's powerful -- a decentralized trust registry. For `did:tdw`, the approach is very simple -- just transform the DID to its HTTPS equivalent, and `GET /whois`. Need to know who issued the VCs in the VP? Get the issuer DIDs from the VCs, and resolve `/whois`. This is comparable to walking a CA (Credential 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 an mining company 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 `/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 the 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. diff --git a/spec/specification.md b/spec/specification.md index 9c52da4..2fa1f66 100644 --- a/spec/specification.md +++ b/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 `/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 `/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: From 8ccbc75dfc15569106b8f4dc141c43604a2ce083 Mon Sep 17 00:00:00 2001 From: Brian Richter Date: Tue, 9 Apr 2024 20:27:41 -0700 Subject: [PATCH 2/5] Grammar correction Signed-off-by: Brian Richter --- spec/abstract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/abstract.md b/spec/abstract.md index 344c0fd..ef319a8 100644 --- a/spec/abstract.md +++ b/spec/abstract.md @@ -116,7 +116,7 @@ This DID Method introduces what we hope will be a widely embraced convention for We propose that the `/whois` path for a DID enable a comparable, but decentralized version of the `WHOIS` protocol, but for DIDs. Notably, when `/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. So given a DID, one can find out who controls that DID by calling `/whois` and processing the returned VP. That's powerful -- a decentralized trust registry. For `did:tdw`, the approach is very simple -- just transform the DID to its HTTPS equivalent, and `GET /whois`. Need to know who issued the VCs in the VP? Get the issuer DIDs from the VCs, and resolve `/whois`. This is comparable to walking a CA (Credential 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 an mining company 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 `/whois` of the entity and get back a Verifiable Presentation about that DID. It might contain: +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 `/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. From c352188b5c50b2554ae51ba187ad6d8279c7138a Mon Sep 17 00:00:00 2001 From: Brian Richter Date: Tue, 9 Apr 2024 20:27:56 -0700 Subject: [PATCH 3/5] Grammar correction Signed-off-by: Brian Richter --- spec/abstract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/abstract.md b/spec/abstract.md index ef319a8..06f22db 100644 --- a/spec/abstract.md +++ b/spec/abstract.md @@ -114,7 +114,7 @@ the [did:tdw Examples](#didtdw-example) of this specification. 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, but decentralized version of the `WHOIS` protocol, but for DIDs. Notably, when `/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. So given a DID, one can find out who controls that DID by calling `/whois` and processing the returned VP. That's powerful -- a decentralized trust registry. For `did:tdw`, the approach is very simple -- just transform the DID to its HTTPS equivalent, and `GET /whois`. Need to know who issued the VCs in the VP? Get the issuer DIDs from the VCs, and resolve `/whois`. This is comparable to walking a CA (Credential Authority) hierarchy, but self-managed by the DID Controllers -- and the issuers that attest to them. +We propose that the `/whois` path for a DID enable a comparable, decentralized, version of the `WHOIS` protocol for DIDs. Notably, when `/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 `/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 /whois`. Need to know who issued the VCs in the VP? Get the issuer DIDs from the VCs, and resolve `/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 `/whois` of the entity and get back a Verifiable Presentation about that DID. It might contain: From 41467e13c3f90f8981d875b277dcd38738f44bb7 Mon Sep 17 00:00:00 2001 From: Brian Richter Date: Tue, 9 Apr 2024 20:28:04 -0700 Subject: [PATCH 4/5] Grammar correction Signed-off-by: Brian Richter --- spec/abstract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/abstract.md b/spec/abstract.md index 06f22db..79d23ea 100644 --- a/spec/abstract.md +++ b/spec/abstract.md @@ -122,7 +122,7 @@ The following is a use case for the `/whois` capability. Consider an example of - 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 the both the London Metal Exchange and the standard, it can make a trust decision about the original Product Passport Verifiable Credential. +- 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. From 9e9b90f47b1822ba5c65b47cbc8077bcd7d929ec Mon Sep 17 00:00:00 2001 From: Brian Richter Date: Tue, 9 Apr 2024 20:28:25 -0700 Subject: [PATCH 5/5] Remove horizontal scroll in warning Signed-off-by: Brian Richter --- spec/abstract.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec/abstract.md b/spec/abstract.md index 79d23ea..e18526e 100644 --- a/spec/abstract.md +++ b/spec/abstract.md @@ -104,7 +104,8 @@ The following is a `tl;dr` summary of the specification summarizing how 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