Skip to content

Commit

Permalink
Merge pull request #80 from swcurran/main
Browse files Browse the repository at this point in the history 
Align defs and refs
  • Loading branch information
@swcurran
swcurran authored Jul 29, 2024
2 parents e3dfa22 + d4ad812 commit 8bb4598
Show file tree
Hide file tree
Showing 7 changed files with 439 additions and 417 deletions.
12 changes: 6 additions & 6 deletions spec/abstract.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,23 +9,23 @@ limitations. `did:tdw` features include:
- 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 DIDDoc from genesis to deactivation.
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 DIDDoc. The SCID
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.
- DIDDoc updates contain a proof signed by the controller(s) *authorized* to
- [[ref: DIDDoc]] updates contain a proof signed by the controller(s) *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 DID Controller before publication.
that approve of updates to the DID by the [[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 DIDDoc.
as for the [[ref: DIDDoc]].
- A DID URL path `<did>/whois` that defaults to automatically returning (if
published by the DID controller) a [[ref: Verifiable Presentation]] containing
published by the [[ref: DID controller]]) a [[ref: Verifiable Presentation]] containing
[[ref: Verifiable Credentials]] with the DID as the `credentialSubject`,
signed by the DID.

Expand Down
208 changes: 115 additions & 93 deletions spec/definitions.md
View file
Original file line number Diff line number Diff line change
@@ -1,49 +1,9 @@
## Definitions

[[def: DID Log]]

~ A log of JSON arrays each of which provides the information necessary to
generate and validate a version of the DIDDoc from the previous version.

[[def: JSON Lines]]

~ A file of JSON Lines, as described on the site
[https://jsonlines.org/](https://jsonlines.org/). In short, `JSONL` is lines of JSON with
whitespace removed and separated by a newline that is convenient for handling
streaming JSON data or log files.

[[def: self-certifying identifier, SCID]]

~ An object identifier derived from initial data such that an attacker could not
create a new object with the same identifier. The input for a `did:tdw` SCID is
the initial DIDDoc with the placeholder `{SCID}` wherever the SCID is to be
placed.

[[def: parameters]]

~ `did:tdw` parameters are a defined set of configurations that control how the
issuer has generated the DID, and how the resolver should process the DID Log
entries. The use of parameters allows for the controlled evolution of `did:tdw`
log handling, such as evolving the permitted hash algorithms.

[[def: ISO8601, ISO8601 String]]

~ A date/time expressed using the [ISO8601
Standard](https://en.wikipedia.org/wiki/ISO_8601).

[[def: DID Controller]]

~ Per the [[spec:DID-CORE]], a DID controller is an entity that is authorized to
make changes to a DID document.

[[def: Entry Hash]]

~ A `did:tdw` entry hash is a hash generated using a formally defined process over
the data of a log entry. The generated entry hash is subsequently put into the
log entry and *MUST* be verified by a resolver.
[[def: base58btc]]

[[def: multihash]]
~ Per the [[spec:draft-multiformats-multihash-07]], Multihash is a specification for differentiating hashes. Multihash defines that by prefixing hashes with a hash function identifier and the hash size.
~ Applies [[spec:draft-msporny-base58-03]] to convert
data to a `base58` encoding. Used in `did:tdw` for encoding hashes for [[ref: SCIDs]] and [[ref: entry hashes]].

[[def: Data Integrity]]

Expand All @@ -53,84 +13,106 @@ is a specification of mechanisms for ensuring the authenticity and integrity of
structured digital documents using cryptography, such as digital signatures and
other digital mathematical proofs.

[[def: JSON Patch]]
[[def: Decentralized Identifier, Decentralized Identifiers]]

~ Decentralized Identifiers (DIDs) [[spec:did-core]] are a type of identifier that enable
verifiable, decentralized digital identities. A DID refers to any subject (e.g.,
a person, organization, thing, data model, abstract entity, etc.) as determined
by the controller of the DID.

[[def: DIDDoc]]

~ A DID Document as defined by the [[spec: DID-Core]] -- the document returned when a DID is resolved.

~ [[spec:rfc6902]] is a web
standard format for describing how to change a JSON document from one state to
another. It is used in `did:tdw` to define how a DIDDoc is changed from one
version to the next.
[[def: DID:key]]

[[def: Key Pre-Rotation]]
~ `DID:key`...

~ A technique for a controller of a cryptographic key to commit to the next public
key that it will use for a purpose, without exposing the public key. It protects
from an attacker that gains knowledger of the current private key from being
able to rotate to a new key the controller does not know.
[[def: DID Log, DID Logs]]

[[def: DID Log Entry, DID Log Entries]]
~ 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.

[[def: DID [[ref: Log Entry]], [[ref: DID Log]] Entries]]

~ A DID Log Entry is a JSON array of items that define the authorized
transformation of a DIDDoc from one version to the next. The initial entry
establishes the DID and version 1 of the DIDDoc.
transformation of a [[ref: DIDDoc]] from one version to the next. The initial entry
establishes the DID and version 1 of the [[ref: DIDDoc]].

[[def: DID Method, DID Methods]]

~ DID methods are the mechanism by which a particular type of DID and its
associated DID document are created, resolved, updated, and deactivated. DID
methods are defined using separate DID method specifications. This document is
the DID Method Specification for `DID:tdw`.

[[def: DID Portability, did:tdw portability, `did:tdw` portability]]
[[def: DID Portability, DID:tdw portability, `DID:tdw` portability]]

`did:tdw` 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: base58btc]]
[[def: DID:web]]

~ Applies [[spec:draft-msporny-base58-03]] to convert
data to a `base58` encoding.
~ `DID:web`...

[[def: Linked-VP, Linked Verifiable Presentation]]
[[def: Entry Hash, entryHash]]

~ A [[spec:DID-CORE]] `service` entry that specifies where a [[ref: verifiable presentation]] about the
DID subject can be found. The Decentralized Identity Foundation hosts the [Linked VP Specification](https://identity.foundation/linked-vp/).
~ A `DID:tdw` entry hash is a hash generated using a formally defined process
over the input data to a [[ref: log entry]], excluding the [[ref: Data Integrity]] proof
item. The input data includes content from the predecessor to the version of the
DID, ensuring that all the versions are "chained" together in a microledger. The
generated [[ref: entry hash]] is subsequently included in the `versionId` element of the [[ref: log entry]] and **MUST** be
verified by a resolver.

[[def: Verifiable Credential, Verifiable Credentials]]

~ A verifiable credential can represent all of the same information that a physical credential represents, adding technologies such as digital signatures, to make the credentials more tamper-evident and so more trustworthy than their physical counterparts. The [Verifiable Credential Data Model](https://www.w3.org/TR/vc-data-model/) is a W3C Standard.

[[def: Verifiable Presentation]]
[[def: ISO8601, ISO8601 String]]

~ A verifiable presentation data model is part W3C's [Verifiable Credential Data
Model](https://www.w3.org/TR/vc-data-model/) that contains a set of [[ref:
verifiable credentials]] about a `credentialSubject`, and a signature across the
set of VCs generated by that subject. In this specification, the use case of
primary interest is where the DID is the `credentialSubject` and the DID signs
the verifiable presentation.
~ A date/time expressed using the [ISO8601
Standard](https://en.wikipedia.org/wiki/ISO_8601).

[[def: JSON Canonicalization Scheme]]

~ The [[spec:rfc8785]] canonicalizes a JSON
~ [[spec:rfc8785]] defines a method for canonicalizing a JSON
structure such that is suitable for verifiable hashing or signing.

[[def: Decentralized Identifier, Decentralized Identifiers, DID]]
[[def: JSON Lines]]

~ Decentralized Identifiers (DIDs) [[spec:did-core]] are a type of identifier that enable
verifiable, decentralized digital identities. A DID refers to any subject (e.g.,
a person, organization, thing, data model, abstract entity, etc.) as determined
by the controller of the DID.
~ A file of JSON Lines, as described on the site
[https://jsonlines.org/](https://jsonlines.org/). In short, `JSONL` is lines of JSON with
whitespace removed and separated by a newline that is convenient for handling
streaming JSON data or log files.

[[def: DID Method, DID Methods]]
[[def: JSON Patch]]

~ DID methods are the mechanism by which a particular type of DID and its
associated DID document are created, resolved, updated, and deactivated. DID
methods are defined using separate DID method specifications. This document is
the DID Method Specification for `did:tdw`.
~ [[spec:rfc6902]] is a web standard format for describing how to change a JSON
document from one state to another. A [[ref: DID Controller]] **MAY** use it in `DID:tdw`
to define how a [[ref: DIDDoc]] is changed from one version to the next.

[[def: Pre-Rotation]]

~ A technique for a controller of a cryptographic key to commit to the public
key it will rotate to next, without exposing that actual public key. It protects
from an attacker that gains knowledge of the current private key from being
able to rotate to a new key known only to the attacker.

[[def: Verifiable Conditions, verifiableConditions]]
[[def: Linked-VP, Linked Verifiable Presentation]]

~ A [[spec:DID-CORE]] `service` entry that specifies where a [[ref: verifiable
presentation]] about the DID subject can be found. The [Decentralized Identity
Foundation](https://identity.foundation/) hosts the [Linked VP
Specification](https://identity.foundation/linked-vp/).

[[def: multihash]]

~ The (proposed) [verifiableConditions
Specification](https://github.com/w3c-ccg/verifiable-conditions) defines a way
to express complex conditions and additional metadata about verification
methods. It can be used to combine verification methods to form conjugated
conditions such as logical operations (like &&), thresholds, weighted
thresholds, relationships, or delegation to external verification methods.
~ Per the [[spec:draft-multiformats-multihash-07]], [[ref: multihash]] is a specification
for differentiating instances of hashes. Software creating a hash prefixes
(according to the specification) data to the hash indicating the algorithm used
and the length of the hash, so that software receiving the hash knows how to
verify it. Although [[ref: multihash]] supports many hash algorithms, for
interoperability, [[ref: DID Controllers]] **MUST** only use the hash algorithms defined
in this specification as permitted.

[[def: multi-sig, multisig]]

Expand All @@ -139,3 +121,43 @@ thresholds, relationships, or delegation to external verification methods.
multi-signature key reference points to a verification method that defines what
keys may contribute to the signature, and under what conditions the
multi-signature is considered valid.

[[def: parameters]]

~ `DID:tdw` [[ref: parameters]] are a defined set of configurations that control how the
issuer has generated the DID, and how the resolver should process the DID [[ref: Log
entries]]. The use of [[ref: parameters]] allows for the controlled evolution of `DID:tdw`
log handling, such as evolving the permitted hash algorithms.

[[def: self-certifying identifier, SCID, SCIDs]]

~ An object identifier derived from initial data such that an attacker could not
create a new object with the same identifier. The input for a `DID:tdw` SCID is
the initial [[ref: DIDDoc]] with the placeholder `{SCID}` wherever the SCID is to be
placed.

[[def: Verifiable Credential, Verifiable Credentials]]

~ A verifiable credential can represent all of the same information that a physical credential represents, adding technologies such as digital signatures, to make the credentials more tamper-evident and so more trustworthy than their physical counterparts. The [Verifiable Credential Data Model](https://www.w3.org/TR/vc-data-model/) is a W3C Standard.

[[def: Verifiable Presentation, Verifiable Presentations]]

~ A [[ref: verifiable presentation]] data model is part W3C's [Verifiable Credential Data
Model](https://www.w3.org/TR/vc-data-model/) that contains a set of [[ref:
verifiable credentials]] about a `credentialSubject`, and a signature across the
verifiable credentials generated by that subject. In this specification, the use
case of primary interest is where the DID is the `credentialSubject` and the DID
signs the [[ref: verifiable presentation]].

[[def: witness, witnesses]]

~ Witnesses are participants in the process of creating and verifying a version
of a `DID:tdw` [[ref: DIDDoc]]. Notably, a witness receives from the [[ref: DID Controller]] a [[ref: DID
Log]] entry ready for publication, verifies it according to this specification,
and approves it according to its ecosystem governance (whatever that might be). If the verification and
approval process results are positive, witnesses returns to the DID Controller a [[ref: Data Integrity]] proof
attesting to that positive result.

[[def: W3C VCDM]]

~ A Verifiable Credential that uses the Data Model defined by the W3C [[spec: W3C-VC]] specification.
Loading

0 comments on commit 8bb4598

Please sign in to comment.