Support backup of BIP-39 mnemonic derived wallets

o Support 128-, 256- and 512-bit seeds, 20, 33 and 59 words mnemoncs
o Correct wrong "default" Ethereum derivation path in docs (code ok)
o Revise -v output of mnemonics to organize them in enumerated rows/cols

Author: pjkundert

README.org

@@ -46,7 +46,7 @@
 
 The python-slip39 project exists to assist in the safe creation and documentation of Ethereum HD
 Wallet accounts, with various SLIP-39 sharing parameters.  It generates the new wallet seed,
-generates standard Ethereum account(s) (at derivation path =m/66'/40'/0'/0/0= by default) with
+generates standard Ethereum account(s) (at derivation path =m/44'/60'/0'/0/0= by default) with
 Ethereum wallet address and QR code, produces the required SLIP-39 phrases, and outputs a single PDF
 containing all the required printable cards to document the account.
 
@@ -97,9 +97,9 @@
         | sort -r \\
         | python3 -m slip39.recovery \\
         | python3 -m slip39 --secret - --no-card -q
-    2021-12-28 10:55:17 slip39           m/44'/60'/0'/0/0    : 0x68dD9B59D5dF605f4e9612E8b427Ab31187E2C54
+    2021-12-28 10:55:17 slip39           ETH m/44'/60'/0'/0/0    : 0x68dD9B59D5dF605f4e9612E8b427Ab31187E2C54
     2021-12-28 10:55:18 slip39.recovery  Recovered SLIP-39 secret with 4 (1st, 2nd, 7th, 8th) of 8 supplied mnemonics
-    2021-12-28 10:55:18 slip39           m/44'/60'/0'/0/0    : 0x68dD9B59D5dF605f4e9612E8b427Ab31187E2C54
+    2021-12-28 10:55:18 slip39           ETH m/44'/60'/0'/0/0    : 0x68dD9B59D5dF605f4e9612E8b427Ab31187E2C54
 
 Here's an example of PDF containing the SLIP-39 recovery mnemonic cards produced:
 

README.pdf

@@ -5,7 +5,7 @@
 
 from .generate_test	import substitute, nonrandom_bytes
 from .generate		import account, create
-from .recovery		import recover
+from .recovery		import recover, recover_bip39
 
 SEED_XMAS_HEX			= b"dd0e2f02b1f6c92a1a265561bc164135"
 SEED_XMAS			= codecs.decode( SEED_XMAS_HEX, 'hex_codec' )
@@ -79,14 +79,14 @@ def test_recover():
             ]
         )
     }
-    recover( details.groups['one'][1] + details.groups['fren'][1][:3] ) == SEED_XMAS
+    assert recover( details.groups['one'][1] + details.groups['fren'][1][:3] ) == SEED_XMAS
 
     # Enough correct number of mnemonics must be provided (extras ignored)
     with pytest.raises(shamir_mnemonic.MnemonicError) as excinfo:
         recover( details.groups['one'][1] + details.groups['fren'][1][:2] )
     assert "Wrong number of mnemonics" in str(excinfo.value)
 
-    recover( details.groups['one'][1] + details.groups['fren'][1][:4] ) == SEED_XMAS
+    assert recover( details.groups['one'][1] + details.groups['fren'][1][:4] ) == SEED_XMAS
 
     # Invalid mnemonic phrases are rejected (one word changed)
     with pytest.raises(shamir_mnemonic.MnemonicError) as excinfo:
@@ -106,3 +106,71 @@ def test_recover():
             "academic acid academic axle crush swing purple violence teacher curly total equation clock mailman display husband tendency smug laundry disaster"
         ])
     assert "Invalid set of mnemonics" in str(excinfo.value)
+
+
+@substitute( shamir_mnemonic.shamir, 'RANDOM_BYTES', nonrandom_bytes )
+def test_bip39():
+    bip39seed			= recover_bip39( 'zoo ' * 11 + 'wrong' )
+    details			= create(
+        "bip39 recovery test", 2, dict( one = (1,1), two = (1,1), fam = (2,4), fren = (3,5) ),
+        master_secret=bip39seed,
+    )
+    #import json
+    #print( json.dumps( details.groups, indent=4 ))
+    assert details.groups == {
+        "one": (
+            1,
+            [
+                "academic acid acrobat romp academic angel email prospect endorse strategy debris award strike frost actress facility legend safari pistol"
+                " mouse hospital identify unwrap talent entrance trust cause ranked should impulse avoid fangs various radar dilemma indicate says rich work"
+                " presence jerky glance hesitate huge depend tension loan tolerate news agree geology phrase random simple finger alarm depart inherit grin"
+            ]
+        ),
+        "two": (
+            1,
+            [
+                "academic acid beard romp acne floral cricket answer debris making decorate square withdraw empty decorate object artwork tracks rocky tolerate"
+                " syndrome decorate predator sweater ordinary pecan plastic spew facility predator miracle change solution item lizard testify coal excuse lecture"
+                " exercise hamster hand crystal rainbow indicate phantom require satisfy flame acrobat detect closet patent therapy overall muscle spill adjust unhappy"
+            ]
+        ),
+        "fam": (
+            2,
+            [
+                "academic acid ceramic roster acquire again tension ugly edge profile custody geology listen hazard smug branch adequate fishing simple adapt fancy"
+                " hour method emperor tactics float quiet location satoshi guilt fantasy royal machine dictate squeeze devote oven eclipse writing level sheriff"
+                " teacher purchase building veteran spirit woman realize width vanish scholar jewelry desktop stilt random rhyme debut premium theater",
+                "academic acid ceramic scared acid space fantasy breathe true recover privacy tactics boring harvest punish swimming leader talent exchange diet"
+                " enforce vanish volume organize coastal emperor change intend club scene intimate upgrade dragon burning lily huge market calcium forecast holiday"
+                " merit method type ruler equip retailer pancake paces thorn worthy always story promise clock staff floral smart iris repair",
+                "academic acid ceramic shadow acne rumor decent elder aspect lizard obesity friendly regular aircraft beyond military campus employer seafood cover"
+                " ivory dough galaxy victim diminish average music cause behavior declare brave toxic visual academic include lilac repair morning rapids building"
+                " kernel herald careful helpful move hawk flash glimpse seafood listen writing rocky browser change hybrid diet organize system wrote",
+                "academic acid ceramic sister academic both legend raspy pecan mixed broken tenant critical again imply finance pacific single echo capital hesitate"
+                " piece disease crush slush belong airline smug voice organize dryer standard emission curious charity swing pitch senior behavior vintage chemical"
+                " cage editor rebuild costume adult ancestor erode steady makeup depart carpet level sympathy being soldier glimpse airport picture"
+            ]
+        ),
+        "fren": (
+            3,
+            [
+                "academic acid decision round academic academic academic academic academic academic academic academic academic academic academic academic academic"
+                " academic academic academic academic academic academic academic academic academic academic academic academic academic academic academic academic"
+                " academic academic academic academic academic academic academic academic academic academic academic academic academic academic academic academic"
+                " academic academic academic academic academic academic academic aviation endless plastic",
+                "academic acid decision scatter acid ugly raspy famous swimming else length gray raspy brother fake aunt auction premium military emphasis perfect"
+                " surprise class suitable crunch famous burden military laundry inmate regret elder mixture tenant taught smirk voter process steady artist equip"
+                " jury carve acrobat western cylinder gasoline artwork snapshot ancestor object cinema market species platform iris dragon dive medal",
+                "academic acid decision shaft acid carbon credit cards rich living humidity peasant source triumph magazine ladle ruin ocean aspect curious round"
+                " main evoke deny stadium zero discuss union strike pencil golden silent geology display wrap peanut listen aide learn juice decision plot bike example"
+                " obesity ancient square pistol twice sister hour amuse human hobo hospital escape expect wildlife luck",
+                "academic acid decision skin academic vanish olympic evoke gesture rumor unfair scroll grasp very steady include smell diploma package guest greatest"
+                " firm humidity trial width priest class large photo sniff survive machine usher stick capacity heat improve predator float iris jacket soldier apart"
+                " excuse garden cleanup realize permit dough script veteran crazy theater rival secret drink kernel lips pants",
+                "academic acid decision snake acid vegan darkness bucket benefit therapy valuable impulse canyon swing distance vampire round losing twin medal treat"
+                " amount fiction hush remind faint distance custody device believe campus guest preach mule exhaust regular short phrase column rescue steady float"
+                " mixture testify taught fiction usher snake museum detailed agree intend inherit likely typical blimp symbolic prayer course"
+            ]
+        )
+    }
+    assert recover( details.groups['one'][1][:] + details.groups['fren'][1][:3] ) == bip39seed

setup.py

@@ -50,3 +50,12 @@
 PAGE_MARGIN			= 1/4  # Typical printers cannot print within 1/4" of edge
 
 PAPER				= 'Letter'
+
+BITS				= (128, 256, 512)
+BITS_DEFAULT			= 128
+
+MNEM_ROWS_COLS			= {
+    20:	( 7, 3),		# 128-bit seed
+    33:	(11, 3),		# 256-bit seed
+    59:	(12, 5),		# 512-bit seed, eg. from BIP-39 (Unsupported on Trezor hardware wallet)
+}

slip39/api_test.py

@@ -1,4 +1,5 @@
 import codecs
+import logging
 import secrets
 from collections	import namedtuple
 from typing		import Dict, List, Sequence, Tuple
@@ -7,23 +8,57 @@
 
 from shamir_mnemonic	import generate_mnemonics
 
-from .defaults		import PATH_ETH_DEFAULT
+from .defaults		import PATH_ETH_DEFAULT, BITS_DEFAULT, MNEM_ROWS_COLS
+from .util		import ordinal
 
 RANDOM_BYTES			= secrets.token_bytes
 
+log				= logging.getLogger( __package__ )
 
-def random_secret() -> bytes:
-    return RANDOM_BYTES( 16 )
+
+def random_secret(
+    seed_length			= BITS_DEFAULT // 8
+) -> bytes:
+    return RANDOM_BYTES( seed_length )
 
 
 Details = namedtuple( 'Details', ('name', 'group_threshold', 'groups', 'accounts') )
 
 
+def enumerate_mnemonic( mnemonic ):
+    if isinstance( mnemonic, str ):
+        mnemonic		= mnemonic.split( ' ' )
+    return dict(
+        (i, f"{i+1:>2d} {w}")
+        for i,w in enumerate( mnemonic )
+    )
+
+
+def organize_mnemonic( mnemonic, rows=None, cols=None, label="" ):
+    """Given a SLIP-39 "word word ... word" or ["word", "word", ..., "word"] mnemonic, emit rows
+    organized in the desired rows and cols (with defaults, if not provided).  We return the fully
+    formatted line, plus the list of individual words in that line.
+
+    """
+    num_words			= enumerate_mnemonic( mnemonic )
+    if not rows or not cols:
+        rows,cols		= MNEM_ROWS_COLS.get( len(num_words), (7, 3))
+    for r in range( rows ):
+        line			= label if r == 0 else ' ' * len( label )
+        words			= []
+        for c in range( cols ):
+            word		= num_words.get( c * rows + r )
+            if word:
+                words.append( word )
+                line	       += f"{word:<13}"
+        yield line,words
+
+
 def create(
     name: str,
     group_threshold: int,
     groups: Dict[str,Tuple[int, int]],
-    master_secret: bytes	= None,
+    master_secret: bytes	= None,		# Default: 128-bit seeds
     passphrase: bytes		= b"",
     iteration_exponent: int	= 1,
     paths: Sequence[str]	= None,		# Default: PATH_ETH_DEFAULT
@@ -54,6 +89,17 @@ def create(
         g_name: (g_of, g_mnems)
         for (g_name,(g_of, _),g_mnems) in zip( g_names, g_dims, mnems )
     }
+    if log.isEnabledFor( logging.INFO ):
+        group_reqs			= list(
+            f"{g_nam}({g_of}/{len(g_mns)})" if g_of != len(g_mns) else f"{g_nam}({g_of})"
+            for g_nam,(g_of,g_mns) in groups.items() )
+        requires		= f"Recover w/ {group_threshold} of {len(groups)} groups {', '.join(group_reqs)}"
+        for g_n,(g_name,(g_of,g_mnems)) in enumerate( groups.items() ):
+            log.info( f"{g_name}({g_of}/{len(g_mnems)}): {requires}" )
+            for mn_n,mnem in enumerate( g_mnems ):
+                for line,_ in organize_mnemonic( mnem, label=f"{ordinal(mn_n+1)} " ):
+                    log.info( f"{line}" )
+    
     return Details(name, group_threshold, groups, accounts)
 
 
@@ -70,9 +116,9 @@ def mnemonics(
     """
     if master_secret is None:
         master_secret		= random_secret()
-    if len( master_secret ) != 16:
+    if len( master_secret ) not in (16, 32, 64):
         raise ValueError(
-            f"Only 128-bit (16 byte) seeds supported; {len(master_secret)*8}-bit master_secret supplied" )
+            f"Only 128-, 256- and 512bit seeds supported; {len(master_secret)*8}-bit master_secret supplied" )
     return generate_mnemonics(
         group_threshold	= group_threshold,
         groups		= groups,

slip39/defaults.py

@@ -1,6 +1,9 @@
 import codecs
 import contextlib
-#import json
+import json
+import pytest
+
+from eth_account.hdaccount.mnemonic import Mnemonic
 
 import shamir_mnemonic
 
@@ -66,3 +69,54 @@ def test_share_2_of_groups():
         == shamir_mnemonic.combine_mnemonics(mnemonics[1] + mnemonics[2][2:4])
     assert mnemonics[2][0] == "academic acid ceramic roster academic photo daisy indicate salary hunting fancy guest taste diploma express usher regret equip install prevent"
     assert mnemonics[2][1] == "academic acid ceramic scared cubic episode metric intend symbolic overall employer course kind human criminal width game duration maiden favorite"
+
+
+@substitute( shamir_mnemonic.shamir, 'RANDOM_BYTES', nonrandom_bytes )
+@pytest.mark.parametrize("entropy,expected_BIP39,expected_seed,expected_SLIP39", [
+    (
+        "00000000000000000000000000000000",
+        "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
+        "c55257c360c07c72029aebc1b53c05ed0362ada38ead3e3e9efa3708e53495531f09a6987599d18264c1e1c92f2cf141630c7a3c4ab7c81b2f001698e7463b04",
+        "academic acid acrobat romp academic facility filter scared decision likely luxury acid aquatic campus submit cleanup style repair taste"
+        " funding rebuild exotic busy perfect research curly snake exact seafood geology necklace axle fatigue valuable amuse spray pile union"
+        " blue switch parking repeat pumps trend cleanup nuclear breathe guitar jacket party home science recover apart render artwork lair ambition market",
+    ),
+    (
+        "7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f",
+        "legal winner thank year wave sausage worth useful legal winner thank yellow",
+        "2e8905819b8723fe2c1d161860e5ee1830318dbf49a83bd451cfb8440c28bd6fa457fe1296106559a3c80937a1c1069be3a3a5bd381ee6260e8d9739fce1f607",
+        "academic acid acrobat romp acquire home transfer threaten year remove laundry editor midst climate research observe safari deadline staff"
+        " twin downtown cause suitable airport total downtown image boundary tracks hospital brother squeeze phrase webcam grief deploy garbage climate"
+        " lawsuit headset license aluminum hawk bedroom evidence thumb thorn shrimp finger easy exercise wisdom warn axis timber paper salon harvest luck",
+    ),
+])
+def test_bip39( entropy, expected_BIP39, expected_seed, expected_SLIP39 ):
+
+    # Generate a BIP39 Mnemonic seed.  This is a one-way process; a BIP39 Mnemonic (and its
+    # originating Entropy) is *not* recoverable from the Seed, as the derivation function is not
+    # reversible.  The process is Entropy --> BIP39 Mnemonic --> Seed
+    m = Mnemonic("english")
+    mnemonic = m.to_mnemonic(bytes.fromhex(entropy))
+    assert m.is_mnemonic_valid(mnemonic)
+    assert mnemonic == expected_BIP39
+
+    seed = Mnemonic.to_seed(mnemonic, passphrase="TREZOR")
+    assert seed.hex() == expected_seed
+
+    # Now that we have the desired seed from the BIP39 process, we *can* save the 512-bit Seed via a
+    # (large) SLIP39 Mnemonic.
+
+    mnemonics			= shamir_mnemonic.generate_mnemonics(
+        group_threshold	= 2,
+        groups		= [(1, 1), (1, 1), (2, 5), (3, 6)],
+        master_secret	= seed,
+        passphrase	= b"",
+    )
+
+    print( json.dumps( mnemonics, indent=4 ))
+    assert len( mnemonics ) == 4
+    assert shamir_mnemonic.combine_mnemonics(mnemonics[0] + mnemonics[2][0:2]) \
+        == shamir_mnemonic.combine_mnemonics(mnemonics[1] + mnemonics[2][2:4]) \
+        == seed
+    assert all( len( m.split(' ')) == 59 for g in mnemonics for m in g )
+    assert any( m == expected_SLIP39     for g in mnemonics for m in g )

slip39/generate.py

@@ -4,7 +4,7 @@
 
 from fpdf		import FPDF
 
-from .defaults		import FONTS
+from .defaults		import FONTS, MNEM_ROWS_COLS
 
 
 class Region:
@@ -133,6 +133,7 @@ def element( self ):
 def card(
     card_size: Coordinate,
     card_margin: int,
+    num_mnemonics: int	= 20,
 ):
     card			= Box( 'card', 0, 0, card_size.x, card_size.y )
     card_interior		= card.add_region_relative(
@@ -191,13 +192,15 @@ def card(
         Text( 'card-ETH', x1=0, y1=75/100, x2=1, y2=100/100, align='R' )
     )
 
-    rows,cols		= 7,3
+    assert num_mnemonics in MNEM_ROWS_COLS, \
+        f"Invalid SLIP-39 mnemonic word count: {num_mnemonics}"
+    rows,cols		= MNEM_ROWS_COLS[num_mnemonics]
     for r in range( rows ):
         for c in range( cols ):
             card_mnemonics.add_region_proportional(
                 Text( f"mnem-{c * rows + r}",
                       x1=c/cols, y1=r/rows, x2=(c+1)/cols, y2=(r+1)/rows,
-                      font='mono', size_ratio=1/2 )
+                      font='mono', size_ratio=9/16 )
             )
     return card