mmgen-autosign: expand and revise help notes, add examples

mmgen/help/autosign.py

@@ -44,31 +44,57 @@ list_led  - list boards with tested LED signaling support
 test_led  - test the current board for LED signaling support
 
 
-                               USAGE NOTES
+                                  DESCRIPTION
 
-If no operation is specified, this program mounts a removable device
-(typically a USB flash drive) containing unsigned MMGen transactions, message
-files, and/or XMR wallet output files, signs them, unmounts the removable
-device and exits.
+This program is intended to be run on an offline signing computer, preferably
+air-gapped and with no or disabled RF devices (e.g. wi-fi and bluetooth).
+Memory, storage and CPU requirements for signing operations are modest, so an
+old laptop is suitable for the job, or better yet, a Raspberry Pi or Pi clone
+from among the list of supported devices (see LED SIGNALING SUPPORT below).
+OS support is currently limited to Linux and macOS.
 
-If invoked with ‘wait’, the program waits in a loop, mounting the removable
-device, performing signing operations and unmounting the device every time it
-is inserted.
+Before using the program, a removable device (typically a USB flash drive)
+must first be prepared and the current signing session set up, both as
+described below.
 
-The removable device must have a partition with a filesystem labeled MMGEN_TX
-and a user-writable root directory.  For interoperability between OS-es, it’s
-recommended to use the exFAT file system.
+If run with no arguments, the program mounts the removable device, signs any
+unsigned MMGen signables (transactions, message files, and/or XMR wallet
+output files) on the device, unmounts the device and exits.
 
-On both the signing and online machines the mountpoint ‘{asi.mountpoint}’
-(as currently configured) must exist.  Linux (not macOS) machines must have
-an ‘/etc/fstab’ with the following entry:
+If invoked with ‘wait’, the program waits in a loop: mounting, signing and
+unmounting every time the removable device is inserted.  Wait mode permits
+“hands-free” operation, i.e. repeated signing of signables with no keyboard
+input, by simply inserting the removable device and then removing it when the
+program indicates that signing is complete (see LED SIGNALING SUPPORT below).
 
-    LABEL=MMGEN_TX {asi.mountpoint} auto noauto,user 0 0
+Signing is performed with a temporary session wallet written in volatile
+memory in the directory ‘{asi.wallet_dir}’ (as currently configured).  The
+wallet is encrypted with a random password saved in the file ‘autosign.key’
+on the removable device.
 
-Signing is performed with a temporary wallet created in volatile memory in
-the directory ‘{asi.wallet_dir}’ (as currently configured).  The wallet is
-encrypted with a 32-byte password saved in the file ‘autosign.key’ in the
-root of the removable device’s filesystem.
+By default, the session wallet is created from the user’s default MMGen
+wallet, if it exists.  However, the user may optionally generate the session
+wallet by interactively entering a seed phrase during session setup. Thus it
+is possible to perform signing and other wallet operations with no seed data
+ever written to disk, even in encrypted form (“wallet-less” operation).
+
+Depending on the coin, signing is performed either internally by MMGen Wallet
+or using an external backend, according to the table below.  Thus you must
+install the corresponding backend executable, if any, for each coin you wish
+to transact and start it with the listed command, if any, at the beginning of
+each signing session.  It’s recommended to install the executables into
+‘/usr/local/bin’.
+
+  Coin          Backend           Executable        Command
+  ----          -------           ----------        -------
+  BTC           Bitcoin Core      bitcoind          bitcoind --listen=0 --daemon
+  LTC           Litecoin Core     litecoind         litecoind --listen=0 --daemon
+  BCH           Bitcoin Cash Node bitcoind-bchn*    bitcoind-bchn --daemon --listen=0 --rpcport=8432 --datadir=$HOME/.bitcoin-bchn
+  XMR           Monero CLI Wallet monero-wallet-rpc -
+  ETH,ETC,ERC20 none              -                 -
+  RUNE          none              -                 -
+
+  * Executable must be renamed from the default ‘bitcoind’
 
 
                              LED SIGNALING SUPPORT
@@ -76,6 +102,8 @@ root of the removable device’s filesystem.
 On supported platforms (selected Orange Pi, Rock Pi, Banana Pi, Nano Pi and
 Raspberry Pi boards), a flashing LED indicates whether signing is in progress
 or the program is in standby mode, i.e. ready for device insertion or removal.
+In the absence of LED support, the user must observe the signing progress
+on-screen and wait for the “safe to extract” message to appear.
 
 The operation ‘test_led’ tests the current installation for LED support, while
 ‘list_led’ displays a list of supported board/OS combinations.  Note that this
@@ -87,14 +115,32 @@ following shell command:
 
     ls -RH /sys/class/leds/{{*status*,*led*}}
 
-In the absence of LED support, the user must observe the signing progress
-on-screen and wait for the “safe to extract” message to appear.
+
+                         PREPARING THE REMOVABLE DEVICE
+
+Create a partition on the removable device with a filesystem labeled ‘MMGEN_TX’
+and a user-writable root directory.  For interoperability between different
+operating systems, it’s recommended to use the exFAT filesystem.
+
+On both the offline and online machines, create the mountpoint ‘{asi.mountpoint}’
+(as currently configured) and, for Linux, the following entry in ‘/etc/fstab’:
+
+    LABEL=MMGEN_TX {asi.mountpoint} auto noauto,user 0 0
+
+If your Linux distribution mounts volumes automatically, it’s advisable to
+disable that functionality.
 
 
-The password and temporary wallet may be created in one operation by invoking
-‘mmgen-autosign setup’ with the removable device inserted.  In this case, the
-temporary wallet is created from the user’s default wallet, if it exists and
-the user so desires.  If not, the user is prompted to enter a seed phrase.
+                         SETTING UP A SIGNING SESSION
+
+Invoke ‘mmgen-autosign setup’ with the removable device inserted.  This will
+create the temporary session wallet from the user’s default MMGen wallet (if
+it exists) or, optionally, a seed phrase.  In addition, the session wallet
+password is created and written to the removable device.  Additional options
+may be required.  See OPTIONS above and EXAMPLES below.
+
+
+                       ALTERNATIVE (MANUAL) SESSION SETUP
 
 Alternatively, the password and temporary wallet may be created separately by
 first invoking ‘mmgen-autosign gen_key’ and then creating and encrypting the
@@ -104,28 +150,95 @@ wallet using the -P (--passwd-file) option:
 
 Note that the hash preset must be ‘1’.  To use a wallet file as the source
 instead of an MMGen seed phrase, omit the ‘-i’ option and add the wallet
-file path to the end of the command line.  Multiple temporary wallets may
-be created in this way and used for signing (note, however, that for XMR
-operations only one wallet is supported).
+file path to the end of the command line.  Multiple session wallets may
+be created in this way (note, however, that for XMR operations only one
+session wallet is supported).
 
-Autosigning is currently supported on Linux and macOS only.
+
+                           XMR SIGNING SESSION SETUP
+
+To set up an XMR signing session, run ‘setup’ with the --xmrwallets option,
+supplying an integer, range, or comma-separated list of integers as the
+option’s parameter.  Each integer in the list or range represents a wallet
+number.  For each wallet number, the program generates a Monero address and
+creates a temporary session Monero signing wallet in volatile memory under
+‘{asi.wallet_dir}’ with this number and base address.  In addition, data is
+written to the removable device which will allow the online installation to
+create a watch-only wallet matching the session signing wallet when the user
+runs ‘mmgen-addrimport --coin=xmr’ on the online machine with the removable
+device inserted (type ‘mmgen-addrimport --coin=xmr --help’ for details).
+
+The use of multiple Monero wallets can help protect against certain known
+deanonymization attacks such as the Janus attack.  However, since wallet
+creation and online syncing of multiple wallets, as well as switching among
+them during the signing process, are all time-consuming, it’s recommended to
+limit the number of wallets created.  First-time users are thus advised to
+begin with ‘--xmrwallets=1’.  More wallets may be added in later signing
+sessions if necessary.  See EXAMPLES below.
 
 
                                SECURITY NOTE
 
-By placing wallet and password on separate devices, this program creates
-a two-factor authentication setup whereby an attacker must gain physical
-control of both the removable device and signing machine in order to sign
-transactions.  It’s therefore recommended to always keep the removable device
-secure, separated from the signing machine and hidden (in your pocket, for
-example) when not transacting.  In addition, since login access on the
-signing machine is required to steal the user’s seed, it’s good practice
-to lock the signing machine’s screen once the setup process is complete.
+By placing the session wallet and password on separate devices, this program
+creates a two-factor authentication setup whereby an attacker must gain
+physical control of both the removable device and signing machine in order to
+sign transactions or steal the user’s seed.  It’s therefore recommended to
+always keep the removable device secure, separated from the signing machine
+and hidden (in your pocket, for example) when not transacting.  In addition,
+it’s good practice to lock the signing machine’s screen when unattended.
+
+For Monero, passwords for the watch-only wallets are also stored on the
+removable device, meaning that a local attacker must gain access to the latter
+not only to sign transactions but also to observe the user’s XMR balances and
+transaction history (a remote attacker could possibly observe these, but
+extracting the removable device when it’s not in use makes such an attack
+less feasible).
 
 As a last resort, cutting power to the signing machine will destroy the
-volatile memory where the temporary wallet resides and foil any attack,
-even if you’ve lost control of the removable device.
+volatile memory where the session wallets reside and prevent a signing or
+seed-stealing attack, even if the attacker has gained control of the removable
+device.
 
 Always remember to power off the signing machine when your signing session
 is over.
+
+After each signing operation, this program displays a summary showing each
+transaction’s non-wallet destination address(es) and amount(s).  As an extra
+security measure, it’s a good idea to compare these with the address(es) and
+amount(s) displayed by your online installation. A discrepancy would indicate
+that your online setup has been compromised.
+
+
+                                    EXAMPLES
+
+Set up a signing session:
+$ mmgen-autosign setup
+
+Start the Bitcoin Core daemon:
+$ bitcoind --daemon --listen=0
+
+Start the signing loop (BTC-only signing):
+$ mmgen-autosign wait # exit loop with Ctrl-C
+
+Set up a signing session with one XMR wallet:
+$ mmgen-autosign --xmrwallets=1 setup
+
+In a later signing session, add two more XMR wallets:
+$ mmgen-autosign --xmrwallets=1-3 setup
+
+Start the Litecoin Core daemon:
+$ litecoind --daemon --listen=0
+
+Start the signing loop (BTC, LTC and XMR signing):
+$ mmgen-autosign --coins=btc,ltc,xmr wait
+
+Set up a signing session with 3 XMR wallets, prompting for a 12-word BIP39 seed phrase:
+$ mmgen-autosign --xmrwallets=2,5,8 --mnemonic-fmt=bip39 --seed-len=128 setup
+
+Start the signing loop in stealth LED mode with full TX summary (LTC, RUNE and XMR signing):
+$ mmgen-autosign --coins=ltc,rune,xmr --stealth-led --full-summary wait
+
+Generate a list of 10 LTC Bech32 addresses using your session wallet:
+$ mount /mnt/mmgen_autosign
+$ mmgen-addrgen -P /mnt/mmgen_autosign/autosign.key --coin=ltc --type=B /dev/shm/autosign/*.mmdat 1-10
 """

mmgen/main_autosign.py

@@ -67,7 +67,7 @@ opts_data = {
 -W, --allow-non-wallet-swap Allow signing of swap transactions that send funds
                       to non-wallet addresses
 -x, --xmrwallets=L    Range or list of wallet numbers to be used for XMR
-                      autosigning
+                      autosigning (see XMR SIGNING SESSION SETUP below)
 """,
 	'notes': '{n_as}'
 	},