diff --git a/.github/workflows/type-check.yml b/.github/workflows/type-check.yml index 09a04c08c..401ab8e27 100644 --- a/.github/workflows/type-check.yml +++ b/.github/workflows/type-check.yml @@ -32,6 +32,7 @@ jobs: hwilib/devices/__init__.py hwilib/devices/keepkey.py hwilib/devices/ledger.py + hwilib/devices/ledger_registration.py hwilib/devices/trezor.py hwilib/errors.py hwilib/_script.py @@ -40,4 +41,5 @@ jobs: hwilib/hwwclient.py hwilib/__init__.py hwilib/key.py + hwilib/policy.py hwilib/udevinstaller.py diff --git a/hwilib/_cli.py b/hwilib/_cli.py index e0afa7dd2..040de08cc 100644 --- a/hwilib/_cli.py +++ b/hwilib/_cli.py @@ -12,6 +12,7 @@ getdescriptors, prompt_pin, toggle_passphrase, + register, restore_device, send_pin, setup_device, @@ -24,6 +25,7 @@ AddressType, Chain, ) +from .policy import BIP388Policy from .errors import ( handle_errors, DEVICE_CONN_ERROR, @@ -59,6 +61,10 @@ def backup_device_handler(args: argparse.Namespace, client: HardwareWalletClient def displayaddress_handler(args: argparse.Namespace, client: HardwareWalletClient) -> Dict[str, str]: return displayaddress(client, desc=args.desc, path=args.path, addr_type=args.addr_type) +def register_handler(args: argparse.Namespace, client: HardwareWalletClient) -> Dict[str, Optional[str]]: + policy = BIP388Policy.from_descriptor(name=args.name, descriptor=args.desc) + return register(client, bip388_policy=policy) + def enumerate_handler(args: argparse.Namespace) -> List[Dict[str, Any]]: return enumerate(password=args.password, expert=args.expert, chain=args.chain, allow_emulators=args.allow_emulators) @@ -197,6 +203,11 @@ def get_parser() -> HWIArgumentParser: displayaddr_parser.add_argument("--addr-type", help="The address type to display", type=AddressType.argparse, choices=list(AddressType), default=AddressType.WIT) # type: ignore displayaddr_parser.set_defaults(func=displayaddress_handler) + register_parser = subparsers.add_parser('register', help='Register a BIP388 wallet policy') + register_parser.add_argument('--name', help='Name for the policy', required=True) + register_parser.add_argument('--desc', help='Combined multipath output descriptor', required=True) + register_parser.set_defaults(func=register_handler) + setupdev_parser = subparsers.add_parser('setup', help='Setup a device. Passphrase protection uses the password given by -p. Requires interactive mode') setupdev_parser.add_argument('--label', '-l', help='The name to give to the device', default='') setupdev_parser.add_argument('--backup_passphrase', '-b', help='The passphrase to use for the backup, if applicable', default='') diff --git a/hwilib/commands.py b/hwilib/commands.py index 6d192aa5f..7f88065e2 100644 --- a/hwilib/commands.py +++ b/hwilib/commands.py @@ -55,6 +55,7 @@ Chain, ) from .hwwclient import HardwareWalletClient +from .policy import BIP388Policy from .psbt import PSBT from itertools import count @@ -494,6 +495,16 @@ def displayaddress( return {"address": client.display_singlesig_address(pubkey.get_full_derivation_path(0), addr_type)} raise BadArgumentError("Missing both path and descriptor") +def register( + client: HardwareWalletClient, + bip388_policy: BIP388Policy, +) -> Dict[str, Optional[str]]: + """Register a BIP388 policy on the device.""" + + if bip388_policy.registration is not None: + raise BadArgumentError("A policy being registered cannot already have a registration") + return {"registration": client.register_bip388_policy(bip388_policy)} + def setup_device(client: HardwareWalletClient, label: str = "", backup_passphrase: str = "") -> Dict[str, bool]: """ Setup a device that has not yet been initialized. diff --git a/hwilib/common.py b/hwilib/common.py index 0c5c00606..5dcc533e9 100644 --- a/hwilib/common.py +++ b/hwilib/common.py @@ -9,7 +9,6 @@ from typing import Union - class Chain(Enum): """ The blockchain network to use @@ -56,7 +55,6 @@ def argparse(s: str) -> Union['AddressType', str]: except KeyError: return s - def sha256(s: bytes) -> bytes: """ Perform a single SHA256 hash. diff --git a/hwilib/devices/bitbox02.py b/hwilib/devices/bitbox02.py index cc6b783b3..288f83d44 100644 --- a/hwilib/devices/bitbox02.py +++ b/hwilib/devices/bitbox02.py @@ -23,7 +23,7 @@ from functools import wraps from .._base58 import decode_check, encode_check -from ..descriptor import MultisigDescriptor +from ..descriptor import MultisigDescriptor, PubkeyProvider from ..hwwclient import HardwareWalletClient from ..key import ExtendedKey from .._script import ( @@ -59,6 +59,7 @@ AddressType, Chain, ) +from ..policy import BIP388Policy import hid @@ -438,6 +439,63 @@ def _maybe_register_script_config( xpub_type=bitbox02.btc.BTCRegisterScriptConfigRequest.AUTO_XPUB_TPUB, ) + def _bip388_script_config( + self, + bip388_policy: BIP388Policy, + ) -> Tuple[bitbox02.btc.BTCScriptConfig, Sequence[int]]: + device_fingerprint = self.get_master_fingerprint() + our_keypath: Optional[Sequence[int]] = None + keys = [] + + for key_info in bip388_policy.keys_info: + pubkey = PubkeyProvider.parse(key_info) + if pubkey.extkey is None or pubkey.extkey.is_private or pubkey.deriv_path is not None: + raise BadArgumentError("Invalid BIP388 key information") + + origin = pubkey.origin + keys.append( + bitbox02.common.KeyOriginInfo( + root_fingerprint=b"" if origin is None else origin.fingerprint, + keypath=[] if origin is None else origin.path, + xpub=util.parse_xpub(pubkey.extkey.to_string()), + ) + ) + + if origin is not None and origin.fingerprint == device_fingerprint: + device_xpub = decode_check(self._get_xpub(origin.path)) + if _xpubs_equal_ignoring_version(device_xpub, pubkey.extkey.serialize()): + if our_keypath is not None: + raise BadArgumentError("This BitBox02 occurs more than once in the policy") + our_keypath = origin.path + + if our_keypath is None: + raise BadArgumentError("This BitBox02 is not one of the policy keys") + + return ( + bitbox02.btc.BTCScriptConfig( + policy=bitbox02.btc.BTCScriptConfig.Policy( + policy=bip388_policy.descriptor_template, + keys=keys, + ) + ), + our_keypath, + ) + + @bitbox02_exception + def register_bip388_policy( + self, + bip388_policy: BIP388Policy, + ) -> Optional[str]: + script_config, keypath = self._bip388_script_config(bip388_policy) + self.init().btc_register_script_config( + coin=self._get_coin(), + script_config=script_config, + keypath=keypath, + name=bip388_policy.name, + xpub_type=bitbox02.btc.BTCRegisterScriptConfigRequest.AUTO_XPUB_TPUB, + ) + return None + def _multisig_scriptconfig( self, threshold: int, diff --git a/hwilib/devices/ledger.py b/hwilib/devices/ledger.py index fdb6b6d82..6239a4e36 100644 --- a/hwilib/devices/ledger.py +++ b/hwilib/devices/ledger.py @@ -33,6 +33,8 @@ AddressType, Chain, ) +from ..policy import BIP388Policy +from .ledger_registration import encode_policy_registration from .ledger_bitcoin.client import ( createClient, NewClient, @@ -482,6 +484,24 @@ def format_key_info(pubkey: PubkeyProvider) -> str: return self.client.get_wallet_address(multisig_wallet, registered_hmac, change, address_index, True) + @ledger_exception + def register_bip388_policy( + self, + bip388_policy: BIP388Policy, + ) -> Optional[str]: + if isinstance(self.client, LegacyClient): + raise BadArgumentError( + "Registering a BIP388 policy is not supported by this version of the Bitcoin App" + ) + + wallet_policy = WalletPolicy( + name=bip388_policy.name, + descriptor_template=bip388_policy.descriptor_template, + keys_info=bip388_policy.keys_info, + ) + _, registration = self.client.register_wallet(wallet_policy) + return encode_policy_registration(registration, bip388_policy.name) + def setup_device(self, label: str = "", passphrase: str = "") -> bool: """ Ledgers do not support setup via software. diff --git a/hwilib/devices/ledger_registration.py b/hwilib/devices/ledger_registration.py new file mode 100644 index 000000000..f1ce14053 --- /dev/null +++ b/hwilib/devices/ledger_registration.py @@ -0,0 +1,51 @@ +"""Encoding helpers for opaque Ledger policy registrations.""" + +from typing import List, Sequence, Tuple + +from ..errors import BadArgumentError + + +def _encode_fields(fields: Sequence[bytes]) -> bytes: + encoded = bytearray() + for field in fields: + if len(field) > 255: + raise BadArgumentError("Ledger policy registration fields cannot exceed 255 bytes") + encoded.append(len(field)) + encoded.extend(field) + return bytes(encoded) + + +def _decode_fields(encoded: bytes) -> List[bytes]: + fields: List[bytes] = [] + offset = 0 + while offset < len(encoded): + field_length = encoded[offset] + offset += 1 + field_end = offset + field_length + if field_end > len(encoded): + raise BadArgumentError("Invalid Ledger policy registration") + fields.append(encoded[offset:field_end]) + offset = field_end + return fields + + +def encode_policy_registration(device_registration: bytes, policy_name: str) -> str: + """Encode the device registration and policy name as an opaque hex string.""" + + try: + name = policy_name.encode("latin-1") + except UnicodeEncodeError as exc: + raise BadArgumentError("Ledger policy names must use Latin-1 characters") from exc + return _encode_fields([device_registration, name]).hex() + + +def decode_policy_registration(registration: str) -> Tuple[bytes, str]: + """Decode the device registration and policy name from an opaque hex string.""" + + try: + fields = _decode_fields(bytes.fromhex(registration)) + except ValueError as exc: + raise BadArgumentError("Invalid Ledger policy registration") from exc + if len(fields) < 2: + raise BadArgumentError("Invalid Ledger policy registration") + return fields[0], fields[1].decode("latin-1") diff --git a/hwilib/hwwclient.py b/hwilib/hwwclient.py index 565afcf44..ae9104dbd 100644 --- a/hwilib/hwwclient.py +++ b/hwilib/hwwclient.py @@ -17,7 +17,11 @@ get_bip44_chain, ) from .psbt import PSBT -from .common import AddressType, Chain +from .common import ( + AddressType, + Chain, +) +from .policy import BIP388Policy class HardwareWalletClient(object): @@ -135,6 +139,16 @@ def display_multisig_address( raise NotImplementedError("The HardwareWalletClient base class " "does not implement this method") + def register_bip388_policy( + self, + bip388_policy: BIP388Policy, + ) -> Optional[str]: + """Register a BIP388 policy and return an opaque registration, if any.""" + + raise NotImplementedError( + "This device does not support BIP388 policy registration or it is not yet implemented" + ) + def wipe_device(self) -> bool: """ Wipe the device. diff --git a/hwilib/policy.py b/hwilib/policy.py new file mode 100644 index 000000000..04c325554 --- /dev/null +++ b/hwilib/policy.py @@ -0,0 +1,201 @@ +"""BIP388 wallet policy helpers.""" + +from dataclasses import dataclass +import re +from typing import Dict, List, Optional, Set, Tuple + +from .descriptor import DescriptorChecksum +from .errors import BadArgumentError +from .key import ExtendedKey, KeyOriginInfo + + +_EXTENDED_KEY_RE = re.compile( + r"(?P\[[^\]]+\])?(?P[1-9A-HJ-NP-Za-km-z]{100,120})" +) +_PLACEHOLDER_RE = re.compile(r"@(0|[1-9][0-9]*)") +_MUSIG_RE = re.compile(r"(? "BIP388Policy": + """Convert a combined multipath output descriptor into a BIP388 policy.""" + + descriptor = _strip_and_check_checksum(descriptor) + if any(char.isspace() for char in descriptor): + raise BadArgumentError("Whitespace is not allowed in a BIP388 descriptor") + _check_balanced(descriptor) + + keys_info: List[str] = [] + key_indexes: Dict[str, int] = {} + xpub_origins: Dict[str, str] = {} + template_parts: List[str] = [] + last_end = 0 + + for match in _EXTENDED_KEY_RE.finditer(descriptor): + key_str = match.group("key") + try: + extkey = ExtendedKey.deserialize(key_str) + except Exception as exc: + raise BadArgumentError(f"Invalid extended key in descriptor: {key_str}") from exc + if extkey.is_private: + raise BadArgumentError("BIP388 key information must use extended public keys") + + origin_str = "" + raw_origin = match.group("origin") + if raw_origin is not None: + try: + origin = KeyOriginInfo.from_string(raw_origin[1:-1]) + except Exception as exc: + raise BadArgumentError(f"Invalid key origin: {raw_origin}") from exc + normalized_origin = origin.to_string(hardened_char="'") + origin_str = f"[{normalized_origin}]" + elif match.start("key") > 0 and descriptor[match.start("key") - 1] == "]": + raise BadArgumentError("Invalid key origin in descriptor") + + canonical_xpub = extkey.to_string() + key_info = origin_str + canonical_xpub + previous_key_info = xpub_origins.setdefault(canonical_xpub, key_info) + if previous_key_info != key_info: + raise BadArgumentError("The same extended public key has conflicting origins") + + if key_info not in key_indexes: + key_indexes[key_info] = len(keys_info) + keys_info.append(key_info) + + template_parts.append(descriptor[last_end:match.start()]) + template_parts.append(f"@{key_indexes[key_info]}") + last_end = match.end() + + if not keys_info: + raise BadArgumentError("Descriptor does not contain any extended public keys") + + template_parts.append(descriptor[last_end:]) + descriptor_template = "".join(template_parts).replace("/<0;1>/*", "/**") + _validate_template(descriptor_template, len(keys_info)) + + return cls( + name=name, + descriptor_template=descriptor_template, + keys_info=keys_info, + registration=registration, + ) + + +def _strip_and_check_checksum(descriptor: str) -> str: + if descriptor.count("#") > 1: + raise BadArgumentError("Descriptor has more than one checksum separator") + if "#" not in descriptor: + return descriptor + + descriptor, checksum = descriptor.split("#", 1) + expected = DescriptorChecksum(descriptor) + if checksum != expected: + raise BadArgumentError( + f"The descriptor checksum does not match: got {checksum}, expected {expected}" + ) + return descriptor + + +def _check_balanced(descriptor: str) -> None: + pairs = {")": "(", "}": "{"} + stack: List[str] = [] + for char in descriptor: + if char in "({": + stack.append(char) + elif char in pairs: + if not stack or stack.pop() != pairs[char]: + raise BadArgumentError("Descriptor has unbalanced delimiters") + if stack: + raise BadArgumentError("Descriptor has unbalanced delimiters") + + +def _find_closing_parenthesis(template: str, open_pos: int) -> int: + depth = 1 + for pos in range(open_pos + 1, len(template)): + if template[pos] == "(": + depth += 1 + elif template[pos] == ")": + depth -= 1 + if depth == 0: + return pos + raise BadArgumentError("Descriptor has an unterminated musig expression") + + +def _parse_derivation(template: str, pos: int) -> Tuple[int, Set[int]]: + if template.startswith("/**", pos): + return pos + 3, {0, 1} + + match = re.match(r"/<(0|[1-9][0-9]*);(0|[1-9][0-9]*)>/\*", template[pos:]) + if match is None: + raise BadArgumentError( + "Every BIP388 key placeholder must use /** or //*" + ) + first = int(match.group(1)) + second = int(match.group(2)) + if first == second or first >= (1 << 31) or second >= (1 << 31): + raise BadArgumentError("Invalid BIP388 receive/change derivation") + return pos + match.end(), {first, second} + + +def _validate_template(template: str, key_count: int) -> None: + if "[" in template or "]" in template: + raise BadArgumentError("Descriptor contains key origin data without an extended key") + if _EXTENDED_KEY_RE.search(template) is not None: + raise BadArgumentError("A BIP388 descriptor template may only contain key placeholders") + + musig_placeholder_spans: List[Tuple[int, int]] = [] + usages: Dict[Tuple[str, Tuple[int, ...]], List[Set[int]]] = {} + for match in _MUSIG_RE.finditer(template): + close_pos = _find_closing_parenthesis(template, match.end() - 1) + args = template[match.end():close_pos] + if re.fullmatch(r"@[0-9]+(?:,@[0-9]+)+", args) is None: + raise BadArgumentError("A BIP388 musig expression must contain only key placeholders") + indexes = tuple(int(value) for value in re.findall(r"@([0-9]+)", args)) + if len(set(indexes)) != len(indexes): + raise BadArgumentError("A BIP388 musig expression cannot repeat a key") + _, branches = _parse_derivation(template, close_pos + 1) + identity = ("musig", tuple(sorted(indexes))) + usages.setdefault(identity, []).append(branches) + musig_placeholder_spans.append((match.end(), close_pos)) + + def in_musig(pos: int) -> bool: + return any(start <= pos < end for start, end in musig_placeholder_spans) + + seen: Set[int] = set() + next_index = 0 + for match in _PLACEHOLDER_RE.finditer(template): + index = int(match.group(1)) + if index >= key_count: + raise BadArgumentError(f"BIP388 placeholder @{index} has no corresponding key") + if index not in seen: + if index != next_index: + raise BadArgumentError("BIP388 keys are not ordered by first placeholder use") + seen.add(index) + next_index += 1 + if not in_musig(match.start()): + _, branches = _parse_derivation(template, match.end()) + usages.setdefault(("key", (index,)), []).append(branches) + + if seen != set(range(key_count)): + raise BadArgumentError("Not every BIP388 key is used by the descriptor template") + + for branch_sets in usages.values(): + used: Set[int] = set() + for branches in branch_sets: + if used.intersection(branches): + raise BadArgumentError("A BIP388 key is reused in overlapping derivation branches") + used.update(branches) diff --git a/test/data/speculos-automation.json b/test/data/speculos-automation.json index 31f69f72a..80af21109 100644 --- a/test/data/speculos-automation.json +++ b/test/data/speculos-automation.json @@ -28,7 +28,7 @@ ] }, { - "regexp": "^(Address|Review|Amount|Fee|Confirm|The derivation|Derivation path|Reject if|The change path|Change path|Register wallet|Policy map|Key|Path|Public key|Spend from|Wallet name|Wallet policy|Descriptor template|Verify Bitcoin|Output|Warning).*", + "regexp": "^(Address|Review|Account name|Amount|Fee|Confirm|The derivation|Derivation path|Reject if|The change path|Change path|Register wallet|Policy map|Key|Our key|Path|Public key|Spend from|Wallet name|Wallet policy|Descriptor template|Verify Bitcoin|Output|Warning).*", "actions": [ [ "button", 2, true ], [ "button", 2, false ] diff --git a/test/run_tests.py b/test/run_tests.py index 80300db1f..4d190c321 100755 --- a/test/run_tests.py +++ b/test/run_tests.py @@ -13,6 +13,8 @@ from test_psbt import TestPSBT from test_trezor import trezor_test_suite from test_ledger import ledger_test_suite +from test_policy import TestBIP388Policy +from test_ledger_registration import TestLedgerRegistration from test_digitalbitbox import digitalbitbox_test_suite from test_keepkey import keepkey_test_suite from test_jade import jade_test_suite @@ -84,6 +86,8 @@ suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestPSBT)) suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestBase58)) suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestBIP32)) + suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestBIP388Policy)) + suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestLedgerRegistration)) if sys.platform.startswith("linux"): suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestUdevRulesInstaller)) success = unittest.TextTestRunner(stream=sys.stdout, verbosity=2).run(suite).wasSuccessful() diff --git a/test/test_bitbox02.py b/test/test_bitbox02.py index a9d64b999..ef62fa377 100644 --- a/test/test_bitbox02.py +++ b/test/test_bitbox02.py @@ -18,6 +18,7 @@ TestDisplayAddress, TestGetKeypool, TestGetDescriptors, + TestPolicyRegistration, TestSignTx, ) @@ -124,6 +125,7 @@ def bitbox02_test_suite(simulator, bitcoind, interface): suite.addTest(DeviceTestCase.parameterize(TestGetDescriptors, bitcoind, emulator=dev_emulator, interface=interface)) suite.addTest(DeviceTestCase.parameterize(TestSignTx, bitcoind, emulator=dev_emulator, interface=interface, signtx_cases=signtx_cases)) suite.addTest(DeviceTestCase.parameterize(TestDisplayAddress, bitcoind, emulator=dev_emulator, interface=interface)) + suite.addTest(DeviceTestCase.parameterize(TestPolicyRegistration, bitcoind, emulator=dev_emulator, interface=interface, returns_registration=False)) # TestSignMessage is removed, since its only testcase is for legacy p2pkh, which is not supported by BitBox02 # suite.addTest(DeviceTestCase.parameterize(TestSignMessage, bitcoind, emulator=dev_emulator, interface=interface)) suite.addTest(DeviceTestCase.parameterize(TestBitbox02GetXpub, bitcoind, emulator=dev_emulator, interface=interface)) diff --git a/test/test_device.py b/test/test_device.py index abc6ef1ae..62d07ff17 100644 --- a/test/test_device.py +++ b/test/test_device.py @@ -261,6 +261,33 @@ def test_type_only_autodetect(self): self.assertEqual(gmxp_res['error'], 'Unknown device type specified') self.assertEqual(gmxp_res['code'], -4) +class TestPolicyRegistration(DeviceTestCase): + def __init__(self, *args, returns_registration, **kwargs): + super().__init__(*args, **kwargs) + self.returns_registration = returns_registration + + def assert_registration(self, registration): + self.assertRegex(registration, r"^(?:[0-9a-f]{2})+$") + + def test_register_policy(self): + account_path = "m/48h/1h/0h/2h" + account_xpub = self.do_command(self.dev_args + ["getxpub", account_path])["xpub"] + descriptor = ( + f"wsh(pk([{self.emulator.fingerprint}/48h/1h/0h/2h]" + f"{account_xpub}" + "/<0;1>/*))" + ) + result = self.do_command( + self.dev_args + ["register", "--name", "HWI policy", "--desc", descriptor] + ) + + self.assertNotIn("error", result) + self.assertIn("registration", result) + if self.returns_registration: + self.assert_registration(result["registration"]) + else: + self.assertIsNone(result["registration"]) + class TestGetKeypool(DeviceTestCase): def setUp(self): super().setUp() diff --git a/test/test_ledger.py b/test/test_ledger.py index 6ab162e74..e48028897 100755 --- a/test/test_ledger.py +++ b/test/test_ledger.py @@ -17,11 +17,13 @@ TestDisplayAddress, TestGetKeypool, TestGetDescriptors, + TestPolicyRegistration, TestSignMessage, TestSignTx, ) from hwilib._cli import process_commands +from hwilib.devices.ledger_registration import decode_policy_registration class LedgerEmulator(DeviceEmulator): def __init__(self, path, legacy=False): @@ -164,6 +166,13 @@ def test_getxpub(self): self.assertEqual(result['chaincode'], "1067f2a53975faf7ac265be505c1c50ef80a0dcbe1f53f50497c5618e8888dbd") self.assertEqual(result['pubkey'], "035879ca173a9c1b3f300ec587fb4cc6d54d618e30584e425c1b53b98828708f1d") +class TestLedgerPolicyRegistration(TestPolicyRegistration): + def assert_registration(self, registration): + super().assert_registration(registration) + device_registration, policy_name = decode_policy_registration(registration) + self.assertNotEqual(device_registration, b"") + self.assertEqual(policy_name, "HWI policy") + def ledger_test_suite(emulator, bitcoind, interface, legacy=False): dev_emulator = LedgerEmulator(emulator, legacy) @@ -186,6 +195,8 @@ def ledger_test_suite(emulator, bitcoind, interface, legacy=False): suite.addTest(DeviceTestCase.parameterize(TestGetDescriptors, bitcoind, emulator=dev_emulator, interface=interface)) suite.addTest(DeviceTestCase.parameterize(TestGetKeypool, bitcoind, emulator=dev_emulator, interface=interface)) suite.addTest(DeviceTestCase.parameterize(TestDisplayAddress, bitcoind, emulator=dev_emulator, interface=interface)) + if not legacy: + suite.addTest(DeviceTestCase.parameterize(TestLedgerPolicyRegistration, bitcoind, emulator=dev_emulator, interface=interface, returns_registration=True)) suite.addTest(DeviceTestCase.parameterize(TestSignMessage, bitcoind, emulator=dev_emulator, interface=interface)) suite.addTest(DeviceTestCase.parameterize(TestSignTx, bitcoind, emulator=dev_emulator, interface=interface, signtx_cases=signtx_cases)) diff --git a/test/test_ledger_registration.py b/test/test_ledger_registration.py new file mode 100644 index 000000000..e9912c407 --- /dev/null +++ b/test/test_ledger_registration.py @@ -0,0 +1,41 @@ +#!/usr/bin/env python3 + +import unittest + +from hwilib.devices.ledger_registration import ( + decode_policy_registration, + encode_policy_registration, +) +from hwilib.errors import BadArgumentError + + +class TestLedgerRegistration(unittest.TestCase): + def test_round_trip(self) -> None: + registration = encode_policy_registration(b"\xaa\xbb\xcc", "Møøse") + + self.assertEqual(registration, "03aabbcc054df8f87365") + self.assertEqual( + decode_policy_registration(registration), + (b"\xaa\xbb\xcc", "Møøse"), + ) + + def test_ignores_additional_fields(self) -> None: + registration = encode_policy_registration(b"\xaa", "name") + "01ff" + + self.assertEqual(decode_policy_registration(registration), (b"\xaa", "name")) + + def test_rejects_invalid_encoding(self) -> None: + for registration in ["", "zz", "01", "02aa", "01aa"]: + with self.subTest(registration=registration): + with self.assertRaises(BadArgumentError): + decode_policy_registration(registration) + + def test_rejects_long_fields(self) -> None: + with self.assertRaises(BadArgumentError): + encode_policy_registration(b"\x00" * 256, "name") + with self.assertRaises(BadArgumentError): + encode_policy_registration(b"\x00", "a" * 256) + + +if __name__ == "__main__": + unittest.main() diff --git a/test/test_policy.py b/test/test_policy.py new file mode 100644 index 000000000..63b750c0d --- /dev/null +++ b/test/test_policy.py @@ -0,0 +1,190 @@ +#!/usr/bin/env python3 + +import unittest + +from hwilib.descriptor import AddChecksum +from hwilib.errors import BadArgumentError +from hwilib.policy import BIP388Policy, _validate_template + + +XPUB_A = "tpubDCwYjpDhUdPGP5rS3wgNg13mTrrjBuG8V9VpWbyptX6TRPbNoZVXsoVUSkCjmQ8jJycjuDKBb9eataSymXakTTaGifxR6kmVsfFehH1ZgJT" +XPUB_B = "tpubDDoFYQF4zAhrW8LRtCxePR8bJsAh5SXU6PwPNi2oRfeh67qhmxZawJ4m3V76P8AYSEueKmwvNyiSPAGYtynGfzJNvTHyzj2FJTbp729jmYM" + +# Canonical test vectors from BIP388 version 1.1.0: +# https://github.com/bitcoin/bips/blob/master/bip-0388.mediawiki#test-vectors +BIP44_KEY = "[6738736c/44'/0'/0']xpub6Br37sWxruYfT8ASpCjVHKGwgdnYFEn98DwiN76i2oyY6fgH1LAPmmDcF46xjxJr22gw4jmVjTE2E3URMnRPEPYyo1zoPSUba563ESMXCeb" +BIP49_KEY = "[6738736c/49'/0'/1']xpub6Bex1CHWGXNNwGVKHLqNC7kcV348FxkCxpZXyCWp1k27kin8sRPayjZUKDjyQeZzGUdyeAj2emoW5zStFFUAHRgd5w8iVVbLgZ7PmjAKAm9" +BIP84_KEY = "[6738736c/84'/0'/2']xpub6CRQzb8u9dmMcq5XAwwRn9gcoYCjndJkhKgD11WKzbVGd932UmrExWFxCAvRnDN3ez6ZujLmMvmLBaSWdfWVn75L83Qxu1qSX4fJNrJg2Gt" +BIP86_KEY = "[6738736c/86'/0'/0']xpub6CryUDWPS28eR2cDyojB8G354izmx294BdjeSvH469Ty3o2E6Tq5VjBJCn8rWBgesvTJnyXNAJ3QpLFGuNwqFXNt3gn612raffLWfdHNkYL" +BIP48_KEY_0 = "[6738736c/48'/0'/0'/2']xpub6FC1fXFP1GXLX5TKtcjHGT4q89SDRehkQLtbKJ2PzWcvbBHtyDsJPLtpLtkGqYNYZdVVAjRQ5kug9CsapegmmeRutpP7PW4u4wVF9JfkDhw" +BIP48_KEY_1 = "[b2b1f0cf/48'/0'/0'/2']xpub6EWhjpPa6FqrcaPBuGBZRJVjzGJ1ZsMygRF26RwN932Vfkn1gyCiTbECVitBjRCkexEvetLdiqzTcYimmzYxyR1BZ79KNevgt61PDcukmC7" +POLICY_KEY_0 = "[6738736c/48'/0'/0'/100']xpub6FC1fXFP1GXQpyRFfSE1vzzySqs3Vg63bzimYLeqtNUYbzA87kMNTcuy9ubr7MmavGRjW2FRYHP4WGKjwutbf1ghgkUW9H7e3ceaPLRcVwa" +POLICY_KEY_1 = "[b2b1f0cf/44'/0'/0'/100']xpub6EYajCJHe2CK53RLVXrN14uWoEttZgrRSaRztujsXg7yRhGtHmLBt9ot9Pd5ugfwWEu6eWyJYKSshyvZFKDXiNbBcoK42KRZbxwjRQpm5Js" +POLICY_KEY_2 = "[a666a867/44'/0'/0'/100']xpub6Dgsze3ujLi1EiHoCtHFMS9VLS1UheVqxrHGfP7sBJ2DBfChEUHV4MDwmxAXR2ayeytpwm3zJEU3H3pjCR6q6U5sP2p2qzAD71x9z5QShK2" +POLICY_KEY_3 = "[bb641298/44'/0'/0'/100']xpub6Dz8PHFmXkYkykQ83ySkruky567XtJb9N69uXScJZqweYiQn6FyieajdiyjCvWzRZ2GoLHMRE1cwDfuJZ6461YvNRGVBJNnLA35cZrQKSRJ" +TAPROOT_KEY_1 = "xpub6Fc2TRaCWNgfT49nRGG2G78d1dPnjhW66gEXi7oYZML7qEFN8e21b2DLDipTZZnfV6V7ivrMkvh4VbnHY2ChHTS9qM3XVLJiAgcfagYQk6K" +TAPROOT_KEY_2 = "xpub6GxHB9kRdFfTqYka8tgtX9Gh3Td3A9XS8uakUGVcJ9NGZ1uLrGZrRVr67DjpMNCHprZmVmceFTY4X4wWfksy8nVwPiNvzJ5pjLxzPtpnfEM" +TAPROOT_KEY_3 = "xpub6GjFUVVYewLj5no5uoNKCWuyWhQ1rKGvV8DgXBG9Uc6DvAKxt2dhrj1EZFrTNB5qxAoBkVW3wF8uCS3q1ri9fueAa6y7heFTcf27Q4gyeh6" +NON_PLACEHOLDER_XPUB = "xpub6AHA9hZDN11k2ijHMeS5QqHx2KP9aMBRhTDqANMnwVtdyw2TDYRmF8PjpvwUFcL1Et8Hj59S3gTSMcUQ5gAqTz3Wd8EsMTmF3DChhqPQBnU" +RECEIVE_CHANGE_DERIVATION = "/<0;1>/*" +ALTERNATE_DERIVATION = "/<2;3>/*" +OVERLAPPING_DERIVATION = "/<1;2>/*" + + +class TestBIP388Policy(unittest.TestCase): + def test_bip388_valid_policy_vectors(self) -> None: + musig_3_of_3 = f"musig({POLICY_KEY_0},{POLICY_KEY_1},{POLICY_KEY_2})" + musig_0_1 = f"musig({POLICY_KEY_0},{POLICY_KEY_1})" + musig_0_2 = f"musig({POLICY_KEY_0},{POLICY_KEY_2})" + musig_1_2 = f"musig({POLICY_KEY_1},{POLICY_KEY_2})" + + valid_policies = [ + ( + "BIP-44, first account", + "pkh(@0/**)", + [BIP44_KEY], + f"pkh({BIP44_KEY}{RECEIVE_CHANGE_DERIVATION})", + ), + ( + "BIP-49, second account", + "sh(wpkh(@0/**))", + [BIP49_KEY], + f"sh(wpkh({BIP49_KEY}{RECEIVE_CHANGE_DERIVATION}))", + ), + ( + "BIP-84, third account", + "wpkh(@0/**)", + [BIP84_KEY], + f"wpkh({BIP84_KEY}{RECEIVE_CHANGE_DERIVATION})", + ), + ( + "BIP-86, first account", + "tr(@0/**)", + [BIP86_KEY], + f"tr({BIP86_KEY}{RECEIVE_CHANGE_DERIVATION})", + ), + ( + "BIP-48 P2WSH multisig", + "wsh(sortedmulti(2,@0/**,@1/**))", + [BIP48_KEY_0, BIP48_KEY_1], + f"wsh(sortedmulti(2,{BIP48_KEY_0}{RECEIVE_CHANGE_DERIVATION},{BIP48_KEY_1}{RECEIVE_CHANGE_DERIVATION}))", + ), + ( + "Miniscript 3-of-3 degrading to 2-of-3", + "wsh(thresh(3,pk(@0/**),s:pk(@1/**),s:pk(@2/**),sln:older(12960)))", + [POLICY_KEY_0, POLICY_KEY_1, POLICY_KEY_2], + f"wsh(thresh(3,pk({POLICY_KEY_0}{RECEIVE_CHANGE_DERIVATION}),s:pk({POLICY_KEY_1}{RECEIVE_CHANGE_DERIVATION}),s:pk({POLICY_KEY_2}{RECEIVE_CHANGE_DERIVATION}),sln:older(12960)))", + ), + ( + "Miniscript automatic inheritance", + "wsh(or_d(pk(@0/**),and_v(v:multi(2,@1/**,@2/**,@3/**),older(65535))))", + [POLICY_KEY_0, POLICY_KEY_1, POLICY_KEY_2, POLICY_KEY_3], + f"wsh(or_d(pk({POLICY_KEY_0}{RECEIVE_CHANGE_DERIVATION}),and_v(v:multi(2,{POLICY_KEY_1}{RECEIVE_CHANGE_DERIVATION},{POLICY_KEY_2}{RECEIVE_CHANGE_DERIVATION},{POLICY_KEY_3}{RECEIVE_CHANGE_DERIVATION}),older(65535))))", + ), + ( + "Taproot sortedmulti_a and miniscript leaves", + "tr(@0/**,{sortedmulti_a(1,@0/<2;3>/*,@1/**),or_b(pk(@2/**),s:pk(@3/**))})", + [POLICY_KEY_0, TAPROOT_KEY_1, TAPROOT_KEY_2, TAPROOT_KEY_3], + f"tr({POLICY_KEY_0}{RECEIVE_CHANGE_DERIVATION},{{sortedmulti_a(1,{POLICY_KEY_0}{ALTERNATE_DERIVATION},{TAPROOT_KEY_1}{RECEIVE_CHANGE_DERIVATION}),or_b(pk({TAPROOT_KEY_2}{RECEIVE_CHANGE_DERIVATION}),s:pk({TAPROOT_KEY_3}{RECEIVE_CHANGE_DERIVATION}))}})", + ), + ( + "Taproot MuSig2 with recovery paths", + "tr(musig(@0,@1,@2)/**,{and_v(v:pk(musig(@0,@1)/**),older(12960)),{and_v(v:pk(musig(@0,@2)/**),older(12960)),and_v(v:pk(musig(@1,@2)/**),older(12960))}})", + [POLICY_KEY_0, POLICY_KEY_1, POLICY_KEY_2], + f"tr({musig_3_of_3}{RECEIVE_CHANGE_DERIVATION},{{and_v(v:pk({musig_0_1}{RECEIVE_CHANGE_DERIVATION}),older(12960)),{{and_v(v:pk({musig_0_2}{RECEIVE_CHANGE_DERIVATION}),older(12960)),and_v(v:pk({musig_1_2}{RECEIVE_CHANGE_DERIVATION}),older(12960))}}}})", + ), + ] + + for name, descriptor_template, keys_info, descriptor in valid_policies: + with self.subTest(name=name): + policy = BIP388Policy.from_descriptor(name, descriptor) + self.assertEqual(policy.descriptor_template, descriptor_template) + self.assertEqual(policy.keys_info, keys_info) + + def test_bip388_invalid_policy_vectors(self) -> None: + invalid_templates = [ + ("Key placeholder with no path", "pkh(@0)", 1), + ("Key placeholder with an explicit path", "pkh(@0/0/**)", 1), + ("Key placeholders out of order", "sh(multi(1,@1/**,@0/**))", 2), + ("Skipped key placeholder", "sh(multi(1,@0/**,@2/**))", 3), + ("Repeated key path", "sh(multi(1,@0/**,@0/**))", 1), + ( + "Non-disjoint multipath expressions", + "sh(multi(1,@0/<0;1>/*,@0/<1;2>/*))", + 1, + ), + ( + "Non-placeholder key", + f"sh(multi(1,@0/**,{NON_PLACEHOLDER_XPUB}{RECEIVE_CHANGE_DERIVATION}))", + 1, + ), + ("Multipath cardinality greater than two", "pkh(@0/<0;1;2>/*)", 1), + ("Derivation before MuSig2 aggregation", "tr(musig(@0/**,@1/**))", 2), + ] + + for name, descriptor_template, key_count in invalid_templates: + with self.subTest(name=name): + with self.assertRaises(BadArgumentError): + _validate_template(descriptor_template, key_count) + + def test_single_key_descriptor(self) -> None: + descriptor = f"wpkh([f5acc2fd/84h/1h/0h]{XPUB_A}{RECEIVE_CHANGE_DERIVATION})" + policy = BIP388Policy.from_descriptor("single", AddChecksum(descriptor)) + + self.assertEqual(policy.name, "single") + self.assertEqual(policy.descriptor_template, "wpkh(@0/**)") + self.assertEqual( + policy.keys_info, + [f"[f5acc2fd/84'/1'/0']{XPUB_A}"], + ) + self.assertIsNone(policy.registration) + + def test_musig_descriptor(self) -> None: + descriptor = ( + f"tr(musig([f5acc2fd/87h/1h/0h]{XPUB_A}," + f"[4c00739d/87h/1h/0h]{XPUB_B}){RECEIVE_CHANGE_DERIVATION})" + ) + policy = BIP388Policy.from_descriptor("musig", descriptor, "00" * 32) + + self.assertEqual(policy.descriptor_template, "tr(musig(@0,@1)/**)") + self.assertEqual(len(policy.keys_info), 2) + self.assertEqual(policy.registration, "00" * 32) + + def test_reused_key_with_disjoint_branches(self) -> None: + descriptor = ( + f"wsh(or_b(pk([f5acc2fd/84h/1h/0h]{XPUB_A}{RECEIVE_CHANGE_DERIVATION})," + f"s:pk([f5acc2fd/84h/1h/0h]{XPUB_A}{ALTERNATE_DERIVATION})))" + ) + policy = BIP388Policy.from_descriptor("branches", descriptor) + + self.assertEqual(len(policy.keys_info), 1) + self.assertEqual( + policy.descriptor_template, + "wsh(or_b(pk(@0/**),s:pk(@0/<2;3>/*)))", + ) + + def test_rejects_non_combined_descriptor(self) -> None: + with self.assertRaisesRegex(BadArgumentError, "Every BIP388 key placeholder"): + BIP388Policy.from_descriptor( + "receive only", + f"wpkh([f5acc2fd/84h/1h/0h]{XPUB_A}/0/*)", + ) + + def test_rejects_bad_checksum(self) -> None: + with self.assertRaisesRegex(BadArgumentError, "checksum does not match"): + BIP388Policy.from_descriptor( + "bad checksum", + f"wpkh([f5acc2fd/84h/1h/0h]{XPUB_A}{RECEIVE_CHANGE_DERIVATION})#aaaaaaaa", + ) + + def test_rejects_overlapping_key_reuse(self) -> None: + descriptor = ( + f"wsh(or_b(pk([f5acc2fd/84h/1h/0h]{XPUB_A}{RECEIVE_CHANGE_DERIVATION})," + f"s:pk([f5acc2fd/84h/1h/0h]{XPUB_A}{OVERLAPPING_DERIVATION})))" + ) + with self.assertRaisesRegex(BadArgumentError, "overlapping derivation"): + BIP388Policy.from_descriptor("overlap", descriptor) + + +if __name__ == "__main__": + unittest.main()