doc/wiki: update mmgen-autosign command help
This commit is contained in:
parent
7e093fbef8
commit
b3bdc76eb7
GPG key ID:
3F8B1861E32B7DA2
2 changed files with 181 additions and 45 deletions
|
|
@ -1,6 +1,8 @@
|
||||||
```text
|
```text
|
||||||
MMGEN-AUTOSIGN: Auto-sign MMGen transactions, message files and XMR wallet output files
|
MMGEN-AUTOSIGN: Auto-sign MMGen transactions, message files and XMR wallet output files
|
||||||
|
|
||||||
USAGE: mmgen-autosign [opts] [operation]
|
USAGE: mmgen-autosign [opts] [operation]
|
||||||
|
|
||||||
OPTIONS:
|
OPTIONS:
|
||||||
-h, --help Print this help message
|
-h, --help Print this help message
|
||||||
--longhelp Print help message for long (global) options
|
--longhelp Print help message for long (global) options
|
||||||
|
|
@ -12,7 +14,8 @@
|
||||||
the file in volatile memory for use during the signing
|
the file in volatile memory for use during the signing
|
||||||
session, thus permitting the deletion of the original
|
session, thus permitting the deletion of the original
|
||||||
file for increased security.
|
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
|
-L, --led Use status LED to signal standby, busy and error
|
||||||
-m, --mountpoint M Specify an alternate mountpoint 'M'
|
-m, --mountpoint M Specify an alternate mountpoint 'M'
|
||||||
(default: '/mnt/mmgen_autosign')
|
(default: '/mnt/mmgen_autosign')
|
||||||
|
|
@ -35,7 +38,8 @@
|
||||||
(default: '/dev/shm/autosign')
|
(default: '/dev/shm/autosign')
|
||||||
-W, --allow-non-wallet-swap Allow signing of swap transactions that send funds
|
-W, --allow-non-wallet-swap Allow signing of swap transactions that send funds
|
||||||
to non-wallet addresses
|
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
|
||||||
|
|
@ -63,42 +67,107 @@
|
||||||
signing transactions or stealing the user’s seed impossible.
|
signing transactions or stealing the user’s seed impossible.
|
||||||
The operation is intended as a ‘kill switch’ and thus performed
|
The operation is intended as a ‘kill switch’ and thus performed
|
||||||
without prompting
|
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
|
This program is intended to be run on an offline signing computer, preferably
|
||||||
(typically a USB flash drive) containing unsigned MMGen transactions, message
|
air-gapped and with no or disabled RF devices (e.g. wi-fi and bluetooth).
|
||||||
files, and/or XMR wallet output files, signs them, unmounts the removable
|
Memory, storage and CPU requirements for signing operations are modest, so an
|
||||||
device and exits.
|
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
|
Before using the program, a removable device (typically a USB flash drive)
|
||||||
device, performing signing operations and unmounting the device every time it
|
must first be prepared and the current signing session set up, both as
|
||||||
is inserted.
|
described below.
|
||||||
|
|
||||||
On supported platforms (currently Orange Pi, Rock Pi and Raspberry Pi boards),
|
If run with no arguments, the program mounts the removable device, signs any
|
||||||
the status LED indicates whether the program is busy or in standby mode, i.e.
|
unsigned MMGen signables (transactions, message files, and/or XMR wallet
|
||||||
ready for device insertion or removal.
|
output files) on the device, unmounts the device and exits.
|
||||||
|
|
||||||
The removable device must have a partition with a filesystem labeled MMGEN_TX
|
If invoked with ‘wait’, the program waits in a loop: mounting, signing and
|
||||||
and a user-writable root directory. For interoperability between OS-es, it’s
|
unmounting every time the removable device is inserted. Wait mode permits
|
||||||
recommended to use the exFAT file system.
|
“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’
|
Signing is performed with a temporary session wallet written in volatile
|
||||||
(as currently configured) must exist. Linux (not macOS) machines must have
|
memory in the directory ‘/dev/shm/autosign’ (as currently configured). The
|
||||||
an ‘/etc/fstab’ with the following entry:
|
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
|
LABEL=MMGEN_TX /mnt/mmgen_autosign auto noauto,user 0 0
|
||||||
|
|
||||||
Signing is performed with a temporary wallet created in volatile memory in
|
If your Linux distribution mounts volumes automatically, it’s advisable to
|
||||||
the directory ‘/dev/shm/autosign’ (as currently configured). The wallet is
|
disable that functionality.
|
||||||
encrypted with a 32-byte password saved in the file ‘autosign.key’ in the
|
|
||||||
root of the removable device’s filesystem.
|
|
||||||
|
|
||||||
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
|
SETTING UP A SIGNING SESSION
|
||||||
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.
|
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
|
Alternatively, the password and temporary wallet may be created separately by
|
||||||
first invoking ‘mmgen-autosign gen_key’ and then creating and encrypting the
|
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
|
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
|
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
|
file path to the end of the command line. Multiple session wallets may
|
||||||
be created in this way and used for signing (note, however, that for XMR
|
be created in this way (note, however, that for XMR operations only one
|
||||||
operations only one wallet is supported).
|
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
|
SECURITY NOTE
|
||||||
|
|
||||||
By placing wallet and password on separate devices, this program creates
|
By placing the session wallet and password on separate devices, this program
|
||||||
a two-factor authentication setup whereby an attacker must gain physical
|
creates a two-factor authentication setup whereby an attacker must gain
|
||||||
control of both the removable device and signing machine in order to sign
|
physical control of both the removable device and signing machine in order to
|
||||||
transactions. It’s therefore recommended to always keep the removable device
|
sign transactions or steal the user’s seed. It’s therefore recommended to
|
||||||
secure, separated from the signing machine and hidden (in your pocket, for
|
always keep the removable device secure, separated from the signing machine
|
||||||
example) when not transacting. In addition, since login access on the
|
and hidden (in your pocket, for example) when not transacting. In addition,
|
||||||
signing machine is required to steal the user’s seed, it’s good practice
|
it’s good practice to lock the signing machine’s screen when unattended.
|
||||||
to lock the signing machine’s screen once the setup process is complete.
|
|
||||||
|
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
|
As a last resort, cutting power to the signing machine will destroy the
|
||||||
volatile memory where the temporary wallet resides and foil any attack,
|
volatile memory where the session wallets reside and prevent a signing or
|
||||||
even if you’ve lost control of the removable device.
|
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
|
Always remember to power off the signing machine when your signing session
|
||||||
is over.
|
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)
|
||||||
```
|
```
|
||||||
|
|
|
||||||
|
|
@ -1 +1 @@
|
||||||
16.1.dev37
|
16.1.dev38
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue