hsmtools: a plugin for all things hsm_secret

README.md

@@ -12,6 +12,7 @@ c-lightning is a lighweight, highly customizable and [standard compliant][std] i
 	* [Configuration File](#configuration-file)
 * [Further Information](#further-information)
     * [Pruning](#pruning)
+    * [HD wallet encryption](#hd-wallet-encryption)
 	* [Developers](#developers)
 
 ## Project Status
@@ -102,8 +103,6 @@ Once you've started for the first time, there's a script called
 `contrib/bootstrap-node.sh` which will connect you to other nodes on
 the lightning network.
 
-You can encrypt the BIP32 root seed (what is stored in `hsm_secret`) by passing the `--encrypted-hsm` startup argument. You can start `lightningd` with `--encrypted-hsm` on an already existing `lightning-dir` (with a not encrypted `hsm_secret`). If you pass that option, you __will not__ be able to start `lightningd` (with the same wallet) again without the password, so please beware with your password management. Also beware of not feeling too safe with an encrypted `hsm_secret`: unlike for `bitcoind` where the wallet encryption can restrict the usage of some RPC command, `lightningd` always need to access keys from the wallet which is thus __not locked__ (yet), even with an encrypted BIP32 master seed.
-
 There are also numerous plugins available for c-lightning which add
 capabilities: in particular there's a collection at:
 
@@ -202,6 +201,13 @@ If `bitcoind` prunes a block that c-lightning has not processed yet, e.g., c-lig
 In order to avoid this situation you should be monitoring the gap between c-lightning's blockheight using `lightning-cli getinfo` and `bitcoind`'s blockheight using `bitcoin-cli getblockchaininfo`.
 If the two blockheights drift apart it might be necessary to intervene.
 
+
+### HD wallet encryption
+
+You can encrypt the `hsm_secret` content (which is used to derive the HD wallet's master key) by passing the `--encrypted-hsm` startup argument, or by using the `encrypthsm` RPC call. You can unencrypt an encrypted `hsm_secret` using the `decrypthsm` RPC call.
+
+If you encrypt your `hsm_secret`, you will have to pass the `--encrypted-hsm` startup option to `lightningd`. Once your `hsm_secret` is encrypted, you __will not__ be able to access your funds without your password, so please beware with your password management. Also beware of not feeling too safe with an encrypted `hsm_secret`: unlike for `bitcoind` where the wallet encryption can restrict the usage of some RPC command, `lightningd` always need to access keys from the wallet which is thus __not locked__ (yet), even with an encrypted BIP32 master seed.
+
 ### Developers
 
 Developers wishing to contribute should start with the developer guide [here](doc/HACKING.md).

doc/Makefile

@@ -13,9 +13,11 @@ MANPAGES := doc/lightning-cli.1 \
 	doc/lightning-close.7 \
 	doc/lightning-connect.7 \
 	doc/lightning-decodepay.7 \
+	doc/lightning-decrypthsm.7 \
 	doc/lightning-delexpiredinvoice.7 \
 	doc/lightning-delinvoice.7 \
 	doc/lightning-disconnect.7 \
+	doc/lightning-encrypthsm.7 \
 	doc/lightning-fundchannel.7 \
 	doc/lightning-fundchannel_start.7 \
 	doc/lightning-fundchannel_complete.7 \

doc/index.rst

@@ -36,9 +36,11 @@ c-lightning Documentation
    lightning-close <lightning-close.7.md>
    lightning-connect <lightning-connect.7.md>
    lightning-decodepay <lightning-decodepay.7.md>
+   lightning-decrypthsm <lightning-decrypthsm.7.md>
    lightning-delexpiredinvoice <lightning-delexpiredinvoice.7.md>
    lightning-delinvoice <lightning-delinvoice.7.md>
    lightning-disconnect <lightning-disconnect.7.md>
+   lightning-encrypthsm <lightning-encrypthsm.7.md>
    lightning-fundchannel <lightning-fundchannel.7.md>
    lightning-fundchannel_cancel <lightning-fundchannel_cancel.7.md>
    lightning-fundchannel_complete <lightning-fundchannel_complete.7.md>

doc/lightning-decrypthsm.7

@@ -0,0 +1,39 @@
+.TH "LIGHTNING-DECRYPTHSM" "7" "" "" "lightning-decrypthsm"
+.SH NAME
+lightning-encrypthsm - Decrypt your hsm_secret
+.SH SYNOPSIS
+
+\fBdecrypthsm\fR \fIpassword\fR
+
+.SH DESCRIPTION
+
+The \fBhsm_secret\fR file in your lightning-dir comports a seed from which is
+derived the HD wallet master key\. If you previously encrypted it using the
+\fB--encrypted-hsm\fR startup option or the \fBencrypthsm\fR RPC command, you can decrypt it
+by using the \fBdecrypthsm\fR RPC command with the same \fIpassword\fR used to encrypt it\.
+
+.SH RETURN VALUE
+
+An error can be returned in two main cases:
+
+.RS
+.IP \[bu]
+decryption failed, in which case the error description will give more details
+.IP \[bu]
+hsm_secret failure (either opening, creating, or writing), in which case the JSONRPC
+  error field will be populated with the errno\.
+
+.RE
+.SH AUTHOR
+
+Antoine Poinsot \fI<darosior@protonmail.com\fR>\.
+
+.SH SEE ALSO
+
+\fBlightning-encrypthsm\fR(7)
+\fBlightningd-config\fR(5)
+
+.SH RESOURCES
+
+Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
+

doc/lightning-decrypthsm.7.md

@@ -0,0 +1,39 @@
+lightning-encrypthsm -- Decrypt your hsm_secret
+===============================================
+
+SYNOPSIS
+--------
+
+**decrypthsm** *password*
+
+DESCRIPTION
+-----------
+
+The `hsm_secret` file in your lightning-dir comports a seed from which is
+derived the HD wallet master key. If you previously encrypted it using the
+`--encrypted-hsm` startup option or the `encrypthsm` RPC command, you can decrypt it
+by using the **decrypthsm** RPC command with the same *password* used to encrypt it.
+
+RETURN VALUE
+------------
+
+An error can be returned in two main cases:
+- decryption failed, in which case the error description will give more details
+- hsm_secret failure (either opening, creating, or writing), in which case the JSONRPC
+    error field will be populated with the errno.
+
+AUTHOR
+------
+
+Antoine Poinsot <<darosior@protonmail.com>>.
+
+SEE ALSO
+--------
+
+lightning-encrypthsm(7)
+lightningd-config(5)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>

doc/lightning-encrypthsm.7.md

@@ -0,0 +1,51 @@
+lightning-encrypthsm -- Encrypt your hsm_secret
+===============================================
+
+SYNOPSIS
+--------
+
+**encrypthsm** *password*
+
+DESCRIPTION
+-----------
+
+The `hsm_secret` file in your lightning-dir comports a seed from which is
+derived the HD wallet master key.
+
+The **encrypthsm** command allows you to encrypt this seed with a provided *password*.
+
+Note however that the RPC connection is not encrypted and that your password will be
+transmitted in clear (in addition to being in your command history if you use the CLI).
+You can use the `--encrypted-hsm` startup option, which hide your password as you type
+it, as an alternative.
+
+Once your `hsm_secret` is encrypted, you will have to explicitly start `lightningd` with
+the `--encrypted-hsm` option.
+
+The algorithm used to derive the encryption key from the password is
+[Argon2id](https://github.com/p-h-c/phc-winner-argon2). The seed is then encrypted using
+[xChacha20Poly1305](https://tools.ietf.org/html/draft-arciszewski-xchacha-03).
+
+RETURN VALUE
+------------
+
+An error can be returned in two main cases:
+- encryption failed, in which case the error description will give more details
+- hsm_secret failure (either opening, creating, or writing), in which case the JSONRPC
+    error field will be populated with the errno.
+
+AUTHOR
+------
+
+Antoine Poinsot <<darosior@protonmail.com>>.
+
+SEE ALSO
+--------
+
+lightning-decrypthsm(7)
+lightningd-config(5)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>

plugins/Makefile

@@ -7,6 +7,9 @@ PLUGIN_AUTOCLEAN_OBJS := $(PLUGIN_AUTOCLEAN_SRC:.c=.o)
 PLUGIN_FUNDCHANNEL_SRC := plugins/fundchannel.c
 PLUGIN_FUNDCHANNEL_OBJS := $(PLUGIN_FUNDCHANNEL_SRC:.c=.o)
 
+PLUGIN_HSMTOOLS_SRC := plugins/hsmtools.c
+PLUGIN_HSMTOOLS_OBJS := $(PLUGIN_HSMTOOLS_SRC:.c=.o)
+
 PLUGIN_LIB_SRC := plugins/libplugin.c
 PLUGIN_LIB_HEADER := plugins/libplugin.h
 PLUGIN_LIB_OBJS := $(PLUGIN_LIB_SRC:.c=.o)
@@ -47,17 +50,20 @@ plugins/autoclean: bitcoin/chainparams.o $(PLUGIN_AUTOCLEAN_OBJS) $(PLUGIN_LIB_O
 
 plugins/fundchannel: common/addr.o $(PLUGIN_FUNDCHANNEL_OBJS) $(PLUGIN_LIB_OBJS) $(PLUGIN_COMMON_OBJS) $(JSMN_OBJS) $(CCAN_OBJS)
 
-$(PLUGIN_PAY_OBJS) $(PLUGIN_AUTOCLEAN_OBJS) $(PLUGIN_FUNDCHANNEL_OBJS) $(PLUGIN_LIB_OBJS): $(PLUGIN_LIB_HEADER)
+plugins/hsmtools: bitcoin/chainparams.o bitcoin/privkey.o $(PLUGIN_HSMTOOLS_OBJS) $(PLUGIN_LIB_OBJS) $(PLUGIN_COMMON_OBJS) $(JSMN_OBJS) $(CCAN_OBJS)
+
+$(PLUGIN_PAY_OBJS) $(PLUGIN_AUTOCLEAN_OBJS) $(PLUGIN_FUNDCHANNEL_OBJS) $(PLUGIN_HSMTOOLS_OBJS) $(PLUGIN_LIB_OBJS): $(PLUGIN_LIB_HEADER)
 
 # Make sure these depend on everything.
-ALL_PROGRAMS += plugins/pay plugins/autoclean plugins/fundchannel
-ALL_OBJS += $(PLUGIN_PAY_OBJS) $(PLUGIN_AUTOCLEAN_OBJS) $(PLUGIN_FUNDCHANNEL_OBJS) $(PLUGIN_LIB_OBJS)
+ALL_PROGRAMS += plugins/pay plugins/autoclean plugins/fundchannel plugins/hsmtools
+ALL_OBJS += $(PLUGIN_PAY_OBJS) $(PLUGIN_AUTOCLEAN_OBJS) $(PLUGIN_FUNDCHANNEL_OBJS) $(PLUGIN_HSMTOOLS_OBJS) $(PLUGIN_LIB_OBJS)
+
+check-source: $(PLUGIN_PAY_SRC:%=check-src-include-order/%) $(PLUGIN_AUTOCLEAN_SRC:%=check-src-include-order/%) $(PLUGIN_FUNDCHANNEL_SRC:%=check-src-include-order/%) # $(PLUGIN_HSMTOOLS_SRC:%=check-src-include-order/%)
+check-source-bolt: $(PLUGIN_PAY_SRC:%=bolt-check/%) $(PLUGIN_AUTOCLEAN_SRC:%=bolt-check/%) $(PLUGIN_FUNDCHANNEL_SRC:%=bolt-check/%) # $(PLUGIN_HSMTOOLS_SRC:%bolt-check/%)
+check-whitespace: $(PLUGIN_PAY_SRC:%=check-whitespace/%) $(PLUGIN_AUTOCLEAN_SRC:%=check-whitespace/%) $(PLUGIN_FUNDCHANNEL_SRC:%=check-whitespace/%) # $(PLUGIN_HSMTOOLS_SRC:%=check-whitespace/%)
 
-check-source: $(PLUGIN_PAY_SRC:%=check-src-include-order/%) $(PLUGIN_AUTOCLEAN_SRC:%=check-src-include-order/%) $(PLUGIN_FUNDCHANNEL_SRC:%=check-src-include-order/%)
-check-source-bolt: $(PLUGIN_PAY_SRC:%=bolt-check/%) $(PLUGIN_AUTOCLEAN_SRC:%=bolt-check/%) $(PLUGIN_FUNDCHANNEL_SRC:%=bolt-check/%)
-check-whitespace: $(PLUGIN_PAY_SRC:%=check-whitespace/%) $(PLUGIN_AUTOCLEAN_SRC:%=check-whitespace/%) $(PLUGIN_FUNDCHANNEL_SRC:%=check-whitespace/%)
 
 clean: plugin-clean
 
 plugin-clean:
-	$(RM) $(PLUGIN_PAY_OBJS) $(PLUGIN_AUTOCLEAN_OBJS) $(PLUGIN_FUNDCHANNEL_OBJS) $(PLUGIN_LIB_OBJS)
+	$(RM) $(PLUGIN_PAY_OBJS) $(PLUGIN_AUTOCLEAN_OBJS) $(PLUGIN_FUNDCHANNEL_OBJS) $(PLUGIN_HSMTOOLS_OBJS) $(PLUGIN_LIB_OBJS)