aboutsummaryrefslogtreecommitdiff
path: root/spec/srv-spec
diff options
context:
space:
mode:
authorNick Mathewson <nickm@torproject.org>2023-10-14 14:07:40 -0400
committerNick Mathewson <nickm@torproject.org>2023-10-14 14:07:40 -0400
commit4ba45dfd9afd08edeb46243127a480f1d23b9640 (patch)
tree4dcdb3b4ac378b255d8292693ef234100bf67ac5 /spec/srv-spec
parentd4b9bcc71565e1c3b7b74ddfcd44730697c10c6b (diff)
downloadtorspec-4ba45dfd9afd08edeb46243127a480f1d23b9640.tar.gz
torspec-4ba45dfd9afd08edeb46243127a480f1d23b9640.zip
Run mdformat on the spec files.
Diffstat (limited to 'spec/srv-spec')
-rw-r--r--spec/srv-spec/overview.md8
-rw-r--r--spec/srv-spec/protocol.md24
-rw-r--r--spec/srv-spec/security-analysis.md8
-rw-r--r--spec/srv-spec/specification-spec.md34
4 files changed, 37 insertions, 37 deletions
diff --git a/spec/srv-spec/overview.md b/spec/srv-spec/overview.md
index 6da4599..a9f4c99 100644
--- a/spec/srv-spec/overview.md
+++ b/spec/srv-spec/overview.md
@@ -22,7 +22,7 @@ cryptographically hashes the random value and calls the output its
The idea is that given a reveal value you can cryptographically confirm that
it corresponds to a given commitment value (by hashing it). However given a
commitment value you should not be able to derive the underlying reveal
-value. The construction of these values is specified in section [COMMITREVEAL].
+value. The construction of these values is specified in section \[COMMITREVEAL\].
<a id="srv-spec.txt-2.1"></a>
@@ -62,7 +62,7 @@ Commit phase:
<a id="srv-spec.txt-2.3"></a>
-## How we use the consensus [CONS]
+## How we use the consensus \[CONS\]
The produced shared random values need to be readily available to
clients. For this reason we include them in the consensus documents.
@@ -70,7 +70,7 @@ clients. For this reason we include them in the consensus documents.
Every hour the consensus documents need to include the shared random value
of the day, as well as the shared random value of the previous day. That's
because either of these values might be needed at a given time for a Tor
-client to access a hidden service according to section [TIME-OVERLAP] of
+client to access a hidden service according to section \[TIME-OVERLAP\] of
proposal 224. This means that both of these two values need to be included
in votes as well.
@@ -124,7 +124,7 @@ reachability consequences for hidden service clients.
<a id="srv-spec.txt-2.4"></a>
-## Persistent State of the Protocol [STATE]
+## Persistent State of the Protocol \[STATE\]
A directory authority needs to keep a persistent state on disk of the on
going protocol run. This allows an authority to join the protocol seamlessly
diff --git a/spec/srv-spec/protocol.md b/spec/srv-spec/protocol.md
index 7a17004..683b65e 100644
--- a/spec/srv-spec/protocol.md
+++ b/spec/srv-spec/protocol.md
@@ -4,13 +4,13 @@
In this section we give a detailed specification of the protocol. We
describe the protocol participants' logic and the messages they send. The
-encoding of the messages is specified in the next section ([SPEC]).
+encoding of the messages is specified in the next section (\[SPEC\]).
Now we go through the phases of the protocol:
<a id="srv-spec.txt-3.1"></a>
-## Commitment Phase [COMMITMENTPHASE]
+## Commitment Phase \[COMMITMENTPHASE\]
The commit phase lasts from 00:00UTC to 12:00UTC.
@@ -43,7 +43,7 @@ authorities. Any subsequent commitments MUST be ignored.
<a id="srv-spec.txt-3.1.2"></a>
-### Persistent State During Commitment Phase [STATECOMMIT]
+### Persistent State During Commitment Phase \[STATECOMMIT\]
During the commitment phase, authorities save in their persistent state the
authoritative commits they have received from each authority. Only one commit
@@ -77,12 +77,12 @@ the new commitment MUST be ignored.
<a id="srv-spec.txt-3.2.2"></a>
-### Persistent State During Reveal Phase [STATEREVEAL]
+### Persistent State During Reveal Phase \[STATEREVEAL\]
During the reveal phase, authorities keep the authoritative commits from the
commit phase in their persistent state. They also save any received reveals
that correspond to authoritative commits and are valid (as specified in
-[VALIDATEVALUES]).
+\[VALIDATEVALUES\]).
An authority that just received a reveal value from another authority's vote,
MUST wait till the next voting round before including that reveal value in
@@ -96,18 +96,18 @@ Finally, at 00:00UTC every day, authorities compute a fresh shared random
value and this value must be added to the consensus so clients can use it.
Authorities calculate the shared random value using the reveal values in
-their state as specified in subsection [SRCALC].
+their state as specified in subsection \[SRCALC\].
Authorities at 00:00UTC start including this new shared random value in
their votes, replacing the one from two protocol runs ago. Authorities also
start including this new shared random value in the consensus as well.
Apart from that, authorities at 00:00UTC proceed voting normally as they
-would in the first round of the commitment phase (section [COMMITMENTPHASE]).
+would in the first round of the commitment phase (section \[COMMITMENTPHASE\]).
<a id="srv-spec.txt-3.3.1"></a>
-### Shared Randomness Calculation [SRCALC]
+### Shared Randomness Calculation \[SRCALC\]
An authority that wants to derive the shared random value SRV, should use
the appropriate reveal values for that time period and calculate SRV as
@@ -126,7 +126,7 @@ is the corresponding reveal value of that authority for the current period.
Also, REVEAL_NUM is the number of revealed values in this construction,
VERSION is the protocol version number and PREVIOUS_SRV is the previous
shared random value. If no previous shared random value is known, then
-PREVIOUS_SRV is set to 32 NUL (\x00) bytes.
+PREVIOUS_SRV is set to 32 NUL (\\x00) bytes.
To maintain consistent ordering in HASHED_REVEALS, all the ID_a | R_a pairs
are ordered based on the R_a value in ascending order.
@@ -135,7 +135,7 @@ are ordered based on the R_a value in ascending order.
## Bootstrapping Procedure
-As described in [CONS], two shared random values are required for the HSDir
+As described in \[CONS\], two shared random values are required for the HSDir
overlay periods to work properly as specified in proposal 224. Hence
clients MUST NOT use the randomness of this system till it has bootstrapped
completely; that is, until two shared random values are included in a
@@ -144,7 +144,7 @@ produced, which takes 48 hours.
<a id="srv-spec.txt-3.5"></a>
-## Rebooting Directory Authorities [REBOOT]
+## Rebooting Directory Authorities \[REBOOT\]
The shared randomness protocol must be able to support directory
authorities who leave or join in the middle of the protocol execution.
@@ -162,4 +162,4 @@ the protocol SHOULD still carry commits and reveals of others in their vote.
Finally, authorities MUST implement their persistent state in such a way that they
will never commit two different values in the same protocol run, even if they
have to reboot in the middle (assuming that their persistent state file is
-kept). A suggested way to structure the persistent state is found at [STATEFORMAT].
+kept). A suggested way to structure the persistent state is found at \[STATEFORMAT\].
diff --git a/spec/srv-spec/security-analysis.md b/spec/srv-spec/security-analysis.md
index 658c2f8..a1cc72d 100644
--- a/spec/srv-spec/security-analysis.md
+++ b/spec/srv-spec/security-analysis.md
@@ -19,12 +19,12 @@ for now.
Here are some examples of possible future directions:
-- Schemes based on threshold signatures (e.g. see [HOPPER])
-- Unicorn scheme by Lenstra et al. [UNICORN]
-- Schemes based on Verifiable Delay Functions [VDFS]
+- Schemes based on threshold signatures (e.g. see \[HOPPER\])
+- Unicorn scheme by Lenstra et al. \[UNICORN\]
+- Schemes based on Verifiable Delay Functions \[VDFS\]
For more alternative approaches on collaborative random number generation
-also see the discussion at [RNGMESSAGING].
+also see the discussion at \[RNGMESSAGING\].
<a id="srv-spec.txt-5.2"></a>
diff --git a/spec/srv-spec/specification-spec.md b/spec/srv-spec/specification-spec.md
index 8a35d22..63ffaff 100644
--- a/spec/srv-spec/specification-spec.md
+++ b/spec/srv-spec/specification-spec.md
@@ -1,6 +1,6 @@
<a id="srv-spec.txt-4"></a>
-# Specification [SPEC]
+# Specification \[SPEC\]
<a id="srv-spec.txt-4.1"></a>
@@ -20,7 +20,7 @@ in their votes to announce that they take part in the protocol.
<a id="srv-spec.txt-4.1.1"></a>
-### Computing commitments and reveals [COMMITREVEAL]
+### Computing commitments and reveals \[COMMITREVEAL\]
A directory authority that wants to participate in this protocol needs to
create a new pair of commitment/reveal values for every protocol
@@ -48,7 +48,7 @@ REVEAL = base64-encode( TIMESTAMP || H(RN) )
<a id="srv-spec.txt-4.1.2"></a>
-### Validating commitments and reveals [VALIDATEVALUES]
+### Validating commitments and reveals \[VALIDATEVALUES\]
Given a COMMIT message and a REVEAL message it should be possible to verify
that they indeed correspond. To do so, the client extracts the random value
@@ -64,17 +64,17 @@ correspond to commit values published during the Commitment Phase.
<a id="srv-spec.txt-4.1.4"></a>
-### Encoding commit/reveal values in votes [COMMITVOTE]
+### Encoding commit/reveal values in votes \[COMMITVOTE\]
An authority puts in its vote the commitments and reveals it has produced and
seen from the other authorities. To do so, it includes the following in its
votes:
-"shared-rand-commit" SP VERSION SP ALGNAME SP IDENTITY SP COMMIT [SP REVEAL] NL
+"shared-rand-commit" SP VERSION SP ALGNAME SP IDENTITY SP COMMIT \[SP REVEAL\] NL
where VERSION is the version of the protocol the commit was created with.
IDENTITY is the authority's SHA1 identity fingerprint and COMMIT is the
-encoded commit [COMMITREVEAL]. Authorities during the reveal phase can
+encoded commit \[COMMITREVEAL\]. Authorities during the reveal phase can
also optionally include an encoded reveal value REVEAL. There MUST be only
one line per authority else the vote is considered invalid. Finally, the
ALGNAME is the hash algorithm that should be used to compute COMMIT and
@@ -82,7 +82,7 @@ REVEAL which is "sha3-256" for version 1.
<a id="srv-spec.txt-4.1.5"></a>
-### Shared Random Value [SRVOTE]
+### Shared Random Value \[SRVOTE\]
Authorities include a shared random value (SRV) in their votes using the
following encoding for the previous and current value respectively:
@@ -93,7 +93,7 @@ following encoding for the previous and current value respectively:
```
where VALUE is the actual shared random value encoded in hex (computed as
-specified in section [SRCALC]. NUM_REVEALS is the number of reveal values
+specified in section \[SRCALC\]. NUM_REVEALS is the number of reveal values
used to generate this SRV.
To maintain consistent ordering, the shared random values of the previous
@@ -101,14 +101,14 @@ period should be listed before the values of the current period.
<a id="srv-spec.txt-4.2"></a>
-## Encoding Shared Random Values in the consensus [SRCONSENSUS]
+## Encoding Shared Random Values in the consensus \[SRCONSENSUS\]
Authorities insert the two active shared random values in the consensus
-following the same encoding format as in [SRVOTE].
+following the same encoding format as in \[SRVOTE\].
<a id="srv-spec.txt-4.3"></a>
-## Persistent state format [STATEFORMAT]
+## Persistent state format \[STATEFORMAT\]
As a way to keep ground truth state in this protocol, an authority MUST
keep a persistent state of the protocol. The next sub-section suggest a
@@ -122,13 +122,13 @@ the order given here:
"Version" SP version NL
-[At start, exactly once.]
+\[At start, exactly once.\]
A document format version. For this specification, version is "1".
"ValidUntil" SP YYYY-MM-DD SP HH:MM:SS NL
-[Exactly once]
+\[Exactly once\]
```text
After this time, this state is expired and shouldn't be used nor
@@ -139,11 +139,11 @@ A document format version. For this specification, version is "1".
The following details the commitment and reveal section. They are encoded
the same as in the vote. This makes it easier for implementation purposes.
-"Commit" SP version SP algname SP identity SP commit [SP reveal] NL
+"Commit" SP version SP algname SP identity SP commit \[SP reveal\] NL
-[Exactly once per authority]
+\[Exactly once per authority\]
-The values are the same as detailed in section [COMMITVOTE].
+The values are the same as detailed in section \[COMMITVOTE\].
This line is also used by an authority to store its own value.
@@ -151,7 +151,7 @@ Finally is the shared random value section.
"SharedRandPreviousValue" SP num_reveals SP value NL
-[At most once]
+\[At most once\]
```text
This is the previous shared random value agreed on at the previous