forked from openssi/peer-did-method-spec
-
Notifications
You must be signed in to change notification settings - Fork 0
/
security.html
178 lines (169 loc) · 11.5 KB
/
security.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>Security Considerations</h1>
<section class="informative">
<h2>Guarantees</h2>
<p>This spec uses a <a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/concepts/0003-protocols/README.md#what-is-a-protocol">
protocol</a>, rather than a public oracle, as the root of trust. This protocol reliably communicates data
about peer DIDs and peer DID docs; peers must persist that data into a local cache or database that functions
as the <a target="didspec" href="https://w3c-ccg.github.io/did-spec/#dfn-dir">Decentralized Identifier
Registry</a> for the method. The method is worthy of trust because it guarantees the following properties:
</p>
<dl>
<dt>DIDs are associated with at least one key pair at the moment of creation.</dt>
<dd>This prevents a category of man-in-the-middle attacks where an attacker could rotate a DID's keys
at the outset of a relationship, unbeknownst to peers.
</dd>
<dt>DIDs have an acceptable level of uniqueness.</dt>
<dd>This is NOT a guarantee that DIDs will never be reused by their owner, NOR is it a guarantee that
collusion cannot subvert uniqueness. Thus, it is not a uniqueness upon which deep trust can be based.
Rather, it is a guarantee that good behavior will not produce accidental collisions. In this
sense, it is a bit like the uniqueness offered by NATing mechanisms in IPv4. It provides
enough uniqueness that a DID can be used as an index in a database or as a routing target
in DID communication. It also makes it possible for blockchains to <a href="#grafting">graft</a> a peer
DID by mapping it into their namespace, without incurring the risk of ambiguity. Any time a peer
DID is discovered to be less than unique, a true problem exists and systems can fairly
raise an exception.
</dd>
<dt>The values of DIDs are securely random.</dt>
<dd>This prevents attackers from discovering patterns in DIDs that might undermine privacy.
</dd>
<dt>Parties to a relationship can prove the orderly and authorized evolution of their
keys to one another.</dt>
</dl>
</section>
<section class="informative">
<h2>Enforcement</h2>
<p>In centralized systems, security is enforced at the center. This is so obvious that we take it for
granted—you can't access a database unless you log in first, and it's the database that enforces
this.
</p>
<p>Despite their other decentralized features, blockchains are no different in this respect. If a
blockchain accepts updates to a DID doc, then the blockchain must guarantee that those updates are
only made by authorized parties. Thus, most DID methods imagine a blockchain parsing the
authorization section of a DID doc, and rejecting mischief from hackers.
</p>
<p>However, in a peer relationship, there IS no centralized authority. This leads to an interesting
inversion of responsibility that must be understood: Bob enforces Alice's <a href="#authorization">
authorization policy</a>, and Alice enforces Bob's.
</p>
<p>This might seem wrong—shouldn't Alice enforce her own security? But it is quite rational. Who cares
whether the agents he is dealing with truly belong to Alice and are authorized by her? Bob does.
And if one of Alice's agents gets hacked and attempts to subvert the Alice:Bob relationship,
who is the uncontaminated party that can refuse to cooperate with the rogue agent? Bob is.
</p>
<p>Another way to think about this is that, within the Alice:Bob relationship, Bob acts as a substitute
for a centralized resource that Alice's agents try to access. In such a mental model, of course, Bob
would be a logical place to enforce access rules for Alice.
</p>
</section>
<section>
<h2>Secure communication</h2>
<p>All the messages in this protocol (except for a connection invitation that requires no security, by design)
must be sent encrypted, using the encryption format specified in <a target="aries"
href="https://github.com/hyperledger/aries-rfcs/blob/master/features/0019-encryption-envelope/README.md">
DIDComm's encryption envelope</a>. This gives strong guarantees about the confidentiality and integrity of
exchanged data, regardless of the transport mechanism used to transmit the messages.</p>
</section>
<section>
<h2>Proof of Control</h2>
<p>Because peer DIDs are generated from an <a href="#namestring-generation-method">algorithm</a> that includes the values of their initial public key(s)
as input, they cannot be created without the creator controlling them. As mentioned earlier, this prevents
man-in-the-middle attacks at the time of creation. A man-in-the-middle attacker might still try to exchange
the public key(s) in a DID Doc, while keeping the DID the same. If unnoticed, this would bind a DID generated
by an honest party to the attacker's public key(s). To prevent this, the receiver of a freshly generated peer
DID and DID Doc must verify that the DID was properly generated using the <a href="#namestring-generation-method">algorithm</a>.
This check is required when the received (DID, DID Doc) pair was not otherwise authenticated, which is the case
for the exchange request during <a href="#create-register">peer DID Exchange</a>.
</p>
</section>
<section>
<h2>Entropy</h2>
<p>
Since keys must be created from keys generated by a secure random number generator, they are guaranteed
to be unpredictable and globally unique at creation time.</p>
</section>
<section>
<h2>Key Management</h2>
<p>Keys used to control peer DIDs, or keys authorized to communicate and update the DID docs
for peer DIDs, should be managed according to best practices for DKMS, as described in
<a target="aries" href="https://github.com/hyperledger/aries-rfcs/blob/master/concepts/0051-dkms/dkms-v4.md">
the DKMS spec</a>. See the <a href="#static-and-key-rotation">note about key rotation and static-DID-only
support</a> in the <a href="#impl">Implementation section</a>.
</p>
<p><a target="sgl" href="https://evernym.github.io/sgl/docs/reference.html#rules">SGL rules</a> are powerful and
flexible, and should be used to implement best practices.</p>
</section>
<section>
<h2>Handling the trust-on-first-use (TOFU) problem</h2>
<p>
The trust-on-first-use is described in detail in its
<a target="wikipedia" href="https://en.wikipedia.org/wiki/Trust_on_first_use">Wikipedia article</a>.
In brief, the TOFU problem occurs because it's not possible to verify, with only a public key,
who is the owner of a private key. This lack of knowledge enables MITM attacks.
</p>
<p>
There are two separate ways to handle the TOFU problem with the peer DID method spec. The more common
variant is to bootstrap based upon a trusted third party channel. The second approach is made
possible by verifiable credentials.
</p>
<section>
<h3>Bootstrap from Trusted Third Party Channel</h3>
<p>
The core premise of using an out of band channel based solution is to be able to bootstrap the new
channel of communication from a third party trusted channel of communication. In many cases this is an
adequette solution, and in others it may require additional pieces of information in order to establish
trust, such as a verifiable credential exchange.
</p>
<p>
This method has been used in previous systems to rely on in person interactions to verify some piece of
information. For example, in some end to end messaging apps, they rely on key fingerprinting which
require a use to verify that a key fingerprint sent over a trusted communication channel or viewed in
person (usually a number) matches between the two parties. This method allows user to verify that the
channel hasn't been Man in the Middle (MITM) attacked.
</p>
<p>
There's also ways that the user experience could be improved using this same security process. For
example, a <a target="superuser" href="https://superuser.com/questions/22535/
what-is-randomart-produced-by-ssh-keygen">randomart image</a> could be embedded into a QR code and then
the randomart image could be displayed on the users device as well. The user would then be required to
verify the image displayed on the user's device is the same as the one embedded in the QR code. This is
a great way to handle short-lived, ephemeral connections such as unlocking a door while being sure the
connection has not been MITM attacked.
</p>
</section>
<section>
<h3>Binding Verifiable Credentials with Public Keys</h3>
<p>
A verifiable credential method is a new approach to bootstrapping trust entirely within the connection.
The idea behind this is that a verifiable credential issued by a third party can be combined with a
self-attested attribute in a credential proof to link the possession of the key to a verifiable
credential.
</p>
<p>
The reason this works is because the cryptographic proof generated by the holder binds the attributes
provided from a verifiable credential with the self-attested public key attribute. This is done in a way
that only the holder could generate this proof and therefore the recipient can identify all keys
recognized by the sender while also being able to identify attributes about the sender in a way that a
trust decision can be made. If Bob detects that the key that Alice
provides in the DID Document is different than the key he received in the Credential Proof, then he’s
able to detect that some aspect of the setup was done incorrectly or was tampered with. This is good
enough indication that Bob SHOULD NOT trust this connection and SHOULD scrap it and reset.
</p>
<p>
One thing of particular importance in this method is that the credential requested must be unique enough
such that a malicious party cannot also generate a satisfactory proof. If a malicious party does holder
a credential which is not unique enough then the malicious party could conduct a MITM attack. This
attack would require a malicious party to first intercept the plaintext DID Document sent in the
invitation during the create operation, change the key, endpoint, and signature of the invitation. Then
the malicious party must generate a proof that meets the request of the verifier and impersonate the
sender.
</p>
<p>
In the majority of security threat models the use of a unique proof which includes all public keys
listed in the DID Document as self attested attributes in the proof. As recommendation, a unique proof
SHOULD include proof attributes issued by at least 2 unique issuers. This method SHOULD be satisfactory
for high value financial transactions while accommdating for internet wide scale. If a threat model
needs greater assurances, the parties SHOULD meet in person for a connection setup.
</p>
</section>
</section>