Merge pull request #34 from BlockchainCommons/shannona-Docs-update

Shannona docs update

Author: wolfmcnally

Docs/Install-Windows.md

@@ -0,0 +1,59 @@
+# Building Seedtool on Windows
+
+This document describes building `seedtool` with `MSYS2` and its usage on `Windows 10` 64-bit.
+
+## Installing MSYS2 and Packages
+
+1. Install `MSYS2` by downloading the installer and following the installation guide in [www.msys2.org](www.msys2.org).
+2. Run `MSYS2` and make sure the package database is updated:
+```bash
+# pacman -Syu
+# pacman -Su
+```
+3. Next, install the compiler and the required packages:
+```bash
+# pacman -S mingw-w64-x86_64-clang
+# pacman -S patch
+# pacman -S git
+# pacman -S make
+# pacman -S mingw-w64-x86_64-libc++
+# pacman -S autoconf
+# pacman -S automake1.8
+```
+
+## Compiling Seedtool
+
+1. Clone `bc-seedtool-cli`, e.g. into `C:\msys64\home`
+2. Open `MSYS2 MinGW 64-bit` application and `cd` into `C:\msys64\home\bc-seedtool-cli`
+3. Run the build script with:
+```bash
+# export CC="clang" && export CXX="clang++" && ./build.sh
+```
+4. Install:
+```bash
+# make install
+```
+You can now freely use `seedtool` inside `MSYS2 MinGW 64-bit` console.
+
+### Running Seedtool as a Native Windows App
+
+To be able to use `seedtool` as a native app on Windows outside `msys2/mingw64`, you have to expose three files to the system: `seedtool.exe`, `libc++.dll`, and `libunwind.dll`, which all reside in `C:\msys64\mingw64\bin`. 
+
+To do so, add that folder to the `Windows PATH` by the following command in `Windows Cmd`:
+```bash
+# set PATH=%PATH%;C:\msys64\mingw64\bin
+```
+That's it. Now you can use `seedtool` as a native Windows app in the Windows command-line tool.
+
+*Note:* If you want to pipe seedtool ouput into a QR code generator, you could use:
+
+```bash
+# seedtool --ur | python -c "import sys; print(sys.stdin.readlines()[0].upper())" | qr > seedqrcode.png
+```
+
+For this you'll need `Python` and the following package:
+
+```bash
+# pip install qrcode[pil]
+```
+

MANUAL.md Docs/MANUAL.mdMANUAL.md renamed to Docs/MANUAL.md

@@ -1,6 +1,6 @@
 # 🌱 Seedtool
 
-**Version 0.8.0**<br/>**September 15, 2020**
+**Version 0.8.1**<br/>**September 22, 2020**
 
 *Copyright © 2020 by Blockchain Commons, LLC*<br/>*Licensed under the "BSD-2-Clause Plus Patent License"*
 
@@ -10,7 +10,7 @@
 
 * [Introduction](#introduction)
 * [General Functionality](#general-functionality)
-* [Generate Random Seeds](#generate-random-seeds)
+* [Generating Random Seeds](#generating-random-seeds)
 * [Generating Seeds from Provided Entropy](#generating-seeds-from-provided-entropy)
 * [Deterministic Randomness](#deterministic-randomness)
 * [Compatibility](#compatibility)
@@ -21,7 +21,7 @@
 
 `seedtool` is a command-line tool for creating and transforming cryptographic seeds of the sort commonly used by blockchain applications.
 
-See [`README.md`](README.md) for installation and credits.
+See [`README.md`](../README.md) for installation and credits.
 
 ## General Functionality
 
@@ -52,6 +52,8 @@ $ seedtool --in random --out hex
 06799f71d16fad08ec5407d32d670147
 ```
 
+### Bytewords
+
 The Bytewords format can be used in place of `hex`. Unlike hex, where every possible input is a seed, Bytewords includes error detection.
 
 ```
@@ -83,7 +85,7 @@ deli-need-cats-taxi-dice-door-webs-vows-free-zest-legs-wall-half-waxy-trip-oval-
 $ seedtool --in hex --out btwm 279b18d0282aefe845fb83e956eed8a6
 dindcstidedrwsvsfeztlswlhfwytpolmossrkhl
 ```
-
+### Outputs & Counts
 An output format `--out` and count `--count` may be specified. Count may be in [1-1024] and the default `count` is 16. For the `hex` and Bytewords (`btw`, `btwu`, `btwm`) output formats, the count is the number of bytes generated. For other output formats, `count` is the number of "output units" (e.g., bits, cards, die rolls, etc.)
 
 ```
@@ -139,6 +141,7 @@ $ seedtool --out cards --count 5
 
 **✅ NOTE:** Playing cards may be duplicated; it is as if each card is drawn from a freshly shuffled deck.
 
+### Low & High
 Sequences of random integers may be generated. By default, `--count` is 16, `--low` is 0, and `--high` is 9.
 
 `low` < `high` < `256`
@@ -159,6 +162,8 @@ $ seedtool --out ints --count 8 --low 1 --high 100
 76 15 25 57 99 41 4 95
 ```
 
+### BIP39
+
 BIP39 can be used as an output format. The default `--count` is 16 bytes (128 bits, 12 words), but may be any multiple of 2 in [12,32].
 
 ```
@@ -177,6 +182,8 @@ $ seedtool --out bip39 --count 32
 mind knock evoke recycle payment snack pear party mean rubber open work rug trophy federal connect indicate security release three buzz buddy motion game
 ```
 
+### SSKRs
+
 SSKR can be used as an output format. By default `--count` is 16 bytes (128 bits, 20 words), but may be any multiple of 2 in [16-32]. By default a single 1-of-1 share is generated. This is the same as running `seedtool --out sskr --group-threshold 1 --group 1-of-1`.
 
 ```
@@ -240,6 +247,8 @@ tuna acid epic gyro into knob brag cusp aqua slot film each horn cash sets hang
 
 When the `--in` option is used, seedtool takes one or more arguments and uses them to construct the seed. If no arguments are given on the command line, it reads input from stdin and uses what it reads to construct the seed. In the examples below, the end of input to stdin is marked by `^D` on its own line.
 
+### Hex & Bytewords
+
 When the input format is `hex` or Bytewords (`btw`, `btwu`, `btwm`), the construction is the identity function (passthrough.)
 
 ```
@@ -262,6 +271,8 @@ dindcstidedrwsvsfeztlswlhfwytpolmossrkhl
 279b18d0282aefe845fb83e956eed8a6
 ```
 
+### Other Inputs
+
 For the other input formats, each "unit" of the input (bit, digit, card, etc.) is converted to a byte and placed in an array. The SHA256 is then taken of the resulting array, yielding a deterministic seed. This seed is then used to generate a cryptographic seed of `count` bytes.
 
 ```
@@ -346,6 +357,8 @@ $ seedtool --in ints 71 22 95 6 23 65 27 10 67 16
 a38385ba7a67b7f5882b37f75b43c2df
 ```
 
+### Piping Output & Input
+
 Output of one call to seedtool can be piped into another.
 
 ```
@@ -367,6 +380,8 @@ $ cat dice.asc
 4435442555226432
 ```
 
+### Count Options
+
 If a smaller or larger seed is desired, the `--count` option specifies how many bytes it contains.
 
 ```
@@ -392,6 +407,8 @@ $ seedtool --in cards --count 20 6c2c3hthacts6d4hkhtd2d7c6c3sqs6h
 731e0a4c76189b2b55f4c705ccbb0105d3ee72c0
 ```
 
+### Inputs for BIP39 & SSKR
+
 `bip39` and `sskr` output formats can be combined with the `random` (default) input format. If the `--count N` option is used with the `hex` or Bytewords (`btw`, `btwu`, `btwm`) input formats, it results in a seed of `N` bytes being generated and used.
 
 ```
@@ -613,7 +630,7 @@ $ seedtool --in sskr "tuna acid epic gyro brag aqua able able able hill code dut
 5d1c30bbc6f3cfd070067b63c851ffe7
 ```
 
-Seedtool also provides the `--deterministic S` option, which takes a string `S`, produces the SHA256 hash of that string, and then uses that to seed it's own cryptography-quality random number generator it uses for the rest of its run. This means that seeds generated by seedtool with the same `--deterministic` input will yield the same results.
+Seedtool also provides the `--deterministic S` option, which takes a string `S`, produces the SHA256 hash of that string, and then uses that to seed its own cryptography-quality random number generator, which it uses for the rest of its run. This means that seeds generated by seedtool with the same `--deterministic` input will yield the same results.
 
 ```
 #
@@ -797,7 +814,7 @@ UR:CRYPTO-SEED/OEADGDHHGTPKFXLGHHLBPYMHLFRYHLPLSSRKPKAOTPIECFFDENTNJNWNPF
 
 `seedqrcode.png`:
 
-![](manual-images/seedqrcode.png)
+![](../manual-images/seedqrcode.png)
 
 The payload of a UR is [CBOR](https://tools.ietf.org/html/rfc7049) encoded as [Bytewords](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-012-bytewords.md). If you wish to examine the CBOR encoding, you can use seedtool to decode the Bytewords payload of a UR. In this example we use the seed above, but only decode the part after the slash as Bytewords.
 

Docs/Usage.md

@@ -0,0 +1,127 @@
+# 🌱 Seedtool Usage Examples
+
+## Basic Information
+
+### Display usage and help information
+
+```
+$ seedtool --help
+```
+
+## Seed Generation
+
+### Generate a cryptographically-strong 16-byte seed
+
+```
+$ seedtool
+8935a8068526d84da555cdb741a3b8a8
+```
+
+### Generate a seed using entropy provided as coin flips
+
+```
+$ seedtool --in bits 1110110001110111
+8d933e43b1bc8f2e3fc27adc98ad4534
+```
+
+### Generate a 32-byte seed using entropy provided as cards drawn from a deck of playing cards
+
+```
+$ seedtool --count 32 --in cards 6c9s8c7c9c4cah6c2sjs7d5c2s4c4dqs
+7df301924511326d7350be14c9e7176d98e945f9ad0ed034726ad4ee0de59c25
+```
+
+## BIP-39 Mnemonics
+
+### Encode a 16-byte seed as BIP-39
+
+```
+$ seedtool --in hex --out bip39 8935a8068526d84da555cdb741a3b8a8
+matrix pull accuse apart horn chat next rifle resemble artist until eye
+```
+
+### Decode BIP-39 mnemonics to hex
+
+```
+$ seedtool --in bip39 "matrix pull accuse apart horn chat next rifle resemble artist until eye"
+8935a8068526d84da555cdb741a3b8a8
+```
+
+## Bytewords
+
+### Decode Bytewords to hex
+
+```
+$ seedtool --in btw "deli need cats taxi dice door webs vows free zest legs wall half waxy trip oval memo sets rock hill"
+279b18d0282aefe845fb83e956eed8a6
+```
+
+## SSKR
+
+### Generate a 16-byte seed and encode it using SSKR as 3 shares, 2 of which are required for recovery
+
+```
+$ seedtool --out sskr --group 2-of-3
+tuna acid epic gyro edge twin able acid able yoga nail wand keno paid ruin jazz keys acid time film pool skew flew luck ruby song owls soap obey
+tuna acid epic gyro edge twin able acid acid yell omit mild webs warm epic flew liar view fuel deli fund glow skew dull knob claw gray surf wand
+tuna acid epic gyro edge twin able acid also visa wave bulb hope drum quad duty need tied vast barn kick task gray tent crux owls easy jolt toil
+```
+
+### Recover a SSKR-encoded seed using 2 of the 3 shares
+
+```
+$ seedtool --in sskr
+tuna acid epic gyro edge twin able acid able yoga nail wand keno paid ruin jazz keys acid time film pool skew flew luck ruby song owls soap obey
+tuna acid epic gyro edge twin able acid also visa wave bulb hope drum quad duty need tied vast barn kick task gray tent crux owls easy jolt toil
+^D
+8a7e9c3c0d783371d80e1192e5f6217d
+```
+
+## UR
+
+### Generate a seed, encode it as UR, transform it to upper case, display it on the console, and encode it to a QR Code in the file "seedqrcode.png"
+
+```
+$ seedtool --ur | tr [:lower:] [:upper:] | tee /dev/tty | qrencode -o seedqrcode.png -l L
+UR:CRYPTO-SEED/OEADGDHHGTPKFXLGHHLBPYMHLFRYHLPLSSRKPKAOTPIECFFDENTNJNWNPF
+```
+
+![](../manual-images/seedqrcode.png)
+
+### Generate a 64-byte seed using a deterministic random number generator and encode it as a multi-part UR with a maximum fragment size of 20 bytes
+
+```
+$ seedtool --deterministic=TEST --count 64 --ur=20
+ur:crypto-seed/1-4/ltadaacsgecyuywdrnesguoeadhdfznteelblrcygldwvarflojtcywyjytpfsmdidpk
+ur:crypto-seed/2-4/ltaoaacsgecyuywdrnesgudkfwprylienshnjnpluypmamtkmybsjkspvseeehwnpdbb
+ur:crypto-seed/3-4/ltaxaacsgecyuywdrnesgusawmrltdlplgkplfbkqzztglfeoyaegsnedtronnfgpsas
+ur:crypto-seed/4-4/ltaaaacsgecyuywdrnesguwsdpgtimmwzspfqdjkhshyaotpiecffdemaeaedmnsoxhf
+```
+
+### Same as above, but generate 5 additional parts using fountain codes
+
+```
+$ seedtool --deterministic=TEST --count 64 --ur=20 --parts 5
+ur:crypto-seed/1-4/ltadaacsgecyuywdrnesguoeadhdfznteelblrcygldwvarflojtcywyjytpfsmdidpk
+ur:crypto-seed/2-4/ltaoaacsgecyuywdrnesgudkfwprylienshnjnpluypmamtkmybsjkspvseeehwnpdbb
+ur:crypto-seed/3-4/ltaxaacsgecyuywdrnesgusawmrltdlplgkplfbkqzztglfeoyaegsnedtronnfgpsas
+ur:crypto-seed/4-4/ltaaaacsgecyuywdrnesguwsdpgtimmwzspfqdjkhshyaotpiecffdemaeaedmnsoxhf
+ur:crypto-seed/5-4/ltahaacsgecyuywdrnesguwsdpgtimmwzspfqdjkhshyaotpiecffdemaeaegtndkijp
+ur:crypto-seed/6-4/ltamaacsgecyuywdrnesguoeadhdfznteelblrcygldwvarflojtcywyjytptkwfjech
+ur:crypto-seed/7-4/ltataacsgecyuywdrnesgusbjlzontwtiytiueutrdwfaachwmcmfrzovseerfsefmdp
+ur:crypto-seed/8-4/ltayaacsgecyuywdrnesguhnwdwsmocwrhbkambezstspdytdtjthfjshlhnbdpygmao
+ur:crypto-seed/9-4/ltasaacsgecyuywdrnesgusawmrltdlplgkplfbkqzztglfeoyaegsnedtroynmduyvl
+```
+
+### Recover the seed from UR using a subset of the generated parts
+
+```
+$ seedtool --in ur
+ur:crypto-seed/2-4/ltaoaacsgecyuywdrnesgudkfwprylienshnjnpluypmamtkmybsjkspvseeehwnpdbb
+ur:crypto-seed/4-4/ltaaaacsgecyuywdrnesguwsdpgtimmwzspfqdjkhshyaotpiecffdemaeaedmnsoxhf
+ur:crypto-seed/6-4/ltamaacsgecyuywdrnesguoeadhdfznteelblrcygldwvarflojtcywyjytptkwfjech
+ur:crypto-seed/8-4/ltayaacsgecyuywdrnesguhnwdwsmocwrhbkambezstspdytdtjthfjshlhnbdpygmao
+^D
+9d347f841a4e2ce6bc886e1aee74d82442b2f7649c606daedbad06cf8f0f73c8e834c2ebb7d2868d75820ab4fb4e45a1004c9f29b8ef2d4d6a94fab0b373615e
+```
+