-
Notifications
You must be signed in to change notification settings - Fork 3
/
index.html
1112 lines (988 loc) · 37.3 KB
/
index.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
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<title>Veres One DID Method 1.0</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<!--
=== NOTA BENE ===
For the three scripts below, if your spec resides on dev.w3 you can check them
out in the same tree and use relative links so that they'll work offline,
-->
<script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove'></script>
<script src="./common.js"></script>
<script type="text/javascript" class="remove">
var respecConfig = {
// specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
specStatus: "CG-DRAFT",
// the specification's short name, as in http://www.w3.org/TR/short-name/
shortName: "didm-veres-one",
// subtitle
subtitle: "A decentralized identifier method for the Veres One Blockchain",
// if you wish the publication date to be other than today, set this
// publishDate: "2009-08-06",
// if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
// and its maturity status
// previousPublishDate: "1977-03-15",
// previousMaturity: "WD",
// extend the bibliography entries
localBiblio: ccg.localBiblio,
github: "https://github.com/w3c-ccg/didm-veres-one",
includePermalinks: false,
// if there a publicly available Editor's Draft, this is the link
edDraftURI: "https://w3c-ccg.github.io/didm-veres-one/",
// if this is a LCWD, uncomment and set the end of its review period
// lcEnd: "2009-08-05",
// editors, add as many as you like
// only "name" is required
editors: [
{ name: "Manu Sporny", url: "http://manu.sporny.org/",
company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/" },
{ name: "Dave Longley", url: "https://github.com/dlongley",
company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/"},
],
// authors, add as many as you like.
// This is optional, uncomment if you have authors as well as editors.
// only "name" is required. Same format as editors.
authors:
[
{ name: "Manu Sporny", url: "http://manu.sporny.org/",
company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/" },
{ name: "Dave Longley", url: "https://github.com/dlongley",
company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/"},
{ name: "Chris Webber", url: "https://dustycloud.org/",
company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/"}
],
// name of the WG
wg: "Credentials Community Group",
// URI of the public WG page
wgURI: "https://www.w3.org/community/credentials/",
// name (with the @w3c.org) of the public mailing to which comments are due
wgPublicList: "public-credentials",
// URI of the patent status for this WG, for Rec-track documents
// !!!! IMPORTANT !!!!
// This is important for Rec-track documents, do not copy a patent URI from a random
// document unless you know what you're doing. If in doubt ask your friendly neighbourhood
// Team Contact.
wgPatentURI: "https://www.w3.org/community/about/agreements/cla/",
maxTocLevel: 4,
inlineCSS: true
};
</script>
<style>
pre .highlight {
font-weight: bold;
color: green;
}
pre .comment {
font-weight: bold;
color: Gray;
}
.sequence-diagram {
margin: auto;
}
</style>
</head>
<body>
<section id='abstract'>
<p>
The
<a href="https://veres.one/">Veres One</a> Blockchain is a permissionless
public ledger designed specifically for the creation and management of
<a href="https://w3c-ccg.github.io/did-spec/">decentralized identifiers</a>
(DIDs).
Veres One DIDs are self-administered identifiers that may be used by people,
organizations, and digital devices to establish an identifier that is
under their control. Veres One DIDs are useful in ecosystems where one needs
to issue, store, and use
<a href="https://w3c.github.io/vc-data-model/">Verifiable Credentials</a>. This
specification defines how a developer may create and update DIDs in the Veres
One Blockchain.
</p>
</section>
<section id='sotd'>
<p>
Comments regarding this document are welcome. Please file issues
directly on <a href="https://github.com/w3c-ccg/didm-veres-one/issues/">GitHub</a>,
or send them to
<a href="mailto:public-credentials@w3.org">public-credentials@w3.org</a>
(<a href="mailto:public-credentials-request@w3.org?subject=subscribe">subscribe</a>,
<a href="https://lists.w3.org/Archives/Public/public-credentials/">archives</a>).
</p>
<p>
Work on this specification has been funded in part by the United States
Department of Homeland Security's Science and Technology Directorate under
contract HSHQDC-17-C-00019. The content of this specification
does not necessarily reflect the position or the policy of the U.S.
Government and no official endorsement should be inferred.
</p>
<p>
Work on this specification has also been supported by the Rebooting the
Web of Trust group facilitated by Christopher Allen, Shannon Appelcline,
Kiara Robles, Kaliya Young, Brian Weller, Betty Dhamers, and Joe Andrieu.
</p>
<p>
Work on this specification has also been supported by the Internet Identity
Workshop co-founded by Phil Windley, Kaliya Young, and Doc Searls and
energized by true believers in the user-centric identity movement.
</p>
</section>
<section>
<h1>Introduction</h1>
<p>
The Veres One Project envisions a world where people and organizations
control their identifiers and their identity data. The Veres One
Blockchain is a fit-for-purpose blockchain optimized for identity on the
Web. The network ecosystem is designed to be self-sufficient through the
use of an innovative operational and funding model. The operational model
ensures openness, prevents attacks against the network, and financially
rewards individuals and organizations that choose to run software to
ensure the security of the network. Human dignity demands that every
individual be able to participate equally in our increasingly digital
society. That means everyone deserves the ability create and administer
unique, globally resolvable identifiers. For that reason, the network is
global and open to the public; anyone may participate.
</p>
<section>
<h2>The Problem</h2>
<p>
To date, every identifier you use online does not belong to you; it
belongs to someone else.
</p>
<p>
The Internet was not designed with interoperable identity systems in mind.
This inevitably forced websites to create their own solutions, which are
not interoperable.
</p>
<p>
When you sign up to a website, you typically create a username and a
password. The website asks you for this information so that it can start
to associate data with you. The more benevolent use of this data is to
customize an experience suited to your needs. This identifier and data,
however, are locked away on the site; they are not portable. Even the
global identifiers that websites use, such as your email address, are not
owned by you. The email address "you@bigcorp.com" isn’t owned by you, it’s
owned by BigCorp. You do not have control over your identifier nor your
data.
</p>
<p>
Since this data is not portable, you must rebuild your identity
information -- your identifiers and data -- from scratch on many different
websites. Duplicating that information often means sharing more than
intended, allowing websites to learn things and <em>infer</em> things about you
that you didn’t expect. It also means that each website accumulates toxic
data about you, inviting behavior like spam, financial fraud, data
siloing, data warehousing, and identity theft. Initiatives like the
European Union’s General Data Protection Regulation (GDPR) only increase
the pressure to address these problems.
</p>
<p>
In addition to risks from the information we explicitly share with
websites, there is also a vast amount of identity information already out
there, with few mechanisms for managing it. This outside information is
often combined with the information we share to create surprisingly
detailed profiles, used for everything from ad targeting to site
customization to custom pricing (not always for lower prices). The result
is a strong economic incentive for large data warehousing companies to
store and sell your information, often without your consent.
</p>
</section>
<section>
<h2>The Vision</h2>
<p>
The Veres One Blockchain's purpose is to enable all people and organizations
in the world to:
</p>
<ol>
<li>
create and own their online identifiers, and
</li>
<li>
control their identity data and with whom they share that data.
</li>
</ol>
<p>
Achieving this vision will enable a Web where:
</p>
<ul>
<li>
Our identity information and identifiers are owned and controlled by
each of us.
</li>
<li>
We can more strongly prove key attributes about our digital personas,
reducing fraud.
</li>
<li>
Data can be bound to identifiers under our control instead of only to
websites, or stuck on paper in file cabinets, improving data portability.
</li>
<li>
Privacy can be enhanced by choosing when and with whom our information
is shared.
</li>
<li>
Data sharing can be more easily reduced to the minimum required for a
given interaction.
</li>
</ul>
<p>
This vision is shared among a large community of people working within
global organizations such as the Internet Identity Workshop, World Wide
Web Consortium, Internet Engineering Task Force, United Nations ID2020,
Decentralized Identity Foundation, and the Rebooting the Web of Trust
project. This DID Method specification is a realization of this vision.
</p>
</section>
<section>
<h2>Goals</h2>
<p>
The Veres One Blockchain is a fit-for-purpose blockchain built
specifically for Decentralized Identifiers. This specialization enables
the blockchain to be faster, more cost effective, and more privacy
enhancing compared to existing blockchains that are being repurposed for
identity management. The Veres One Blockchain was designed and built with
the following goals in mind:
</p>
<ul>
<li>
<strong><em>Public</em></strong> - Anyone in the world may read and audit the
entire contents of the ledger.
</li>
<li>
<strong><em>Permissionless</em></strong> - Any person or organization in the
world may create and control their identifiers.
</li>
<li>
<strong><em>Leaderless</em></strong> - Blockchain consensus relies on leaderless
elector collaboration, not proof of work, to determine when consensus has been
finalized. Electors are selected dynamically to allow participants to join
and leave the network and to ensure that there is no centralization or
single point of failure for the ledger.
</li>
<li>
<strong><em>
Based entirely on open standards and open specifications
</strong></em>
- Broad implementation and interoperability can only be achieved if all aspects
of the system are documented and standardized in a non-discriminatory,
patent-free and royalty-free manner while ensuring that the creators and
maintainers of the system are properly funded.
</li>
<li>
<strong><em>Built on a stakeholder driven governance model</em></strong> - The
source code and development team have a strict mission-driven focus that always
puts the users of the ledger first.
</li>
<li>
<strong><em>Economically sustainable</em></strong> - The people that create,
run, and protect the network are paid by the Veres One Project to do so.
Avoiding a "tragedy of the commons" is essential for sound network economics
for a global public utility.
</li>
<li>
<strong><em>Non-speculative</em></strong> - Unlike other ledgers, the Veres
One Blockchain does not need a speculative network token or cryptocurrency,
which eliminates currency speculation, thus ensuring predictable long term
operational costs.
</li>
</ul>
</section>
<section>
<h2>Performance</h2>
<p>
Based on the goals stated in the previous section, benchmarking has been
performed on the reference Veres One implementation that is able to achieve
the following performance characteristics.
</p>
<p class="issue"
title="Warning: Benchmarks are not reflective of real world performance">
Benchmarking is a poor substitute for measurements taken over long periods of
time in hostile environments such as the public Internet. Attacks, routing
inefficiencies, packet drops, misconfigured software, and annoying physical
limitations such as the speed of light all contribute to degraded performance
in real world settings. This section should be taken with a large grain of salt
until we have dependable real world data.
</p>
<p class="issue"
title="Warning: Benchmarks are highly dependent on node configuration">
The configuration for the benchmarks used 1 database with 7 electors
configured. The database was an AWS AWS i3.large instance consisting
of 2 vCPUs, 15.25GB RAM and Local NVME Storage. Each node was an AWS
c5.large instance with 2 vCPUs and 4GB RAM.
</p>
<p>
The Veres One Blockchain uses a leaderless, non-blocking,
byzantine fault tolerant consensus algorithm called Continuity.
There are 3f+1 nodes in the system where <em>f</em> is the number of
byzantine failures the network can tolerate.
Since the algorithm is non-blocking and nodes can progress
at their own pace, the limiting factor is how quickly events can be gossiped
around the network. This approach results in very high throughputs.
Transactions are limited by two factors: 1) the fastest 2/3rds
of elector's database write speeds and 2) the time it takes to distribute
12f + 1 merge events to every elector in the network, the rate of which is
an exponential function.
</p>
<table class="simple">
<thead>
<tr>
<th>Metric</th>
<th>Capability</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
Throughput
</td>
<td>
209/sec, 18M/day, 6.6B/year
</td>
<td>
The throughput is a function of how quickly 12f+1 events can be transmitted to
each elector. Limiting factors include database write speed,
communication speed, and digital signature verification speed.
</td>
</tr>
<tr>
<td>
Consensus Latency
</td>
<td>
~15-30 seconds
</td>
<td>
The latency is a function of how many electors there are in the system. How
many electors there are in the system is a function of the risk tolerance of
the network.
</td>
</tr>
</tbody>
</table>
</section>
<section>
<h3>Document Organization</h3>
<p>
This document is organized as follows:
</p>
<ul>
<li>
<a href="#introduction">Section 1: Introduction</a> provides a basic
introduction to the Veres One DID Method.
</li>
<li>
<a href="#terminology">Section 2: Terminology</a> defines basic terminology
used throughout this document.
</li>
<li>
<a href="#data-model">Section 3: The Data Model</a> describes the basic data
model used for the <a>ledger</a>.
</li>
<li>
<a href="#basic-concepts">Section 4: Basic Concepts</a> describes the
Veres One DID format, and how authentication and authorization is performed
using Veres One DIDs.
</li>
<li>
<a href="#syntax">Section 5: Operations</a> describes HTTP API discovery and
how to execute operations on the ledger.
</li>
<li>
<a href="#examples">Appendix A: Examples</a> provides complete examples that
may be useful to developers.
</li>
</ul>
<section id="conformance">
<!-- boilerplate will be added here -->
<p>
There are two conformance classes described in this specification. The first
are clients that use the HTTP API to perform <a>operations</a>. The second
are Veres One Nodes, which expose the HTTP API to clients. Clients and
Veres One Nodes MUST implement all mandatory features as listed by this
specification and SHOULD implement optional features.
</p>
</section>
</section>
</section>
<section class="normative">
<h2>Terminology</h2>
<dl class="termlist">
<dt><dfn data-lt="blocks">block</dfn></dt>
<dd>
A data structure that contains one or more <a>ledger</a> <a>events</a>.
</dd>
<dt><dfn data-lt="blockchain|blockchains">blockchain</dfn></dt>
<dd>
A <a>ledger</a> containing a series of <a>blocks</a> where the ordering of
the blocks can be mathematically proven to be correct.
</dd>
<dt><dfn data-lt="consensus algorithm|consensus algorithms">consensus algorithm</dfn></dt>
<dd>
An algorithm that enables multiple nodes in a network to make a decision
in a deterministic fashion.
</dd>
<dt><dfn data-lt="cryptographic ledger|cryptographic ledgers|ledger">cryptographic ledger</dfn></dt>
<dd>
A method of recording changes in a <a>state machine</a> where the
accuracy of the ledger can be mathematically proven to be correct.
</dd>
<dt><dfn data-lt="decentralized system|decentralized systems">decentralized system</dfn></dt>
<dd>
A system in which lower level components operate on local information to
accomplish global goals. For example, an ant colony is a decentralized system
as there is no central control determining when food must be collected or
how new tunnels should be excavated.
</dd>
<dt><dfn data-lt="decentralized ledger|decentralized ledgers">decentralized ledger</dfn></dt>
<dd>
A <a>cryptographic ledger</a> that uses a <a>consensus algorithm</a> that
enables a network of <a>ledger nodes</a> to come to consensus in a
decentralized yet deterministic fashion.
</dd>
<dt><dfn data-lt="event|events">event</dfn></dt>
<dd>
Any data recorded in a <a>ledger</a> that changes the
<a>state machine</a>. Events typically contain <a>operations</a>.
</dd>
<dt><dfn data-lt="ledger agent|ledger agents">ledger agent</dfn></dt>
<dd>
A software program that instructs a <a>ledger node</a> to perform specific
actions such as reading or writing data.
</dd>
<dt><dfn data-lt="ledger node|ledger nodes">ledger node</dfn></dt>
<dd>
A software program that reads and writes from particular instance of
a <a>ledger</a> by executing algorithms according to the rules of the ledger.
The ledger node may be instructed to perform actions on the ledger by a
<a>ledger agent</a>.
</dd>
<dt><dfn data-lt="operations">operation</dfn></dt>
<dd>
An instruction to a <a>ledger agent</a> to modify the <a>state machine</a>
in a particular way.
</dd>
<dt><dfn data-lt="state machine|state machines">state machine</dfn></dt>
<dd>
A system that when given a particular input changes from one internal state
to another internal state. For example, a computer system that operates a
light bulb starts with the light state set to off. When an input to turn
the light on is given, the internal computer system state sets the light
state to on, thus illuminating the light bulb.
</dd>
</dl>
</section>
<section>
<h1>Core Data Model</h1>
<p>
The Veres One Data model is a graph-based data model. The syntax used for the
data model is [[!JSON-LD]], which is based on 18+ years of Linked Data
standardization work at the W3C. The ledger portions of the data model build
upon the [[!WEB-LEDGER]] specification. The digital signatures and proofs data
models build upon the, [[!LD-PROOFS]] and [[!LD-SIGNATURES]] specifications.
The Decentralized Identifiers portion of the data model builds upon
the [[!DID]] specification.
</p>
<figure>
<img src="diagrams/data-model.svg" style="max-width: 50%;"/>
<figcaption>
The Veres One data model
</figcaption>
</figure>
<p>
The core data model is fairly simple and consists of a Ledger. The Ledger
contains Blocks. The Blocks contain Operations. The Operations contain
instructions that modify the state of the ledger. For example, there are
Operations to create a DID Document and update a DID Document.
</p>
<p>
The data model also consists of a state machine that is modified as
Operations execute. The state machine can be queried using Veres One DIDs,
which will return the current DID Document associated with the Veres One DID.
</p>
</section>
<section>
<h1>Basic Concepts</h1>
<section>
<h2>Veres One DID Format</h2>
<p>
Veres One DIDs have the following format:
</p>
<p class="issue" title="ABNF needs to be more restrictive">
The ABNF below needs to be tightened up. For example, it should enforce
the UUID format if UUID-based Veres One DIDs are used.
</p>
<pre class="nohighlight">
v1-did = "did:v1:" v1-did-type ": " v1-identifier
[ ";" did-service ] [ "/" did-path ]
[ "?" did-query ] [ "#" did-fragment ]
v1-did-type = ( "nym" / "uuid" )
v1-identifier = %x41-5A / %x61-7A / %x5F / %2D
</pre>
<p>
There are two primary classes of DID-based identifiers in Veres One. The first
type of identifier is called a cryptonym-based identifier. This identifier
is a SHA-256 hash of a public key. Cryptonym-based identifiers are not required
to be registered on the ledger and may be used as unregistered pseudonymous
pairwise identifiers. These identifiers may also be registered on the
ledger and MUST contain a <code>authentication</code> key with a public key
fingerprint equal to the value of the cryptonym-based identifier.
</p>
<pre class="example nohighlight" title="A valid Veres One Cryptonym-based Decentralized Identifier">
did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ
</pre>
<p>
The second type of identifier on Veres One is a UUID-based identifier and
may be used by entities that want to store metadata on the ledger. These sorts
of identifiers are often used, but not limited to, storing and refering to
Capabilities and Revocation lists.
</p>
<pre class="example nohighlight" title="A valid Veres One UUID-based Decentralized Identifier">
did:v1:uuid:804c6ac3-ce3b-46ce-b134-17175d5bee74
</pre>
</section>
<section>
<h2>Authentication</h2>
<p>
Authentication is the process the ledger uses to determine if an entity
is associated with a DID.
</p>
<pre class="example nohighlight" title="Expressing authentication credentials">
{
"@context": "https://w3id.org/veres-one/v1",
"id": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ",
<span class="highlight">"authentication": [... array of acceptable authentication suites ...]</span>
}
</pre>
<p>
A detailed example of a valid set of authentication credentials follows:
</p>
<pre class="example nohighlight" title="Detailed example of authentication credentials entry">{
"@context": "https://w3id.org/veres-one/v1",
"id": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ",
"authentication": [{
"type": "Ed25519SignatureAuthentication2018",
"publicKey": {
"id": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ#authn-key-1",
"type": "Ed25519VerificationKey2018",
"owner": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ",
"publicKeyBase58": "HURvcFiZbmtaQQMhkVVoq1JpxxRe8UrBS5wBQMJhXkfM",
}
}],
...</pre>
</section>
<section>
<h2>Authorization</h2>
<p>
The Veres One Ledger uses
<a href="https://w3c-ccg.github.io/ld-ocap/">Linked Data Object
Capabilities</a> to authorize operations to be performed on DID Documents.
</p>
<p>
Granting a capability is equivalent to giving someone your car keys. Your
car doesn't know who the person is with the key, it just knows that when the
key is turned in the ignition, the car should start.
The benefit of object capabilities is that, unlike a car key, you can set
arbitrary restrictions on the usage of a capability. For example, setting
an expiration time for the capability, or a geofenced zone in which it can
be used.
</p>
<p>
The Veres One data model supports two types of capability suites, one for
granting capabilities and the other for invoking capabilities.
</p>
<pre class="example nohighlight" title="">{
"@context": "https://w3id.org/veres-one/v1",
"id": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ",
<span class="highlight">"grantCapability": [... array of capability grant suites ...]</span>
<span class="highlight">"invokeCapability": [... array of capability invocation suites ...]</span>
}
</pre>
<p>
A detailed example of a valid set of authorization capability descriptions
follows:
</p>
<pre class="example nohighlight" title="">
{
"@context": "https://w3id.org/veres-one/v1",
"id": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ",
...
"grantCapability": [{
"type": "Ed25519SignatureCapabilityAuthorization2018",
"publicKey": {
"id": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ#ocap-grant-key-1",
"type": "Ed25519VerificationKey2018",
"owner": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ",
"publicKeyBase58": "HURvcFiZbmtaQQMhkVVoq1JpxxRe8UrBS5wBQMJhXkfM"
}
}],
"invokeCapability": [{
"type": "Ed25519SignatureCapabilityAuthorization2018",
"publicKey": {
"id": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ#ocap-invoke-key-1",
"type": "Ed25519VerificationKey2018",
"owner": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ",
"publicKeyBase58": "Gu5yfYsbYvmSeSsAbBBNafy9i6G3o5kiX5PxUGPg1iFJ"
}
}]
}
</pre>
</section>
</section>
<section>
<h1>Operations</h1>
<p>
Every conforming Veres One Blockchain Node MUST expose at least the following
HTTP endpoints:
</p>
<table class="simple">
<thead>
<th>Service</th>
<th>Example URL</th>
<th>Description</th>
</thead>
<tbody>
<tr>
<td>veresOneOperationsService</td>
<td>POST /ledger-agents/123/operations</td>
<td>Create or update a DID Document.</td>
</tr>
<tr>
<td>veresOneReadService</td>
<td>GET /dids/{did}</td>
<td>Gets an existing DID Document.</td>
</tr>
</tbody>
</table>
<section>
<h2>HTTP API Discovery</h2>
<p>
A website may provide HTTP API endpoint discovery by embedding JSON-LD in their
top-most HTML web page (e.g. at <code>https://example.com/</code>):
</p>
<pre class="example highlight" title="Example of HTML-based service description">
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Example Website</title>
<link rel="stylesheet" href="style.css">
<script src="script.js"></script>
<script type="application/ld+json">
{
"@context": "https://w3id.org/veres-one/v1",
"id": "https://example.com/",
"name": "Example Website",
"veresOneOperationsService": "https://example.com/ledger-agents/123/operations",
"veresOneReadService": "https://example.com/veres-one/dids/"
}
</script>
</head>
<body>
<!-- page content -->
</body>
</html>
</pre>
<p>
Service descriptions may also be requested via content negotiation.
In the following example a JSON-compatible service description is provided
(e.g. <code>curl -H "Accept: application/json" https://example.com/</code>):
</p>
<pre class="example highlight" title="Example of a JSON-based service description">
{
"@context": "https://w3id.org/veres-one/v1",
"id": "https://example.com/",
"name": "Example Website",
"veresOneOperationsService": "https://example.com/ledger-agents/123/operations",
"veresOneReadService": "https://example.com/veres-one/dids/"
}
</pre>
</section>
<section>
<h2>Creating a DID</h2>
<p>
A DID is created by performing an HTTP POST of a signed operation
to the <code>veresOneOperationsService</code>. The following HTTP status codes
are defined for this service:
</p>
<table class="simple">
<thead>
<th style="white-space: nowrap">HTTP Status</th>
<th>Description</th>
</thead>
<tbody>
<tr>
<td>202</td>
<td>
DID creation request was accepted. The HTTP <code>Location</code> header will
contain the URL for the newly created ledger operation. The operation is not
guaranteed to succeed. You can check to see if the operation succeeded by
requesting the operation, which will eventually refer to an event and a block
if it was successful.
</td>
</tr>
<tr>
<td>400</td>
<td>Operation failed.</td>
</tr>
<tr>
<td>409</td>
<td>Create operation failed because a duplicate DID exists.</td>
</tr>
</tbody>
</table>
<p>
An example exchange of DID creation request is shown below:
</p>
<pre class="example highlight" title="DID creation request">
POST /ledger-agents/123/operations HTTP/1.1
Host: example.com
Content-Type: application/ld+json
Content-Length: 1062
Accept: application/ld+json, application/json, text/plain, */*
Accept-Encoding: gzip, deflate
{
"@context": "https://w3id.org/veres-one/v1",
"type": "CreateWebLedgerRecord",
"record": {
"@context": "https://w3id.org/veres-one/v1",
"id": "did:v1:test:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ",
"authentication": [{
"type": "Ed25519SignatureAuthentication2018",
"publicKey": {
"id": "did:v1:test:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ#authn-key-1",
"type": "Ed25519SigningKey2018",
"owner": "did:v1:test:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ",
"publicKeyBase58": "Gu5yfYsbYvmSeSsAbBBNafy9i6G3o5kiX5PxUGPg1iFJ"
}
}],
"grantCapability": [{
"type": "Ed25519SignatureCapabilityAuthorization2018",
"publicKey": {
"id": "did:v1:test:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ#ocap-grant-key-1",
"type": "Ed25519SigningKey2018",
"owner": "did:v1:test:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ",
"publicKeyBase58": "HURvcFiZbmtaQQMhkVVoq1JpxxRe8UrBS5wBQMJhXkfM"
}
}],
"invokeCapability": [{
"type": "Ed25519SignatureCapabilityAuthorization2018",
"publicKey": {
"id": "did:v1:test:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ#ocap-invoke-key-1",
"type": "Ed25519SigningKey2018",
"owner": "did:v1:test:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ",
"publicKeyBase58": "FPa3QX9pPk1Qw75CAnhF2Qv2HwuWke4yxbqxzQbU5PLU"
}
}]
},
"proof": [{
"type" : "Ed25519Signature2018",
"created" : "2018-02-24T22:23:44Z",
"creator" : "did:v1:test:nym:5YSwjvBZqDbYQkoRG7jD7bCKifVdHBtxHMrATZyTX8xv#ocap-invoke-key-1",
"capability" : "did:v1:test:nym:5YSwjvBZqDbYQkoRG7jD7bCKifVdHBtxHMrATZyTX8xv",
"capabilityAction" : "RegisterDid",
"jws" : "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..
_h3x8FRH6GXbSBGgtqtGRQc_HabNgYSv4M124oFG-1dzi4nJzJyXTXcNt8vb7mJV3fj
Izyt0jhO8hsmMJWf8Cw",
"proofPurpose" : "invokeCapability"
}, {
"type" : "EquihashProof2018",
"created" : "2018-02-24T22:23:45Z",
"equihashParameterK" : 3,
"equihashParameterN" : 64,
"nonce" : "AgAAAA==",
"proofValue" : "AAAVYwABwK8AAME7AAGOjAAAVkIAATc9AAFDLQABrc8="
}]
}
</pre>
<p>
If the creation of the DID was successful, an HTTP 201 status code is
expected in return:
</p>
<pre class="example highlight" title="Successful DID creation response">
HTTP/1.1 202 Accepted
Location: https://ledger.example.com/ledger-agents/123/operations/ni%3A%2F%2F%2Fsha-256%3BXk0ruJlbQTpFOyzbsl_KL8vKQiahMj7t9h-v70BMwAQ
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Date: Fri, 14 Oct 2016 18:35:33 GMT
Connection: keep-alive
Transfer-Encoding: chunked
</pre>
</section>
<section>
<h2>Updating a DID Document</h2>
<p>
A DID is updated by performing an HTTP POST of a signed DID Document
to the <code>veresOneUpdateService</code>. The following HTTP status codes
are defined for this service:
</p>
<table class="simple">
<thead>
<th style="white-space: nowrap">HTTP Status</th>
<th>Description</th>
</thead>
<tbody>
<tr>
<td>200</td>
<td>
DID update request was successful.
</td>
</tr>
<tr>
<td>400</td>
<td>DID update request failed.</td>
</tr>
</tbody>
</table>
<p>
An example exchange for a DID update request is shown below:
</p>
<pre class="example highlight" title="DID Document update request">
POST /ledger-agents/123/operations HTTP/1.1
Host: example.com
Content-Type: application/ld+json
Content-Length: 1062
Accept: application/ld+json, application/json, text/plain, */*
Accept-Encoding: gzip, deflate
{
"@context": "https://w3id.org/veres-one/v1",
"type": "UpdateWebLedgerRecord",
"patch": [{
"op": "add",
"path": "/authentication",
"value": {
"type": "Ed25519SignatureAuthentication2018",
"publicKey": {
"id": "did:v1:test:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ#authn-key-2",
"type": "Ed25519SigningKey2018",
"owner": "did:v1:test:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ",
"publicKeyBase58": "BpJk2oxtkm99ubKqhtLF7fB2fCM1bETgpJLFg8QEuQK2"
}
}
}, {
"op": "remove",
"path": "/services/3",
}],
"proof": [{
"type" : "Ed25519Signature2018",
"created" : "2018-02-24T22:23:42Z",
"creator" : "did:v1:test:nym:91LAKSKtybvFjUdkTitBVXEF1kz9s24TCARuLfWBKGmw#ocap-invoke-key-1",
"capability" : "did:v1:test:nym:91LAKSKtybvFjUdkTitBVXEF1kz9s24TCARuLfWBKGmw",
"capabilityAction" : "RegisterDid",
"jws" : "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..Ldx
5HbvS7-SvKTPGbRwBhc5xub95th__2-pphFRZUHFNd4Qs6R3u9j5elQkHciuLhvKB6a0
fURMa4puZNWLLDg",
"proofPurpose" : "invokeCapability"
}, {
"type": "EquihashProof2017",
"equihashParameterN": 64,
"equihashParameterK": 3,
"nonce": "AQAAAA==",
"proofValue": "AAAOgAA0jcAEAAXbA1EsQMgAAGfF7TwABAfNiAA78QA="
}]
}
</pre>
<p>
If the update request for the DID Document was successful, an HTTP 202 status
code is expected in return: