Merge pull request #60 from gorazdko/allow_fixing_invalid_mnemonic

Allow invalid bip39 mnemonic, add cosigner
BlockchainCommons · Apr 6, 2021 · e26ccf5 · e26ccf5
2 parents bbed818 + 973d5fe
commit e26ccf5
Show file tree

Hide file tree

Showing 32 changed files with 588 additions and 153 deletions.
diff --git a/.gitmodules b/.gitmodules
@@ -1,33 +1,33 @@
 [submodule "deps/bc-crypto-base"]
 	path = deps/bc-crypto-base
-	url = git@github.com:BlockchainCommons/bc-crypto-base.git
+	url = https://github.com/BlockchainCommons/bc-crypto-base.git
 [submodule "deps/bc-shamir"]
 	path = deps/bc-shamir
-	url = git@github.com:BlockchainCommons/bc-shamir.git
+	url = https://github.com/BlockchainCommons/bc-shamir.git
 [submodule "deps/TRNG-for-ATSAMD51J19A-Adafruit-Metro-M4-"]
 	path = deps/TRNG-for-ATSAMD51J19A-Adafruit-Metro-M4-
-	url = git@github.com:SapientHetero/TRNG-for-ATSAMD51J19A-Adafruit-Metro-M4-.git
+	url = https://github.com/SapientHetero/TRNG-for-ATSAMD51J19A-Adafruit-Metro-M4-.git
 [submodule "deps/bc-bip39"]
 	path = deps/bc-bip39
-	url = git@github.com:BlockchainCommons/bc-bip39.git
+	url = https://github.com/BlockchainCommons/bc-bip39.git
 [submodule "deps/GxEPD2"]
 	path = deps/GxEPD2
-	url = git@github.com:BlockchainCommons/GxEPD2.git
+	url = https://github.com/BlockchainCommons/GxEPD2.git
 [submodule "deps/libwally-core"]
 	path = deps/libwally-core
-	url = git@github.com:ElementsProject/libwally-core.git
+	url = https://github.com/ElementsProject/libwally-core.git
 [submodule "deps/secp256k1-embedded"]
 	path = deps/secp256k1-embedded
-	url = git@github.com:BlockchainCommons/secp256k1-embedded.git
+	url = https://github.com/BlockchainCommons/secp256k1-embedded.git
 [submodule "deps/bc-bytewords"]
 	path = deps/bc-bytewords
-	url = git@github.com:BlockchainCommons/bc-bytewords.git
+	url = https://github.com/BlockchainCommons/bc-bytewords.git
 [submodule "deps/bc-sskr"]
 	path = deps/bc-sskr
-	url = git@github.com:BlockchainCommons/bc-sskr.git
+	url = https://github.com/BlockchainCommons/bc-sskr.git
 [submodule "deps/Library-Arduino-Cbor"]
 	path = deps/Library-Arduino-Cbor
-	url = git@github.com:jjtara/Library-Arduino-Cbor.git
+	url = https://github.com/jjtara/Library-Arduino-Cbor.git
 [submodule "deps/ArduinoSTL"]
 	path = deps/ArduinoSTL
-	url = git@github.com:mike-matera/ArduinoSTL.git
+	url = https://github.com/mike-matera/ArduinoSTL.git
diff --git a/doc/installation.md b/doc/installation.md
@@ -47,7 +47,7 @@ The installation script creates symbolic links in
 `Arduino/Libraries` which point back to the appropriate
 dependencies in `$LK_ROOT/deps`.
 
-### Notes
+#### Notes
 
 It's safe to re-run the installation at any time.
 
@@ -59,6 +59,10 @@ $ cd bc-lethekit
 $ export LK_ROOT=`pwd` && $LK_ROOT/scripts/install-lethekit $LK_ROOT
 ```
 
+### Next steps
+
+Proceed to [Seedtool Installation Instructions](../seedtool/doc/build.md) to compile and install the `seedtool` firmware on your LetheKit.
+
 <!-- TODO
 If you want to uninstall LetheKit use the installation script with
 the `--uninstall` option:

diff --git a/scripts/install-lethekit b/scripts/install-lethekit
@@ -1,5 +1,9 @@
 #!/bin/bash
 
+# Terminal colors
+RED=`tput setaf 1`
+RESET=`tput sgr0`
+
 git submodule update --init --recursive
 
 # usage: install-lethkit <lethkit-root> <arduino-sketchbook>
@@ -24,7 +28,7 @@ while (( "$#" )); do
       break
       ;;
     -*|--*=) # unsupported flags
-      echo "Error: Unsupported flag $1" >&2
+      echo "${RED}==Error: Unsupported flag $1 ==${RESET}" >&2
       exit 1
       ;;
     *) # preserve positional arguments
@@ -36,7 +40,7 @@ done
 
 if [ ${#args[@]} -ne 1 ]
 then
-    usage_error "must be 1 argument"
+    usage_error "${RED}== Error: must be 1 argument==${RESET}"
 fi
 
 echo "Note: Arduino sketchbook location is set in Arduino IDE: click File->Preferences"
@@ -72,7 +76,7 @@ libpath="${aroot}/libraries"
 # We need python to create libwally for arduino
 if ! python3 --version -v COMMAND &> /dev/null
 then
-    echo "Please, install python3."
+    echo "${RED}== Error: Please, install python3.==${RESET}"
     exit
 fi
 
@@ -91,8 +95,7 @@ popd
 # First, check if GxEPD2 is already installed (as a directory), warn
 # and stop in this case.
 gxepd2_path="${aroot}/libraries/GxEPD2"
-[ -d ${gxepd2_path} ] && ! [ -L ${gxepd2_path} ] && echo "GxEPD2 already installed in ${libpath}. Please remove it; we need to replace with SW SPI enabled version." && exit 1
-
+[ -d ${gxepd2_path} ] && ! [ -L ${gxepd2_path} ] && echo "${RED}== ERROR: GxEPD2 already installed in ${libpath}. Please remove it and re-run the last command==${RESET}" && exit 1
 declare -a libs=(
     ArduinoSTL
     bc-ur-arduino

diff --git a/seedtool/README.md b/seedtool/README.md
@@ -6,25 +6,32 @@ HD wallet master seeds using
 [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki)
 and
 [SSKR](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-011-sskr.md)
-formats. In addition, it supports viewing XPUB keys and addresses in different formats.
+formats. In addition, it supports viewing extended keys and addresses in different formats.
 
-## Compile and Upload Instruction
 
-Please see the [Seedtool Installation Instructions](doc/build.md).
+This guide assumes you have successfully completed with [Seedtool Installation Instructions](doc/build.md).
 
 ## "No Seed" Functions
 
-There are three ways to insert a key into the *seedtool*:
+There are 4 ways to insert a seed into the *seedtool*:  
+A - Generate seed with Dice  
+B - Restore seed from BIP39  
+C - Restore seed from SSKR  
+D - Complete a randomly constructed BIP39 sentence
 
 ![No Seed Menu](doc/images/no-seed.png)
 
-### Key Generation with Dice
+### Seed Generation with Dice
 
 By rolling dice and typing the values, you can gather enough auditable entropy to generate a secure master seed. Rolling 50 dice gathers
 roughly 128 bits of entropy.
 
 ![Generate Seed](doc/images/generate-seed.png)
 
+If you press C, 128 bits of TRNG entropy will be mixed in:
+
+![Generate Seed](doc/images/generate-seed-trng.png)
+
 ### BIP-39 Key Recovery
 
 You can insert a key into the *seedtool* by entering its BIP-39
@@ -41,10 +48,14 @@ mnemonic passphrase which will allow you to use it with most wallets.
 
 ![SSKR Recovery Menu](doc/images/sskr-restore-menu.png) ![SSKR Share Entry](doc/images/sskr-share-restore.png)
 
+### Completing a randomly constructed BIP39 sentence
+
+This is a way to generate your own seed without relying on hardware or software. See [instructions](doc/bip39_sentence_completion.md)
+
 ## Functions with a Seed
 
 Once you have a seed through any of the prior flows, you can create
-BIP-39 and SSKR mnemonic passphrases. In addition you can view extended public
+BIP-39 and SSKR mnemonic passphrases. In addition, you can view extended public and private
 keys, wallet addresses etc. 
 
 ![Seed Present Menu](doc/images/seed-present.png)
@@ -67,10 +78,10 @@ You can choose among different formats:
 ![SSKR Share Format](doc/images/sskr-share-format.png)
 ![SSKR Share View UR](doc/images/sskr-share-view-ur.png) ![SSKR Share View QRUR](doc/images/sskr-share-view-qrur.png)
 
-### Displaying XPUBs
+### Displaying Keys
 
-Extended public keys (XPUBs) can be shown in different formats (base58, UR, QR) with different
-options (slip132, with derivation path). Derivation path can be manually set.
+Extended public and private keys (XPUBs and XPRIVs) can be shown in different formats (base58, UR, QR) with different
+options: slip132, with derivation path and privkey. If privkey is selected, an extended private key (XPRIV) is shown. Derivation path can be manually set or chosen among standard ones: *native segwit*, *nested segwit* and *cosigner*. Cosigner is the one that can be used in multisignature setups.
 
 ![XPUB BASE58](doc/images/xpub_base58.png)
 ![XPUB OPTIONS](doc/images/xpub_options.png)
@@ -99,6 +110,13 @@ A wallet can be exported in the 4 different formats (text, QR, UR and QR-UR):
 ![wallet export](doc/images/wallet_export.png) ![wallet export text](doc/images/wallet_export_text.png)
 ![wallet export text](doc/images/wallet_export_qr.png) ![wallet export text](doc/images/wallet_export_qrur.png)
 
+### Setting network
+
+By pressing 1 in `Seed Present` menu, you can choose among `mainnet`, `testnet` and `regtest`:
+
+![wallet export text](doc/images/network.png)
+
+
 ## Common Workflows
 
 There are several common key management workflows that *seedtool* is

diff --git a/seedtool/doc/bip39_sentence_completion.md b/seedtool/doc/bip39_sentence_completion.md
@@ -0,0 +1,51 @@
+## BIP39 Sentence Completion
+
+Option `D` (`Complete BIP39`) allows you to
+complete a randomly constructed BIP39 sentence. This means that your seed, keys and wallet creation does not rely on hardware nor software but entirely on a randomized procedure conducted by yourself tossing coins. It is true however that the LetheKit completes the last word, i.e. `checksum word`, so that mnemonic sentence can be correctly parsed.
+
+![](images/no-seed.png)
+
+
+### Procedure
+
+First print out the following table and prepare a coin.
+
+![](images/bip39_complete_table.png)
+
+To randomly choose a BIP39 word you have to toss a coin 11 times and fill out a row in the table. For heads you can write 1 and for tails 0.
+
+For example if your first eleven throws are:
+
+`heads` `tails` `tails` `heads` `tails` `heads` `heads` `tails` `tails` `tails` `heads`
+
+then your first row should look like this:
+
+![](images/bip39_complete_tosses.png)
+
+Coin tosses in every row represent a binary number which can be converted to a BIP39 word with the help of a [lookup table](https://www.rudefox.io/custody/walkthrough/create-seed/lookup-tables.pdf)
+
+![](images/bip39_complete_row.png)
+
+You have to repeat the procedure 12 times to fill out the table and obtain a full mnemonic sentence of 12 words. Then input all the words into LetheKit
+
+![](images/bip39_complete_orig.png)
+
+When `done` LetheKit will ask you if your procedure was truly randomized.
+
+⚠️ : If the procedure is not randomized, i.e. the words are not obtained by flipping a coin, the mnemonic sentence is insecure and leads to a loss of funds.
+
+![](images/bip39_complete_warning.png)
+
+After confirmation, LetheKit will show you the completed BIP39 sentence, i.e. the last word (i.e. `checksum word`) will be transformed to make the sentence complete, while the first eleven words will stay the same.
+
+![](images/bip39_complete_fixed.png)
+
+At this point you have to update the last word on your sheet:
+
+![](images/bip39_complete_last_completed.png)
+
+When done, LetheKit will ask you whether you have updated the last word on your sheet?
+
+![](images/bip39_complete_warning2.png)
+
+By confirming with `yes`, LetheKit will generate a seed, keys and a wallet.
diff --git a/seedtool/doc/build.md b/seedtool/doc/build.md
@@ -28,14 +28,15 @@ application will be built and uploaded to your device.
 
 ![](images/arduino-upload.png)
 
-You should see LetheKit refreshing its screen and starting selftest.
+You should see LetheKit refreshing its screen and starting selftest. Selftest can be skipped by holding any key.
+on the keypad.
 
 *Note:* once you enter the bootloader mode it may take some moments for your system
 to recognize your device and port again. Uploading immediately may result in error.
 
-### Use *seedtool*
+### Next steps
 
-See the [Seedtool Application Instructions](../README.md) for information on using the *seedtool*.
+Proceed to [Seedtool Application Instructions](../README.md) for information on using the *seedtool*.
 
 ### Entering Bootloader
 

diff --git a/seedtool/doc/images/bip39_complete_fixed.png b/seedtool/doc/images/bip39_complete_fixed.png
diff --git a/seedtool/doc/images/bip39_complete_last.png b/seedtool/doc/images/bip39_complete_last.png
diff --git a/seedtool/doc/images/bip39_complete_last_completed.png b/seedtool/doc/images/bip39_complete_last_completed.png
diff --git a/seedtool/doc/images/bip39_complete_orig.png b/seedtool/doc/images/bip39_complete_orig.png
diff --git a/seedtool/doc/images/bip39_complete_row.png b/seedtool/doc/images/bip39_complete_row.png
diff --git a/seedtool/doc/images/bip39_complete_table.png b/seedtool/doc/images/bip39_complete_table.png
diff --git a/seedtool/doc/images/bip39_complete_tosses.png b/seedtool/doc/images/bip39_complete_tosses.png
diff --git a/seedtool/doc/images/bip39_complete_warning.png b/seedtool/doc/images/bip39_complete_warning.png
diff --git a/seedtool/doc/images/bip39_complete_warning2.png b/seedtool/doc/images/bip39_complete_warning2.png
diff --git a/seedtool/doc/images/complete_bip39.png b/seedtool/doc/images/complete_bip39.png
diff --git a/seedtool/doc/images/generate-seed-trng.png b/seedtool/doc/images/generate-seed-trng.png
diff --git a/seedtool/doc/images/generate-seed.png b/seedtool/doc/images/generate-seed.png
diff --git a/seedtool/doc/images/network.png b/seedtool/doc/images/network.png
diff --git a/seedtool/doc/images/no-seed.png b/seedtool/doc/images/no-seed.png
diff --git a/seedtool/doc/images/seed-present.png b/seedtool/doc/images/seed-present.png
diff --git a/seedtool/doc/images/xpub_derivation.png b/seedtool/doc/images/xpub_derivation.png
diff --git a/seedtool/doc/images/xpub_options.png b/seedtool/doc/images/xpub_options.png
diff --git a/seedtool/keystore.h b/seedtool/keystore.h
@@ -11,7 +11,8 @@
 
 enum stdDerivation {
   SINGLE_NATIVE_SEGWIT,
-  SINGLE_NESTED_SEGWIT
+  SINGLE_NESTED_SEGWIT,
+  MULTISIG_NATIVE_SEGWIT
 };
 
 
@@ -37,11 +38,16 @@ class Keystore
     String get_derivation_path(void);
 
     /**
-     * @brief  get xpub key based on the last derivation_path set by user
+     * @brief  get xpriv key based on the last derivation_path set by user
      *         or default one if none set
      * @pre    update_root_key()
      */
-    bool get_xpub(ext_key *key_out);
+    bool get_xpriv(ext_key *key_out);
+
+    /**
+     * @brief  convert hdkey to base58
+     */
+    bool xpriv_to_base58(ext_key *key, char **output, bool slip132);
 
     /**
      * @brief  convert hdkey to base58
@@ -66,9 +72,9 @@ class Keystore
     bool save_standard_derivation_path(stdDerivation *path, NetwtorkType network);
 
     /**
-     *  @brief is the last saved derivation path a standard one
+     *  @brief is the last saved derivation path a standard one and which one
      */
-    bool is_standard_derivation_path(void);
+    bool is_standard_derivation_path(const stdDerivation *p = NULL);
 
     /**
      * @brief check if bip32 index is hardened