diff options
author | Nick Mathewson <nickm@torproject.org> | 2023-10-14 14:07:40 -0400 |
---|---|---|
committer | Nick Mathewson <nickm@torproject.org> | 2023-10-14 14:07:40 -0400 |
commit | 4ba45dfd9afd08edeb46243127a480f1d23b9640 (patch) | |
tree | 4dcdb3b4ac378b255d8292693ef234100bf67ac5 /spec/srv-spec | |
parent | d4b9bcc71565e1c3b7b74ddfcd44730697c10c6b (diff) | |
download | torspec-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.md | 8 | ||||
-rw-r--r-- | spec/srv-spec/protocol.md | 24 | ||||
-rw-r--r-- | spec/srv-spec/security-analysis.md | 8 | ||||
-rw-r--r-- | spec/srv-spec/specification-spec.md | 34 |
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 |