From 57ac0601ba0ee9d690ffb81faa2eadaa2f846626 Mon Sep 17 00:00:00 2001 From: ZmnSCPxj jxPCSnmZ Date: Mon, 29 Jun 2020 14:28:46 +0800 Subject: [PATCH] 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. --- .gitignore | 1 + Makefile | 3 +- doc/Makefile | 1 + doc/index.rst | 1 + doc/lightning-hsmtool.8 | 78 ++++++++++++++++++++++++++++++++++++++ doc/lightning-hsmtool.8.md | 78 ++++++++++++++++++++++++++++++++++++++ doc/lightningd-config.5 | 4 ++ doc/lightningd-config.5.md | 4 ++ doc/lightningd.8 | 3 +- doc/lightningd.8.md | 3 +- tools/Makefile | 5 ++- tools/hsmtool.c | 16 ++++---- 12 files changed, 185 insertions(+), 12 deletions(-) create mode 100644 doc/lightning-hsmtool.8 create mode 100644 doc/lightning-hsmtool.8.md diff --git a/.gitignore b/.gitignore index b2e02920c52a..0652806fc1d4 100644 --- a/.gitignore +++ b/.gitignore @@ -20,6 +20,7 @@ gen_* cli/lightning-cli tools/check-bolt tools/hsmtool +tools/lightning-hsmtool coverage ccan/config.h __pycache__ diff --git a/Makefile b/Makefile index 9161bf0b61d1..6be1aa1da2f3 100644 --- a/Makefile +++ b/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 \ diff --git a/doc/Makefile b/doc/Makefile index 2f2c4c59cef1..2190c8c3d305 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -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 \ diff --git a/doc/index.rst b/doc/index.rst index 20533eab703b..8c8dc0bd82b2 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -46,6 +46,7 @@ c-lightning Documentation lightning-fundchannel_start lightning-getroute lightning-getsharedsecret + lightning-hsmtool lightning-invoice lightning-listchannels lightning-listforwards diff --git a/doc/lightning-hsmtool.8 b/doc/lightning-hsmtool.8 new file mode 100644 index 000000000000..bfc8d69e38eb --- /dev/null +++ b/doc/lightning-hsmtool.8 @@ -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 \fBlightnigd\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 + diff --git a/doc/lightning-hsmtool.8.md b/doc/lightning-hsmtool.8.md new file mode 100644 index 000000000000..f8d4a4b2ecb5 --- /dev/null +++ b/doc/lightning-hsmtool.8.md @@ -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 < > 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: + +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: diff --git a/doc/lightningd-config.5 b/doc/lightningd-config.5 index d78554b5dedc..18432a18a8d1 100644 --- a/doc/lightningd-config.5 +++ b/doc/lightningd-config.5 @@ -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 diff --git a/doc/lightningd-config.5.md b/doc/lightningd-config.5.md index 9f8585581a96..2bdfc14730c5 100644 --- a/doc/lightningd-config.5.md +++ b/doc/lightningd-config.5.md @@ -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 --------- diff --git a/doc/lightningd.8 b/doc/lightningd.8 index e1e275e45f5e..dd1d69d915b4 100644 --- a/doc/lightningd.8 +++ b/doc/lightningd.8 @@ -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 diff --git a/doc/lightningd.8.md b/doc/lightningd.8.md index e045af8c049b..91ecb591d7c9 100644 --- a/doc/lightningd.8.md +++ b/doc/lightningd.8.md @@ -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 --------- diff --git a/tools/Makefile b/tools/Makefile index 7f555ed5f59d..917fb5c228fb 100644 --- a/tools/Makefile +++ b/tools/Makefile @@ -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 diff --git a/tools/hsmtool.c b/tools/hsmtool.c index 79e5394f574e..41488e746e67 100644 --- a/tools/hsmtool.c +++ b/tools/hsmtool.c @@ -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 [arguments]\n"); + printf("%s [arguments]\n", progname); printf("methods:\n"); printf(" - decrypt \n"); printf(" - encrypt \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]); }