Introduction to did:vh¶
Editors Draft
The did:vh specification is a
v0.1 Editors Draft. It can change at any time. The specification is the
authority: if this page disagrees with it, the specification is right.
did:vh (DID + Verifiable History) is a DID method that gives a DID a
cryptographically verifiable history without tying it to any location. It is
derived from did:webvh, and is the same method with the "web" taken out:
did:webvh:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ:example.com:dids:issuer
did:vh:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ
When a did:vh DID is shared, it can carry a hint about where its DID Log is
kept, in the ?src= DID URL parameter:
Why a DID Without a Location?¶
In did:webvh, the domain name does two jobs: it tells a resolver where to find
the DID Log, and it makes the DID a web identifier. It isn't needed for
security, because the SCID and the verifiable history provide that on their
own. But it does tie the DID to one location. When the location changes, the
DID changes. did:webvh handles this with its optional portability mechanism,
but the DID is still no longer the same string.
Many uses of DIDs need an identifier that never changes: a permanent account
identifier, a DID embedded in content-addressed data, or one held in long-lived
credentials. Others have no web location at all: DIDs exchanged between two
parties, DIDs kept in an organisation's database, or DIDs anchored on a ledger.
did:vh is for those uses.
What Is the Same as did:webvh¶
did:vh is deliberately as close to did:webvh as its lack of a location
allows. These are the same in both methods:
- The DID Log format: a JSON Lines file (
did.jsonl) of entries withversionId,versionTime,parameters,stateandproof. - The SCID and entry hash algorithms, chaining every entry to the one before.
- Key authorization and pre-rotation.
- Witnesses (identified by
did:keyDIDs) and the witness proofs file (did-witness.json). - Watchers.
- The
versionId,versionTimeandversionNumberresolution options.
The relationship section of the
specification
summarises the differences. An implementation of did:webvh can support
did:vh by replacing the DID-to-HTTPS transformation with the did:vh
resolution options, and dropping the features that depend on a web location.
What Is Different¶
did:webvh |
did:vh |
|
|---|---|---|
| DID | did:webvh:<SCID>:<domain>[:<path>] |
did:vh:<SCID> |
| Finding the DID Log | The DID-to-HTTPS transformation | The client sources the log and gives it to the resolver, possibly from a location named in a ?src= DID URL parameter |
method parameter values |
did:webvh:1.0 |
did:vh:1.0 |
Portability (portable parameter) |
Optional | Not used: the DID never changes |
Parallel did:web DID |
Optional | Not applicable |
DID URL paths, /whois, implicit #files and #whois services |
Defined | Not defined |
Resolving a did:vh DID¶
A did:vh resolver doesn't look for the DID Log. It implements the standard
DID Resolution resolve(did, resolutionOptions) function, and the client gives
it the DID Log and the witness proofs file (if any) in the did:vh resolution
options,
in one of two ways:
- Pass directly: the content of the files, in the
didLoganddidWitnessoptions. - Pass by reference: a reference to each file, in the
srcLogandsrcWitnessoptions. A reference can be a web location (https), a URL with another scheme the resolver supports (such asipns), or, for a resolver local to its client only, afile:URL or loopbackhttpweb location.
For example, passing the files by reference to a web location:
{
"did": "did:vh:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ",
"resolutionOptions": {
"srcLog": "https://example.com/dids/issuer/did.jsonl",
"srcWitness": "https://example.com/dids/issuer/did-witness.json"
}
}
The resolver verifies every entry of the log exactly as a did:webvh resolver
does, and returns the DIDDoc. A reference is not authoritative: it says
nothing about who controls the DID, and the log found there may not be the
latest.
The ?src= DID URL Parameter¶
A did:vh DID can be shared with a hint about where its DID Log is kept, by
adding the src DID URL query
parameter,
adopted from the proposed did:scid metamethod. Its value names the location
of the DID Log, that is, the location holding did.jsonl and (if witnesses
are active) did-witness.json:
src can be combined with the version selection parameters, such as
?src=https://example.com/dids/issuer&versionNumber=2.
When such a DID URL is dereferenced, the dereferencer (the resolver's client)
derives the file references by removing any trailing / from the src value
and appending the file names, then passes them by reference to the resolver:
{
"did": "did:vh:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ",
"resolutionOptions": {
"srcLog": "https://example.com/dids/issuer/did.jsonl",
"srcWitness": "https://example.com/dids/issuer/did-witness.json"
}
}
Alternatively, it retrieves the files itself and passes them directly in
didLog and didWitness. Some things to know about src:
- It is a DID URL parameter only. It is not a resolution option: a
resolver is always given
srcLogandsrcWitness(ordidLoganddidWitness). Likewise, those resolution options must not be used as DID URL parameters. - It is a hint, not an instruction. The dereferencer may apply its own
policy, for example using
srconly if it names a location the dereferencer trusts, or ignoring it in favour of a copy of the DID Log it already has.srcnever changes which version of the DIDDoc is returned. - It is not authoritative. Anyone can publish a copy of a DID Log at a
location they control, and anyone can put any
srcvalue in a DID URL. The domain in asrcvalue says nothing about who controls the DID. - It must be a safe URL. The value is an absolute
httpsURL (or a URL with another hierarchical scheme the resolver supports, such asipns), percent-encoded, with no query or fragment. Because a DID URL can come from an untrusted party,srcmust not be afile:orhttpURL. An invalidsrcvalue results in aninvalidDidUrlerror.
See Reading did:vh DID
URLs in the
specification for the full rules.
Sourcing the DID Log¶
Before resolving, the client needs to source the DID Log: get the log itself, or a reference to where it is kept. The specification describes the common ways non-normatively, and a log sourced in any of them is verified in the same way:
- Known in
context. The log,
or its location, arrives with the DID (for example, in a credential
exchange), is held by an ecosystem's DID host, was kept from an earlier
resolution, or is named in a
srcDID URL parameter. - From watchers. A
watcher indexes DID Logs by SCID, and a
did:vhDID is its SCID, so a client can ask a watcher for the log withGET <WATCHER URL>/log?scid=<SCID>. - Peer-to-peer
exchange.
Parties exchange DID Logs directly, in the manner of
did:peer, and send each other updates. Unlikedid:peer, the DIDs keep key rotation and pre-rotation. A newdid:vhDID can be created for each relationship. - From a web
location. A
location learned from a
srcparameter, from the DIDDoc'salsoKnownAsproperty, or from context.
Freshness and Duplicity¶
With no authoritative location, a client faces two risks that did:webvh
handles by trusting the DID's web location:
- Staleness: the copy of the log it has may be missing recent updates, such as a key rotation or deactivation.
- Duplicity: the DID Controller, or an attacker holding its keys, could fork the log and show different versions to different parties.
A client reduces these risks by sourcing the log from a source expected to be
current, such as a watcher listed in the log, and by comparing copies. A
resolver can do the comparison itself, using the checkWatchers,
extraWatchers and minCopies resolution options, and fails with logForked
if the log has been forked. Witnesses and watchers matter more for did:vh
than for did:webvh. DID Controllers of widely relied-on did:vh DIDs are
encouraged to use them, and relying parties are encouraged to use watchers they
trust. See Log Freshness and
Duplicity
in the specification.
Relationship to did:scid¶
The proposed
did:scid
metamethod defines a family of location-independent DIDs, each using the format
of an existing SCID-based DID method. Its did:scid:vh format uses the
did:webvh format, so it is comparable to did:vh. did:vh shares its design
goals and adopts its src parameter, but is a standalone DID method, and
carries the specification version in the method parameter of the log rather
than in the DID. See Relationship to
did:scid in
the specification.
Learn More¶
- The
did:vhspecification - The specification source on GitHub, for issues and discussion