diff --git a/doc/beginners-guide/backup-and-recovery/hsm-secret.md b/doc/beginners-guide/backup-and-recovery/hsm-secret.md index d23ef5373..583134dbe 100644 --- a/doc/beginners-guide/backup-and-recovery/hsm-secret.md +++ b/doc/beginners-guide/backup-and-recovery/hsm-secret.md @@ -8,31 +8,71 @@ privacy: --- -## Generate HSM Secret +## Mnemonic-Based HSM Secrets (v25.12+) -If you are deploying a new node that has no funds and channels yet, you can generate BIP39 words using any process, and create the `hsm_secret` using the `lightning-hsmtool generatehsm` command. If you did `make install` then `hsmtool` is installed as [`lightning-hsmtool`](ref:lightning-hsmtool), else you can find it in the `tools/` directory of the build directory. +Starting with Core Lightning v25.12, new nodes are automatically created with a BIP39 12-word mnemonic phrase as their root secret. This provides a more user-friendly backup method compared to the previous 32-byte binary format. + + +### Automatic HSM Secret Creation + +When you first start `lightningd` (v25.12+), it will automatically generate a random BIP39 mnemonic and create the `hsm_secret` file **without a passphrase**. No prompts are shown during this process. + +If you want to add a passphrase for additional security, start `lightningd` with the `--hsm-passphrase` option: ```shell -lightning-hsmtool generatehsm hsm_secret +lightningd --hsm-passphrase ``` -Then enter the BIP39 words, plus an optional passphrase. Then copy the `hsm_secret` to `${LIGHTNINGDIR}` - -You can regenerate the same `hsm_secret` file using the same BIP39 words, which again, you can back up on paper. +This will prompt you to enter a passphrase (and confirm it) before creating the `hsm_secret`. The passphrase becomes part of the BIP39 seed derivation process, providing an additional security factor. If you use a passphrase, you must use `--hsm-passphrase` every time you start `lightningd`. -## Encrypt HSM Secret +### Creating HSM Secret with Your Own Mnemonic -You can encrypt the `hsm_secret` content (which is used to derive the HD wallet's master key): -- either by passing the `--encrypted-hsm` startup argument +If you want to use your own mnemonic (instead of a randomly generated one), create the `hsm_secret` manually using the `lightning-hsmtool generatehsm` command before starting `lightningd`. If you did `make install` then `hsmtool` is installed as [`lightning-hsmtool`](ref:lightning-hsmtool), else you can find it in the `tools/` directory of the build directory. + +```shell +lightning-hsmtool generatehsm $LIGHTNINGDIR/hsm_secret +``` + +The command will prompt you interactively in the command line: +1. Enter your BIP39 mnemonic phrase (12 words, separated by spaces) +2. Enter an optional passphrase (you can press Enter to skip adding a passphrase) + +The passphrase provides additional security by adding entropy to the seed derivation process according to BIP39. + +You can regenerate the same `hsm_secret` file using the same BIP39 words and passphrase, which you can back up on paper. **Important:** If you use a passphrase, you must back it up separately along with your mnemonic, as both are required to recover your funds. + + +### Extract Mnemonic for Backup + +If your `hsm_secret` does **not** use a passphrase, you can extract your mnemonic using the `exposesecret` RPC command (requires setting `exposesecret-passphrase` in your config): + +```shell +lightning-cli exposesecret passphrase= +``` + +This returns your mnemonic phrase, which you can then write down and store securely. + +**Important:** `exposesecret` does not work with passphrase-protected `hsm_secret` files. If you used `--hsm-passphrase` when creating your node, you must have backed up your mnemonic during the `generatehsm` step. + + +## Legacy HSM Secret Formats (Pre-v25.12) + +For nodes created before v25.12, the `hsm_secret` was stored as a 32-byte binary file. These legacy formats are still supported for backward compatibility. + + +### Encrypt Legacy HSM Secret + +You can encrypt a legacy `hsm_secret` content (which is used to derive the HD wallet's master key): +- either by passing the `--hsm-passphrase` startup argument (this replaced the deprecated `--encrypted-hsm` option in v25.12) - or by using the `encrypt` method from `/tools/lightning-hsmtool`. -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 needs to access keys from the wallet which is thus **not locked** (yet), even with an encrypted BIP32 master seed. +If you encrypt your legacy `hsm_secret`, you will have to pass the `--hsm-passphrase` 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 needs to access keys from the wallet which is thus **not locked** (yet), even with an encrypted BIP32 master seed. -## Decrypt HSM Secret +### Decrypt Legacy HSM Secret -You can unencrypt an encrypted `hsm_secret` using the `lightning-hsmtool` with the `decrypt` method. +You can unencrypt an encrypted legacy `hsm_secret` using the `lightning-hsmtool` with the `decrypt` method. ```shell lightning-hsmtool decrypt ${LIGHTNINGDIR}/hsm_secret diff --git a/doc/beginners-guide/backup.md b/doc/beginners-guide/backup.md index 09a24c5a8..e0c287469 100644 --- a/doc/beginners-guide/backup.md +++ b/doc/beginners-guide/backup.md @@ -38,11 +38,92 @@ Core Lightning has an internal bitcoin wallet and you can backup three main comp it is kept in a secure location. -The `hsm_secret` is created when you first create the node, and does not change. Thus, a one-time backup of `hsm_secret` is sufficient. -It should be noted down a few times on a piece of paper, in either hexadecimal or codex32 format, as described below: +The `hsm_secret` is created when you first create the node, and does not change. Thus, a one-time backup of `hsm_secret` is sufficient. -#### Hex Format +#### Mnemonic Format (v25.12+) + +Starting with Core Lightning v25.12, new nodes are created with a BIP39 12-word mnemonic phrase as their root secret. By default, **no passphrase is used**. You can optionally protect your mnemonic with a passphrase for additional security by starting `lightningd` with the `--hsm-passphrase` option. + +**Backing up your mnemonic:** + +The **best way to back up your mnemonic** is to use `lightning-hsmtool getsecret`: + +```shell +lightning-hsmtool getsecret $LIGHTNINGDIR/hsm_secret +``` + +This will output your 12-word mnemonic. Write it down on paper and store it securely. **Important:** If you used a passphrase when creating your node, you must back it up separately along with your mnemonic, as both are required to recover your funds. + +**Alternative: Creating your own mnemonic before first start** + +If you prefer to use your own mnemonic instead of having `lightningd` generate a random one, create the `hsm_secret` manually before starting your node for the first time: + +```shell +lightning-hsmtool generatehsm $LIGHTNINGDIR/hsm_secret +``` + +This will prompt you to enter your mnemonic (12 words) and an optional passphrase. If you choose to use a passphrase, you must start `lightningd` with the `--hsm-passphrase` option to provide it. + +**Alternative: Using `exposesecret`** + +If your node was already created (with a randomly-generated mnemonic) and you did **not** use a passphrase (`--hsm-passphrase`), you can extract the mnemonic using the `exposesecret` RPC command: + +```shell +lightning-cli exposesecret passphrase= +``` + +Note: This requires setting `exposesecret-passphrase` in your config. This is a separate security measure for the `exposesecret` command itself, not related to the HSM passphrase. **`exposesecret` does not work if your `hsm_secret` uses a passphrase** - it only works with non-passphrase-protected secrets. + +**Recovery with mnemonic:** + +For v25.12+ nodes, you can use the `recover` RPC command to recover directly from your mnemonic: + +```shell +lightning-cli recover hsmsecret="word1 word2 word3 ... word12" +``` + +Alternatively, you can manually recreate the `hsm_secret` file using `lightning-hsmtool generatehsm`: + +```shell +lightning-hsmtool generatehsm $LIGHTNINGDIR/hsm_secret +``` + +The command will prompt you to: +1. Enter your backed-up mnemonic words (12 words, separated by spaces) +2. Enter your passphrase (if you used one, or press Enter if you didn't) + +Then start `lightningd` normally (with `--hsm-passphrase` if you used a passphrase). + + +#### Readable Format + +Run `tools/lightning-hsmtool getsecret ` to get the `hsm_secret` in readable format. For v25.12+ nodes, this returns the 12-word mnemonic. For older nodes, you will get a codex32 string instead, and must supply a four-letter id to attach to it, like so: + +Example for newer nodes: `tools/lightning-hsmtool getsecret ~/.lightning/bitcoin/hsm_secret` + +Example for older nodes: `tools/lightning-hsmtool getsecret ~/.lightning/bitcoin/hsm_secret adt0`. + +`hsm/secret/path` in the above command is `$LIGHTNINGDIR/hsm_secret`, and +`id` is any 4 character string used to identify this secret. It **cannot** contain `i`, `o`, or `b`, but **can** contain all digits except `1`. + +**Recovery with codex32 (legacy nodes):** + +Legacy nodes can recover using the `recover` RPC command with a codex32 secret: + +```shell +lightning-cli recover hsmsecret= +``` + +Click [here](doc:hsm-secret) to learn more about other cool hsm methods. + + +#### Legacy Formats (Pre-v25.12) + +For nodes created before v25.12, the `hsm_secret` was stored as a 32-byte binary file. These can be backed up in hexadecimal format: + + +##### Hex Format The secret is just 32 bytes, and can be converted into hexadecimal digits like below: @@ -63,19 +144,6 @@ chmod 0400 hsm_secret ``` -#### Readable Format - -Run `tools/lightning-hsmtool getsecret ` to get the `hsm_secret` mnemonic (12 words). For older -nodes, you will get a codex32 string instead, and must supply a four-letter id to attach to it, like so: - -Example `tools/lightning-hsmtool getsecret ~/.lightning/bitcoin/hsm_secret adt0`. - -`hsm/secret/path` in the above command is `$LIGHTNINGDIR/hsm_secret`, and -`id` is any 4 character string used to identify this secret. It **cannot** contain `i`, `o`, or `b`, but **can** contain all digits except `1`. - -Click [here](doc:hsm-secret) to learn more about other cool hsm methods. - - ### Static Channel Backup