|
|
@@ -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
|
|
|
+
|
|
|
+
|
|
|
+ DESCRIPTION
|
|
|
+
|
|
|
+ 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.
|
|
|
+
|
|
|
+ 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.
|
|
|
+
|
|
|
+ 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.
|
|
|
+
|
|
|
+ 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).
|
|
|
+
|
|
|
+ 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).
|
|
|
|
|
|
- USAGE NOTES
|
|
|
+ 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’.
|
|
|
|
|
|
- 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.
|
|
|
+ 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 - -
|
|
|
|
|
|
- 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.
|
|
|
+ * Executable must be renamed from the default ‘bitcoind’
|
|
|
|
|
|
- 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.
|
|
|
|
|
|
- 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.
|
|
|
+ LED SIGNALING SUPPORT
|
|
|
|
|
|
- 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:
|
|
|
+ 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.
|
|
|
+
|
|
|
+
|
|
|
+ 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.
|
|
|
|
|
|
- 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.
|
|
|
+
|
|
|
+ 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).
|
|
|
+
|
|
|
+
|
|
|
+ XMR SIGNING SESSION SETUP
|
|
|
|
|
|
- Autosigning is currently supported on Linux and macOS only.
|
|
|
+ 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)
|
|
|
```
|
