mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-19 01:43:36 +01:00
Makefile: Install tools/hsmtool as lightning-hsmtool.
Changelog-Added: We now install `lightning-hsmtool` for your `hsm_secret` needs. See: https://github.com/ElementsProject/lightning/issues/3717#issuecomment-644844594 It seems reasonable to add this to the standard install, and to document it properly as well, hopefully we can fill in the documentation better later on.
This commit is contained in:
ZmnSCPxj jxPCSnmZ
Rusty Russell
parent
7b899da801
commit
5d720536e2
1
.gitignore
vendored
1
.gitignore
vendored
@ -20,6 +20,7 @@ gen_*
|
||||
cli/lightning-cli
|
||||
tools/check-bolt
|
||||
tools/hsmtool
|
||||
tools/lightning-hsmtool
|
||||
coverage
|
||||
ccan/config.h
|
||||
__pycache__
|
||||
|
||||
3
Makefile
3
Makefile
@ -523,7 +523,8 @@ installdirs:
|
||||
# the individual Makefiles, however.
|
||||
BIN_PROGRAMS = \
|
||||
cli/lightning-cli \
|
||||
lightningd/lightningd
|
||||
lightningd/lightningd \
|
||||
tools/lightning-hsmtool
|
||||
PKGLIBEXEC_PROGRAMS = \
|
||||
lightningd/lightning_channeld \
|
||||
lightningd/lightning_closingd \
|
||||
|
||||
@ -24,6 +24,7 @@ MANPAGES := doc/lightning-cli.1 \
|
||||
doc/lightning-fundchannel_cancel.7 \
|
||||
doc/lightning-getroute.7 \
|
||||
doc/lightning-getsharedsecret.7 \
|
||||
doc/lightning-hsmtool.8 \
|
||||
doc/lightning-invoice.7 \
|
||||
doc/lightning-listchannels.7 \
|
||||
doc/lightning-listforwards.7 \
|
||||
|
||||
@ -46,6 +46,7 @@ c-lightning Documentation
|
||||
lightning-fundchannel_start <lightning-fundchannel_start.7.md>
|
||||
lightning-getroute <lightning-getroute.7.md>
|
||||
lightning-getsharedsecret <lightning-getsharedsecret.7.md>
|
||||
lightning-hsmtool <lightning-hsmtool.8.md>
|
||||
lightning-invoice <lightning-invoice.7.md>
|
||||
lightning-listchannels <lightning-listchannels.7.md>
|
||||
lightning-listforwards <lightning-listforwards.7.md>
|
||||
|
||||
78
doc/lightning-hsmtool.8
Normal file
78
doc/lightning-hsmtool.8
Normal file
@ -0,0 +1,78 @@
|
||||
.TH "LIGHTNING-HSMTOOL" "8" "" "" "lightning-hsmtool"
|
||||
.SH NAME
|
||||
lightning-hsmtool - Tool for working with software HSM secrets of lightningd
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
.RS
|
||||
lightning-hsmtool method [ARGUMENTS]...
|
||||
.RE
|
||||
|
||||
.fi
|
||||
.SH DESCRIPTION
|
||||
|
||||
\fBlightning-hsmtool\fR performs various operations on the \fBhsm_secret\fR
|
||||
file used by the software HSM component of \fBlightningd\fR\.
|
||||
|
||||
|
||||
This can be used to encrypt and decrypt the \fBhsm_secret\fR file,
|
||||
as well as derive secrets used in channel commitments\.
|
||||
|
||||
.SH METHODS
|
||||
|
||||
\fBencrypt\fR \fIhsm_secret\fR \fIpassword\fR
|
||||
Encrypt the \fBhsm_secret\fR file so that it can only be decrypted at
|
||||
\fBlightningd\fR startup\.
|
||||
You must give the option \fB--encrypted-hsm\fR to \fBlightningd\fR\.
|
||||
The password of the \fBhsm_secret\fR file will be asked whenever you
|
||||
start \fBlightningd\fR\.
|
||||
|
||||
|
||||
\fBdecrypt\fR \fIhsm_secret\fR \fIpassword\fR
|
||||
Decrypt the \fBhsm_secret\fR file that was encrypted with the \fBencrypt\fR
|
||||
method\.
|
||||
|
||||
|
||||
\fBdumpcommitments\fR \fInode_id\fR \fIchannel_dbid\fR \fIdepth\fR \fIhsm_secret\fR [\fIpassword\fR]
|
||||
Show the per-commitment secret and point of up to \fIdepth\fR commitments,
|
||||
of the specified channel with the specified peer,
|
||||
identified by the channel database index\.
|
||||
Specify \fIpassword\fR if the \fBhsm_secret\fR is encrypted\.
|
||||
|
||||
|
||||
\fBguesstoremote\fR \fIp2wpkh\fR \fInode_id\fR \fImax_channel_dbid\fR \fIhsm_secret\fR [\fIpassword\fR]
|
||||
Brute-force the private key to our funds from a remote unilateral close
|
||||
of a channel, in a case where we have lost all database data except for
|
||||
our \fBhsm_secret\fR\.
|
||||
The peer must be the one to close the channel (and the funds will remain
|
||||
unrecoverable until the channel is closed)\.
|
||||
\fImax_channel_dbid\fR is your own guess on what the \fIchannel_dbid\fR was,
|
||||
or at least the maximum possible value,
|
||||
and is usually no greater than the number of channels that the node has
|
||||
ever had\.
|
||||
Specify \fIpassword\fR if the \fBhsm_secret\fR is encrypted\.
|
||||
|
||||
.SH BUGS
|
||||
|
||||
You should report bugs on our github issues page, and maybe submit a fix
|
||||
to gain our eternal gratitude!
|
||||
|
||||
.SH AUTHOR
|
||||
|
||||
ZmnSCPxj < \fIZmnSCPxj@protonmail.com\fR > wrote the initial version of
|
||||
this man page, but many others did the hard work of actually implementing
|
||||
\fBlightning-hsmtool\fR\.
|
||||
|
||||
.SH SEE ALSO
|
||||
|
||||
\fBlightningd\fR(8), \fBlightningd-config\fR(5)
|
||||
|
||||
.SH RESOURCES
|
||||
|
||||
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
|
||||
|
||||
.SH COPYING
|
||||
|
||||
Note: the modules in the ccan/ directory have their own licenses, but
|
||||
the rest of the code is covered by the BSD-style MIT license\.
|
||||
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
|
||||
|
||||
78
doc/lightning-hsmtool.8.md
Normal file
78
doc/lightning-hsmtool.8.md
Normal file
@ -0,0 +1,78 @@
|
||||
lightning-hsmtool -- Tool for working with software HSM secrets of lightningd
|
||||
=============================================================================
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
```bash
|
||||
lightning-hsmtool method [ARGUMENTS]...
|
||||
```
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
**lightning-hsmtool** performs various operations on the `hsm_secret`
|
||||
file used by the software HSM component of **lightningd**.
|
||||
|
||||
This can be used to encrypt and decrypt the `hsm_secret` file,
|
||||
as well as derive secrets used in channel commitments.
|
||||
|
||||
METHODS
|
||||
-------
|
||||
|
||||
**encrypt** *hsm\_secret* *password*
|
||||
Encrypt the `hsm_secret` file so that it can only be decrypted at
|
||||
**lightningd** startup.
|
||||
You must give the option **--encrypted-hsm** to **lightningd**.
|
||||
The password of the `hsm_secret` file will be asked whenever you
|
||||
start **lightningd**.
|
||||
|
||||
**decrypt** *hsm\_secret* *password*
|
||||
Decrypt the `hsm_secret` file that was encrypted with the **encrypt**
|
||||
method.
|
||||
|
||||
**dumpcommitments** *node\_id* *channel\_dbid* *depth* *hsm\_secret* \[*password*\]
|
||||
Show the per-commitment secret and point of up to *depth* commitments,
|
||||
of the specified channel with the specified peer,
|
||||
identified by the channel database index.
|
||||
Specify *password* if the `hsm_secret` is encrypted.
|
||||
|
||||
**guesstoremote** *p2wpkh* *node\_id* *max\_channel\_dbid* *hsm\_secret* \[*password*\]
|
||||
Brute-force the private key to our funds from a remote unilateral close
|
||||
of a channel, in a case where we have lost all database data except for
|
||||
our `hsm_secret`.
|
||||
The peer must be the one to close the channel (and the funds will remain
|
||||
unrecoverable until the channel is closed).
|
||||
*max\_channel\_dbid* is your own guess on what the *channel\_dbid* was,
|
||||
or at least the maximum possible value,
|
||||
and is usually no greater than the number of channels that the node has
|
||||
ever had.
|
||||
Specify *password* if the `hsm_secret` is encrypted.
|
||||
|
||||
BUGS
|
||||
----
|
||||
|
||||
You should report bugs on our github issues page, and maybe submit a fix
|
||||
to gain our eternal gratitude!
|
||||
|
||||
AUTHOR
|
||||
------
|
||||
ZmnSCPxj < <ZmnSCPxj@protonmail.com> > wrote the initial version of
|
||||
this man page, but many others did the hard work of actually implementing
|
||||
**lightning-hsmtool**.
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
lightningd(8), lightningd-config(5)
|
||||
|
||||
RESOURCES
|
||||
---------
|
||||
|
||||
Main web site: <https://github.com/ElementsProject/lightning>
|
||||
|
||||
COPYING
|
||||
-------
|
||||
|
||||
Note: the modules in the ccan/ directory have their own licenses, but
|
||||
the rest of the code is covered by the BSD-style MIT license.
|
||||
Main web site: <https://github.com/ElementsProject/lightning>
|
||||
@ -255,6 +255,9 @@ automatically by \fBlightningd\fR\.
|
||||
If set, you will be prompted to enter a password used to encrypt the \fBhsm_secret\fR\.
|
||||
Note that once you encrypt the \fBhsm_secret\fR this option will be mandatory for
|
||||
\fBlightningd\fR to start\.
|
||||
If there is no \fBhsm_secret\fR yet, \fBlightningd\fR will create a new encrypted secret\.
|
||||
If you have an unencrypted \fBhsm_secret\fR you want to encrypt on-disk, or vice versa,
|
||||
see \fBlightning-hsmtool\fR(8)\.
|
||||
|
||||
.SH Lightning node customization options
|
||||
|
||||
@ -548,6 +551,7 @@ actually implementing these options\.
|
||||
.SH SEE ALSO
|
||||
|
||||
\fBlightning-listconfigs\fR(7) \fBlightning-setchannelfee\fR(7) \fBlightningd\fR(8)
|
||||
\fBlightning-hsmtool\fR(8)
|
||||
|
||||
.SH RESOURCES
|
||||
|
||||
|
||||
@ -203,6 +203,9 @@ automatically by `lightningd`.
|
||||
If set, you will be prompted to enter a password used to encrypt the `hsm_secret`.
|
||||
Note that once you encrypt the `hsm_secret` this option will be mandatory for
|
||||
`lightningd` to start.
|
||||
If there is no `hsm_secret` yet, `lightningd` will create a new encrypted secret.
|
||||
If you have an unencrypted `hsm_secret` you want to encrypt on-disk, or vice versa,
|
||||
see lightning-hsmtool(8).
|
||||
|
||||
### Lightning node customization options
|
||||
|
||||
@ -457,6 +460,7 @@ SEE ALSO
|
||||
--------
|
||||
|
||||
lightning-listconfigs(7) lightning-setchannelfee(7) lightningd(8)
|
||||
lightning-hsmtool(8)
|
||||
|
||||
RESOURCES
|
||||
---------
|
||||
|
||||
@ -245,7 +245,8 @@ implementation\.
|
||||
|
||||
\fBlightning-listconfigs\fR(7), \fBlightning-config\fR(5), \fBlightning-cli\fR(1),
|
||||
\fBlightning-newaddr\fR(7), \fBlightning-listfunds\fR(7), \fBlightning-connect\fR(7),
|
||||
\fBlightning-fundchannel\fR(7), \fBlightning-listpeers\fR(7), \fBlightning-pay\fR(7)
|
||||
\fBlightning-fundchannel\fR(7), \fBlightning-listpeers\fR(7), \fBlightning-pay\fR(7),
|
||||
\fBlightning-hsmtool\fR(8)
|
||||
|
||||
.SH RESOURCES
|
||||
|
||||
|
||||
@ -171,7 +171,8 @@ SEE ALSO
|
||||
|
||||
lightning-listconfigs(7), lightning-config(5), lightning-cli(1),
|
||||
lightning-newaddr(7), lightning-listfunds(7), lightning-connect(7),
|
||||
lightning-fundchannel(7), lightning-listpeers(7), lightning-pay(7)
|
||||
lightning-fundchannel(7), lightning-listpeers(7), lightning-pay(7),
|
||||
lightning-hsmtool(8)
|
||||
|
||||
RESOURCES
|
||||
---------
|
||||
|
||||
@ -16,11 +16,14 @@ tools/check-bolt: tools/check-bolt.o $(CCAN_OBJS) $(TOOLS_COMMON_OBJS)
|
||||
|
||||
tools/hsmtool: tools/hsmtool.o $(CCAN_OBJS) $(TOOLS_COMMON_OBJS) $(BITCOIN_OBJS) common/amount.o common/bech32.o common/bigsize.o common/derive_basepoints.o common/node_id.o common/type_to_string.o wire/fromwire.o wire/towire.o
|
||||
|
||||
tools/lightning-hsmtool: tools/hsmtool
|
||||
cp $< $@
|
||||
|
||||
clean: tools-clean
|
||||
|
||||
tools-clean:
|
||||
$(RM) tools/check-bolt tools/*.o
|
||||
$(RM) tools/headerversions
|
||||
$(RM) $(TOOLS_OBJ) $(TOOLS)
|
||||
$(RM) $(TOOLS_OBJ) $(TOOLS) tools/lightning-hsmtool
|
||||
|
||||
include tools/test/Makefile
|
||||
|
||||
@ -23,9 +23,9 @@
|
||||
#define ERROR_LIBWALLY 4
|
||||
#define ERROR_KEYDERIV 5
|
||||
|
||||
static void show_usage(void)
|
||||
static void show_usage(const char *progname)
|
||||
{
|
||||
printf("./hsmtool <method> [arguments]\n");
|
||||
printf("%s <method> [arguments]\n", progname);
|
||||
printf("methods:\n");
|
||||
printf(" - decrypt <path/to/hsm_secret> <password>\n");
|
||||
printf(" - encrypt <path/to/hsm_secret> <password>\n");
|
||||
@ -377,24 +377,24 @@ int main(int argc, char *argv[])
|
||||
|
||||
method = argc > 1 ? argv[1] : NULL;
|
||||
if (!method)
|
||||
show_usage();
|
||||
show_usage(argv[0]);
|
||||
|
||||
if (streq(method, "decrypt")) {
|
||||
if (argc < 4)
|
||||
show_usage();
|
||||
show_usage(argv[0]);
|
||||
return decrypt_hsm(argv[2], argv[3]);
|
||||
}
|
||||
|
||||
if (streq(method, "encrypt")) {
|
||||
if (argc < 4)
|
||||
show_usage();
|
||||
show_usage(argv[0]);
|
||||
return encrypt_hsm(argv[2], argv[3]);
|
||||
}
|
||||
|
||||
if (streq(method, "dumpcommitments")) {
|
||||
/* node_id channel_id depth hsm_secret ?password? */
|
||||
if (argc < 7)
|
||||
show_usage();
|
||||
show_usage(argv[0]);
|
||||
struct node_id node_id;
|
||||
if (!node_id_from_hexstr(argv[2], strlen(argv[2]), &node_id))
|
||||
err(ERROR_USAGE, "Bad node id");
|
||||
@ -405,7 +405,7 @@ int main(int argc, char *argv[])
|
||||
if (streq(method, "guesstoremote")) {
|
||||
/* address node_id depth hsm_secret ?password? */
|
||||
if (argc < 7)
|
||||
show_usage();
|
||||
show_usage(argv[0]);
|
||||
struct node_id node_id;
|
||||
if (!node_id_from_hexstr(argv[3], strlen(argv[3]), &node_id))
|
||||
errx(ERROR_USAGE, "Bad node id");
|
||||
@ -413,5 +413,5 @@ int main(int argc, char *argv[])
|
||||
argv[5], argv[6]);
|
||||
}
|
||||
|
||||
show_usage();
|
||||
show_usage(argv[0]);
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user