-
Notifications
You must be signed in to change notification settings - Fork 17
/
impl.html
178 lines (170 loc) · 13.1 KB
/
impl.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
<h1>Implementation</h1>
<section>
<h2>Layers of Support</h2>
<p>Different software may need to support peer DIDs to different degrees. We talk about these varying amounts of
support as "layers", following conventions used in other W3C specs. Some natural clusters of functionality that
make sense as layers include:
</p>
<figure id="impl-layers">
<img src="impl-layers.png" alt="3 layers of impl"/>
<figcaption>Natural ways to approach implementation.</figcaption>
</figure>
<dl>
<dt>Layer 1: Recognize</dt>
<dd>
<p>An implementation offering support at <dfn>Layer 1</dfn> MUST understand at a surface level what a peer
DID is and how it works. It MUST be able to tell whether a string is a valid peer DID or not. It
MUST correctly compare two peer DIDs when sorting or testing for equality, taking into account the case
sensitivity rules associated with how the <a>numeric basis</a> is encoded. If relevant, the implementation
SHOULD display, hyphenate, and abbreviate peer DIDs correctly. See
<a href="#recognizing-and-handling-peer-dids">Recognizing and handling peer DIDs</a>.
</p>
<p>This might be an appropriate support target for a database that needs to store peer DIDs as an
indexed field, but that otherwise has little need to provide peer DID features.
</p>
<p><em>Expected effort</em>: a few minutes of coder time. See the <a href="#matching-regex">matching regex
</a> and <a href="#reserved-values">Reserved Values</a>.
</p>
</dd>
<dt>Layer 2a: Accept static peer DIDs from others</dt>
<dd>
<p>An implementation offering <dfn>Layer 2a</dfn> support builds atop <a>Layer 1</a> support, and is also
willing to interact with other parties that use peer DIDs (e.g., to perform a <a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/features/0023-did-exchange/README.md">DID
Exchange</a> and additional protocols)--as long as the other parties do not attempt to update their DID
docs. This "static" (no update) constraint drastically simplifies implementation because support for
<a>backing storage</a>, <a>deltas</a>, and the <a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/features/0030-sync-connection/README.md">
Sync Connection</a> or remote <a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/features/0124-did-resolution-protocol/README.md">
DID Resolution</a> protocols is NOT REQUIRED. The implementation MUST recognize peer DIDs (Layer 1
1), MUST store peer DID docs, and MUST look up those docs as a form of resolution. The implementation
MAY engage in DIDComm-based protocols; if so, it SHOULD handle an <a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/features/0030-sync-connection/abandon-connection-protocol/README.md">
<code>abandon_connect/announce</code> message</a> gracefully, deleting the peer DID Doc from its cache.
If the implementation supports DIDComm, it MUST return a
<a href="https://github.com/hyperledger/aries-rfcs/blob/master/features/0035-report-problem/README.md"
target="aries"><code>problem_report</code></a> with <code>code</code> == <code>unsupported-protocol</code>
if a remote party attempts to use dynamic peer DID protocols. The implementation SHOULD report that it
supports the DID Exchange protocol if it receives and supports a <a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/features/0031-discover-features/README.md">
<code>discover-features/query</code> message</a>.
</p>
<p>This might be a beginning level of support for software that's already supporting other DID methods,
that wants meaningful interoperability as quickly and cheaply as possible. However, it is NOT RECOMMENDED
as a permanent goal, because it places limits on the behaviors of other peer DID users. Upgrading to
<a>Layer 3a</a> support is strongly preferred.
</p>
<p><em>Expected effort</em>: a few hours of coder time if a codebase already has some DID features, or a
couple days of effort if starting from scratch.
</p>
</dd>
<dt>Layer 2b: Give static peer DIDs to others</dt>
<dd>
<p>An implementation with <dfn>Layer 2b</dfn> support includes <a>Layer 1</a> support. It also creates peer
DIDs and gives them to other parties as the basis of interactions. <a>Layer 2a</a> and Layer 2b are not
hierarchical; either or both may be chosen, and the effort to implement is somewhat independent.
</p>
<p>Like <a>Layer 2a</a>, Layer 2b gets significant compatibility at a low cost because the effort of
supporting<a>backing storage</a>, <a>deltas</a>, and the <a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/features/0030-sync-connection/README.md">
Sync Connection</a> and <a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/features/0124-did-resolution-protocol/README.md">
DID Resolution</a> protocols is NOT REQUIRED. Resolving peer DIDs against a cached version
of a peer DID Doc is also NOT REQUIRED. However, Layer 2b-compliant implementations MUST be capable of
generating a genesis version of their own DID doc and calculating the <a>numeric basis</a> and DID
value that goes with it. If an implementation supports DIDComm, it SHOULD receive and MAY emit an
<a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/features/0030-sync-connection/abandon-connection-protocol/README.md">
<code>abandon_connect/announce</code> message</a> gracefully; it SHOULD also return a
<a href="https://github.com/hyperledger/aries-rfcs/blob/master/features/0035-report-problem/README.md"
target="aries"><code>problem_report</code></a> with <code>code</code> == <code>unsupported-protocol</code>
if a remote party attempts to use dynamic peer DID protocols, and it implementation SHOULD report that
it supports the DID Exchange protocol if it receives a <a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/features/0031-discover-features/README.md">
<code>discover-features/query</code> message</a>.
</p>
<p>This might be an appropriate level of support for software that wants to use peer DIDs, but doesn't
intend to ever rotate its keys.
</p>
<p class="note" id="static-and-key-rotation">
Key rotation is an important security feature. It is generally a bad idea to provide no way to change
how proof of control is provided. The wisdom of supporting neither key rotation NOR <a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/features/0030-sync-connection/abandon-connection-protocol/README.md">
a way to abandon a connection</a> is particularly dubious. However, these static-only levels of support
are provided anyway, because some connections might be so short-lived that the security risks are
acceptable. Use good judgment. [[TODO: Do we need to support expiration of a conn?]]
</p>
<p><em>Expected effort</em>: a few hours of coder time if a codebase already has some DID features--especially
<a>Layer 2a</a> support--or a couple days of effort if starting from scratch.
</p>
</dd>
<dt>Layer 3a: Accept dynamic peer DIDs from others</dt>
<dd>
<p>Software with <dfn>Layer 3a</dfn> support includes <a>Layer 2a</a> support and is maximally interoperable
with others who want to use peer DIDs in rich ways. It may or may not use any peer DIDs of its own.
</p>
<p>Such an implementation MUST provide<a>backing storage</a> to persist others' peer DID Docs and the
<a>deltas</a> for them. It MUST support the <a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/features/0030-sync-connection/README.md">
Sync Connection</a> and <a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/features/0124-did-resolution-protocol/README.md">
DID Resolution</a> protocols, but, if <a>Layer 3b</a> is supported, it can support those protocols
only for the dynamic data of others (meaning the only role it has to support in Query Connection State
is <code>responder</code>). The implementation SHOULD report that it supports these protocols if it
receives a relevant <a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/features/0031-discover-features/README.md">
<code>discover-features/query</code> message</a>.
</p>
<p>This level of support for accepting peer DIDs is RECOMMENDED for software that wants to offer rich peer
DID support to others, regardless of the level of peer DID usage it intends for itself. Anything less
than this level of support, insofar as <em>accepting</em> DIDs from others is concerned, in software
that expects to interact richly on the DID landscape, will hamper pervasive interoperability.
</p>
<p><em>Expected effort</em>: a few hours of coder time if a codebase already has support for <a>Layer 2a</a>.
A couple days if the codebase has support for <a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/concepts/0005-didcomm/README.md">DIDComm</a>
and <a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/concepts/0005-didcomm/README.md">protocols</a>,
but only different DID types. A couple weeks if starting from scratch.
</p>
</dd>
<dt>Layer 3b: Give dynamic peer DIDs to others</dt>
<dd>
<p>Software with <dfn>Layer 3b</dfn> support includes <a>Layer 2b</a> support. It MUST also provide
<a>backing storage</a> to persist its own peer DID Docs and the <a>deltas</a> for them. It MUST
support the same protocols as <a>Layer 3a</a>, but with its own data as the management target.
</p>
<p>This level of support is RECOMMENDED for all software that wants to create peer DIDs.
</p>
<p><em>Expected effort</em>: A couple days of coder time if a codebase already has support for <a>Layer 2b</a>.
A couple days if the codebase has support for <a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/concepts/0005-didcomm/README.md">DIDComm</a>
and <a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/concepts/0005-didcomm/README.md">protocols</a>,
but only different DID types. A couple weeks if starting from scratch.
</p>
</dd>
</dl>
</section>
<section>
<h2>Encryption Envelope</h2>
<p>The encryption envelope for DID Communication has three independent implementations—one in
<a target="_blank" href="https://github.com/hyperledger/indy-sdk/blob/fbad7422/libindy/src/api/crypto.rs#L634">
libindy</a>, one in <a target="_blank"
href="https://github.com/bcgov/indy-catalyst/blob/bba2ef5c/agent/indy_catalyst_agent/wallet/crypto.py#L402">
python with no Indy dependencies</a>, and one in <a target="_blank"
href="https://github.com/dbluhm/indy-pack-unpack-js/blob/db9d83e4/index.js">
javascript with no Indy dependencies</a>.
</p>
<p>The connection protocol that creates and registers peer DIDs, including support for DID resolution
after forming a connection, has been fully implemented by
half a dozen different organizations, as of March 2019. One of these organizations did not use
libindy. The connection management protocols that allow update of DIDs are in various states of
implementation. An up-to-date summary of implementation status, including links to the implementations,
can be found in the
<a target="_blank" href="https://github.com/hyperledger/indy-agent">indy-agent repo on github</a>.
</p>
<p>There is a formal test suite for the protocols as well, in the same github repo.
</p>
</section>