From 7e093fbef81d3e36f868d48cb67556e8cdcc3b22 Mon Sep 17 00:00:00 2001 From: The MMGen Project Date: Thu, 7 May 2026 17:52:59 +0000 Subject: [PATCH] mmgen-autosign: expand and revise help notes, add examples --- mmgen/help/autosign.py | 191 ++++++++++++++++++++++++++++++++--------- mmgen/main_autosign.py | 2 +- 2 files changed, 153 insertions(+), 40 deletions(-) diff --git a/mmgen/help/autosign.py b/mmgen/help/autosign.py index 1e97222c..7c889a93 100755 --- a/mmgen/help/autosign.py +++ b/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 """ diff --git a/mmgen/main_autosign.py b/mmgen/main_autosign.py index 0bab5d0f..21d2f1ae 100755 --- a/mmgen/main_autosign.py +++ b/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}' },