From 165d43a38e4ba825a30ed672af2959befb744038 Mon Sep 17 00:00:00 2001 From: Ferdinando Ametrano Date: Tue, 8 Sep 2026 21:44:02 +0200 Subject: [PATCH] descriptor: validate raw public keys in key expressions A public key written as raw hex in a descriptor is checked against the secp256k1 curve for the context it appears in. A 33-byte compressed key is accepted everywhere; a 32-byte x-only key only inside tr(); a 65-byte uncompressed key only at the top level and under sh(), and never under the segwit contexts wpkh() and wsh() or inside tr(). A key whose length, prefix, or encoded point is invalid is rejected with a ValueError. Previously such keys were only tested for being hex rather than an extended key, so a descriptor carrying off-curve, wrong-length, bad-prefix, or context-inappropriate bytes parsed without complaint. --- hwilib/descriptor.py | 65 +++++++++++++++++++++++++++++++++-------- hwilib/key.py | 19 ++++++++++++ test/test_descriptor.py | 44 ++++++++++++++++++++++++++++ 3 files changed, 116 insertions(+), 12 deletions(-) diff --git a/hwilib/descriptor.py b/hwilib/descriptor.py index 1373ad2d2..6443e5ab4 100644 --- a/hwilib/descriptor.py +++ b/hwilib/descriptor.py @@ -16,6 +16,8 @@ parse_multipath, multipath_to_string, path_to_string, + point_on_curve, + x_coord_on_curve, ) from .common import AddressType from .errors import BadArgumentError, InvalidPolicyError @@ -106,6 +108,33 @@ def AddChecksum(desc: str) -> str: return desc + "#" + DescriptorChecksum(desc) +def _validate_pubkey(pubkey_bytes: bytes, x_only: bool, permit_uncompressed: bool) -> None: + """ + Check that raw public key bytes encode a valid secp256k1 point for the + context they appear in, raising ``ValueError`` otherwise. + + A 33-byte compressed key is accepted everywhere. A 32-byte x-only key is + accepted only in a taproot context. A 65-byte uncompressed key is accepted + only where uncompressed keys are permitted, i.e. at the top level and under + ``sh()``, and never under the segwit contexts ``wpkh()`` and ``wsh()`` or + in a taproot context. In every case the encoded point must lie on the curve. + + :param pubkey_bytes: The raw public key bytes + :param x_only: Whether the key appears in a ``tr()`` context, where x-only keys are permitted + :param permit_uncompressed: Whether an uncompressed key is permitted in this context + """ + if x_only and len(pubkey_bytes) == 32: + if x_coord_on_curve(int.from_bytes(pubkey_bytes, "big")): + return + elif len(pubkey_bytes) == 33 and pubkey_bytes[0] in (2, 3): + if x_coord_on_curve(int.from_bytes(pubkey_bytes[1:], "big")): + return + elif not x_only and permit_uncompressed and len(pubkey_bytes) == 65 and pubkey_bytes[0] == 4: + if point_on_curve(int.from_bytes(pubkey_bytes[1:33], "big"), int.from_bytes(pubkey_bytes[33:], "big")): + return + raise ValueError("Pubkey '{}' is invalid".format(pubkey_bytes.hex())) + + class PubkeyProvider(object): """ A public key expression in a descriptor. @@ -118,13 +147,17 @@ def __init__( pubkey: str, deriv_path: Optional[List[List[int]]], expr_index: int, - ranged: bool + ranged: bool, + x_only: bool = False, + permit_uncompressed: bool = True ) -> None: """ :param origin: The key origin if one is available :param pubkey: The public key. Either a hex string or a serialized extended pubkey :param deriv_path: Additional derivation path if the pubkey is an extended pubkey :param expr_index: The position of this key within the descriptor + :param x_only: Whether the key appears in a ``tr()`` context, where x-only keys are permitted + :param permit_uncompressed: Whether an uncompressed key is permitted in this context """ self.origin = origin self.pubkey = pubkey @@ -136,19 +169,23 @@ def __init__( # Make ExtendedKey from pubkey if it isn't hex self.extkey = None try: - unhexlify(self.pubkey) - # Is hex, normal pubkey + pubkey_bytes = unhexlify(self.pubkey) except Exception: # Not hex, maybe xpub self.extkey = ExtendedKey.deserialize(self.pubkey) + else: + # Is hex, a raw public key. Reject it if it is not a valid point. + _validate_pubkey(pubkey_bytes, x_only, permit_uncompressed) @classmethod - def parse(cls, s: str, key_expr_index: int) -> 'PubkeyProvider': + def parse(cls, s: str, key_expr_index: int, x_only: bool = False, permit_uncompressed: bool = True) -> 'PubkeyProvider': """ Deserialize a key expression from the string into a ``PubkeyProvider``. :param s: String containing the key expression :param key_expr_index: The position of this key within the descriptor + :param x_only: Whether the key appears in a ``tr()`` context, where x-only keys are permitted + :param permit_uncompressed: Whether an uncompressed key is permitted in this context :return: A new ``PubkeyProvider`` containing the details given by ``s`` """ origin = None @@ -171,7 +208,7 @@ def parse(cls, s: str, key_expr_index: int) -> 'PubkeyProvider': if len(path_str) > 0: deriv_path = parse_multipath(path_str) - return cls(origin, pubkey, deriv_path, key_expr_index, ranged) + return cls(origin, pubkey, deriv_path, key_expr_index, ranged, x_only, permit_uncompressed) def to_string(self, hardened_char: str = "h") -> str: """ @@ -585,12 +622,14 @@ def _get_expr(s: str) -> Tuple[str, str]: return s, "" return s[0:i], s[i:] -def parse_pubkey(expr: str, key_expr_index: int) -> Tuple['PubkeyProvider', str, int]: +def parse_pubkey(expr: str, key_expr_index: int, x_only: bool = False, permit_uncompressed: bool = True) -> Tuple['PubkeyProvider', str, int]: """ Parses an individual pubkey expression from a string that may contain more than one pubkey expression. :param expr: The expression to parse a pubkey expression from :param key_expr_index: The position of the next key to be parsed + :param x_only: Whether the key appears in a ``tr()`` context, where x-only keys are permitted + :param permit_uncompressed: Whether an uncompressed key is permitted in this context :return: The :class:`PubkeyProvider` that is parsed as the first item of a tuple, the remainder of the expression as the second item, and the index of the next key expression as the third. """ end = len(expr) @@ -599,7 +638,7 @@ def parse_pubkey(expr: str, key_expr_index: int) -> Tuple['PubkeyProvider', str, if comma_idx != -1: end = comma_idx next_expr = expr[end + 1:] - return PubkeyProvider.parse(expr[:end], key_expr_index), next_expr, (key_expr_index + 1) + return PubkeyProvider.parse(expr[:end], key_expr_index, x_only, permit_uncompressed), next_expr, (key_expr_index + 1) class _ParseDescriptorContext(Enum): @@ -637,15 +676,16 @@ def _parse_descriptor(desc: str, ctx: '_ParseDescriptorContext', key_expr_index: :raises: ValueError: if the descriptor is malformed """ func, expr = _get_func_expr(desc) + permit_uncompressed = ctx == _ParseDescriptorContext.TOP or ctx == _ParseDescriptorContext.P2SH if func == "pk": - pubkey, expr, key_expr_index = parse_pubkey(expr, key_expr_index) + pubkey, expr, key_expr_index = parse_pubkey(expr, key_expr_index, ctx == _ParseDescriptorContext.P2TR, permit_uncompressed) if expr: raise ValueError("more than one pubkey in pk descriptor") return PKDescriptor(pubkey), key_expr_index if func == "pkh": if not (ctx == _ParseDescriptorContext.TOP or ctx == _ParseDescriptorContext.P2SH or ctx == _ParseDescriptorContext.P2WSH): raise ValueError("Can only have pkh at top level, in sh(), or in wsh()") - pubkey, expr, key_expr_index = parse_pubkey(expr, key_expr_index) + pubkey, expr, key_expr_index = parse_pubkey(expr, key_expr_index, permit_uncompressed=permit_uncompressed) if expr: raise ValueError("More than one pubkey in pkh descriptor") return PKHDescriptor(pubkey), key_expr_index @@ -659,7 +699,7 @@ def _parse_descriptor(desc: str, ctx: '_ParseDescriptorContext', key_expr_index: pubkeys = [] multipath_len = None while expr: - pubkey, expr, key_expr_index = parse_pubkey(expr, key_expr_index) + pubkey, expr, key_expr_index = parse_pubkey(expr, key_expr_index, permit_uncompressed=permit_uncompressed) if pubkey.multipath_len > 1: if multipath_len is None: multipath_len = pubkey.multipath_len @@ -678,7 +718,8 @@ def _parse_descriptor(desc: str, ctx: '_ParseDescriptorContext', key_expr_index: if func == "wpkh": if not (ctx == _ParseDescriptorContext.TOP or ctx == _ParseDescriptorContext.P2SH): raise ValueError("Can only have wpkh() at top level or inside sh()") - pubkey, expr, key_expr_index = parse_pubkey(expr, key_expr_index) + # A wpkh() key is a segwit witness program, so uncompressed keys are never permitted. + pubkey, expr, key_expr_index = parse_pubkey(expr, key_expr_index, permit_uncompressed=False) if expr: raise ValueError("More than one pubkey in pkh descriptor") return WPKHDescriptor(pubkey), key_expr_index @@ -696,7 +737,7 @@ def _parse_descriptor(desc: str, ctx: '_ParseDescriptorContext', key_expr_index: if ctx != _ParseDescriptorContext.TOP: raise ValueError("Can only have tr at top level") multipath_len = None - internal_key, expr, key_expr_index = parse_pubkey(expr, key_expr_index) + internal_key, expr, key_expr_index = parse_pubkey(expr, key_expr_index, x_only=True) if internal_key.multipath_len > 1: multipath_len = internal_key.multipath_len subscripts = [] diff --git a/hwilib/key.py b/hwilib/key.py index 506fb1aad..50e1732e1 100644 --- a/hwilib/key.py +++ b/hwilib/key.py @@ -99,6 +99,25 @@ def point_to_bytes(p: Point) -> bytes: return (b'\x03' if p[1] & 1 else b'\x02') + p[0].to_bytes(32, byteorder="big") +def point_on_curve(x: int, y: int) -> bool: + """ + Returns whether the affine point ``(x, y)`` lies on the secp256k1 curve, + i.e. both coordinates are field elements and ``y^2 == x^3 + 7 (mod p)``. + """ + return 0 <= x < p and 0 <= y < p and (y * y - (x * x * x + 7)) % p == 0 + + +def x_coord_on_curve(x: int) -> bool: + """ + Returns whether ``x`` is the x coordinate of a point on the secp256k1 + curve, i.e. ``x`` is a field element for which ``x^3 + 7`` is a quadratic + residue modulo ``p``. + """ + if not 0 <= x < p: + return False + return pow((x * x * x + 7) % p, (p - 1) // 2, p) == 1 + + # An extended public key (xpub) or private key (xprv). Just a data container for now. # Only handles deserialization of extended keys into component data to be handled by something else class ExtendedKey(object): diff --git a/test/test_descriptor.py b/test/test_descriptor.py index dca4fbe80..081655f21 100755 --- a/test/test_descriptor.py +++ b/test/test_descriptor.py @@ -350,6 +350,50 @@ def check(descriptor, error): "BIP 388 requires all multipath specifiers to be exactly 2 elements" ) + def test_pubkey_validation(self): + compressed = "02c97dc3f4420402e01a113984311bf4a1b8de376cac0bdcfaf1b3ac81f13433c7" + uncompressed = "04c97dc3f4420402e01a113984311bf4a1b8de376cac0bdcfaf1b3ac81f13433c7a4f5dc6a5c6d18b0cea4d35deeddfd9a43f1b4d4bade8f4fd05e3e70d74b1bb4" + xonly = "a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd" + # A compressed key whose x coordinate (5) is not on the curve + off_curve = "020000000000000000000000000000000000000000000000000000000000000005" + off_curve_xonly = "0000000000000000000000000000000000000000000000000000000000000005" + + with self.subTest(msg="Valid keys are accepted"): + self.assertIsNotNone(parse_descriptor(f"pkh({compressed})")) + self.assertIsNotNone(parse_descriptor(f"wpkh({compressed})")) + # Both x-only and compressed keys are valid taproot internal keys + self.assertIsNotNone(parse_descriptor(f"tr({xonly})")) + self.assertIsNotNone(parse_descriptor(f"tr({compressed})")) + # A tapscript leaf key is x-only + self.assertIsNotNone(parse_descriptor(f"tr({xonly},pk({xonly}))")) + + with self.subTest(msg="Uncompressed keys are accepted at top level and under sh()"): + self.assertIsNotNone(parse_descriptor(f"pkh({uncompressed})")) + self.assertIsNotNone(parse_descriptor(f"sh(pkh({uncompressed}))")) + self.assertIsNotNone(parse_descriptor(f"multi(1,{uncompressed})")) + self.assertIsNotNone(parse_descriptor(f"sh(multi(1,{uncompressed}))")) + + with self.subTest(msg="Uncompressed keys are rejected in segwit contexts"): + self.assertRaises(ValueError, parse_descriptor, f"wpkh({uncompressed})") + self.assertRaises(ValueError, parse_descriptor, f"wsh(pk({uncompressed}))") + self.assertRaises(ValueError, parse_descriptor, f"wsh(multi(1,{uncompressed}))") + self.assertRaises(ValueError, parse_descriptor, f"sh(wsh(pk({uncompressed})))") + self.assertRaises(ValueError, parse_descriptor, f"tr({uncompressed})") + + with self.subTest(msg="Off-curve keys are rejected"): + self.assertRaises(ValueError, parse_descriptor, f"pkh({off_curve})") + self.assertRaises(ValueError, parse_descriptor, f"wpkh({off_curve})") + self.assertRaises(ValueError, parse_descriptor, f"sh(multi(1,{off_curve}))") + self.assertRaises(ValueError, parse_descriptor, f"tr({off_curve_xonly})") + self.assertRaises(ValueError, parse_descriptor, f"tr({xonly},pk({off_curve_xonly}))") + + with self.subTest(msg="Wrong length or context keys are rejected"): + # An x-only key is not allowed outside of a taproot context + self.assertRaises(ValueError, parse_descriptor, f"pkh({xonly})") + + with self.subTest(msg="Bad prefix keys are rejected"): + self.assertRaises(ValueError, parse_descriptor, "pkh(05c97dc3f4420402e01a113984311bf4a1b8de376cac0bdcfaf1b3ac81f13433c7)") + if __name__ == "__main__": unittest.main()