api: add a custom BIP85 derivation for Lightning hot wallets

For the generation of a mnemonic for Breez-SDK Lightning hot wallets
in the BitBoxApp.

Using the regular BIP85-BIP39 path like `m/83696968'/39'/0'/12'/0'`
for this is problematic as a user might use the same mnemonics for
something else, e.g. another cold storage wallet. In such a case, the
derived mnemonic of the user would become hot without the user
realizing it.

For the purpose of generating entropy for a lightning hot wallet using
BIP85, we should instead use a different application number dedicated
to this.

We are going with number `19534'`, which is unlikely to interfere with
other uses. It's hex representation `0x4c4e` spells `LN` in ASCII.

The BIP85 derivation would then be
`m/83696968'/{app_no}/{language}'/{words}'/` as in BIP85-BIP39, but
use `19534'` for the `app_no` instead of `39'`, so:

    m/83696968'/19534'/0'/12'/0'

We restrict to only 16 byte derived entropy (equivalent of 12 words
mnemonics) for LN hot wallet mnemonics for simplicity and easier
recovery for users.

The index represents the account number - for now we only allow
`0` (the first account), and can extend to multiple if there is ever a
need.

Author: benma

CHANGELOG.md

@@ -9,6 +9,10 @@ customers cannot upgrade their bootloader, its changes are recorded separately.
 ### [Unreleased]
 - Add support for deriving BIP-39 mnemonics according to BIP-85
 
+### 9.17.0
+- Add support for deriving mnemonics for Lightning hot wallets according to BIP-85 (using a custom
+  BIP-85 application number)
+
 ### 9.16.0
 - Disable screensaver when displaying a receive address, confirming a transaction, and other interactive actions
 - Add Sepolia testnet for Ethereum

messages/keystore.proto

@@ -15,13 +15,19 @@ message ElectrumEncryptionKeyResponse {
 }
 
 message BIP85Request {
+  message AppLn {
+    uint32 account_number = 1;
+  }
+
   oneof app {
     google.protobuf.Empty bip39 = 1;
+    AppLn ln = 2;
   }
 }
 
 message BIP85Response {
   oneof app {
     google.protobuf.Empty bip39 = 1;
+    bytes ln = 2;
   }
 }

py/bitbox02/bitbox02/bitbox02/bitbox02.py

@@ -690,7 +690,28 @@ def bip85_bip39(self) -> None:
                 bip39=google.protobuf.empty_pb2.Empty(),
             )
         )
-        self._msg_query(request)
+        response = self._msg_query(request, expected_response="bip85").bip85
+        assert response.WhichOneof("app") == "bip39"
+
+    def bip85_ln(self) -> bytes:
+        """
+        Generates and returns a mnemonic for a hot Lightning wallet from the device using BIP-85.
+        """
+        self._require_atleast(semver.VersionInfo(9, 17, 0))
+
+        # Only account_number=0 is allowed for now.
+        account_number = 0
+
+        # pylint: disable=no-member
+        request = hww.Request()
+        request.bip85.CopyFrom(
+            keystore.BIP85Request(
+                ln=keystore.BIP85Request.AppLn(account_number=account_number),
+            )
+        )
+        response = self._msg_query(request, expected_response="bip85").bip85
+        assert response.WhichOneof("app") == "ln"
+        return response.ln
 
     def enable_mnemonic_passphrase(self) -> None:
         """

py/bitbox02/bitbox02/communication/generated/keystore_pb2.py

@@ -37,28 +37,45 @@ global___ElectrumEncryptionKeyResponse = ElectrumEncryptionKeyResponse
 
 class BIP85Request(google.protobuf.message.Message):
     DESCRIPTOR: google.protobuf.descriptor.Descriptor
+    class AppLn(google.protobuf.message.Message):
+        DESCRIPTOR: google.protobuf.descriptor.Descriptor
+        ACCOUNT_NUMBER_FIELD_NUMBER: builtins.int
+        account_number: builtins.int
+        def __init__(self,
+            *,
+            account_number: builtins.int = ...,
+            ) -> None: ...
+        def ClearField(self, field_name: typing_extensions.Literal["account_number",b"account_number"]) -> None: ...
+
     BIP39_FIELD_NUMBER: builtins.int
+    LN_FIELD_NUMBER: builtins.int
     @property
     def bip39(self) -> google.protobuf.empty_pb2.Empty: ...
+    @property
+    def ln(self) -> global___BIP85Request.AppLn: ...
     def __init__(self,
         *,
         bip39: typing.Optional[google.protobuf.empty_pb2.Empty] = ...,
+        ln: typing.Optional[global___BIP85Request.AppLn] = ...,
         ) -> None: ...
-    def HasField(self, field_name: typing_extensions.Literal["app",b"app","bip39",b"bip39"]) -> builtins.bool: ...
-    def ClearField(self, field_name: typing_extensions.Literal["app",b"app","bip39",b"bip39"]) -> None: ...
-    def WhichOneof(self, oneof_group: typing_extensions.Literal["app",b"app"]) -> typing.Optional[typing_extensions.Literal["bip39"]]: ...
+    def HasField(self, field_name: typing_extensions.Literal["app",b"app","bip39",b"bip39","ln",b"ln"]) -> builtins.bool: ...
+    def ClearField(self, field_name: typing_extensions.Literal["app",b"app","bip39",b"bip39","ln",b"ln"]) -> None: ...
+    def WhichOneof(self, oneof_group: typing_extensions.Literal["app",b"app"]) -> typing.Optional[typing_extensions.Literal["bip39","ln"]]: ...
 global___BIP85Request = BIP85Request
 
 class BIP85Response(google.protobuf.message.Message):
     DESCRIPTOR: google.protobuf.descriptor.Descriptor
     BIP39_FIELD_NUMBER: builtins.int
+    LN_FIELD_NUMBER: builtins.int
     @property
     def bip39(self) -> google.protobuf.empty_pb2.Empty: ...
+    ln: builtins.bytes
     def __init__(self,
         *,
         bip39: typing.Optional[google.protobuf.empty_pb2.Empty] = ...,
+        ln: builtins.bytes = ...,
         ) -> None: ...
-    def HasField(self, field_name: typing_extensions.Literal["app",b"app","bip39",b"bip39"]) -> builtins.bool: ...
-    def ClearField(self, field_name: typing_extensions.Literal["app",b"app","bip39",b"bip39"]) -> None: ...
-    def WhichOneof(self, oneof_group: typing_extensions.Literal["app",b"app"]) -> typing.Optional[typing_extensions.Literal["bip39"]]: ...
+    def HasField(self, field_name: typing_extensions.Literal["app",b"app","bip39",b"bip39","ln",b"ln"]) -> builtins.bool: ...
+    def ClearField(self, field_name: typing_extensions.Literal["app",b"app","bip39",b"bip39","ln",b"ln"]) -> None: ...
+    def WhichOneof(self, oneof_group: typing_extensions.Literal["app",b"app"]) -> typing.Optional[typing_extensions.Literal["bip39","ln"]]: ...
 global___BIP85Response = BIP85Response

py/bitbox02/bitbox02/communication/generated/keystore_pb2.pyi

@@ -341,7 +341,17 @@ def _get_electrum_encryption_key(self) -> None:
         )
 
     def _bip85_bip39(self) -> None:
-        self._device.bip85_bip39()
+        try:
+            self._device.bip85_bip39()
+        except UserAbortException:
+            print("Aborted by user")
+
+    def _bip85_ln(self) -> None:
+        try:
+            entropy = self._device.bip85_ln()
+            print("Derived entropy for a Breez Lightning wallet:", entropy.hex())
+        except UserAbortException:
+            print("Aborted by user")
 
     def _btc_address(self) -> None:
         def address(display: bool) -> str:
@@ -1392,6 +1402,7 @@ def _menu_init(self) -> None:
             ("Cardano", self._cardano),
             ("Show Electrum wallet encryption key", self._get_electrum_encryption_key),
             ("BIP85 - BIP39", self._bip85_bip39),
+            ("BIP85 - LN", self._bip85_ln),
             ("Reset Device", self._reset_device),
         )
         choice = ask_user(choices)

py/send_message.py

@@ -330,6 +330,7 @@ add_custom_target(rust-bindgen
     --allowlist-function keystore_get_bip39_word
     --allowlist-function keystore_get_ed25519_seed
     --allowlist-function keystore_bip85_bip39
+    --allowlist-function keystore_bip85_ln
     --allowlist-function keystore_secp256k1_compressed_to_uncompressed
     --allowlist-function keystore_secp256k1_nonce_commit
     --allowlist-function keystore_secp256k1_sign

src/CMakeLists.txt

@@ -864,6 +864,30 @@ bool keystore_bip85_bip39(
     return snprintf_result >= 0 && snprintf_result < (int)mnemonic_out_size;
 }
 
+bool keystore_bip85_ln(uint32_t index, uint8_t* entropy_out)
+{
+    if (index >= BIP32_INITIAL_HARDENED_CHILD) {
+        return false;
+    }
+
+    const uint32_t keypath[] = {
+        83696968 + BIP32_INITIAL_HARDENED_CHILD,
+        19534 + BIP32_INITIAL_HARDENED_CHILD,
+        0 + BIP32_INITIAL_HARDENED_CHILD,
+        12 + BIP32_INITIAL_HARDENED_CHILD,
+        index + BIP32_INITIAL_HARDENED_CHILD,
+    };
+
+    uint8_t entropy[64] = {0};
+    UTIL_CLEANUP_64(entropy);
+    if (!_bip85_entropy(keypath, sizeof(keypath) / sizeof(uint32_t), entropy)) {
+        return false;
+    }
+
+    memcpy(entropy_out, entropy, 16);
+    return true;
+}
+
 USE_RESULT bool keystore_encode_xpub_at_keypath(
     const uint32_t* keypath,
     size_t keypath_len,

src/keystore.c

@@ -253,6 +253,16 @@ USE_RESULT bool keystore_bip85_bip39(
     char* mnemonic_out,
     size_t mnemonic_out_size);
 
+/**
+ * Computes a 16 byte deterministic seed specifically for Lightning hot wallets according to BIP-85.
+ * It is the same as BIP-85 with app number 39', but instead using app number 19534' (= 0x4c4e =
+ * 'LN'). https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki#bip39
+ * Restricted to 16 byte output entropy.
+ * @param[in] index must be smaller than `BIP32_INITIAL_HARDENED_CHILD`.
+ * @param[out] entropy_out resulting entropy, must be at least 16 bytes in size.
+ */
+USE_RESULT bool keystore_bip85_ln(uint32_t index, uint8_t* entropy_out);
+
 /**
  * Encode an xpub at the given `keypath` as 78 bytes according to BIP32. The version bytes are
  * the ones corresponding to `xpub`, i.e. 0x0488B21E.

src/keystore.h

@@ -107,7 +107,7 @@ app-cardano = [
   "ed25519"
 ]
 
-app-bip85 = []
+app-bip85-bip39 = []
 
 testing = [
   # enable these deps