From b3bdc76eb755043d934e7a5c9ab5aac5e2b1f783 Mon Sep 17 00:00:00 2001 From: The MMGen Project Date: Thu, 7 May 2026 17:52:59 +0000 Subject: [PATCH] doc/wiki: update `mmgen-autosign` command help --- doc/wiki/cmds/command-help-autosign.md | 224 ++++++++++++++++++++----- mmgen/data/version | 2 +- 2 files changed, 181 insertions(+), 45 deletions(-) diff --git a/doc/wiki/cmds/command-help-autosign.md b/doc/wiki/cmds/command-help-autosign.md index 12c7f77e..395addd9 100644 --- a/doc/wiki/cmds/command-help-autosign.md +++ b/doc/wiki/cmds/command-help-autosign.md @@ -1,6 +1,8 @@ ```text MMGEN-AUTOSIGN: Auto-sign MMGen transactions, message files and XMR wallet output files - USAGE: mmgen-autosign [opts] [operation] + + USAGE: mmgen-autosign [opts] [operation] + OPTIONS: -h, --help Print this help message --longhelp Print help message for long (global) options @@ -12,7 +14,8 @@ the file in volatile memory for use during the signing session, thus permitting the deletion of the original file for increased security. - -l, --seed-len N Specify wallet seed length of ‘N’ bits (for setup only) + -l, --seed-len N Specify wallet seed length of ‘N’ bits (for setup with + mnemonic seed phrase only) -L, --led Use status LED to signal standby, busy and error -m, --mountpoint M Specify an alternate mountpoint 'M' (default: '/mnt/mmgen_autosign') @@ -35,10 +38,11 @@ (default: '/dev/shm/autosign') -W, --allow-non-wallet-swap Allow signing of swap transactions that send funds to non-wallet addresses - -x, --xmrwallets L Range or list of wallets to be used for XMR autosigning + -x, --xmrwallets L Range or list of wallet numbers to be used for XMR + autosigning (see XMR SIGNING SESSION SETUP below) - OPERATIONS + OPERATIONS clean - clean the removable device of unneeded files, removing only non- essential data @@ -63,42 +67,107 @@ signing transactions or stealing the user’s seed impossible. The operation is intended as a ‘kill switch’ and thus performed without prompting + 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. - On supported platforms (currently Orange Pi, Rock Pi and Raspberry Pi boards), - the status LED indicates whether the program is busy or in standby mode, i.e. - ready for device insertion or removal. + 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. - 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 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). - On both the signing and online machines the mountpoint ‘/mnt/mmgen_autosign’ - (as currently configured) must exist. Linux (not macOS) machines must have - an ‘/etc/fstab’ with the following entry: + Signing is performed with a temporary session wallet written in volatile + memory in the directory ‘/dev/shm/autosign’ (as currently configured). The + wallet is encrypted with a random password saved in the file ‘autosign.key’ + on the removable device. + + 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 + + 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 + list is not exhaustive: signaling may work with other boards, especially those + produced by the listed manufacturers. If ‘test_led’ reports that your board is + not supported, please submit an issue to the mmgen-wallet repository on Github + or via e-mail, including the board model, OS version and output of the + following shell command: + + ls -RH /sys/class/leds/{*status*,*led*} + + + 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 ‘/mnt/mmgen_autosign’ + (as currently configured) and, for Linux, the following entry in ‘/etc/fstab’: LABEL=MMGEN_TX /mnt/mmgen_autosign auto noauto,user 0 0 - Signing is performed with a temporary wallet created in volatile memory in - the directory ‘/dev/shm/autosign’ (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. + 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 @@ -108,30 +177,97 @@ 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 + ‘/dev/shm/autosign’ 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. - MMGEN-WALLET 16.0.0 September 2025 MMGEN-AUTOSIGN(1) + 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-WALLET 16.1.dev38 May 2026 MMGEN-AUTOSIGN(1) ``` diff --git a/mmgen/data/version b/mmgen/data/version index e2bee6d0..eb197c3c 100644 --- a/mmgen/data/version +++ b/mmgen/data/version @@ -1 +1 @@ -16.1.dev37 +16.1.dev38