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

Simplify id property via separation of deterministic equivalence functionality #431

Closed
wants to merge 32 commits into from
Closed

Simplify id property via separation of deterministic equivalence functionality #431

Changes from 16 commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
cbde13f
Modify id prop to clarify equivalent DID allowance
Aug 20, 2020
39c4d39
Update normative directive from SHOULD to MUST
Aug 21, 2020
be5f177
Update index.html
csuwildcat Aug 24, 2020
0b0e82d
Update to add in requested changes
Aug 25, 2020
e03e448
removing errant vscode settings file
Aug 26, 2020
2559e6a
update to more closely match suggestions
Aug 26, 2020
5f677ba
Merge branch 'master' of https://github.com/w3c/did-core
csuwildcat Oct 7, 2020
596b319
Simplify id prop text via separation of deterministic equivalence prop
csuwildcat Oct 7, 2020
507dd0a
title attribute typo
csuwildcat Oct 7, 2020
96659b2
Merge branch 'master' of https://github.com/w3c/did-core
csuwildcat Oct 26, 2020
1c8c31c
Updating with latest from DID Core
csuwildcat Oct 26, 2020
42f333f
Update sameAs text, add canonicalId
csuwildcat Nov 4, 2020
450b2bd
typo
csuwildcat Nov 4, 2020
9cb760c
Update property definitions
csuwildcat Nov 12, 2020
386ae78
add security considerations for equivalence properties
csuwildcat Nov 12, 2020
99c9b88
Switch to MUST so the outcomes are testable
csuwildcat Nov 12, 2020
710b513
Move equivalence properties to Document metadata
csuwildcat Nov 24, 2020
eb59f1b
Update index.html
csuwildcat Nov 30, 2020
e973bb0
Update index.html
csuwildcat Nov 30, 2020
f7ab06a
Update index.html
csuwildcat Nov 30, 2020
cde8a61
Update index.html
csuwildcat Nov 30, 2020
fb0a123
Update index.html
csuwildcat Nov 30, 2020
4c02d7f
Update index.html
csuwildcat Nov 30, 2020
8983bf4
Update index.html
csuwildcat Nov 30, 2020
4e1b1d1
Update index.html
csuwildcat Nov 30, 2020
176c40e
Update index.html
csuwildcat Nov 30, 2020
8b665a8
Update index.html
csuwildcat Nov 30, 2020
6b2b965
Update index.html
csuwildcat Nov 30, 2020
fd0831a
Merge branch 'master' of https://github.com/w3c/did-core
csuwildcat Dec 3, 2020
5760cd1
Update index.html
csuwildcat Dec 3, 2020
50d68f7
Update index.html
csuwildcat Dec 3, 2020
4055fa0
Merge remote-tracking branch 'origin/master'
csuwildcat Dec 3, 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
149 changes: 146 additions & 3 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1298,9 +1298,7 @@ <h2>DID Subject</h2>
However, the fully resolved <a>DID document</a> always contains a valid
<code><a>id</a></code> property. The value of <code><a>id</a></code> in the
resolved <a>DID document</a> MUST match the <a>DID</a> that was
resolved, or be populated with the equivalent canonical <a>DID</a>
specified by the <a>DID method</a>, which SHOULD be used by the resolving
party going forward.
resolved.
</p>

<section>
Expand Down Expand Up @@ -1350,6 +1348,115 @@ <h3>alsoKnownAs</h3>
</div>

</section>

<section>
<h3>sameAs</h3>
<p>
A <a>DID Method</a> can define different forms of a DID that are
logically equivalent. An example is when a DID takes one form prior
to registration in a verifiable data registry and another form after
such registration. In this case, the <a>DID Method</a> specification
may need to express one or more DIDs that are logically equivalent to
the resolved DID as a property of the DID document. This is the
purpose of the sameAs property.
</p>

<dl>
<dt><dfn>sameAs</dfn></dt>
<dd>
The value of <code>sameAs</code> MUST be a
<a data-cite="INFRA#lists">list</a> where each item in the list
is a DID conforming to the requirements in Section 3.1.
</dd>
<dd>
The relationship is a statement that each <code><a>sameAs</a></code>
DID value is logically equivalent to the <code>id</code> property DID
value and thus identifies the same DID subject.
</dd>
<dd>
Each <code><a>sameAs</a></code> DID value MUST be produced by the same
DID method as the <code>id</code> property DID value.
</dd>
<dd>
A conforming <a>DID Method</a> specification MUST guarantee that each
<code><a>sameAs</a></code> DID value is logically equivalent to the
<code>id</code> property DID value.
</dd>
<dd>
A resolving party MUST retain the DIDs from the <code>id</code> and
<code><a>sameAs</a></code> properties to ensure any subsequent
interactions with any of the DIDs they contain are correctly handled
as logically equivalent DIDs (e.g. retain all variants in a database so an
interaction with any one maps to the same underlying account).
</dd>
</dl>

<div class="note" title="Equivalence and sameAs">
<p>
<code><a>sameAs</a></code> was chosen as the name for this property because
from a graph modeling standpoint the intended semantics are identical to
the <code>owl:sameAs</code> property. <code><a>sameAs</a></code> is a much
stronger form of equivalence than <code><a>alsoKnownAs</a></code> because the
equivalence MUST be guaranteed by the governing DID method. <code><a>sameAs</a></code>
represents a full graph merge because the same DID document describes both
the <code><a>sameAs</a></code> DID and the <code>id</code> property DID.
</p>
</div>

</section>

<section>
<h3>canonicalId</h3>
<p>
The <code><a>canonicalID</a></code> property is identical to the
<code><a>sameAs</a></code> property except: a) it accepts only a single
DID as its value, and b) that DID is defined to be the canonical DID
for the DID subject within the scope of the containing DID document.
</p>

<dl>
<dt><dfn>canonicalId</dfn></dt>
<dd>
The value of <code><a>canonicalID</a></code> MUST be a DID conforming to the
requirements in Section 3.1.
</dd>
<dd>
The relationship is a statement that the <code><a>canonicalID</a></code> DID
value is logically equivalent to the <code>id</code> property DID value and
that the <code><a>canonicalID</a></code> DID value is defined by the
<a>DID Method</a> to be the canonical DID for the DID subject in the scope
of the containing DID document.
</dd>
<dd>
A <code><a>canonicalID</a></code> DID value MUST be produced by the same
<a>DID Method</a> as the <code>id</code> property DID value.
</dd>
<dd>
A conforming <a>DID Method</a> specification MUST guarantee that the
<code><a>canonicalID</a></code> DID value is logically equivalent to the
<code>id</code> property DID value.
</dd>
<dd>
A resolving party MUST use the <code><a>canonicalID</a></code> DID value
as its primary ID value for the DID subject and treat all other equivalent
DIDs as secondary aliases. (e.g. update corresponding primary references in
their systems to reflect the new canonical ID directive).
</dd>
</dl>

<div class="note" title="Equivalence and canonicalId">
<p>
<code><a>canonicalID</a></code> is the same statement of equivalence as
<code><a>sameAs</a></code> except it is constrained to a single value that
is defined to be canonical for the DID subject in the scope of the DID
document. Like <code><a>sameAs</a></code>, <code><a>canonicalID</a></code>
represents a full graph merge because the same DID document describes both
the <code><a>canonicalID</a></code> DID and the <code>id</code> property DID.
</p>
</div>

</section>

</section>

<section>
Expand Down Expand Up @@ -4175,6 +4282,42 @@ <h2>

</section>

<section>
<h2>
Equivalence Properties
</h2>
<p>
The three equivalence properties defined in Core Properties
—<code><a>alsoKnownAs</a></code>, <code><a>sameAs</a></code>, and
<code><a>canonicalID</a></code>—are subject to special security
considerations related to attacks against DIDs that are asserted to be
equivalent. Each of the equivalence property sections describes relevant
mitigation instructions. In general, they are:
</p>
<p>
The <code><a>sameAs</a></code> and <code><a>canonicalID</a></code> properties
that constrain equivalence assertions to variants of a single DID produced by
the same <a>DID method</a> (e.g. <code>did:foo:123</code> ≡ <code>did:foo:hash(123)</code>)
can be trusted to the extent the resolving party trusts the <a>DID method</a> (and a
conforming producer) itself.
</p>
<p>
The <code><a>alsoKnownAs</a></code> property that permits an equivalence assertion
to URIs that are not governed by the same <a>DID method</a> (or may not be DIDs at
all) cannot be trusted without performing verification steps outside of the governing
<a>DID method</a>. See Section 5.1.1 for the recommendation to verify inverse relationships.
</p>
<p>
As with any other sensitive properties in the DID Document (e.g. public key references),
parties relying on any equivalence statement in a DID Document should guard against the
values of these properties being substituted by an attacker after the proper verification
has been performed. Any write access to a DID document stored in memory or disk after
verification has been performed is an attack vector that will circumvent verification
unless the DID document is re-verified.
</p>

</section>

</section>

<section class="informative">
Expand Down