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

@@ -20,6 +20,7 @@ gen_*
 cli/lightning-cli
 tools/check-bolt
 tools/hsmtool
+tools/lightning-hsmtool
 coverage
 ccan/config.h
 __pycache__

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 \

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 \

doc/index.rst

@@ -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>

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 \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
+

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 < <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>

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
 

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
 ---------

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
 

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
 ---------

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

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 <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]);
 }