diff --git a/XOR-Seed-Splitting:-Theory-and-Practice.md b/XOR-Seed-Splitting:-Theory-and-Practice.md index ca9f987..e967442 100644 --- a/XOR-Seed-Splitting:-Theory-and-Practice.md +++ b/XOR-Seed-Splitting:-Theory-and-Practice.md @@ -81,8 +81,8 @@ is commutative, the order in which we combine them isn’t important: ![]["share2 ⊕ share1 = seed"] Thanks to XOR’s associativity, splits of any arbitrary length *n* can be created -by using *n*-1 random shares, with the *n*-th share being the result of the XOR -operation: +by using *n*-1 random shares, with the *n*-th share being the result of the +chained XOR operations: Perform an *n*-way split: @@ -140,7 +140,7 @@ shares has been nullified. ***Important disclaimer:*** *there are other reasons, beyond the scope of this discussion, why using a bare hash of the seed as our random number source might -not be a good idea. Bear in mind that this is a simplified, **theoretical,** +not be a good idea. Bear in mind that this is a simplified **theoretical** introduction, and the examples presented herein are not suitable for implementation in real production code.* @@ -226,10 +226,10 @@ And rejoining the seed looks like this: ![]["seed = HMAC(master1,'friends:share1:of4') ⊕ share_bob ⊕ share_alice ⊕ share_carol"] -The rejoining process now involves more than a simple XOR’ing of shares: the +The rejoining process now involves more than a simple XOR’ing of shares: The name of the split must be input to the join function, so it should something -that’s easy to memorize. If you *really* don’t trust your memory, you could -write it down somewhere. +that’s easy to memorize. If you *really* don’t trust yourself to remember +the word “friends”, you could write it down somewhere. Also note that an additional field, `master`, has been appended to the share identifiers. This is to ensure that the shares of each master share split are @@ -237,10 +237,10 @@ unique, and differ from their non-master-share counterparts. ### Seed Splitting with MMGen -The MMGen wallet implements seed-splitting functionality via the commands -`mmgen-seedsplit` and `mmgen-seedjoin`. +The MMGen wallet implements seed splitting and joining functionality via the +commands [`mmgen-seedsplit`][mms] and [`mmgen-seedjoin`][mmj]. -TBD +For usage information, follow the above links. [⊕]: https://mmgen.github.io/images/ss/o_xor.svg "⊕" ["a: 1 0 0 1 0 1 0 0"]: https://mmgen.github.io/images/ss/byte_a.svg "a: 1 0 0 1 0 1 0 0" @@ -274,3 +274,5 @@ TBD [wm]: https://en.wikipedia.org/wiki/Modular_arithmetic [otp]: https://en.wikipedia.org/wiki/One-time_pad [sc]: https://en.wikipedia.org/wiki/Stream_cipher +[mms]: seedsplit-[MMGen-command-help] +[mmj]: seedjoin-[MMGen-command-help] diff --git a/seedjoin-[MMGen-command-help].md b/seedjoin-[MMGen-command-help].md new file mode 100644 index 0000000..5721e93 --- /dev/null +++ b/seedjoin-[MMGen-command-help].md @@ -0,0 +1,63 @@ + MMGEN-SEEDJOIN: Regenerate an MMGen deterministic wallet from seed shares + created by 'mmgen-seedsplit' + USAGE: mmgen-seedjoin [options] share1 share2 [...shareN] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long options (common options) + -d, --outdir d Output file to directory 'd' instead of working dir + -e, --echo-passphrase Echo passphrases and other user input to screen + -i, --id-str s ID String of split (required for master share join only) + -H, --hidden-incog-input-params f,o Read hidden incognito data from file + 'f' at offset 'o' (comma-separated). NOTE: only the + first share may be in hidden incognito format! + -J, --hidden-incog-output-params f,o Write hidden incognito data to file + 'f' at offset 'o' (comma-separated). File 'f' will be + created if necessary and filled with random data. + -o, --out-fmt f Output to wallet format 'f' (see FMT CODES below) + -O, --old-incog-fmt Specify old-format incognito input + -L, --label l Specify a label 'l' for output wallet + -M, --master-share i Use a master share with index 'i' (min:1, max:1024) + -p, --hash-preset p Use the scrypt hash parameters defined by preset 'p' + for password hashing (default: '3') + -z, --show-hash-presets Show information on available hash presets + -P, --passwd-file f Get wallet passphrase from file 'f' + -q, --quiet Produce quieter output; suppress some warnings + -r, --usr-randchars n Get 'n' characters of additional randomness from user + (min=10, max=80, default=30) + -S, --stdout Write wallet data to stdout instead of file + -v, --verbose Produce more verbose output + + + COMMAND NOTES: + + When joining with a master share, the master share must be listed first. + The remaining shares may be listed in any order. + + The --id-str option is required only for master share joins. For ordinary + joins it will be ignored. + + For usage examples, see the help screen for the 'mmgen-seedsplit' command. + + PASSPHRASE NOTE: + + For passphrases all combinations of whitespace are equal, and leading and + trailing space are ignored. This permits reading passphrase or brainwallet + data from a multi-line file with free spacing and indentation. + + FMT CODES: + + Format FileExt Valid codes + ------ ------- ----------- + BIP39Mnemonic .bip39 bip39 + Brainwallet .mmbrain mmbrain,brainwallet,brain,bw,b + DieRollSeedFile .b6d b6d,die,dieroll + IncogWallet .mmincog mmincog,incog,icg,i + IncogWalletHex .mmincox mmincox,incox,incog_hex,xincog,ix,xi + IncogWalletHidden None incog_hidden,hincog,ih,hi + MMGenHexSeedFile .mmhex seedhex,hexseed,mmhex + MMGenMnemonic .mmwords mmwords,words,mnemonic,mnem,mn,m + MMGenSeedFile .mmseed mmseed,seed,s + PlainHexSeedFile .hex hex,rawhex,plainhex + Wallet .mmdat wallet,w + + MMGEN v0.11.099 December 2019 MMGEN-SEEDJOIN(1) diff --git a/seedsplit-[MMGen-command-help].md b/seedsplit-[MMGen-command-help].md new file mode 100644 index 0000000..1699e92 --- /dev/null +++ b/seedsplit-[MMGen-command-help].md @@ -0,0 +1,126 @@ + MMGEN-SEEDSPLIT: Generate a seed share from the default or specified MMGen wallet + USAGE: mmgen-seedsplit [opts] [infile] [:]: + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long options (common options) + -d, --outdir d Output files to directory 'd' instead of working dir + -e, --echo-passphrase Echo passphrases and other user input to screen + -i, --in-fmt f Input from wallet format 'f' (see FMT CODES below) + -o, --out-fmt f Output to wallet format 'f' (see FMT CODES below) + -H, --hidden-incog-input-params f,o Read hidden incognito data from file + 'f' at offset 'o' (comma-separated) + -J, --hidden-incog-output-params f,o Write hidden incognito data to file + 'f' at offset 'o' (comma-separated). File 'f' will be + created if necessary and filled with random data. + -O, --old-incog-fmt Specify old-format incognito input + -l, --seed-len l Specify wallet seed length of 'l' bits. This option + is required only for brainwallet and incognito inputs + with non-standard (< 256-bit) seed lengths. + -L, --label l Specify a label 'l' for output wallet + -M, --master-share i Use a master share with index 'i' (min:1, max:1024) + -p, --hash-preset p Use the scrypt hash parameters defined by preset 'p' + for password hashing (default: '3') + -z, --show-hash-presets Show information on available hash presets + -P, --passwd-file f Get wallet passphrase from file 'f' + -q, --quiet Produce quieter output; suppress some warnings + -r, --usr-randchars n Get 'n' characters of additional randomness from user + (min=10, max=80, default=30) + -S, --stdout Write wallet data to stdout instead of file + -v, --verbose Produce more verbose output + + + COMMAND NOTES: + + This command generates shares one at a time. Shares may be output to any + MMGen wallet format, with one limitation: only one share in a given split may + be in hidden incognito format, and it must be the master share in the case of + a master-share split. + + If the command's optional first argument is omitted, the default wallet is + used for the split. + + The last argument is a seed split specifier consisting of an optional split + ID, a share index, and a share count, all separated by colons. The split ID + must be a valid UTF-8 string. If omitted, the ID 'default' is used. The + share index (the index of the share being generated) must be in the range + 1-1024 and the share count (the total number of shares in the split) + in the range 2-1024. + + Master Shares + + Each seed has a total of 1024 master shares, which can be used as the first + shares in multiple splits if desired. To generate a master share, use the + --master-share (-M) option with an index in the range 1-1024 and omit + the last argument. + + When creating and joining a split using a master share, ensure that the same + master share index is used in all split and join commands. + + EXAMPLES: + + Create a 3-way default split of your default wallet, outputting all shares + to default wallet format. Rejoin the split: + + $ mmgen-seedsplit 1:3 # Step A + $ mmgen-seedsplit 2:3 # Step B + $ mmgen-seedsplit 3:3 # Step C + $ mmgen-seedjoin + + Create a 2-way split of your default wallet with ID string 'alice', + outputting shares to MMGen native mnemonic format. Rejoin the split: + + $ mmgen-seedsplit -o words alice:1:2 # Step D + $ mmgen-seedsplit -o words alice:2:2 # Step E + $ mmgen-seedjoin + + Create a 2-way split of your default wallet with ID string 'bob' using + master share #7, outputting share #1 (the master share) to default wallet + format and share #2 to BIP39 format. Rejoin the split: + + $ mmgen-seedsplit -M7 # Step X + $ mmgen-seedsplit -M7 -o bip39 bob:2:2 # Step Y + $ mmgen-seedjoin -M7 --id-str=bob + + Create a 2-way split of your default wallet with ID string 'alice' using + master share #7. Rejoin the split using master share #7 generated in the + previous example: + + $ mmgen-seedsplit -M7 -o bip39 alice:2:2 # Step Z + $ mmgen-seedjoin -M7 --id-str=alice + + Create a 2-way default split of your default wallet with an incognito-format + master share hidden in file 'my.hincog' at offset 1325. Rejoin the split: + + $ mmgen-seedsplit -M4 -o hincog -J my.hincog,1325 1:2 # Step M (share A) + $ mmgen-seedsplit -M4 -o bip39 2:2 # Step N (share B) + $ mmgen-seedjoin -M4 -H my.hincog,1325 + + PASSPHRASE NOTE: + + For passphrases all combinations of whitespace are equal, and leading and + trailing space are ignored. This permits reading passphrase or brainwallet + data from a multi-line file with free spacing and indentation. + + BRAINWALLET NOTE: + + To thwart dictionary attacks, it's recommended to use a strong hash preset + with brainwallets. For a brainwallet passphrase to generate the correct + seed, the same seed length and hash preset parameters must always be used. + + FMT CODES: + + Format FileExt Valid codes + ------ ------- ----------- + BIP39Mnemonic .bip39 bip39 + Brainwallet .mmbrain mmbrain,brainwallet,brain,bw,b + DieRollSeedFile .b6d b6d,die,dieroll + IncogWallet .mmincog mmincog,incog,icg,i + IncogWalletHex .mmincox mmincox,incox,incog_hex,xincog,ix,xi + IncogWalletHidden None incog_hidden,hincog,ih,hi + MMGenHexSeedFile .mmhex seedhex,hexseed,mmhex + MMGenMnemonic .mmwords mmwords,words,mnemonic,mnem,mn,m + MMGenSeedFile .mmseed mmseed,seed,s + PlainHexSeedFile .hex hex,rawhex,plainhex + Wallet .mmdat wallet,w + + MMGEN v0.11.099 December 2019 MMGEN-SEEDSPLIT(1)