Merge pull request #85 from martipos/clarifications-v2.1

Clarifications of did:tdw features (abstract) and definitions - V2

spec/abstract.md

@@ -4,23 +4,25 @@ Trust DID Web (`did:tdw`) is an enhancement to the `did:web` DID method,
 providing complementary web-based features that address `did:web`'s
 limitations. `did:tdw` features include:
 
-- Ongoing publishing of all DID Document (DIDDoc) versions for a DID instead of,
+- Ongoing publishing of all DID Document ([[ref: DIDDoc]]) versions for a DID instead of,
   or alongside a current `did:web` DID/DIDDoc.
 - The same DID-to-HTTPS transformation as `did:web`.
 - Supports the same [High Assurance DID-to-DNS] mechanism.
 - The ability to resolve the full history of the DID using a verifiable chain of
   updates to the [[ref: DIDDoc]] from genesis to deactivation.
-- A [[def: self-certifying identifier]] (SCID) for the DID that is globally
-  unique, embedded in the DID, and derived from the initial [[ref: DIDDoc]]. The SCID
-  enables [[ref: DID portability]], such as moving the DID's web location (and
-  so changing the DID string itself) while retaining a connection to the
-  predecessor DID(s) and the DID's verifiable history.
-- [[ref: DIDDoc]] updates contain a proof signed by the controller(s) *authorized* to
+- A [[ref: self-certifying identifier]] (SCID) for the DID. The SCID, globally unique and
+  embedded in the DID, is derived from the initial [[ref: DID log entry]]. It ensures the integrity
+  of the DID's history mitigating the risk of attackers creating a new object with
+  the same identifier.
+- An optional mechanism for enabling [[ref: DID portability]] via the [[ref: SCID]], allowing
+  the DID's web location to be moved and the DID string to be updated, both while retaining
+  a connection to the predecessor DID(s) and preserving the DID's verifiable history.
+- [[ref: DIDDoc]] updates contain a proof signed by the [[ref: DID Controllers]] *authorized* to
   update the DID.
 - An optional mechanism for publishing "pre-rotation" keys to prevent the loss of
   control of a DID in cases where an active private key is compromised.
-- An optional mechanism for having collaborating "witnesses"
-  that approve of updates to the DID by the [[ref: DID Controller]] before publication.
+- An optional mechanism for having collaborating [[ref: witnesses]]
+  that approve of updates to the DID by a [[ref: DID Controller]] before publication.
 - DID URL path handling that defaults (but can be overridden) to automatically
   resolving `<did>/path/to/file` by using a comparable DID-to-HTTPS translation
   as for the [[ref: DIDDoc]].

spec/definitions.md

@@ -30,14 +30,15 @@ by the controller of the DID.
 
 [[def: DID Log, DID Logs]]
 
-~ A log of JSON arrays each of which provides the information necessary to
-generate and validate a version of the [[ref: DIDDoc]] from the previous version.
+~ A DID Log is a list of [[ref: Entries]] one being added for each update of an entry item,
+including new versions of the [[ref: DIDDoc]] or changed information necessary to generate or validate the DID.
 
-[[def: DID [[ref: Log Entry]], [[ref: DID Log]] Entries]]
+[[def: DID Log Entry, DID Log Entries, Entries]]
 
-~ A DID Log Entry is a JSON array of items that define the authorized
+~ A DID Log Entry is a JSON array of five items which define the authorized
 transformation of a [[ref: DIDDoc]] from one version to the next. The initial entry
-establishes the DID and version 1 of the [[ref: DIDDoc]].
+establishes the DID and version 1 of the [[ref: DIDDoc]]. All entries are stored
+in the [[ref: DID Log]].
 
 [[def: DID Method, DID Methods]]
 
@@ -48,15 +49,21 @@ the DID Method Specification for `DID:tdw`.
 
 [[def: DID Portability, DID:tdw portability, `DID:tdw` portability]]
 
-`did:tdw` [[ref: portability]] encompasses the ability to change the DID string for the
+~ `did:tdw` [[ref: portability]] encompasses the ability to change the DID string for the
 DID while retaining the [[ref: SCID]] and the history of the DID. This is useful
 when forced to change (such as when an organization is acquired by another,
 resulting in a change of domain names) and when changing DID hosting service
 providers.
 
-[[def: DID:web]]
+[[def: did:web]]
 
-~ `DID:web`...
+~ `did:web` as described in the [W3C specification](https://w3c-ccg.github.io/did-method-web/)
+is a DID method that leverages the Domain Name System (DNS) to perform the DID operations.
+It is valued for its simplicity and ease of deployment compared to DID methods that are
+based on distributed ledgers or blockchain technology, but also comes with increased
+challenges related to trust and security. `did:web` provides a starting point for `did:tdw`,
+which complements `did:web` with specific features to address the limitations
+while still providing ease of deployment.
 
 [[def: Entry Hash, entryHash]]
 

spec/header.md

@@ -14,6 +14,7 @@ Trust DID Web - `did:tdw`
 ~ [Andrew Whitehead](https://github.com/andrewwhitehead)
 ~ [Brian Richter](https://github.com/brianorwhatever)
 ~ [Michel Sahli](https://github.com/bj-ms)
+~ [Martina Kolpondinos](https://github.com/martipos)
 
 **Participate:**
 ~ [GitHub repo](https://github.com/bcgov/trustdidweb)