Merge pull request #2 from jamesob/jamesob-25-03-impl-change

refine the `bip32_derive` interface

Author: jamesob

Makefile

@@ -43,7 +43,7 @@ libbip32.so:
 	$(CC) $(CFLAGS) -shared -fPIC bip32.c $(LDFLAGS) -o libbip32.so
 
 fuzz_target: libbip32.so
-	$(CC) -fsanitize=fuzzer,address fuzz.c libbip32.so $(LDFLAGS) -o fuzz_target
+	$(CC) -fsanitize=fuzzer,address test/fuzz.c libbip32.so $(LDFLAGS) -o fuzz_target
 
 .PHONY: test
 test: libbip32.so

README.md

@@ -21,12 +21,16 @@ Install libsecp256k1
 ```bash
 git clone https://github.com/bitcoin-core/secp256k1.git && \
   cd secp256k1 && ./autogen.sh && ./configure && make && sudo make install
+
+# NOTE: in production, you should verify the associated GPG sigs and/or pin hashes.
 ```
 
 Install libsodium
 ```bash
 git clone https://github.com/jedisct1/libsodium.git && \
   cd libsodium && ./autogen.sh -sb && ./configure && make && sudo make install
+
+# NOTE: in production, you should verify the associated GPG sigs and/or pin hashes.
 ```
 
 Install this library
@@ -35,6 +39,13 @@ git clone https://github.com/jamesob/cbip32.git && \
   make && sudo make install
 ```
 
+## Tests
+
+- [Vectors from BIP32](./examples/py/test_bip32.py)
+- [Cross-implementation fuzz](./examples/py/test_fuzz_cross_impl.py)
+- [C unittests](./test/test.c)
+- [C fuzz](./test/fuzz.c)
+
 ## Performance
 
 The Python bindings for this implementation have been shown to be

bip32.c

@@ -235,22 +235,19 @@ static bool has_invalid_path_characters(const char* str) {
     return false;
 }
 
-int bip32_derive(bip32_key *target, const char* source, const char* path) {
+int bip32_derive_from_str(bip32_key* target, const char* source, const char* path) {
     if (!target || !source || !path || strncmp(path, "m", 1) != 0) {
         return 0;
     }
     if (strlen(source) < 1) {
         return 0;
     }
-    if (has_invalid_path_characters(path)) {
-        return 0;
-    }
     bip32_key basekey;
     size_t source_len = strlen(source);
-     
-    if (strncmp(source, "xprv", 4) == 0 || 
+
+    if (strncmp(source, "xprv", 4) == 0 ||
         strncmp(source, "tprv", 4) == 0 ||
-        strncmp(source, "xpub", 4) == 0 || 
+        strncmp(source, "xpub", 4) == 0 ||
         strncmp(source, "tpub", 4) == 0) {
         if (!bip32_deserialize(&basekey, source, strlen(source))) {
             return 0;
@@ -269,36 +266,57 @@ int bip32_derive(bip32_key *target, const char* source, const char* path) {
     } else {
         return 0;
     }
-    
+
+    if (bip32_derive(&basekey, path)) {
+        memcpy(target, &basekey, sizeof(bip32_key));
+        return 1;
+    }
+    return 0;
+}
+
+int bip32_derive_from_seed(bip32_key* target, const unsigned char* seed, size_t seed_len, const char* path) {
+    if (!bip32_from_seed(target, seed, seed_len)) {
+        return 0;
+    }
+    if (bip32_derive(target, path)) {
+        return 1;
+    }
+    return 0;
+}
+
+// Do an in-place derivation on `key`.
+int bip32_derive(bip32_key* key, const char* path) {
+    if (!path || strncmp(path, "m", 1) != 0 || has_invalid_path_characters(path)) {
+        return 0;
+    }
+
     char *p = (char*)strchr(path, '/');
     if (!p) {
-        memcpy(target, &basekey, sizeof(bip32_key));
         return 1;
     }
-    
+
     while (p && *p) {
         char *end;
         uint32_t path_index = strtoul(p + 1, &end, 10);
-        
+
         if (errno == ERANGE || path_index > INT_MAX || end == p + 1) {
             // Overflow detected.
             return 0;
         }
-        
+
         if (*end == '\'' || *end == 'h' || *end == 'H' || *end == 'p' || *end == 'P') {
             path_index |= HARDENED_INDEX;
             end++;
         }
 
         bip32_key tmp;
-        memcpy(&tmp, &basekey, sizeof(bip32_key));
-        if (bip32_index_derive(&basekey, &tmp, path_index) != 1) {
+        memcpy(&tmp, key, sizeof(bip32_key));
+        if (bip32_index_derive(key, &tmp, path_index) != 1) {
             return 0;
         }
         p = strchr(end, '/');
     }
-    
-    memcpy(target, &basekey, sizeof(bip32_key));
+
     return 1;
 }
 
@@ -308,37 +326,37 @@ int bip32_derive(bip32_key *target, const char* source, const char* path) {
 int bip32_serialize(const bip32_key *key, char *str, size_t str_len) {
     unsigned char data[SER_PLUS_CHECKSUM_SIZE];
     uint32_t version;
-    
+
     // Set version bytes based on network and key type
     if (key->is_private) {
         version = key->is_testnet ? VERSION_TPRIV : VERSION_XPRIV;
     } else {
         version = key->is_testnet ? VERSION_TPUB : VERSION_XPUB;
     }
     version = to_big_endian(version);
-    
+
     memcpy(data, &version, sizeof(version));
-    
+
     data[4] = key->depth;
-    
+
     // Write parent fingerprint
     uint32_t parfinger = key->parent_fingerprint;
     memcpy(data + 5, &parfinger, sizeof(parfinger));
 
     // Write child number in big-endian
     uint32_t childnum = to_big_endian(key->child_number);
     memcpy(data + 9, &childnum, sizeof(childnum));
-    
+
     // Copy chain code
     memcpy(data + 13, key->chain_code, 32);
-    
+
     if (key->is_private) {
         data[45] = 0;
         memcpy(data + 46, key->key.privkey, 32);
     } else {
         memcpy(data + 45, key->key.pubkey, 33);
     }
-    
+
     // Add checksum and base58 encode
     uint8_t hash[32];
     bip32_sha256_double(hash, data, 78);
@@ -374,7 +392,7 @@ int bip32_deserialize(bip32_key *key, const char *str, const size_t str_len) {
             key->is_private = 0;
             break;
         case VERSION_XPRIV:
-            key->is_testnet = 0; 
+            key->is_testnet = 0;
             key->is_private = 1;
             break;
         case VERSION_TPRIV:
@@ -454,10 +472,10 @@ void bip32_sha256_double(uint8_t *hash, const uint8_t *data, size_t len) {
 }
 
 void bip32_hmac_sha512(
-    unsigned char* hmac_out, 
-    const unsigned char* key, 
-    size_t key_len, 
-    const unsigned char* msg, 
+    unsigned char* hmac_out,
+    const unsigned char* key,
+    size_t key_len,
+    const unsigned char* msg,
     size_t msg_len
 ) {
     assert(sodium_init() >= 0);

bip32.h

@@ -41,12 +41,24 @@ void bip32_init(bip32_key *key);
  */
 int bip32_from_seed(bip32_key *key, const unsigned char *seed, size_t seed_len);
 
+/** Derive a BIP32 path from a raw seed.
+ *
+ * Returns 1 if successful.
+ */
+int bip32_derive_from_seed(bip32_key* target, const unsigned char* seed, size_t seed_len, const char* path);
+
 /** Derive a BIP32 path. `source` as a null-terminated string that can either be a
  * 32 byte seed (secret), or a serialized BIP32 key (xprv*, xpub*, tprv*, tpub*).
  *
  * Returns 1 if successful.
  */
-int bip32_derive(bip32_key *target, const char* source, const char* path);
+int bip32_derive_from_str(bip32_key *target, const char* source, const char* path);
+
+/** Derive a BIP32 key along a path in-place. This is destructive on `target`.
+ *
+ * Returns 1 if successful.
+ */
+int bip32_derive(bip32_key *target, const char* path);
 
 /** Serialize a BIP32 key to its base58 string representation.
  *

examples/cli.c

@@ -10,7 +10,7 @@ int main(int argc, char *argv[]) {
    bip32_key key;
    char serialized[112];
 
-   if (!bip32_derive(&key, argv[1], argv[2])) {
+   if (!bip32_derive_from_str(&key, argv[1], argv[2])) {
        fprintf(stderr, "Derivation failed\n");
        return 1;
    }

examples/go/cbip32.go

@@ -25,6 +25,6 @@ func Derive(source, path string) (*BIP32Key, bool) {
     defer C.free(unsafe.Pointer(cSource))
     defer C.free(unsafe.Pointer(cPath))
 
-    result := C.bip32_derive(&key.cKey, cSource, cPath)
+    result := C.bip32_derive_from_str(&key.cKey, cSource, cPath)
     return key, result == 1
 }

examples/py/bindings.py

@@ -3,7 +3,7 @@
 from functools import lru_cache
 from pathlib import Path
 from ctypes import (
-    c_uint8, c_uint32, c_size_t, c_char_p, c_void_p,
+    c_uint8, c_uint32, c_size_t, c_char_p, c_ubyte, c_void_p,
     Structure, Union, POINTER, create_string_buffer
 )
 
@@ -20,10 +20,13 @@ def get_bip32_module():
     bip32_lib.bip32_init.argtypes = [POINTER(BIP32Key)]
     bip32_lib.bip32_init.restype = None
 
-    bip32_lib.bip32_derive.argtypes = [POINTER(BIP32Key), c_char_p, c_char_p]
-    bip32_lib.bip32_derive.restype = ctypes.c_int
+    bip32_lib.bip32_derive_from_seed.argtypes = [POINTER(BIP32Key), POINTER(c_ubyte), c_size_t, c_char_p]
+    bip32_lib.bip32_derive_from_seed.restype = ctypes.c_int
+
+    bip32_lib.bip32_derive_from_str.argtypes = [POINTER(BIP32Key), c_char_p, c_char_p]
+    bip32_lib.bip32_derive_from_str.restype = ctypes.c_int
 
-    bip32_lib.bip32_derive.argtypes = [POINTER(BIP32Key), c_char_p, c_char_p]
+    bip32_lib.bip32_derive.argtypes = [POINTER(BIP32Key), c_char_p]
     bip32_lib.bip32_derive.restype = ctypes.c_int
 
     bip32_lib.bip32_serialize.argtypes = [POINTER(BIP32Key), c_char_p, c_size_t]
@@ -103,6 +106,15 @@ def derive(source: str, path: str = 'm') -> BIP32:
 
     """
     b = BIP32()
-    if not get_bip32_module().bip32_derive(b.key, source.encode(), path.encode()):
+    if not get_bip32_module().bip32_derive_from_str(b.key, source.encode(), path.encode()):
+        raise ValueError("failed")
+    return b
+
+
+def derive_from_seed(seed: bytes, path: str = 'm') -> BIP32:
+    b = BIP32()
+    c_seed = ctypes.c_char_p(seed)
+    seed_ptr = ctypes.cast(c_seed, POINTER(c_ubyte))
+    if not get_bip32_module().bip32_derive_from_seed(b.key, seed_ptr, len(seed), path.encode()):
         raise ValueError("failed")
     return b

examples/py/test_bip32.py

@@ -1,6 +1,6 @@
 import unittest
 
-from bindings import derive
+from bindings import derive, derive_from_seed
 
 
 class TestBIP32(unittest.TestCase):
@@ -16,6 +16,12 @@ def test_vectors(self):
                         pub = derived.get_public()
                         self.assertEqual(pub.serialize(), expected["xpub"])
 
+                        # Ensure the equivalent `derive_from_seed` call yields the
+                        # same result.
+                        from_seed = derive_from_seed(bytes.fromhex(seed), path)
+                        self.assertEqual(from_seed.serialize(), derived.serialize())
+
+
     def test_bad_vectors(self):
         for case in BAD_VECTORS:
             ser, msg = case.strip().split(' ', 1)

examples/py/test_fuzz_cross_impl.py

@@ -8,7 +8,6 @@
 # ]
 # ///
 import sys
-import random
 import logging
 import time
 from contextlib import contextmanager
@@ -19,7 +18,7 @@
 import pytest
 from hypothesis import given, strategies as st, target, settings
 
-from bindings import derive
+from bindings import derive, derive_from_seed
 
 log = logging.getLogger(__name__)
 logging.basicConfig()
@@ -130,7 +129,9 @@ def bip32_paths(draw):
 @given(seed_hex_str=valid_seeds, bip32_path=py_compatible_bip32_paths())
 @settings(max_examples=2_000)
 def test_versus_py(seed_hex_str, bip32_path):
-    """Compare implementations of BIP32 on a random seed and path."""
+    """
+    Compare implementations of BIP32 on a random seed and path.
+    """
     with timer('ours'):
         ours = our_derive(seed_hex_str, bip32_path)
     with timer('python-bip32'):
@@ -139,6 +140,21 @@ def test_versus_py(seed_hex_str, bip32_path):
     assert ours == pys
 
 
+@given(seedhex=valid_seeds, path=py_compatible_bip32_paths())
+@settings(max_examples=2_000)
+def test_versus_ourselves(seedhex, path):
+    """
+    Ensure that our different derive functions work properly.
+    """
+    seed = bytes.fromhex(seedhex)
+    from_seed = INVALID_KEY
+    try:
+        from_seed = derive_from_seed(seed, path).serialize()
+    except Exception:
+        pass
+    assert our_derive(seedhex, path) == from_seed
+
+
 @given(seed_hex_str=valid_seeds, bip32_path=py_compatible_bip32_paths())
 @settings(max_examples=100, deadline=5000)  # verstable is slooooww, so allow 5s tests
 def test_versus_vs(seed_hex_str, bip32_path):

test/fuzz.c

@@ -27,7 +27,7 @@ int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
 
     if (path[0] != 'm') path[0] = 'm';
 
-    bip32_derive(&target, source, path);
+    bip32_derive_from_str(&target, source, path);
 
     free(source);
     free(path);