From d6782ae5cf5ac15f715731f775263b4828949856 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Sat, 14 Oct 2023 18:55:42 -0400 Subject: Rename another file that slipped through. --- spec/SUMMARY.md | 2 +- spec/srv-spec/specification-spec.md | 166 ------------------------------------ spec/srv-spec/specification.md | 166 ++++++++++++++++++++++++++++++++++++ 3 files changed, 167 insertions(+), 167 deletions(-) delete mode 100644 spec/srv-spec/specification-spec.md create mode 100644 spec/srv-spec/specification.md diff --git a/spec/SUMMARY.md b/spec/SUMMARY.md index 9ecbfab..3b8ce7e 100644 --- a/spec/SUMMARY.md +++ b/spec/SUMMARY.md @@ -53,7 +53,7 @@ - [Introduction](./srv-spec/introduction.md) - [Overview](./srv-spec/overview.md) - [Protocol](./srv-spec/protocol.md) - - [Specification \[SPEC\]](./srv-spec/specification-spec.md) + - [Specification \[SPEC\]](./srv-spec/specification.md) - [Security Analysis](./srv-spec/security-analysis.md) - [Discussion](./srv-spec/discussion.md) - [Acknowledgements](./srv-spec/acknowledgements.md) diff --git a/spec/srv-spec/specification-spec.md b/spec/srv-spec/specification-spec.md deleted file mode 100644 index 8118f6d..0000000 --- a/spec/srv-spec/specification-spec.md +++ /dev/null @@ -1,166 +0,0 @@ - - -# Specification {#spec} - - - -## Voting - -This section describes how commitments, reveals and SR values are encoded in -votes. We describe how to encode both the authority's own -commitments/reveals and also the commitments/reveals received from the other -authorities. Commitments and reveals share the same line, but reveals are -optional. - -Participating authorities need to include the line: - -"shared-rand-participate" - -in their votes to announce that they take part in the protocol. - - - -### 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 -run. Authorities SHOULD generate a fresh pair of such values right before the -first commitment phase of the day (at 00:00UTC). - -The value REVEAL is computed as follows: - -REVEAL = base64-encode( TIMESTAMP || H(RN) ) - -```text - where RN is the SHA3 hashed value of a 256-bit random value. We hash the - random value to avoid exposing raw bytes from our PRNG to the network (see - [RANDOM-REFS]). - - TIMESTAMP is an 8-bytes network-endian time_t value. Authorities SHOULD - set TIMESTAMP to the valid-after time of the vote document they first plan - to publish their commit into (so usually at 00:00UTC, except if they start - up in a later commit round). - - The value COMMIT is computed as follows: - - COMMIT = base64-encode( TIMESTAMP || H(REVEAL) ) -``` - - - -### 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 -H(RN) from the REVEAL message, hashes it, and compares it with the H(H(RN)) -from the COMMIT message. We say that the COMMIT and REVEAL messages -correspond, if the comparison was successful. - -Participants MUST also check that corresponding COMMIT and REVEAL values -have the same timestamp value. - -Authorities should ignore reveal values during the Reveal Phase that don't -correspond to commit values published during the Commitment Phase. - - - -### 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 - -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 -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 -REVEAL which is "sha3-256" for version 1. - - - -### 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: - -```text - "shared-rand-previous-value" SP NUM_REVEALS SP VALUE NL - "shared-rand-current-value" SP NUM_REVEALS SP VALUE NL -``` - -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 -used to generate this SRV. - -To maintain consistent ordering, the shared random values of the previous -period should be listed before the values of the current period. - - - -## 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\]. - - - -## 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 -format for this state which is the same as the current state file format. - -It contains a preamble, a commitment and reveal section and a list of -shared random values. - -The preamble (or header) contains the following items. They MUST occur in -the order given here: - -"Version" SP version NL - -\[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\] - -```text - After this time, this state is expired and shouldn't be used nor - trusted. The validity time period is till the end of the current - protocol run (the upcoming noon). -``` - -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 - -\[Exactly once per authority\] - -The values are the same as detailed in section \[COMMITVOTE\]. - -This line is also used by an authority to store its own value. - -Finally is the shared random value section. - -"SharedRandPreviousValue" SP num_reveals SP value NL - -\[At most once\] - -```text - This is the previous shared random value agreed on at the previous - period. The fields are the same as in section [SRVOTE]. - - "SharedRandCurrentValue" SP num_reveals SP value NL - - [At most once] - - This is the latest shared random value. The fields are the same as in - section [SRVOTE]. -``` diff --git a/spec/srv-spec/specification.md b/spec/srv-spec/specification.md new file mode 100644 index 0000000..8118f6d --- /dev/null +++ b/spec/srv-spec/specification.md @@ -0,0 +1,166 @@ + + +# Specification {#spec} + + + +## Voting + +This section describes how commitments, reveals and SR values are encoded in +votes. We describe how to encode both the authority's own +commitments/reveals and also the commitments/reveals received from the other +authorities. Commitments and reveals share the same line, but reveals are +optional. + +Participating authorities need to include the line: + +"shared-rand-participate" + +in their votes to announce that they take part in the protocol. + + + +### 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 +run. Authorities SHOULD generate a fresh pair of such values right before the +first commitment phase of the day (at 00:00UTC). + +The value REVEAL is computed as follows: + +REVEAL = base64-encode( TIMESTAMP || H(RN) ) + +```text + where RN is the SHA3 hashed value of a 256-bit random value. We hash the + random value to avoid exposing raw bytes from our PRNG to the network (see + [RANDOM-REFS]). + + TIMESTAMP is an 8-bytes network-endian time_t value. Authorities SHOULD + set TIMESTAMP to the valid-after time of the vote document they first plan + to publish their commit into (so usually at 00:00UTC, except if they start + up in a later commit round). + + The value COMMIT is computed as follows: + + COMMIT = base64-encode( TIMESTAMP || H(REVEAL) ) +``` + + + +### 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 +H(RN) from the REVEAL message, hashes it, and compares it with the H(H(RN)) +from the COMMIT message. We say that the COMMIT and REVEAL messages +correspond, if the comparison was successful. + +Participants MUST also check that corresponding COMMIT and REVEAL values +have the same timestamp value. + +Authorities should ignore reveal values during the Reveal Phase that don't +correspond to commit values published during the Commitment Phase. + + + +### 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 + +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 +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 +REVEAL which is "sha3-256" for version 1. + + + +### 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: + +```text + "shared-rand-previous-value" SP NUM_REVEALS SP VALUE NL + "shared-rand-current-value" SP NUM_REVEALS SP VALUE NL +``` + +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 +used to generate this SRV. + +To maintain consistent ordering, the shared random values of the previous +period should be listed before the values of the current period. + + + +## 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\]. + + + +## 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 +format for this state which is the same as the current state file format. + +It contains a preamble, a commitment and reveal section and a list of +shared random values. + +The preamble (or header) contains the following items. They MUST occur in +the order given here: + +"Version" SP version NL + +\[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\] + +```text + After this time, this state is expired and shouldn't be used nor + trusted. The validity time period is till the end of the current + protocol run (the upcoming noon). +``` + +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 + +\[Exactly once per authority\] + +The values are the same as detailed in section \[COMMITVOTE\]. + +This line is also used by an authority to store its own value. + +Finally is the shared random value section. + +"SharedRandPreviousValue" SP num_reveals SP value NL + +\[At most once\] + +```text + This is the previous shared random value agreed on at the previous + period. The fields are the same as in section [SRVOTE]. + + "SharedRandCurrentValue" SP num_reveals SP value NL + + [At most once] + + This is the latest shared random value. The fields are the same as in + section [SRVOTE]. +``` -- cgit v1.2.3-54-g00ecf