Merge PR #354: Shamir Secret Sharing

docs/book.toml

@@ -4,3 +4,6 @@ language = "en"
 multilingual = false
 src = "src"
 title = "Neptune Documentation"
+
+[output.html]
+mathjax-support = true

docs/src/SUMMARY.md

@@ -14,6 +14,9 @@
   - [Reorganization](./neptune-core/reorganization.md)
   - [Keys and Addresses](./neptune-core/keys.md)
   - [Utxo Notification](./neptune-core/utxo_notification.md)
+- [User Guides](./user-guides.md)
+  - [Installation](./user-guides/installation.md)
+  - [Shamir Secret Sharing](./user-guides/shamir-secret-sharing.md)
 - [Contributing](./contributing.md)
   - [Git Workflow](./contributing/git-workflow.md)
   - [Git Message](./contributing/git-message.md)

docs/src/user-guides.md

@@ -0,0 +1,12 @@
+# User Guides
+
+Explainers and tutorials on how to use or get started using the various software packages that constitute the client.
+
+Building the software, or installing it using a script, yields four executables. Two of these executables are user interfaces. The executables are:
+
+ - `neptune-core` is the daemon that runs the protocol.
+ - `triton-vm-prover` is a binary invoked by `neptune-core` for out-of-process proving tasks.
+ - `neptune-dashboard` is a terminal user interface that requires a running instance of `neptune-core`.
+ - `neptune-cli` is a command-line interface that might require a running instance of `neptune-core` depending on the command.
+
+Except for the [installation instructions](./user-guides/installation.md), the user guides in this section assume these executables are installed.

docs/src/user-guides/installation.md

@@ -0,0 +1,34 @@
+# Installation
+
+## Compile from Source
+
+### Linux Debian/Ubuntu
+
+ - Open a terminal to run the following commands.
+ - Install curl: `sudo apt install curl`
+ - Install the rust compiler and accessories: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y`
+ - Source the rust environment: `source "$HOME/.cargo/env"`
+ - Install build tools: `sudo apt install build-essential`
+ - Install LevelDB: `sudo apt install libleveldb-dev libsnappy-dev cmake`
+ - Download the repository: `git clone https://github.com/Neptune-Crypto/neptune-core.git`
+ - Enter the repository: `cd neptune-core`
+ - Checkout the release branch `git checkout release`. (Alternatively, for the *unstable development* branch, skip this step.)
+
+ - Build for release and put the binaries in your local path (`~/.cargo/bin/`): `cargo install --locked --path .` (needs at least 3 GB of RAM and a few minutes)
+
+### Windows
+
+To install Rust and cargo on Windows, you can follow [these instructions](https://doc.rust-lang.org/cargo/getting-started/installation.html).
+Installing cargo might require you to install Visual Studio with some C++ support but the cargo installer for Windows should handle that.
+With a functioning version of cargo, compilation on Windows should just work out-of-the-box with cargo build etc.
+- Download and run the CMake installer from the [website](https://cmake.org/download/).
+- Open PowerShell to run the following commands.
+- Download the repository: `git clone https://github.com/Neptune-Crypto/neptune-core.git`
+- Enter the repository: `cd neptune-core`
+- Checkout the release branch `git checkout release`. (Alternatively, for the *unstable development* branch, skip this step.)
+
+- Run `cargo install --locked --path .`
+
+## Automatic
+
+Go to the [releases](https://github.com/Neptune-Crypto/neptune-core/releases) page, scroll down to the section "Assets" and select and install the right package for your system.

docs/src/user-guides/shamir-secret-sharing.md

@@ -0,0 +1,155 @@
+# Shamir Secret Sharing
+
+Neptune Core supports Shamir secret sharing to distribute shares in the wallet secret.
+
+## How It Works
+
+A \\(t\\)-out-of-\\(n\\) Shamir secret sharing scheme works as follows. Let \\(S \in \mathbb{F}\\) be the original secret. In the source code, we use `XFieldElement` as the field \\(\mathbb{F}\\) and `SecretKeyMaterial` as a wrapper around `XFieldElement`s when they are used for this purpose.
+
+Sample a univariate polynomial \\(f(X)\\) of degree at most \\(t-1\\) uniformly at random except for the constant coefficient. Choose \\(S\\) for the constant coefficient, so that \\(f(0) = S\\).
+
+With an implicit embedding \\(\mathbb{N} \rightarrow \mathbb{F}\\) we can associate the \\(i\\)th share with the point \\((i, f(i))\\). Note that \\(i=0\\) is disallowed since \\((0, f(0))\\) corresponds to the secret. To generate \\(n\\) shares we let \\(i\\) range from \\(1\\) to \\(n\\) (including the upper bound).
+
+To reconstruct the original secret it suffices to have *any* \\(t\\) secret shares. Just reconstruct the polynomial and evaluate it at \\(0\\).
+
+However, any selection of *fewer than \\(t\\)* secret shares contains *no information* about the original secret.
+
+## How to Use It
+
+First, make sure you have a wallet installed.
+
+ - Whenever you run `neptune-core`, it will read the wallet file or create one if none is found. Unless you moved or removed this file, it is still there.
+ - To test if the wallet file is present, run `neptune-cli which-wallet`.
+ - To generate a wallet file without running `neptune-core`, try `neptune-cli generate-wallet`.
+ - To import a wallet from a seed phrase, first make sure there is no wallet file, and then run `neptune-cli import-seed-phrase`.
+
+To generate \\(n\\) shares in a \\(t\\)-out-of-\\(n\\) scheme, run `neptune-cli shamir-share t n` and replace `t` and `n` with the values you want. This command generates \\(n\\) seed phrases. **Note:** be sure to record the share index ("`i/n`") along with each share, as you will need this information to reconstruct the original secret.
+
+To reconstruct the original secret, first make sure the wallet file is absent. Then run `neptune-cli shamir-combine t` and replace `t` with the same value used earlier. This command will ask you for \\(t\\) secret shares (with index) which you can supply by writing the seed phrase words of each share.
+
+## Example
+
+`> neptune-cli shamir-share 2 3`
+
+```
+Wallet for beta.
+Read from file `[file name redacted]`.
+
+Key share 1/3:
+1. because
+2. curtain
+3. remove
+4. marble
+5. divide
+6. what
+7. early
+8. tilt
+9. debate
+10. evidence
+11. tag
+12. ramp
+13. acquire
+14. side
+15. tenant
+16. cloud
+17. nature
+18. index
+
+Key share 2/3:
+1. twenty
+2. pretty
+3. shiver
+4. position
+5. panda
+6. frown
+7. cargo
+8. target
+9. country
+10. deliver
+11. remind
+12. label
+13. kick
+14. call
+15. exchange
+16. vital
+17. absent
+18. barely
+
+Key share 3/3:
+1. senior
+2. comfort
+3. stomach
+4. since
+5. yard
+6. dove
+7. ability
+8. okay
+9. cloth
+10. chaos
+11. attack
+12. enough
+13. tilt
+14. junk
+15. risk
+16. sail
+17. horse
+18. primary
+```
+
+```
+> neptune-cli shamir-combine 2
+```
+
+```
+Enter share index ("i/n"): 
+1/3
+Enter seed phrase for key share 1/3:
+1. because
+2. curtain
+3. remove
+4. marble
+5. divide
+6. what
+7. early
+8. tilt
+9. debate
+10. evidence
+11. tag
+12. ramp
+13. acquire
+14. side
+15. tenant
+16. cloud
+17. nature
+18. index
+
+Have shares {1}/3.
+
+Enter share index ("i/n"): 
+3/3
+Enter seed phrase for key share 3/3:
+1. senior
+2. comfort
+3. stomach
+4. since
+5. yard
+6. dove
+7. ability
+8. okay
+9. cloth
+10. chaos
+11. attack
+12. enough
+13. tilt
+14. junk 
+15. risk
+16. sail
+17. horse
+18. primary
+
+Have shares {1,3}/3.
+
+Shamir recombination successful.
+Saving wallet to disk at [file name redacted] ...
+Success.
+```