Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add non-normative DID Resolution and Dereferencing sections to Architecture. #262

Merged
merged 14 commits into from
May 1, 2020
Merged

Add non-normative DID Resolution and Dereferencing sections to Architecture. #262

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
153428f
Add initial content for DID Resolution.
peacekeeper Mar 30, 2020
1e352bb
Apply suggestions by @brentzundel.
peacekeeper Apr 2, 2020
7ae96d4
Rename "input options" to "resolver options".
peacekeeper Apr 4, 2020
e36700c
Make structures required, specify formats.
jricher Apr 6, 2020
a27d4d4
Prepare repo for @jricher's rewrite of DID Resolution.
msporny May 1, 2020
1b944da
Add DID Resolution and Dereferencing to Architecture section.
jricher Apr 8, 2020
77d8765
Split Resolvers from Dereferencers.
msporny Apr 20, 2020
72c3a3f
Editorial fixes for DID Dereferencing section.
msporny Apr 20, 2020
bf7ef6e
Move definition of "binding" to terminology.
msporny Apr 20, 2020
ab1b586
Fix incorrect MIME Type usage.
msporny Apr 21, 2020
49c42b7
Apply non-normative DID Resolution suggestions from @jricher.
msporny Apr 23, 2020
74d77a6
Clarify language referring to DID Resolution.
msporny Apr 23, 2020
d9833cb
Fix broken references.
msporny May 1, 2020
e83669a
Apply provided/discussed suggestion from @jricher.
msporny May 1, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added diagrams/binding-local.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added diagrams/binding-remote.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
154 changes: 102 additions & 52 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,18 +154,18 @@
<a>Decentralized identifiers</a> (DIDs) are a new type of identifier that
enables verifiable, decentralized digital identity. A <a>DID</a> identifies
any subject (e.g., a person, organization, thing, data model, abstract entity, etc.)
that the controller of the <a>DID</a> decides that it
identifies. These new identifiers are designed to enable the controller
of a <a>DID</a> to prove control over it and to be implemented independently
of any centralized registry, identity provider, or certificate authority.
<a>DID</a>s are URLs that associate a <a>DID subject</a> with a
<a>DID document</a> allowing trustable interactions associated with that subject.
Each <a>DID document</a> can express cryptographic material, verification methods,
or <a>service endpoints</a>, which provide a set of mechanisms enabling a
<a>DID controller</a> to prove control of the <a>DID</a>. <a>Service
endpoints</a> enable trusted interactions associated with the <a>DID
subject</a>. A <a>DID document</a> might contain semantics about the subject
that it identifies. A <a>DID document</a> might contain the <a>DID subject</a>
that the controller of the <a>DID</a> decides that it
identifies. These new identifiers are designed to enable the controller
of a <a>DID</a> to prove control over it and to be implemented independently
of any centralized registry, identity provider, or certificate authority.
<a>DID</a>s are URLs that associate a <a>DID subject</a> with a
<a>DID document</a> allowing trustable interactions associated with that subject.
Each <a>DID document</a> can express cryptographic material, verification methods,
or <a>service endpoints</a>, which provide a set of mechanisms enabling a
<a>DID controller</a> to prove control of the <a>DID</a>. <a>Service
endpoints</a> enable trusted interactions associated with the <a>DID
subject</a>. A <a>DID document</a> might contain semantics about the subject
that it identifies. A <a>DID document</a> might contain the <a>DID subject</a>
Comment on lines +157 to +168
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do these need to be in this specific pull request? There are several similar changes here. Space cleanup commits like this should be left to separate pull requests so as not to distract from discussion on content.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, agreed, ideally they would be. Merging anyway so that these are fixed when merged into the main document. Will rebase the other PRs so they show up there.

itself (e.g. a data model).
</p>
<p>
Expand Down Expand Up @@ -630,7 +630,41 @@ <h2>DID Documents</h2>
</section>

<section>
<h2>DID Resolvers and DID Resolution</h2>
<h2>DID Resolvers</h2>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think these two sections flow better as a single section, especially at this level of the document.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or better yet, remove this section and incorporate its content into the resolution and dereferencing contract sections below.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As discussed on the call, leaving this as-is for now to talk about the "nouns" in the architecture, and then what the nouns do.


<p>
A <a>DID resolver</a> is a software and/or hardware component that takes a
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's confusing to talk about the component first and then the process that defines them, I would suggest that this be reversed. However, realizing that this section is defining components of the architecture and not actions of the architecture, this ordering might be desired. With that in mind, perhaps these pieces should be moved to the resolution section below instead.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As discussed on the call, leaving this as-is for now to talk about the "nouns" in the architecture, and then what the nouns do.

<a>DID</a> (and associated options) as input and produces a <a>conforming
DID document</a> (and associated metadata) as output in a process
called <a>DID resolution</a>.
</p>
<p>
The inputs and outputs of the <a>DID resolution</a> process are defined in
<a href="#did-resolution"></a>. Additional considerations for implementing a
<a>DID resolver</a> are discussed in [[?DID-RESOLUTION]].
</p>
</section>

<section>
<h2>DID Dereferencers</h2>

<p>
A <a>DID URL dereferencer</a> is a software and/or hardware component that takes
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment about ordering above: define the process, then the component that provides that process.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As discussed on the call, leaving this as-is for now to talk about the "nouns" in the architecture, and then what the nouns do.

a <a>DID URL</a> as input (and associated options) and produces a resource (and
associated metadata) as output in a process called <a>DID URL
dereferencing</a>. The resource produced by <a>DID URL dereferencing</a> might or might not be a
<a>conforming DID Document</a>. Generally, a <a>DID URL dereferencer</a> uses a
<a>DID resolver</a> to execute <a>DID resolution</a> on the <a>DID</a> portion
of a <a>DID URL</a> to obtain a <a>DID document</a>. The <a>DID URL
dereferencer</a> can then perform additional dereferencing on the <a>DID
document</a> using the complete <a>DID URL</a>.
</p>

<p>
The inputs and outputs of the <a>DID URL dereferencing</a> process are defined in
<a href="#did-url-dereferencing"></a>. Additional considerations for implementing a
<a>DID URL dereferencer</a> are discussed in [[?DID-RESOLUTION]].
</p>
</section>

<section>
Expand Down Expand Up @@ -808,8 +842,8 @@ <h2>Persistence</h2>
</p>

<p class="note">
To avoid these issues, developers should refer to the Decentralized Characteristics
Rubric [[?DID-RUBRIC]] to decide which <a>DID method</a> best addresses the needs of
To avoid these issues, developers should refer to the Decentralized Characteristics
Rubric [[?DID-RUBRIC]] to decide which <a>DID method</a> best addresses the needs of
the use case.
</p>

Expand Down Expand Up @@ -933,23 +967,24 @@ <h2>Generic DID URL Parameters</h2>
</table>

<p>
The exact processing rules for these parameters are specified in
[[?DID-RESOLUTION]].
Additional considerations for processing these parameters are discussed
in [?DID-RESOLUTION].
</p>

<p>
Adding a DID parameter to a DID URL means that the parameter becomes part of
an identifier for a <a>resource</a> (the DID document or other). Alternatively, the
DID resolution and the DID URL dereferencing processes can also be influenced
by passing options to a <a>DID resolver</a> that are not part of the DID URL.
Adding a DID parameter to a <a>DID URL</a> means that the parameter becomes part of
an identifier for a <a>resource</a> (the <a>DID document</a> or other). Alternatively, the
<a>DID resolution</a> and the <a>DID URL dereferencing</a> functions can also be influenced
by passing input metadata to a <a>DID resolver</a> that are not part of the DID URL.
(See <a href="#metadata-structure"></a>).
Such options could for example control caching or the desired encoding of a
resolution result. This is comparable to HTTP, where certain parameters could
either be included in an HTTP URL, or alternatively passed as HTTP headers
during the dereferencing process. The important distinction is that DID
parameters that are part of the <a>DID URL</a> should be used to specify
<i>what <a>resource</a> is being identified</i>, whereas <a>DID resolver</a> options
<i>what <a>resource</a> is being identified</i>, whereas <a>DID resolution</a> options
that are not part of the <a>DID URL</a> should be use to control <i>how that
<a>resource</a> is dereferenced</i>.
<a>resource</a> is resolved or dereferenced</i>.
</p>

<p>
Expand Down Expand Up @@ -1076,11 +1111,11 @@ <h2>Fragment</h2>
document</a> to identify a component of the document (for example, a unique
<a>public key description</a> or <a>service endpoint</a>). <a>DID fragment</a>
syntax and semantics are identical to a generic URI fragment and MUST conform
to <a data-cite="RFC3986#section-3.5">RFC&nbsp;3986, section 3.5</a>. To resolve
a <a>DID fragment</a> reference, the complete <a>DID URL</a> including the
<a>DID fragment</a> MUST be used as input to the <a>DID URL</a> dereferencing
algorithm for the target component in the <a>DID document</a> object. For more
information, see [[?DID-RESOLUTION]].
to <a data-cite="RFC3986#section-3.5">RFC&nbsp;3986, section 3.5</a>. To dereference
a <a>DID fragment</a>, the complete <a>DID URL</a> including the
<a>DID fragment</a> MUST be used as input to the <a>DID URL dereferencing</a>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just catching this now. Would it be considered derefencing if I used did:example:123?id=key1? I know we still have to discuss the usage of id query parameter, but figured it should be considered here as well.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I noticed the contract has been removed at this point, but I'm hoping it will come back with your addition of normative statements.

Yes, that's planned in the next PR that layers on top of this one.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be considered derefencing if I used did:example:123?id=key1?

Yes, given that id=key1 becomes a DID Parameter whose purpose is to dereference to a key in the DID Document.

That said, I think that doing this is a bad idea. :)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's part of the separation of concerns between resolution and dereferencing here: the resolution takes only the DID while dereferencing takes in the whole URL. The way the functions and inputs are defined in #253 the query parameters are NOT passed as inputs to the resolution function -- the input metadata is for information outside of the URL, much like HTTP request headers.

Copy link
Member

@kdenhartog kdenhartog Apr 22, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be considered derefencing if I used did:example:123?id=key1?

Yes, given that id=key1 becomes a DID Parameter whose purpose is to dereference to a key in the DID Document.

That said, I think that doing this is a bad idea. :)

Would doing that require an extended document loader to handle that de-referencing which is why you're less than enthused about that approach?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's the concept of "get me this thing that is expressed in the DID Document using this syntax that duplicates the use of fragment identifiers" that is problematic. If you want the key, get the DID Document, look for the key's fragment identifier, and you're done... w/o needing a DID Parameter for that feature. It can be done w/ a simple convenience function.

Copy link
Member

@kdenhartog kdenhartog Apr 24, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

could did:example:123?id=key1 be used as an iri as well if the producer chose to do so? I'm really just trying to understand the edge cases here. I stick to fragments here normally cause they're easier to deal with and commonly used by everyone.

function for the target component in the <a>DID document</a> object. For more
information, see <a href="#did-url-dereferencing"></a>.
</p>

<p>
Expand Down Expand Up @@ -1238,7 +1273,7 @@ <h2>DID Subject</h2>
<p class="note">
<a>DID method</a> specifications can create intermediate representations of a
<a>DID document</a> that do not contain the <code>id</code> key, such as when a
<a>DID resolver</a> is performing resolution. However, the fully resolved
<a>DID resolver</a> is performing <a>DID resolution</a>. However, the fully resolved
<a>DID document</a> always contains a valid <code>id</code> property. The value
of <code>id</code> in the resolved <a>DID document</a> is expected to match the
<a>DID</a> that was resolved.
Expand Down Expand Up @@ -1352,10 +1387,10 @@ <h2>Public Keys</h2>
</p>

<p>
The value of the <code>id</code> property MAY be structured as a <a href="https://en.wikipedia.org/wiki/Compound_key">compound key</a>.
The value of the <code>id</code> property MAY be structured as a <a href="https://en.wikipedia.org/wiki/Compound_key">compound key</a>.
This is especially useful for integrating with existing key management systems and key formats such as <a href="https://tools.ietf.org/html/rfc7517">JWK</a>.
It is RECOMMENDED that <a href="https://tools.ietf.org/html/rfc7517">JWK</a> <code>kid</code> values are set to the <a href="https://tools.ietf.org/html/rfc7638">public key fingerprint</a>.
It is RECOMMENDED that verification methods that use JWKs to represent their
It is RECOMMENDED that <a href="https://tools.ietf.org/html/rfc7517">JWK</a> <code>kid</code> values are set to the <a href="https://tools.ietf.org/html/rfc7638">public key fingerprint</a>.
It is RECOMMENDED that verification methods that use JWKs to represent their
public keys utilize the value of <code>kid</code> as their fragment identifier.
See the first key in <a href="#example-12-various-public-keys">EXAMPLE 12</a> for an example of a public key with a compound key identifier.
</p>
Expand Down Expand Up @@ -1991,7 +2026,8 @@ <h1>Core Representations</h1>
<p>
Producers MUST indicate which representation of a document has been used via a media type
in the document's metadata. Consumers MUST determine which representation a document is in
via a media type in the document's metadata. Consumers MUST NOT determine the representation
via the <code>content-type</code> DID resolver metadata field. (See <a href="#did-resolution"></a>).
Consumers MUST NOT determine the representation
kdenhartog marked this conversation as resolved.
Show resolved Hide resolved
of a document through its content alone.
</p>

Expand Down Expand Up @@ -2019,8 +2055,9 @@ <h2>
</h2>

<p>
When producing and consuming DID documents that are in plain JSON (as noted by
the document metadata), the following rules MUST be followed.
When producing and consuming DID documents that are in plain JSON (as indicated
by a <code>content-type</code> of <code>application/did+json</code> in the
resolver metadata), the following rules MUST be followed.
</p>

<section>
Expand Down Expand Up @@ -2161,8 +2198,9 @@ <h2>
</p>

<p>
When producing and consuming DID documents that are in JSON-LD (as noted by
the document metadata), the following rules MUST be followed.
When producing and consuming DID documents that are in JSON-LD (as indicated by
a <code>content-type</code> of <code>application/did+ld+json</code> in the
resolver metadata), the following rules MUST be followed.
</p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same remark as above: application/json+did does not sound right. Shouldn't it be application/did+json?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct, that was wrong, thanks @iherman!

Fixed in 4f1c79c.


<ul>
Expand Down Expand Up @@ -2416,13 +2454,13 @@ <h3>
The <a>DID method</a> specification MUST specify how a client can update a
<a>DID document</a> on the <a>DID registry</a>, including all cryptographic
operations necessary to establish proof of control, <em>or</em> state that
updates are not possible.
updates are not possible.
</p>

<p>
An update to a <a>DID</a> is any change, after creation, in the data used to produce a <a>DID document</a>.
<a>DID Method</a> implementers are responsible for defining what constitutes an update,
and what properties of the <a>DID document</a> are supported by a given <a>DID method</a>.
An update to a <a>DID</a> is any change, after creation, in the data used to produce a <a>DID document</a>.
<a>DID Method</a> implementers are responsible for defining what constitutes an update,
and what properties of the <a>DID document</a> are supported by a given <a>DID method</a>.
For example, an update operation which replaces key material without changing it could be a valid update that does not result in changes to the <a>DID document</a>.
</p>
</section>
Expand Down Expand Up @@ -2544,17 +2582,29 @@ <h1>
</h1>

<p>
A <a>DID resolver</a> is a software or hardware component with an API for
resolving <a>DIDs</a> of at least one <a>DID method</a>. It executes the read
operation for the <a>DID method</a> corresponding to the <a>DID</a> being
resolved to obtain the authoritative <a>DID document</a>. For more information,
see Section <a href="#read-verify"></a>.
This section defines the inputs and outputs of the
<a>DID resolution</a> and <a>DID URL dereferencing</a> processes. The
exact implementation of these functions is out of scope for this specification,
but some considerations for implementors are available in [[?DID-RESOLUTION]].
</p>

<p>
The interfaces and algorithms for resolving <a>DIDs</a> and dereferencing
<a>DID URLs</a> are specified in [[?DID-RESOLUTION]].
</p>
<section>
<h2>
DID Resolution
</h2>
</section>

<section>
<h2>
DID URL Dereferencing
</h2>
</section>

<section>
<h2>
Metadata Structure
</h2>
</section>

</section>

Expand Down Expand Up @@ -2915,8 +2965,8 @@ <h2>
Encrypted Data in DID Documents
</h2>
<p>
DID documents are typically publicly available. Encryption algorithms have been
known to fail due to advances in cryptography and computing power.
DID documents are typically publicly available. Encryption algorithms have been
known to fail due to advances in cryptography and computing power.
Implementers are advised to assume that any
encrypted data placed in a <a>DID document</a> might eventually be made available in clear
text to the same audience to which the encrypted data is available.
Expand Down
43 changes: 40 additions & 3 deletions terms.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,13 @@
ledger.
</dd>

<dt><dfn>binding</dfn></dt>
<dd>
A concrete mechanism through which a caller invokes a <a>DID resolver</a> or a
<a>DID URL dereferencer</a>. This could be a local command line tool, a
software library, or a network call such as an HTTPS request.
</dd>

<dt><dfn data-lt="decentralized identifiers|DID|DIDs">decentralized identifier</dfn> (DID)</dt>

<dd>
Expand Down Expand Up @@ -123,12 +130,22 @@
verifiable data registry. For more information, see [[VC-DATA-MODEL]].
</dd>

<dt><dfn>DID resolution</dfn></dt>

<dd>
The function that takes as its input a <a>DID</a> and a set of input
metadata and returns a <a>DID document</a> in a conforming representation
plus additional metadata. This function relies on the "Read" operation of the
applicable <a>DID method</a>. The inputs and outputs of this function are defined
in <a href="#did-resolution"></a>.
</dd>

<dt><dfn data-lt="DID resolvers">DID resolver</dfn></dt>

<dd>
A system that is capable of retrieving a <a>DID document</a> for a given
<a>DID</a>. These systems are specified in the DID Resolution specification
[[DID-RESOLUTION]].
A <a>DID resolver</a> is a software and/or hardware component that takes
a <a>DID</a> as input and produces a <a>conforming DID document</a> as
output by performing <a>DID resolution</a>.
</dd>

<dt><dfn data-lt="DID schemes">DID scheme</dfn></dt>
Expand All @@ -154,6 +171,26 @@
by a <a>DID fragment</a>.
</dd>

<dt><dfn>DID URL dereferencing</dfn></dt>

<dd>
The function that takes as its input a <a>DID URL</a>, a <a>DID document</a>,
and a set of dereferencing options and returns a resource, which might be
a <a>DID document</a>, plus additional metadata. This function can use the <a>DID resolution</a>
function to fetch a <a>DID document</a> indicated by the <a>DID</a> within the <a>DID URL</a>.
The dereferencing function then can perform additional processing on the <a>DID document</a> to return
the dereferenced resource indicated by the <a>DID URL</a>. The inputs and outputs of this
process are defined in <a href="#did-url-dereferencing"></a>.
</dd>

<dt><dfn data-lt"DID URL dereferencers">DID URL dereferencer</dfn></dt>

<dd>
A software and/or hardware system that is capable of executing the <a>DID URL dereferencing</a>
function, retrieving some form of data, which might or might not be a <a>DID document</a>) for a given
<a>DID URL</a> by performing <a>DID URL dereferencing</a>.
</dd>

<dt><dfn data-lt="distributed ledger technology|DLT">distributed ledger</dfn> (DLT)</dt>

<dd>
Expand Down