Working BIP-39 backup and recovery

Author: pjkundert

App.pdf

@@ -19,7 +19,9 @@ The best practice for using these wallets is to load this "Seed" into a
 secure hardware device, like a [Trezor "Model T"] hardware wallet.
 SLIP-39 Mnemonic cards contain the recovery words, which are typed
 directly into the Trezor device to recover the Seed, and all of its
-Cryptocurrency accounts.
+Cryptocurrency accounts.  For the [Ledger Nano] and other hardware
+wallets supporting only BIP-39 Mnemonics, you can now use the SLIP-39
+App to securely and reliably back up these BIP-39 phrases.
 
 The [macOS and win32 SLIP-39 App (download here – .dmg for macOS, .msi
 for Windows)] helps you generate Mnemonic cards and back up this Seed,
@@ -54,6 +56,9 @@ Table of Contents
 [Trezor "Model T"]
 <https://shop.trezor.io/product/trezor-model-t?offer_id=15&aff_id=10388>
 
+[Ledger Nano]
+<https://shop.ledger.com/pages/ledger-nano-x?r=2cd1cb6ae51f>
+
 [macOS and win32 SLIP-39 App (download here – .dmg for macOS, .msi for
 Windows)] <https://github.com/pjkundert/python-slip39/releases/latest>
 

App.txt

@@ -41,7 +41,7 @@ else
 endif
 
 # To see all pytest output, uncomment --capture=no
-PYTESTOPTS	= -vv --doctest-modules # --capture=no --log-cli-level=INFO
+PYTESTOPTS	= -vv --doctest-modules --capture=no --log-cli-level=INFO
 
 PY3TEST		= $(PY3) -m pytest $(PYTESTOPTS)
 
@@ -102,20 +102,25 @@ build:			clean wheel
 # 
 # org-mode products.
 #
-#     deps-txt:  All of the gui/.txt files needed to built, before the sdist, wheel or app
+#     deps:  All of the gui/.txt files needed to built, before the sdist, wheel or app
 # 
 %.txt: %.org
 	emacs $< --batch -f org-ascii-export-to-ascii --kill
 
-GUI_TXT		= $(patsubst %.org,%.txt,$(wildcard slip39/gui/*.org))
+TXT		= $(patsubst %.org,%.txt,$(wildcard slip39/*/*.org))
 
 slip39/gui/SLIP-39.txt:
 	toilet --font ascii12 SLIP-39 > $@
 	@echo "        Safe & Effective (tm) Crypto Wallet Backup and Recovery" >> $@
 	@echo "           (explanations and instructions will appear here)" >> $@
 
+slip39/layout/COVER.txt:
+	toilet --width 200 https://slip39.com > $@
+	@echo "        Safe & Effective (tm) Crypto Wallet Backup and Recovery" >> $@
+	@echo "           (explanations and instructions will appear here)" >> $@
+
 # Any build dependencies that are dynamically generated, and may need updating from time to time
-build-deps:		$(GUI_TXT) slip39/gui/SLIP-39.txt
+deps:			$(TXT) slip39/gui/SLIP-39.txt slip39/layout/COVER.txt
 
 # 
 # VirtualEnv build, install and activate
@@ -149,7 +154,7 @@ $(VENV_LOCAL)/$(VENV_NAME)-activate:	$(VENV_LOCAL)/$(VENV_NAME)
 	@bash --init-file $</venv-activate.sh -i
 
 
-wheel:			build-deps dist/slip39-$(VERSION)-py3-none-any.whl
+wheel:			deps dist/slip39-$(VERSION)-py3-none-any.whl
 
 dist/slip39-$(VERSION)-py3-none-any.whl: build-check FORCE
 	$(PY3) -m build
@@ -167,10 +172,10 @@ install:		dist/slip39-$(VERSION)-py3-none-any.whl FORCE
 # o TODO: no signed and notarized package yet accepted for upload by macOS App Store
 installer:		$(INSTALLER)
 
-dmg:			build-deps app-dmg-valid
-msi:			build-deps dist/slip39-$(VERSION)-win64.msi
-exe:			build-deps build/exe.$(CXFREEZE_EXT)/SLIP-39.exe
-app:			build-deps dist/SLIP-39.app
+dmg:			deps app-dmg-valid
+msi:			deps dist/slip39-$(VERSION)-win64.msi
+exe:			deps build/exe.$(CXFREEZE_EXT)/SLIP-39.exe
+app:			deps dist/SLIP-39.app
 
 app-packages:		app-zip-valid app-dmg-valid app-pkg-valid
 app-upload:		app-dmg-upload

GNUmakefile

@@ -48,18 +48,18 @@
     icon_win			= "images/SLIP-39.ico"
 
     shortcut			= (
-        "DesktopShortcut",	# Shortcut
-        "DesktopFolder",	# Directory_
-        "SLIP-39",		# Name
-        "TARGETDIR",	# Component_
-        "[TARGETDIR]SLIP-39.exe",  # Target
-        None,		# Arguments
-        None,		# Description
-        None,		# Hotkey
-        None,		# Icon
-        None,		# IconIndex
-        None,		# ShowCmd
-        "TARGETDIR",	# WkDir
+        "DesktopShortcut",		# Shortcut
+        "DesktopFolder",		# Directory_
+        "SLIP-39",			# Name
+        "TARGETDIR",			# Component_
+        "[TARGETDIR]SLIP-39.exe",	# Target
+        None,				# Arguments
+        None,				# Description
+        None,				# Hotkey
+        None,				# Icon
+        None,				# IconIndex
+        None,				# ShowCmd
+        "TARGETDIR",			# WkDir
        )
 
     msi_data			= dict(
@@ -171,34 +171,57 @@
 
 long_description_content_type	= 'text/markdown'
 long_description		= """\
-Creating Ethereum, Bitcoin and other accounts is complex and fraught with potential for loss of funds.
-
-A BIP-39 seed recovery phrase helps, but a *single* lapse in security dooms the account (and all
-derived accounts, in fact).  If someone finds your recovery phrase (or you lose it), the accounts
-derived from that seed are /gone/.
-
-The SLIP-39 standard allows you to split the seed between 1, 2, or more groups of several mnemonic
-recovery phrases.  This is better, but creating such accounts is difficult; presently, only the
-Trezor supports these, and they can only be created "manually".  Writing down 5 or more sets of 20
-words is difficult, error-prone and time consuming.
-
-The python-slip39 project exists to assist in the safe creation and documentation of Ethereum HD
-Wallet seeds and derived accounts, with various SLIP-39 sharing parameters.  It generates the new
-random wallet seed, and generates the expected standard Ethereum account(s) (at derivation path
-=m/44'/60'/0'/0/0= by default) and Bitcoin accounts (at Bech32 derivation path =m/84'/0'/0'/0/0= by
-default), with wallet address and QR code (compatible with Trezor derivations).  It produces the
-required SLIP-39 phrases, and outputs a single PDF containing all the required printable cards to
-document the seed (and the specified derived accounts).
-
-Output of BIP-38 or JSON encrypted Paper Wallets is supported, for import into standard software
-cryptocurrency wallets.
-
-On an secure (ideally air-gapped) computer, new seeds can safely be generated and the PDF saved to a
-USB drive for printing (or directly printed without the file being saved to disk.).  Presently,
-=slip39= can output example ETH, BTC, LTC and DOGE addresses derived from the seed, to illustrate
-what accounts are associated with the backed-up seed.  Recovery of the seed to a Trezor is simple,
+Creating Ethereum, Bitcoin and other accounts is complex and fraught
+with potential for loss of funds.
+
+A BIP-39 seed recovery phrase helps, but a *single* lapse in security
+dooms the account (and all derived accounts, in fact).  If someone finds
+your recovery phrase (or you lose it), the accounts derived from that
+seed are /gone/.
+
+The SLIP-39 standard allows you to split the seed between 1, 2, or more
+groups of several mnemonic recovery phrases.  This is better, but
+creating such accounts is difficult; presently, only the Trezor supports
+these, and they can only be created "manually".  Writing down 5 or more
+sets of 20 words is difficult, error-prone and time consuming.
+
+The [python-slip39] project (and the SLIP-39-app macOS/win32 App) exists
+to assist in the safe creation and documentation of Ethereum HD Wallet
+seeds and derived accounts, with various SLIP-39 sharing parameters.  It
+generates the new random wallet seed, and generates the expected
+standard Ethereum account(s) (at derivation path `m/44'/60'/0'/0/0' by
+default) and Bitcoin accounts (at Bech32 derivation path
+`m/84'/0'/0'/0/0' by default), with wallet address and QR code
+(compatible with Trezor derivations).  It produces the required SLIP-39
+phrases, and outputs a single PDF containing all the required printable
+cards to document the seed (and the specified derived accounts).
+
+Output of BIP-38 or JSON encrypted Paper Wallets is supported, for
+import into standard software cryptocurrency wallets.
+
+On an secure (ideally air-gapped) computer, new seeds can safely be
+generated and the PDF saved to a USB drive for printing (or directly
+printed without the file being saved to disk.).  Presently, `slip39' can
+output example ETH, BTC, LTC, DOGE, BNB, CRO and XRP addresses derived
+from the seed, to /illustrate/ what accounts are associated with the
+backed-up seed.  Recovery of the seed to a [trezor-model-t] is simple,
 by entering the mnemonics right on the device.
 
+We also support backup of existing insecure and unreliable BIP-39
+recover phrases as SLIP-39 Mnemonic cards, for existing BIP-39 hardware
+wallets like the [ledger-nano]!  Recover from your existing BIP-39
+Mnemonic, select "Using BIP-39", and generate a set of SLIP-39 Mnemonic
+cards.  Later, use the SLIP-39 App to recover from your SLIP-39 Mnemonic
+cards, click "Using BIP-39" to get your BIP-39 Mnemonic back, and use it
+to recover your accounts to your Ledger (or other) hardware wallet.
+
+[python-slip39]: https://github.com/pjkundert/python-slip39.git "python-slip39"
+
+[trezor-model-t]: https://shop.trezor.io/product/trezor-model-t?offer_id=15&aff_id=10388 "Trezor Model T"
+
+[ledger-nano]: <https://shop.ledger.com/pages/ledger-nano-x?r=2cd1cb6ae51f> "Ledger Nano"
+
+
     $ python3 -m slip39 -v Personal      # or run: slip39 -v Personal
     2022-01-26 13:55:30 slip39           First(1/1): Recover w/ 2 of 4 groups First(1), Second(1), Fam(2/4), Frens(2/6)
     2022-01-26 13:55:30 slip39           1st  1 sister     8 cricket   15 unhappy

README.org

@@ -723,6 +723,10 @@ def random_secret(
 
 
 def enumerate_mnemonic( mnemonic ):
+    """Return a dict containing the supplied mnemonics stored by their indexed, starting from 0.
+    Each Mnemonic is labelled with its ordinal index (ie. beginning at 1).
+
+    """
     if isinstance( mnemonic, str ):
         mnemonic		= mnemonic.split( ' ' )
     return dict(
@@ -786,9 +790,9 @@ def create(
     name: str,
     group_threshold: int,
     groups: Dict[str,Tuple[int, int]],
-    master_secret: bytes	= None,	        # Default: 128-bit seeds
+    master_secret: bytes	= None,	        # Default: 128-bit Seed Entropy
     passphrase: bytes		= b"",
-    using_bip39: bool		= False,        # Generate wallet Seed from master_secret Entropy using BIP-39 generation
+    using_bip39: bool		= False,        # Produce wallet Seed from master_secret Entropy using BIP-39 generation
     iteration_exponent: int	= 1,
     cryptopaths: Optional[Sequence[Union[str,Tuple[str,str]]]] = None,  # default: ETH, BTC at default paths
     strength: int		= 128,
@@ -801,11 +805,10 @@ def create(
     used in the SLIP-39 standard fashion (not recommended -- not Trezor "Model T" compatible).
 
     If using_bip39, creates the Cryptocurrency accountgroups from the supplied master_secret
-    Entropy, but by generating the Seed from a BIP-38 Mnemonic produced from the provided entropy
-    (or generated, default 128 bits), plus the supplied passphrase.
+    Entropy, by generating the Seed from a BIP-38 Mnemonic produced from the provided entropy
+    (or generated, default 128 bits), plus any supplied passphrase.
 
     """
-
     if master_secret is None:
         assert strength in BITS, f"Invalid {strength}-bit secret length specified"
         master_secret		= random_secret( strength // 8 )
@@ -822,6 +825,12 @@ def create(
             mnemonic	= bip39_mnem,
             passphrase	= passphrase,
         )
+        log.info(
+            f"SLIP-39 for {name} from {len(master_secret)*8}-bit Entropy using BIP-39 Mnemonic" + (
+                f": {bip39_mnem:.10}... (w/ BIP-39 Passphrase: {passphrase!r:.2}..."  # WARNING: Reveals partial Secret!
+                if log.isEnabledFor( logging.DEBUG ) else ""
+            )
+        )
         accts			= list( accountgroups(
             master_secret	= bip39_seed,
             cryptopaths		= cryptopaths,
@@ -831,13 +840,22 @@ def create(
     else:
         # For SLIP-39, accounts are generated directly from supplied Entropy, and passphrase
         # encrypts the SLIP-39 Mnemonics, below.
+        log.info(
+            f"SLIP-39 for {name} from {len(master_secret)*8}-bit Entropy directly" + (
+                f": {codecs.encode( master_secret, 'hex_codec' ).decode( 'ascii' ):.10}... (w/ SLIP-39 Passphrase: {passphrase!r:.2}..."  # WARNING: Reveals partial Secret!
+                if log.isEnabledFor( logging.DEBUG ) else ""
+            )
+        )
         accts			= list( accountgroups(
             master_secret	= master_secret,
             cryptopaths		= cryptopaths,
             allow_unbounded	= False,
         ))
 
-    # Generate the SLIP-39 Mnemonics representing the supplied
+    # Generate the SLIP-39 Mnemonics representing the supplied master_secret Seed Entropy.  This
+    # always recovers the Seed Entropy; if not using_bip39, this is also the wallet derivation Seed;
+    # if using_bip39, the wallet derivation Seed was produced from the BIP-39 Seed generation
+    # process (and the SLIP-39 password is always b"", here).
     mnems			= mnemonics(
         group_threshold	= group_threshold,
         groups		= g_dims,

README.pdf

@@ -71,7 +71,6 @@ def main( argv=None ):
 data is random, while the nonce is not, but since this construction is only used once, it should be
 satisfactory.  This first nonce record is transmitted with an enumeration prefix of "nonce".
 
-
 """ )
 
     ap.add_argument( '-v', '--verbose', action="count",
@@ -91,13 +90,13 @@ def main( argv=None ):
     ap.add_argument( '-c', '--cryptocurrency', action='append',
                      default=[],
                      help="A crypto name and optional derivation path (default: \"ETH:{Account.path_default('ETH')}\"), optionally w/ ranges, eg: ETH:../0/-" )
-    ap.add_argument( '-p', '--path',
+    ap.add_argument( '--path',
                      default=None,
                      help="Modify all derivation paths by replacing the final segment(s) w/ the supplied range(s), eg. '.../1/-' means .../1/[0,...)")
     ap.add_argument( '-d', '--device', type=str,
                      default=None,
                      help="Use this serial device to transmit (or --receive) records" )
-    ap.add_argument( '-b', '--baudrate', type=int,
+    ap.add_argument( '--baudrate', type=int,
                      default=None,
                      help="Set the baud rate of the serial device (default: 115200)" )
     ap.add_argument( '-e', '--encrypt',