bip32: disallow repeated child numbers in multi-paths per BIP-389
What changed, and why it matters
This commit tightens validation of Bitcoin descriptor multi-path expressions like <0;1;2>. Previously, the library accepted repeated child numbers (e.g., <0;0>) and allowed up to 255 entries by using >= instead of >. The change enforces BIP-389 by rejecting duplicate path components and correcting the limit to 255 distinct items. This is a standards-compliance and safety fix: duplicate paths could silently produce identical derived keys across branches, which may break wallet assumptions, enable fingerprinting, or cause downstream logic to treat different descriptor branches as the same.
Review whether any deployed descriptors or policies rely on repeated child numbers in multi-path expressions; such descriptors will now fail parsing. Update documentation and release notes to note the stricter BIP-389 enforcement. Consider backporting to stable branches if descriptor parsing is exposed to untrusted input.
Security signals we found
Input validation hardening for BIP32 path parsing
BIP-389 standards compliance enforcement
Duplicate child number detection in multi-path descriptors
Off-by-one limit correction (255 vs 256 elements)
New negative test cases for non-distinct multi-paths
Evidence from the diff
In src/bip32.c, get_multi_index() is rewritten to track seen child numbers using a 64-bit bitset for values 0-63 and a wally_map for larger values. It now returns an int status and disallows reused child numbers via check_reused_child_num(). The loop also changes the termination condition from cur_index >= 255 to cur_index > 255, so the maximum supported number of multi-path elements is now 255. Tests in test_descriptor.c are updated: the ‘too many elements’ case now uses 256 distinct numbers, and new negative test cases cover duplicate child numbers at small, boundary (63), and large (32767) values. The fix is defensive: BIP-389 requires distinct child numbers, and the prior off-by-one allowed 256 elements.
Changed components
src/bip32.csrc/ctest/test_descriptor.cbip32_path_from_str_n / path_from_str_nget_multi_indexDescriptor multi-path parsingInspect captured patch +80 / −15
### src/bip32.c
@@ -6,6 +6,7 @@
#include "ccan/ccan/build_assert/build_assert.h"
#include <include/wally_bip32.h>
#include <include/wally_crypto.h>
+#include <include/wally_map.h>
#include "bip32_int.h"
#define BIP32_BTC_DEFINED_FLAGS (BIP32_FLAG_KEY_PRIVATE | \
@@ -87,7 +88,7 @@ static bool is_hardened_indicator(char c, bool allow_upper)
return c == '\'' || c == 'h' || (allow_upper && c == 'H');
}
-static size_t get_child_number(const char *str, size_t str_len, bool allow_upper, uint32_t *v)
+static size_t get_child_num(const char *str, size_t str_len, bool allow_upper, uint32_t *v)
{
uint64_t value = 0;
size_t i = 0;
@@ -107,18 +108,56 @@ static size_t get_child_number(const char *str, size_t str_len, bool allow_upper
return i;
}
-static size_t get_multi_index(const char *str, size_t str_len, uint32_t multi_index, bool allow_upper, uint32_t *features, uint32_t *v)
+static int check_reused_child_num(struct wally_map *child_map,
+ uint64_t *first64, size_t remaining_len,
+ uint32_t child_num)
{
+ if (child_num < 64) {
+ /* Fast path for small numbers uses 'first64' as a bitset */
+ if ((*first64) & (uint64_t)1 << child_num)
+ return WALLY_EINVAL; /* Re-used */
+ (*first64) |= (uint64_t)1 << child_num;
+ return WALLY_OK; /* Unused, added to the bitset */
+ } else {
+ /* Look up large numbers in 'child_map' */
+ int ret;
+ size_t found_idx;
+ if (!child_map->items_allocation_len) {
+ /* Initialize on demand, try to minimize reallocs */
+ ret = wally_map_init((remaining_len >> 2) + 1, NULL, child_map);
+ if (ret != WALLY_OK)
+ return ret;
+ } else {
+ ret = wally_map_find_integer(child_map, child_num, &found_idx);
+ if (ret != WALLY_OK || found_idx != 0)
+ return WALLY_EINVAL; /* Re-used */
+ }
+ /* Unused, add it to 'child_map' */
+ return wally_map_add_integer(child_map, child_num, NULL, 0);
+ }
+}
+
+static int get_multi_index(const char *str, size_t str_len,
+ uint32_t multi_index, bool allow_upper,
+ uint32_t *features, uint32_t *v, size_t *expr_len_out)
+{
+ struct wally_map child_map;
+ uint64_t first64 = 0;
size_t i = 1; /* Start at 1 to skip '<' */
uint32_t cur_index = 0;
bool found_ours = false;
+ int ret = WALLY_OK;
+
+ *expr_len_out = 0;
if (!str_len || str[0] != '<')
- return 0; /* Not a multi-index expression */
+ return WALLY_OK; /* Not a multi-index expression */
+
+ child_map.items_allocation_len = 0; /* Initialized on-demand */
while (i < str_len) {
uint32_t value = 0;
- size_t expr_len = get_child_number(str + i, str_len - i, allow_upper, &value);
+ size_t expr_len = get_child_num(str + i, str_len - i, allow_upper, &value);
if (!expr_len) {
if (str[i] != '>' || !found_ours || cur_index < 2) {
/* No number, improperly terminated, multi_index not found,
@@ -127,14 +166,20 @@ static size_t get_multi_index(const char *str, size_t str_len, uint32_t multi_in
}
*features |= BIP32_PATH_IS_MULTIPATH;
*features |= (cur_index << BIP32_PATH_MULTI_SHIFT);
- return i + 1; /* Consume trailing '>' */
+ if (child_map.items_allocation_len)
+ wally_map_clear(&child_map);
+ *expr_len_out = i + 1; /* Consume trailing '>' */
+ return WALLY_OK;
}
i += expr_len;
+ ret = check_reused_child_num(&child_map, &first64, str_len - i, value);
+ if (ret != WALLY_OK)
+ break;
if (cur_index == multi_index) {
found_ours = true;
*v = value;
}
- if (++cur_index >= 255)
+ if (++cur_index > 255)
break; /* Unsupported number of multi_indices */
if (value & BIP32_INITIAL_HARDENED_CHILD)
*features |= BIP32_PATH_IS_HARDENED;
@@ -148,9 +193,11 @@ static size_t get_multi_index(const char *str, size_t str_len, uint32_t multi_in
}
}
/* No valid multi-index expression found */
+ if (child_map.items_allocation_len)
+ wally_map_clear(&child_map);
*features = 0;
*v = 0;
- return 0;
+ return ret;
}
static int path_from_str_n(const char *str, size_t str_len,
@@ -161,6 +208,7 @@ static int path_from_str_n(const char *str, size_t str_len,
{
const bool allow_upper = flags & BIP32_FLAG_ALLOW_UPPER;
size_t i = 0;
+ int ret = WALLY_OK;
if (written)
*written = 0;
@@ -198,12 +246,12 @@ static int path_from_str_n(const char *str, size_t str_len,
if (!(flags & BIP32_FLAG_STR_MULTIPATH))
goto fail; /* Multi-path not allowed */
flags &= ~BIP32_FLAG_STR_MULTIPATH; /* Only allow one multi-path */
- expr_len = get_multi_index(str + i, str_len - i, multi_index,
- allow_upper, features, &v);
- if (!expr_len)
- goto fail; /* Invalid multi-path expression */
+ ret = get_multi_index(str + i, str_len - i, multi_index,
+ allow_upper, features, &v, &expr_len);
+ if (ret != WALLY_OK || !expr_len)
+ goto fail; /* Error during parse or invalid multi-path */
- } else if (i < str_len && str[i] == '*') {
+ } else if (str[i] == '*') {
/* Wildcard ('*') */
if (!(flags & BIP32_FLAG_STR_WILDCARD))
goto fail; /* Wildcard not allowed, or previously seen */
@@ -219,7 +267,7 @@ static int path_from_str_n(const char *str, size_t str_len,
}
} else {
/* Child number */
- expr_len = get_child_number(str + i, str_len - i, allow_upper, &v);
+ expr_len = get_child_num(str + i, str_len - i, allow_upper, &v);
if (!expr_len)
goto fail; /* Expected a number */
if (v & BIP32_INITIAL_HARDENED_CHILD)
@@ -253,7 +301,7 @@ static int path_from_str_n(const char *str, size_t str_len,
*features = 0;
if (written)
*written = 0;
- return WALLY_EINVAL;
+ return ret != WALLY_OK ? ret : WALLY_EINVAL;
}
int bip32_path_from_str_n(const char *str, size_t str_len,
### src/ctest/test_descriptor.c
@@ -2258,7 +2258,7 @@ static const descriptor_test g_descriptor_cases[] = {
WALLY_NETWORK_BITCOIN_MAINNET, 0, 0, 0, NULL, 0, NULL, "", VARS_STD
}, {
"descriptor - Too many multi-path elements (>255)",
- "pkh(mainnet_xpub/<1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1>)",
+ "pkh(mainnet_xpub/<1;2;3;4;5;6;7;8;9;10;11;12;13;14;15;16;17;18;19;20;21;22;23;24;25;26;27;28;29;30;31;32;33;34;35;36;37;38;39;40;41;42;43;44;45;46;47;48;49;50;51;52;53;54;55;56;57;58;59;60;61;62;63;64;65;66;67;68;69;70;71;72;73;74;75;76;77;78;79;80;81;82;83;84;85;86;87;88;89;90;91;92;93;94;95;96;97;98;99;100;101;102;103;104;105;106;107;108;109;110;111;112;113;114;115;116;117;118;119;120;121;122;123;124;125;126;127;128;129;130;131;132;133;134;135;136;137;138;139;140;141;142;143;144;145;146;147;148;149;150;151;152;153;154;155;156;157;158;159;160;161;162;163;164;165;166;167;168;169;170;171;172;173;174;175;176;177;178;179;180;181;182;183;184;185;186;187;188;189;190;191;192;193;194;195;196;197;198;199;200;201;202;203;204;205;206;207;208;209;210;211;212;213;214;215;216;217;218;219;220;221;222;223;224;225;226;227;228;229;230;231;232;233;234;235;236;237;238;239;240;241;242;243;244;245;246;247;248;249;250;251;252;253;254;255;256>)",
WALLY_NETWORK_BITCOIN_MAINNET, 0, 0, 0, NULL, 0, NULL, "", VARS_STD
}, {
"descriptor - mismatched multi-path element counts",
@@ -2332,6 +2332,23 @@ static const descriptor_test g_descriptor_cases[] = {
"tr(@0/**,pk(@0/<1;2>/*))",
WALLY_NETWORK_BITCOIN_MAINNET, 0, 0, 0, NULL,
WALLY_MINISCRIPT_POLICY_TEMPLATE, NULL, "", VARS_P_1
+ }, {
+ /* Note the non-distinct paths checks is not policy specific;
+ * it applies to all descriptors/bip32 paths */
+ "policy - multi-path non-distinct paths (1)",
+ "pkh(@0/<0;0>)",
+ WALLY_NETWORK_BITCOIN_MAINNET, 0, 0, 0, NULL,
+ WALLY_MINISCRIPT_POLICY_TEMPLATE, NULL, "", VARS_P_1
+ }, {
+ "policy - multi-path non-distinct paths (2)",
+ "pkh(@0/<63;63>)",
+ WALLY_NETWORK_BITCOIN_MAINNET, 0, 0, 0, NULL,
+ WALLY_MINISCRIPT_POLICY_TEMPLATE, NULL, "", VARS_P_1
+ }, {
+ "policy - multi-path non-distinct paths (3)",
+ "pkh(@0/<32767;32767>)",
+ WALLY_NETWORK_BITCOIN_MAINNET, 0, 0, 0, NULL,
+ WALLY_MINISCRIPT_POLICY_TEMPLATE, NULL, "", VARS_P_1
}
#ifdef BUILD_ELEMENTS
/* Elements/Confidential descriptor error cases */Why this scored 48/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.