Add support for mnemonics in hsm_secret #8400

sangbida · 2025-07-08T00:42:19Z

Important

25.09 FREEZE July 28TH: Non-bugfix PRs not ready by this date will wait for 25.12.

RC1 is scheduled on August 11th

The final release is scheduled for September 1st.

Checklist

Before submitting the PR, ensure the following tasks are completed. If an item is not applicable to your PR, please mark it as checked:

The changelog has been updated in the relevant commit(s) according to the guidelines.
Tests have been added or modified to reflect the changes.
Documentation has been reviewed and updated as needed.
Related issues have been listed and linked, including any that this PR closes.

We want to validate if our secret is a mnemonic. In hsm_secret_is_encrypted we're checking if the secret is encrypted, we now have to add an additional check here to see if the secret is a mnemonic.

This adds support for reading a 12-word BIP39 mnemonic from a plaintext hsm_secret file. If the file contains a valid mnemonic, hsmtool will derive the 32-byte seed. There's a few TODOs left through out the code. I think the most important one being that I haven't handled the passphrase case so far. In a BIP39 secret, 512 bits of 64 bytes, the first 32 bytes are for the hsm_seed and the next 32 bytes are for the optional passphrase. We're currently hardcoding the passphrase to an empty string but we will probably want to handle this? I've also refactoed is_mnemonic_secret to use read_and_validate_mnemonic_file so it's a little tidier.

Updates generate_hsm() to write the 12-word BIP39 mnemonic to the hsm_secret file, instead of a 32-byte raw seed.

This is a newer API to replace hsm_encryption.c and hsm_encryption.c, this tidies up the API to be used and also cleans things up to support our new formts. Our hsm_secret formats now include: - Legacy 32-byte plain format - Legacy 73-byte encrypted format - New mnemonic format without passphrase (32 zero bytes + mnemonic) - New mnemonic format with passphrase (32-byte hash + mnemonic) This commit includes support to detect the format based on the file size and content structure. The hsm will store mnemonics in the hsm_secret file as: `passphraseHash`mnemonic`

I'm just committing this now cause it feels like I'm tired and going to write stupid code soon

gets rid of get_hsm_seed which would prompt the user for a password. We were prompting the user for a password 2-3 times., now only load_hsm_secret prompts the user for a password. The exception is check_hsm which requires you to reenter your password. Also, added a skeleton of some tests I'd like to add but none of them work just yet.

rustyrussell · 2025-07-08T00:44:55Z

common/hsm_secret.c

+#include <ccan/tal/str/str.h>
+#include <ccan/tal/tal.h>
+#include <common/errcode.h>
+#include <common/utils.h>
+#include <common/hsm_secret.h>
+#include <errno.h>
+#include <termios.h>
+#include <unistd.h>
+#include <ccan/crypto/sha256/sha256.h>  
+#include <ccan/mem/mem.h>               
+#include <sodium.h>                     
+#include <wally_bip39.h>                
+#include <sys/stat.h>                   
+


These need to be in alphabetical order!

rustyrussell · 2025-07-08T00:45:48Z

common/hsm_secret.c

+	case HSM_SECRET_INVALID:
+		return false;
+	}
+	return false;


rustyrussell · 2025-07-08T00:46:54Z

common/hsm_secret.c

+		return HSM_SECRET_ENCRYPTED;
+
+	/* Check if it starts with our type bytes (mnemonic formats) */
+	if (len > 32) {


if (len < 32)
return HSM_SECRET_INVALID;

rustyrussell · 2025-07-08T00:48:31Z

common/hsm_secret.c

+static void hash_passphrase(const char *passphrase, u8 hash[PASSPHRASE_HASH_LEN])
+{
+	struct sha256 sha;
+	sha256(&sha, passphrase, strlen(passphrase));
+	memcpy(hash, sha.u.u8, PASSPHRASE_HASH_LEN);
+}


We have a sha256 type for a reason, let's use it, not convert to u8[]

rustyrussell · 2025-07-08T00:50:59Z

common/hsm_secret.c

+	/* First 32 bytes are the stored passphrase hash */
+	const u8 *stored_hash = hsm_secret;
+	u8 computed_hash[32];
+
+	hash_passphrase(passphrase, computed_hash);
+	return memcmp(stored_hash, computed_hash, 32) == 0;
+}
+


struct sha256 actual, expected;

/* First 32 bytes are the stored passphrase hash */
memcpy(&expected, hsm_secret, sizeof(struct sha256));
sha256(&actual, passphrase, strlen(passphrase));

return sha256_eq(&expected, &actual);

rustyrussell · 2025-07-08T01:43:55Z

tools/hsmtool.c

+	if (strlen(passphrase) == 0) {
+		passphrase = NULL;


Mildly prefer if (streq(passphrase, "")) ?

rustyrussell · 2025-07-08T01:44:18Z

tools/hsmtool.c

-	if (bip39_mnemonic_to_seed(mnemonic, passphrase, bip32_seed, sizeof(bip32_seed), &bip32_seed_len) != WALLY_OK)
-		errx(ERROR_LIBWALLY, "Unable to derive BIP32 seed from BIP39 mnemonic");
-
+	/* Write to file using your new mnemonic format */
 	int fd = open(hsm_secret_path, O_CREAT|O_EXCL|O_WRONLY, 0400);
 	if (fd < 0) {
 		errx(ERROR_USAGE, "Unable to create hsm_secret file");


err() not errx()

rustyrussell · 2025-07-08T01:44:51Z

tools/hsmtool.c

+		sha256(&sha, passphrase, strlen(passphrase));
+
+		if (!write_all(fd, sha.u.u8, PASSPHRASE_HASH_LEN))
+			errx(ERROR_USAGE, "Error writing passphrase hash to hsm_secret file");


rustyrussell · 2025-07-08T01:50:12Z

tools/hsmtool.c

+	if (passphrase) {
+		/* Write passphrase hash (32 bytes) + mnemonic for protected format */
+		struct sha256 sha;
+		sha256(&sha, passphrase, strlen(passphrase));


This should be hash of the final seed. This is a bit trickier: we need hsm_secret to expose that "calculate seed from mnemonic and passphrase" function (or opencode it with libwally?)

rustyrussell · 2025-07-08T01:50:39Z

tools/hsmtool.c

-	u8 bip32_seed[BIP39_SEED_LEN_512];
-	size_t bip32_seed_len;
-
-	if (bip39_mnemonic_to_seed(mnemonic, passphrase, bip32_seed, sizeof(bip32_seed), &bip32_seed_len) != WALLY_OK)
-		errx(ERROR_LIBWALLY, "Unable to derive BIP32 seed from BIP39 mnemonic");


We still need this for below.,

sangbida added 9 commits July 1, 2025 10:00

Add is_mnemonic_secret

f0c1224

We want to validate if our secret is a mnemonic. In hsm_secret_is_encrypted we're checking if the secret is encrypted, we now have to add an additional check here to see if the secret is a mnemonic.

Write the mnemonic instead of the 32 byte seed in hsm_secret

922c1d5

Updates generate_hsm() to write the 12-word BIP39 mnemonic to the hsm_secret file, instead of a 32-byte raw seed.

An attempt was made at writing the new hsmtool

94d8e7b

I'm just committing this now cause it feels like I'm tired and going to write stupid code soon

Fix up hsmtool to support the new hsm_secret API

85fc8c6

Add in function to read a mnemonic from stdin

2e887e1

Some of the tests work!

1ca8bfa

rustyrussell requested changes Jul 8, 2025

View reviewed changes

TRY to migrate hsmd to use mnemonics

a20abff

sangbida force-pushed the bip39-hsm branch from a6d70de to a20abff Compare July 13, 2025 02:29

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add support for mnemonics in hsm_secret #8400

Add support for mnemonics in hsm_secret #8400

Uh oh!

sangbida commented Jul 8, 2025

Uh oh!

rustyrussell Jul 8, 2025

Uh oh!

rustyrussell Jul 8, 2025

Uh oh!

rustyrussell Jul 8, 2025

Uh oh!

rustyrussell Jul 8, 2025

Uh oh!

rustyrussell Jul 8, 2025

Uh oh!

rustyrussell Jul 8, 2025

Uh oh!

rustyrussell Jul 8, 2025

Uh oh!

rustyrussell Jul 8, 2025

Uh oh!

rustyrussell Jul 8, 2025

Uh oh!

rustyrussell Jul 8, 2025

Uh oh!

Uh oh!

Add support for mnemonics in hsm_secret #8400

Are you sure you want to change the base?

Add support for mnemonics in hsm_secret #8400

Uh oh!

Conversation

sangbida commented Jul 8, 2025

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!