Skip to content

Commit ad47d0e

Browse files
stevenjstevenj
committed
docs(docs): Voter Ballot seems finished
1 parent 1e154c9 commit ad47d0e

File tree

61 files changed

+1730
-732
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

61 files changed

+1730
-732
lines changed

‎.config/dictionaries/project.dic‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
aarch
22
abcz
33
ABNF
4+
abnfb
45
addrr
56
addrs
67
adminer
@@ -43,6 +44,7 @@ childs
4344
Chotivichit
4445
chrono
4546
cids
47+
cidv
4648
ciphertext
4749
ciphertexts
4850
Coap
@@ -191,7 +193,9 @@ moka
191193
MPMC
192194
msvc
193195
Multiaddr
196+
multicodec
194197
multiera
198+
multihash
195199
mutlisig
196200
mypy
197201
nanos
@@ -252,6 +256,7 @@ REMOVEDIR
252256
renameat
253257
Replayability
254258
Repr
259+
reqs
255260
reqwest
256261
retriggering
257262
ristretto

‎.markdownlint.jsonc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,11 @@
2727
// MD007/ul-indent - Unordered list indentation
2828
"MD007": {
2929
// Spaces for indent
30-
"indent": 2,
30+
"indent": 4,
3131
// Whether to indent the first level of the list
3232
"start_indented": false,
3333
// Spaces for first level indent (when start_indented is set)
34-
"start_indent": 2
34+
"start_indent": 4
3535
},
3636
// MD009/no-trailing-spaces - Trailing spaces
3737
"MD009": {

‎docs/src/architecture/08_concepts/signed_doc/cddl/aes_ctr_encrypted_block.cddl‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
; AES-CTR encrypted data.
2+
; The Nonce/IV is the UUIDv7 `document_ver`.
3+
; This is the correct size, and has the necessary randomness properties.
4+
; The first block uses the `document_ver` the second `document_ver+1` and so on.
5+
; The document_ver is interpreted as a Big Endian 128bit integer for the purpose
6+
; of the addition.
7+
;
8+
; As the CTR is predictable, the blocks can be decrypted in parallel for maximum performance.
9+
10+
11+
; AES-CTR Encrypted Data Block
12+
aes-ctr-encrypted-block = bytes .size 16

‎docs/src/architecture/08_concepts/signed_doc/cddl/aes_ctr_encrypted_choices.cddl‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
; Choices are constructed as a CBOR multidimensional array of the form:
2+
; `[ +[+choice] ]`
3+
; reflecting the choices in the rows and columns as present 1:1 in the encrypted
4+
; choices.
5+
;
6+
; This data is then compressed using `brotli` compression, and the result is encrypted
7+
; using AES-CTR and encoded as a sequence of blocks here.
8+
;
9+
; Data needs to be pre-compressed before encryption as encryption will make the data
10+
; incompressible.
11+
;
12+
; The Encryption Key is to be derived from the Voters catalyst key-chain and not to be
13+
; published.
14+
; Derivation *MUST* include the contest Document ID and Version, so that the same
15+
; encryption key is never used twice for different contests, but can still be re-derived
16+
; by a voter that holds their catalyst key-chain recovery keys.
17+
18+
19+
; Encrypted Voter Choices
20+
aes-ctr-encrypted-choices = +aes-ctr-encrypted-block
21+
22+
; AES-CTR Encrypted Data Block
23+
aes-ctr-encrypted-block = bytes .size 16

‎docs/src/architecture/08_concepts/signed_doc/cddl/cbor_cid.cddl‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
; CIDv1 ABNF Constrained for SHA2-256
2+
3+
4+
; CIDv1 ABNF Constrained for SHA2-256
5+
cbor-cid = '
6+
cid = cidv1 codec-cbor sha2-256 digest-32 digest
7+
cidv1 = %x00 %x01
8+
codec-cbor = %x51
9+
sha2-256 = %x12
10+
digest-32 = %x20
11+
digest = 32(%x00-FF)
12+
'

‎docs/src/architecture/08_concepts/signed_doc/cddl/chain.cddl‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -42,9 +42,19 @@ document_ver = uuid_v7
4242

4343
; Where a document can be located, must be a unique identifier.
4444
document_locator = {
45-
"cid" => cid
45+
"cid" : cid
4646
}
4747

48-
; IPLD content identifier
49-
; TODO: add size limits if possible
50-
cid = #6.42(bytes)
48+
; IPLD content identifier.
49+
; Currently limited to SHA2-256 based CIDs.
50+
cid = #6.42(bytes .abnfb ("cid" .det cbor-cid ))
51+
52+
; CIDv1 ABNF Constrained for SHA2-256
53+
cbor-cid = '
54+
cid = cidv1 codec-cbor sha2-256 digest-32 digest
55+
cidv1 = %x00 %x01
56+
codec-cbor = %x51
57+
sha2-256 = %x12
58+
digest-32 = %x20
59+
digest = 32(%x00-FF)
60+
'

‎docs/src/architecture/08_concepts/signed_doc/cddl/choices.cddl‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
; Choices are an array of encrypted or unencrypted choices.
2+
3+
4+
; Voters Choices.
5+
choices = [ 0, clear-choices ] /
6+
[ 1, elgamal-ristretto255-encrypted-choices ]
7+
8+
; Universal Unencrypted Set of Choices
9+
clear-choices = ( +clear-choice )
10+
11+
; Universal Unencrypted Choice
12+
clear-choice = int
13+
14+
; elgamal/ristretto255 Encrypted Choices
15+
elgamal-ristretto255-encrypted-choices = [
16+
[+ elgamal-ristretto255-encrypted-choice],
17+
? row-proof
18+
]
19+
20+
; The elgamal encrypted ciphertext `(c1, c2)`.
21+
elgamal-ristretto255-encrypted-choice = [
22+
c1: elgamal-ristretto255-group-element,
23+
c2: elgamal-ristretto255-group-element,
24+
]
25+
26+
; An individual Elgamal group element that composes the elgamal cipher text.
27+
elgamal-ristretto255-group-element = bytes .size 32
28+
29+
; Universal Encrypted Row Proof
30+
row-proof = [0, zkproof-elgamal-ristretto255-unit-vector-with-single-selection ]
31+
32+
zkproof-elgamal-ristretto255-unit-vector-with-single-selection = [ +zkproof-elgamal-ristretto255-unit-vector-with-single-selection-item, zkproof-ed25519-scalar ]
33+
34+
; Proof that the row is a unit vector with a single selection.
35+
zkproof-elgamal-ristretto255-unit-vector-with-single-selection-item = ( zkproof-elgamal-announcement, ~elgamal-ristretto255-encrypted-choice, zkproof-ed25519-r-response )
36+
37+
; ZK Proof Announcement values for Elgamal.
38+
zkproof-elgamal-announcement = ( zkproof-elgamal-group-element, zkproof-elgamal-group-element, zkproof-elgamal-group-element )
39+
40+
; An individual Elgamal group element used in ZK Proofs.
41+
zkproof-elgamal-group-element = bytes .size 32
42+
43+
; ZK Proof Response values for Ed25519.
44+
zkproof-ed25519-r-response = ( zkproof-ed25519-scalar, zkproof-ed25519-scalar, zkproof-ed25519-scalar )
45+
46+
; An individual Ed25519 scalar used in ZK Proofs.
47+
zkproof-ed25519-scalar = bytes .size 32

‎docs/src/architecture/08_concepts/signed_doc/cddl/cid.cddl‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
; IPLD content identifier.
2+
; Also known as an IPFS CID.
3+
; Currently limited to SHA2-256 based CIDs.
4+
; See: https://docs.ipfs.tech/concepts/content-addressing/#what-is-a-cid
5+
; https://github.com/ipld/cid-cbor/
6+
7+
8+
; IPLD content identifier.
9+
; Currently limited to SHA2-256 based CIDs.
10+
cid = #6.42(bytes .abnfb ("cid" .det cbor-cid ))
11+
12+
; CIDv1 ABNF Constrained for SHA2-256
13+
cbor-cid = '
14+
cid = cidv1 codec-cbor sha2-256 digest-32 digest
15+
cidv1 = %x00 %x01
16+
codec-cbor = %x51
17+
sha2-256 = %x12
18+
digest-32 = %x20
19+
digest = 32(%x00-FF)
20+
'

‎docs/src/architecture/08_concepts/signed_doc/cddl/clear_choice.cddl‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
; An Choice Selection (clear/unencrypted).
2+
;
3+
; This can be a positive or negative integer, and is
4+
; constrained by the parameters of the contest.
5+
6+
7+
; Universal Unencrypted Choice
8+
clear-choice = int

‎docs/src/architecture/08_concepts/signed_doc/cddl/clear_choices.cddl‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
; A Choice Selection (clear/unencrypted).
2+
;
3+
; This can be a positive or negative integer, and is
4+
; constrained by the parameters of the contest.
5+
6+
7+
; Universal Unencrypted Set of Choices
8+
clear-choices = ( +clear-choice )
9+
10+
; Universal Unencrypted Choice
11+
clear-choice = int

0 commit comments

Comments
 (0)