davide/palladum-lightning
1
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

doc: Update docs to reflect new hsm secret format

Browse Source 
Changelog-Changed - Updated backup and hsm secret docs to reflect mnemonic based hsm secret
This commit is contained in:
Sangbida Chaudhuri
2026-01-14 11:48:42 +10:30
committed by Rusty Russell
parent 779a478437
commit b219214a55
2 changed files with 136 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
doc/beginners-guide/backup-and-recovery/hsm-secret.md
View File

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

100
doc/beginners-guide/backup.md
View File

@@ -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=<your-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 <hsm/secret/path>` 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=<codex32secret>
```
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 <hsm/secret/path>` 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