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

Jump to bottom

Add equivalence properties. #473

Merged
merged 16 commits into from
Dec 6, 2020
Merged

Add equivalence properties. #473

Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
f31f79b
Fix merge conflict.
msporny Dec 6, 2020
259401d
Update normative directive from SHOULD to MUST
Aug 21, 2020
2b418e4
Update index.html
csuwildcat Aug 24, 2020
98bb91c
Update to add in requested changes
Aug 25, 2020
a61f6ad
removing errant vscode settings file
Aug 26, 2020
721bf88
update to more closely match suggestions
Aug 26, 2020
2a675ce
Simplify id prop text via separation of deterministic equivalence prop
csuwildcat Oct 7, 2020
39324a4
title attribute typo
csuwildcat Oct 7, 2020
0c220c4
Updating with latest from DID Core
csuwildcat Oct 26, 2020
311d867
Update sameAs text, add canonicalId
csuwildcat Nov 4, 2020
4ecd762
Update property definitions
csuwildcat Nov 12, 2020
a2fbc03
add security considerations for equivalence properties
csuwildcat Nov 12, 2020
1f19f9e
Switch to MUST so the outcomes are testable
csuwildcat Nov 12, 2020
ee15ef9
Move equivalence properties to Document metadata.
csuwildcat Nov 24, 2020
68aa0de
Add warning about testability of equivalence property.
csuwildcat Dec 3, 2020
46532b9
Fix missing quote on URL.
msporny Dec 6, 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
220 changes: 184 additions & 36 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1378,10 +1378,8 @@ <h3>
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.
</p>
resolved.
</p>

<p class="note" title="Nested objects with the id property">
A <a>DID document</a> can contain objects which have their own unique
Expand Down Expand Up @@ -1441,6 +1439,7 @@ <h3>Also Known As</h3>
</div>

</section>

</section>

<section>
Expand Down Expand Up @@ -2804,24 +2803,24 @@ <h2>CBOR</h2>
Representation (CBOR) [[RFC7049]] defines a set of formatting rules for the
portable representation of structured data. CBOR is a more concise,
machine-readable, language-independent data interchange format that is
self-describing and has built-in semantics for interoperability. CBOR prioritizes
self-describing and has built-in semantics for interoperability. CBOR prioritizes
the simplicity of the encoder and decoder over the size of the encoded data.
With specific constraints, CBOR can support all JSON data types for
translation between the DID document model (described in <a
href="#data-model">Data Model</a> and the <a href="#core-properties"> Core Properties section</a> of the DID Document</a>).
</p>

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

<section>
<h3>Production</h3>
<p>
A DID document encoded in CBOR must be represented as a CBOR Map (major type 5) conforming to [[RFC7049]].
Similar to the JSON encoding of a DID document, all properties of the DID document MUST be represented by using the
property name as the name of the member of the CBOR map. The values of properties of the data model described in <a href="#core-properties"> § 5. Core Properties</a>, including
A DID document encoded in CBOR must be represented as a CBOR Map (major type 5) conforming to [[RFC7049]].
Similar to the JSON encoding of a DID document, all properties of the DID document MUST be represented by using the
property name as the name of the member of the CBOR map. The values of properties of the data model described in <a href="#core-properties"> § 5. Core Properties</a>, including
all extensions, MUST be encoded in CBOR [[RFC7049]] by mapping INFRA property values to CBOR types as follows: </p>

<ul>
Expand All @@ -2839,13 +2838,13 @@ <h3>Production</h3>
</ul>


<!-- <p>Additional considerations to enable lossless production of a CBOR representation and to enable a deterministic
canonical CBOR representation of the DID Document between other core representations of the DID document is possible
<!-- <p>Additional considerations to enable lossless production of a CBOR representation and to enable a deterministic
canonical CBOR representation of the DID Document between other core representations of the DID document is possible
with additional constraints to the CBOR representation. -->
<p>
To produce a deterministic canonical CBOR representation of a DID document and faciliate maximal lossless compatiblity with other
To produce a deterministic canonical CBOR representation of a DID document and faciliate maximal lossless compatiblity with other
core representations via the Abstract Data Model the following constraints of a CBOR representation of a DID Document model MUST be followed:

<ul>
<li>Property names MUST be represented as text string (major type 3) and contain only UTF-8 strings. </li>
<li>Undefined Values of Required Properties as defined in <a href="#data-model">the Data Model</a> that are absent from the CBOR representation SHOULD be labeled with Primitive type (major type 7) with value 23 (Undefined value). </li>
Expand All @@ -2858,16 +2857,16 @@ <h3>Production</h3>


<p class="issue">
How to represent Floating-point values that can exceed the range or the precision IEEE 754. See <a href=https://github.com/w3c/did-core/issues/361">issue #361. </a>
How to represent Floating-point values that can exceed the range or the precision IEEE 754. See <a href="https://github.com/w3c/did-core/issues/361">issue #361. </a>
</p>

<p>
The property name `@context` MAY be present in the CBOR representation of a DID Document and if present SHOULD be ignored as this property is reserved for JSON-LD processing.
</p>

<p>
All properties of the DID document represented in CBOR MUST be included in the root map (major type 5).
Properties MAY define additional data sub structures represented as nested CBOR maps (major type 5)
All properties of the DID document represented in CBOR MUST be included in the root map (major type 5).
Properties MAY define additional data sub structures represented as nested CBOR maps (major type 5)
and is subject to the value representation rules in the lists above and conformance to section <a href="#extensibility"> § 4.3 Extensibility</a>.
</p>

Expand All @@ -2888,9 +2887,9 @@ <h3>Production</h3>
79426173653538782C483343324156764C4D7636676D4D4E616D33755641
6A5A70666B634A437744776E5A6E367A3377586D715056
</pre>
<pre class="example nohighlight" title="The same example DID Document shown above but exported
in diagnostic annotation mode for easy readibility">

<pre class="example nohighlight" title="The same example DID Document shown above but exported
in diagnostic annotation mode for easy readibility">
A2 # map(2)
62 # text(2)
6964 # "id"
Expand Down Expand Up @@ -2956,7 +2955,7 @@ <h3>CBOR Extensibility</h3>
href="https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml">IANA CBOR Tag
Registry</a>. This allows for tags to enhance the semantic description of the
data that follows. Extensibility with CBOR tags also facilitates lossless conversion to
othere core representations. CBOR Tags number 21 to 23 indicate that a following byte string
othere core representations. CBOR Tags number 21 to 23 indicate that a following byte string
might require a specific encoding when interoperating with a text-based
representation such as JSON. These tags are useful when an encoder knows that the
byte string data it is writing is likely to be later converted to a
Expand Down Expand Up @@ -3025,15 +3024,15 @@ <h4>DagCBOR</h4>
</section>
<section>
<h3>Converting Data between Core Representations</h3>
<p>Transformation between various core representations SHOULD be performed through parsing and serializing via the Abstract DID Document Data Model (see <a href="#data-model"></a> and <a href="#representations">Production and Consumptions rules between core representation via the Abstract Data Model</a>).
<p>Transformation between various core representations SHOULD be performed through parsing and serializing via the Abstract DID Document Data Model (see <a href="#data-model"></a> and <a href="#representations">Production and Consumptions rules between core representation via the Abstract Data Model</a>).
Given that CBOR is a superset of JSON, the following non-normative advice is given for converting a DID document between CBOR and JSON. </p>

<div class="warning" title="Converting via DID document data model">
<p>
This section conflicts with other parts of the specification, since
conversion has to be defined not between any two representations directly,
but rather in terms of parsing and serializing via the abstract
DID document data model (see <a href="#data-model"></a> and
DID document data model (see <a href="#data-model"></a> and
<a href="#representations"></a>). The content of this section can
potentially be adapted and re-used in other sections such as the one
about the CBOR representation (see <a href="#cbor"></a>).
Expand Down Expand Up @@ -3061,7 +3060,6 @@ <h3>CBOR to JSON</h3>
</section>
</section>


</section>

<section>
Expand Down Expand Up @@ -3586,11 +3584,11 @@ <h3>
This specification defines the following common properties.
</p>

<dl>
<dt>
created
</dt>
<dd>
<section>
<h4>
created
</h4>
<p>
DID document metadata SHOULD include a <code>created</code> property
to indicate the timestamp of the <a href="#create">Create operation</a>.
This property MAY not be supported by a given <a>DID method</a>.
Expand All @@ -3599,18 +3597,132 @@ <h3>
Definition Language (XSD) 1.1 Part 2: Datatypes</a> [[XMLSCHEMA11-2]]. This
datetime value MUST be normalized to UTC 00:00, as indicated by the trailing
"Z".
</dd>
<dt>
updated
</dt>
<dd>
</p>
</section>

<section>
<h4>
updated
</h4>
<p>
DID document metadata SHOULD include an <code>updated</code> property
to indicate the timestamp of the last <a href="#update">Update operation</a>.
This property MAY not be supported by a given <a>DID method</a>.
The value of the property MUST follow the same formatting rules as the
<code>created</code> property.
</dd>
</dl>
</p>
</section>

<section>
<h4>equivalentId</h4>
<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 <code><a>equivalentId</a></code> property.
</p>

<dl>
<dt><dfn>equivalentId</dfn></dt>
<dd>
The value of <code>equivalentId</code> MUST be a
<a data-cite="INFRA#lists">list</a> where each item in the list
is a <a data-cite="INFRA#string">string</a> that conforms to the rules in Section <a href="#did-syntax"></a>.
</dd>
<dd>
The relationship is a statement that each <code><a>equivalentId</a></code>
value is logically equivalent to the <code>id</code> property
value and thus identifies the same DID subject.
</dd>
<dd>
Each <code><a>equivalentId</a></code> DID value MUST be produced by, and a form of,
the same <a>DID Method</a> as the <code>id</code> property value.
(e.g. <code>did:example:abc</code> == <code>did:example:ABC</code>)
</dd>
<dd>
A conforming <a>DID Method</a> specification MUST guarantee that each
<code><a>equivalentId</a></code> value is logically equivalent to the
<code>id</code> property value.
</dd>
<dd>
A resolving party MUST retain the values from the <code>id</code> and
<code><a>equivalentId</a></code> properties to ensure any subsequent
interactions with any of the values they contain are correctly handled
as logically equivalent (e.g. retain all variants in a database so an
interaction with any one maps to the same underlying account). <span class="issue">The testability of
resolving parties is currently under debate and normative statements related to resolving parties
may be downgraded in the future from a MUST to a SHOULD/MAY or similar language.</span>
</dd>
</dl>

<div class="note" title="Equivalence and equivalentId">
<p>
<code><a>equivalentId</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>equivalentId</a></code> represents a full
graph merge because the same DID document describes both the
<code><a>equivalentId</a></code> DID and the <code>id</code> property DID.
</p>
</div>

</section>

<section>
<h4>canonicalId</h4>
<p>
The <code><a>canonicalId</a></code> property is identical to the
<code><a>equivalentId</a></code> property except: a) it accepts only a single
value rather than a list, and b) that DID is defined to be the canonical ID
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 <a data-cite="INFRA#string">string</a> that conforms to the rules in Section <a href="#did-syntax"></a>.
</dd>
<dd>
The relationship is a statement that the <code><a>canonicalId</a></code>
value is logically equivalent to the <code>id</code> property value and
that the <code><a>canonicalId</a></code> value is defined by the
<a>DID Method</a> to be the canonical ID for the DID subject in the scope
of the containing DID document.
</dd>
<dd>
A <code><a>canonicalId</a></code> value MUST be produced by, and a form of,
the same <a>DID Method</a> as the <code>id</code> property value.
(e.g. <code>did:example:abc</code> == <code>did:example:ABC</code>)
</dd>
<dd>
A conforming <a>DID Method</a> specification MUST guarantee that the
<code><a>canonicalId</a></code> value is logically equivalent to the
<code>id</code> property value.
</dd>
<dd>
A resolving party MUST use the <code><a>canonicalId</a></code> value
as its primary ID value for the DID subject and treat all other equivalent
values as secondary aliases. (e.g. update corresponding primary references in
their systems to reflect the new canonical ID directive). <span class="issue">The testability of
resolving parties is currently under debate and normative statements related to resolving parties
may be downgraded in the future from a MUST to a SHOULD/MAY or similar language.</span>
</dd>
</dl>

<div class="note" title="Equivalence and canonicalId">
<p>
<code><a>canonicalId</a></code> is the same statement of equivalence as
<code><a>equivalentId</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>equivalentId</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>

Expand Down Expand Up @@ -4288,6 +4400,42 @@ <h2>

</section>

<section>
<h2>
Equivalence Properties
</h2>
<p>
The three equivalence properties defined in Core Properties
—<code><a>alsoKnownAs</a></code>, <code><a>equivalentId</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>equivalentId</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