diff --git a/Getting-Started-with-MMGen.md b/Getting-Started-with-MMGen.md index d345f3a..4136e00 100644 --- a/Getting-Started-with-MMGen.md +++ b/Getting-Started-with-MMGen.md @@ -1,4 +1,22 @@ -#### 1. Generate a wallet (offline computer): +## Table of Contents + +#### Basic Operations +* Generate a wallet +* Generate addresses +* Import addresses +* Create a transaction +* Sign a transaction +* Send a transaction + +#### Additional Features +* Using the mnemonic and seed features +* Mnemonics and seeds — additional information +* Incognito wallets + + +### Basic Operations + +#### Generate a wallet (offline computer): On your offline computer, generate a wallet with a random seed: @@ -17,7 +35,7 @@ preset are changed. "256" is the seed length; "3" is the scrypt hash preset. These values are configurable: type `mmgen-walletgen --help` for details. -#### 2. Generate addresses (offline computer): +#### Generate addresses (offline computer): Now generate ten addresses with your just-created wallet: @@ -72,7 +90,7 @@ order: addresses need not be consecutive. Copy this file onto a USB stick and transfer it to your online computer. -#### 3. Import addresses (online computer): +#### Import addresses (online computer): On your online computer, start bitcoind and import the addresses into the tracking wallet with the command: @@ -88,17 +106,17 @@ into the tracking wallet using `mmgen-addrimport -l`. $ mmgen-addrimport --rescan -l my_existing_addrs_with_balances -NOTE: The `'--rescan'` option must be used for all addresses with existing +NOTE: The '--rescan' option must be used for all addresses with existing balances. Since the rescanning process is slow, you may want to do it in stages, a few addresses at a time. Continue in this fashion until you've imported all addresses with balances into your tracking wallet. -#### 4. Create a transaction (online computer): +#### Create a transaction (online computer): Now that your existing addresses are imported, you're ready to create a test -transaction using the `mmgen-txcreate` command. Note that transactions are +transaction using the 'mmgen-txcreate' command. Note that transactions are harmless until they're signed and broadcast to the network, so feel free to experiment with different transactions using different combinations of inputs and outputs. @@ -173,14 +191,14 @@ format: Now hit ENTER, choose the transaction's input from the list (10 BTC, address 1F9495H8EJL..., txid 04f97185...,2), and confirm. If all goes well, -`mmgen-txcreate` will exit with the message: +'mmgen-txcreate' will exit with the message: Transaction data saved to file 'tx_1EDCBA[6.6].raw' Note that the transaction has a unique ID, and the non-change output amount, 6.6 BTC, is conveniently included in the filename. -#### 5. Sign the transaction (offline computer): +#### Sign a transaction (offline computer): Now copy the raw transaction you've just created to a USB stick and transfer it to your offline computer for signing. You need to find the key for your @@ -200,7 +218,7 @@ transaction using this list of keys. ... Signed transaction saved to file tx_ABCDEF[0.1].sig -Note that mmgen-pywallet's output is just a flat list of keys. So if you have +Note that 'mmgen-pywallet's output is just a flat list of keys. So if you have several Bitcoin wallets with balances, you can just dump all their keys and merge them into a single file which you can use to sign all future transactions with wallet.dat inputs: @@ -216,6 +234,8 @@ transaction file, and the required keys will be generated automatically, as in this example: $ mmgen-txsign tx_9D2C3A[1.23].raw B73B58EA-125FB230[256,3].mmdat + ... + Signed transaction saved to file tx_9D2C3A[1.23].sig Transactions may contain a mixture of MMGen and non-MMGen inputs as well as inputs with more than one MMGen seed ID. Just provide a seed source for each @@ -225,7 +245,7 @@ Eventually, when you've placed all your BTC under MMGen control, you'll never have deal with keys directly again, because MMGen generates all keys on the fly using the seed. -#### 6. Send the transaction (online computer): +#### Send a transaction (online computer): Now you're ready for the final step: broadcasting the transaction to the network. Copy the `tx_*.sig` file to your online computer, start bitcoind, if it's not @@ -233,7 +253,7 @@ running, and execute the command: $ mmgen-txsend tx_1EDCBA[6.6].sig -Like all mmgen commands, `mmgen-txsend` is interactive, so you'll be asked for +Like all mmgen commands, 'mmgen-txsend' is interactive, so you'll be asked for confirmation before the transaction is actually sent. Once the transaction's confirmed by the network, your three new MMGen addresses @@ -241,11 +261,11 @@ will appear on the listing of `mmgen-txcreate -i`. Type 'm' at the menu to see them displayed in MMGen format. Congratulations! You've performed your first MMGen transaction and placed your -first funds under MMGen control. +first funds under MMGen's control. -### Additional Features +### Additional Features -#### Using the mnemonic and seed features: +#### Using the mnemonic and seed features: Continuing our example above, generate a mnemonic from the wallet: @@ -259,8 +279,8 @@ Continuing our example above, generate a mnemonic from the wallet: dirty measure thorn Note: a 128- or 192-bit seed will generate a shorter mnemonic of 12 or 18 -words. You may generate a wallet with these seed lengths using the `'-l'` -option to `mmgen-walletgen`. +words. You may generate a wallet with these seed lengths using the '-l' +option to 'mmgen-walletgen'. Though some consider 128 bits of entropy to provide adequate security for the foreseeable future, you should stick to the default 256-bit seed length if @@ -308,24 +328,29 @@ the seed's checksum ("0fe02f" in this example) as follows: $ echo -n XnyC NfPH piuW dQ2d nM47 VU | tr -d ' ' |sha256sum |cut -c 1-6 0fe02f -#### Mnemonics and seeds — additional information: +Or better yet, use 'mmgen-tool' to do the same thing: -With the `'-m'` or `'-s'` option, MMGen commands that take mnemonic and seed + $ mmgen-tool str2id6 'XnyC NfPH piuW dQ2d nM47 VU' + 0fe02f + +#### Mnemonics and seeds — additional information: + +With the '-m' or '-s' option, MMGen commands that take mnemonic and seed data may receive the data from a prompt instead of a file. MMGen commands that produce mnemonic and seed data may be forced to print it to -standard output instead of file with the `'-S'` option. This feature has +standard output instead of file with the '-S' option. This feature has intentionally been made optional to safeguard against looking-over-the-shoulder, Van Eyck phreaking and other side-channel attacks. MMGen commands never print private data to the screen unless explicitly asked to. The output of any MMGen command may be written to a directory of your choice -using the `'-d'` option. For example, on a Linux system you could use +using the '-d' option. For example, on a Linux system you can use `'-d /dev/shm'` to write key and seed data to volatile memory instead of disk. This also has obvious security benefits, ensuring that no sensitive data remains on disk after your computer's been powered down. -#### Incognito wallets +#### Incognito wallets A wallet exported to incognito format is indistinguishable from random data, allowing you to hide your wallet at an offset within a random-filled file or @@ -336,12 +361,12 @@ contains anything useful at all, barring any inside knowledge. An incognito wallet with a reasonably secure password could even be hidden on unencrypted cloud storage. Hiding your wallet at some offset in a 1 GB file increases the difficulty of any attack by a factor of one billion, assuming -a potential attacker knows or suspects you have an MMGen wallet hidden there. -You should remember the offset, however! +a potential attacker even knows or suspects you have an MMGen wallet hidden +there. If you plan to store your incognito wallet in an insecure location such as cloud storage, you're advised to use a strong scrypt preset and a strong password. -These can be changed using the `mmgen-passchg` utility: +These can be changed using the 'mmgen-passchg' utility: $ mmgen-passchg -p 5 89ABCDEF-01234567[256,3].mmdat ... @@ -374,55 +399,72 @@ Repeat the same export operation, but output to hexadecimal: b43a 21f9 82c7 6bd1 fe96 bad9 2d54 c4c0 Note that the Incog ID is different here: it's generated from the init vector, -which is randomly generated each time, leading to the incog data as a whole -being different as well. This allows you to store your incog data in multiple -insecure locations without being detected. +which is a different random number each time, which makes the incog data as a +whole different as well. This allows you to store your incog data in multiple +insecure locations without repeated data being detected. As you can see, this data is ideally suited for a paper wallet. Just print it -out on a printer and you're ready to go. This hex dump of apparently random -data is totally unidentifiable as anything related to Bitcoin. +out on a printer and you're ready to go. To an outside observer, the data +appears to be random, and it's totally unidentifiable as anything related to +Bitcoin. Your incognito wallet (whether hex or binary) can be used just like any other -MMGen wallet, mnemonic or seed file. Generate ten addresses with it, for -example: +MMGen wallet, mnemonic or seed file. You can generate addresses with it +directly, for example: $ mmgen-addrgen 89ABCDEF-87654321-CA86420E[256,5].mmincox 100-110 + ... + Generated 10 addresses + Addresses written to file '89ABCDEF[100-110].addrs' + Or sign a transaction: - $ mmgen-txsign tx_my.raw 89ABCDEF-87654321-CA86420E[256,5].mmincox + $ mmgen-txsign tx_FABCDE[0.3].raw 89ABCDEF-87654321-CA86420E[256,5].mmincox + ... + Signed transaction saved to file tx_FABCDE[0.3].sig -With the `-G` (`--export-incog-hidden`) option, you can hide your incog wallet -in a file or on a partition at the offset of your choice. Create a file filled -with 1 GB of random data: +With the `-G` (`--export-incog-hidden`) option, you can create a **hidden +incognito wallet**, i. e. an incognito wallet hidden at a specified offset +in a file or partition. Create a file filled with 1 GB of random data: $ dd if=/dev/urandom of=random.dat bs=1K count=1M -Or better yet, use `mmgen-tool rand2file` to do the same job but with some -additional user entropy and a progress meter: +Or better yet, use 'mmgen-tool' to do the same job but with some additional user +entropy and a progress meter: $ mmgen-tool -r40 rand2file random.dat 1G -Export your wallet to incog format, hiding it in this file at offset 123456789: +Export your wallet to incog format, hiding it in the 1GB random file at offset +123456789: $ mmgen-walletchk -G random.dat,123456789 89ABCDEF-87654321[256,5].mmdat ... Incog ID: ED1F2ACB Data written to file 'random.dat' at offset 123456789 -The file 'random.dat' can now be uploaded to your favorite cloud storage -service, for example (in a real-life situation you'd choose a less obvious -offset than '123456789' though). +The altered random file can now be uploaded to a cloud storage service, for +example, or some other location, preferably a non-public one, on the Net (in a +real-life situation you will choose a less obvious offset than '123456789' +though, won't you?). -Generate ten addresses with your hidden incog data: +If at some point you forget the offset but have your Incog ID written down, you +can easily locate your hidden wallet in the file as follows: + + $ mmgen-tool find_incog_data random.dat ED1F2ACB + ... + Incog data for ID ED1F2ACB found at offset 123456789 + +Hidden incog wallets are almost as convenient to use as ordinary ones. +Generating ten addresses with your hidden incog data is done like this: $ mmgen-addrgen -G random.dat,123456789,256 32-42 -Sign a transaction with your hidden incog data: +Signing a transaction uses the same syntax: $ mmgen-txsign -G random.dat,123456789,256 tx_ABCDEE[0.1].raw ... Signed transaction saved to file tx_ABCDEE[0.1].sig -Note that the seed length parameter here will always be '256' unless you're +Note that the seed length parameter here will always be '256', unless you're using a non-default seed length.