bip85: add support for RSA derivation

Lawrence Nahum · jgriffiths · commit 7ca03254d8cc · 2024-10-21T14:00:56.000+13:00
diff --git a/include/wally.hpp b/include/wally.hpp
@@ -319,6 +319,12 @@ inline int bip85_get_languages(char** output) {
     return detail::check_ret(__FUNCTION__, ret);
 }
 
+template <class HDKEY, class BYTES_OUT>
+inline int bip85_get_rsa_entropy(const HDKEY& hdkey, uint32_t key_bits, uint32_t index, BYTES_OUT& bytes_out, size_t* written) {
+    int ret = ::bip85_get_rsa_entropy(detail::get_p(hdkey), key_bits, index, bytes_out.data(), bytes_out.size(), written);
+    return detail::check_ret(__FUNCTION__, ret);
+}
+
 template <class BYTES, class ADDR_FAMILY>
 inline int addr_segwit_from_bytes(const BYTES& bytes, const ADDR_FAMILY& addr_family, uint32_t flags, char** output) {
     int ret = ::wally_addr_segwit_from_bytes(bytes.data(), bytes.size(), detail::get_p(addr_family), flags, output);
diff --git a/include/wally_bip39.h b/include/wally_bip39.h
@@ -28,7 +28,7 @@ struct words;
 #define BIP39_WORDLIST_LEN 2048
 
 /**
- * Get the list of default supported languages.
+ * Get the list of default supported languages for BIP39.
  *
  * .. note:: The string returned should be freed using `wally_free_string`.
  */
@@ -98,7 +98,7 @@ WALLY_CORE_API int bip39_mnemonic_from_bytes(
  *
  * :param w: Word list to use. Pass NULL to use the default English list.
  * :param mnemonic: Mnemonic to convert.
- * :param bytes_out: Where to store the resulting entropy.
+ * :param bytes_out: Destination for the resulting entropy.
  * MAX_SIZED_OUTPUT(len, bytes_out, BIP39_ENTROPY_MAX_LEN)
  * :param written: Destination for the number of bytes written to ``bytes_out``.
  */
diff --git a/include/wally_bip85.h b/include/wally_bip85.h
@@ -10,24 +10,24 @@ extern "C" {
 struct ext_key;
 
 /**
- * Get the list of default supported languages.
+ * Get the list of default supported languages for BIP85.
  *
  * .. note:: The string returned should be freed using `wally_free_string`.
  */
 WALLY_CORE_API int bip85_get_languages(
     char **output);
 
 /**
- * Generate bip39 mnemonic entropy according to bip85.
+ * Generate BIP39 mnemonic entropy according to BIP85.
  *
- * :param hdkey: The parent extended key to derive entropy from.
+ * :param hdkey: The parent extended key to derive mnemonic entropy from.
  * :param lang: The intended language. Pass NULL to use the default English value.
  * :param num_words: The intended number of words.  Must be 12, 18 or 24.
  * :param index: The index used to create the entropy. Must be less than
  *|    `BIP32_INITIAL_HARDENED_CHILD`.
- * :param bytes_out: Where to store the resulting entropy.
+ * :param bytes_out: Destination for the resulting entropy.
  * MAX_SIZED_OUTPUT(len, bytes_out, HMAC_SHA512_LEN)
- * :param written: Number of bytes in ``bytes_out`` to be used as entropy.
+ * :param written: Destination for the number of bytes written to ``bytes_out``.
  */
 WALLY_CORE_API int bip85_get_bip39_entropy(
     const struct ext_key *hdkey,
@@ -38,6 +38,30 @@ WALLY_CORE_API int bip85_get_bip39_entropy(
     size_t len,
     size_t *written);
 
+/**
+ * Generate entropy for seeding RSA key generation according to BIP85.
+ *
+ * :param hdkey: The parent extended key to derive RSA entropy from.
+ * :param key_bits: The intended RSA key size in bits.
+ * :param index: The index used to create the entropy. Must be less than
+ *|    `BIP32_INITIAL_HARDENED_CHILD`.
+ * :param bytes_out: Destination for the resulting entropy.
+ * MAX_SIZED_OUTPUT(len, bytes_out, HMAC_SHA512_LEN)
+ * :param written: Destination for the number of bytes written to ``bytes_out``.
+ *
+ * .. note:: This function always returns HMAC_SHA512_LEN bytes on success.
+ *
+ * .. note:: The returned entropy must be given to BIP85-DRNG in order
+ *|    to derive the RSA key to use. It MUST NOT be used directly.
+ */
+WALLY_CORE_API int bip85_get_rsa_entropy(
+    const struct ext_key *hdkey,
+    uint32_t key_bits,
+    uint32_t index,
+    unsigned char *bytes_out,
+    size_t len,
+    size_t *written);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/wally_core.h b/include/wally_core.h
@@ -212,7 +212,7 @@ WALLY_CORE_API int wally_hex_from_bytes(
  * Convert a hexadecimal string to bytes.
  *
  * :param hex: String to convert.
- * :param bytes_out: Where to store the resulting bytes.
+ * :param bytes_out: Destination for the resulting bytes.
  * :param len: The length of ``bytes_out`` in bytes.
  * :param written: Destination for the number of bytes written to ``bytes_out``.
  */
diff --git a/src/bip85.c b/src/bip85.c
@@ -9,7 +9,9 @@
 /* Bip85 path element values */
 #define BIP85_PURPOSE  (BIP32_INITIAL_HARDENED_CHILD | 83696968)
 #define BIP85_APPLICATION_39 (BIP32_INITIAL_HARDENED_CHILD | 39)
-#define BIP85_ENTROPY_PATH_LEN 5
+#define BIP85_APPLICATION_RSA (BIP32_INITIAL_HARDENED_CHILD | 828365)
+#define BIP85_BIP39_ENTROPY_PATH_LEN 5
+#define BIP85_RSA_ENTROPY_PATH_LEN 4
 #define BIP85_ENTROPY_HMAC_KEY_LEN 18
 static const uint8_t BIP85_ENTROPY_HMAC_KEY[BIP85_ENTROPY_HMAC_KEY_LEN]
     = { 'b', 'i', 'p', '-', 'e', 'n', 't', 'r', 'o', 'p', 'y', '-', 'f', 'r', 'o', 'm', '-', 'k' };
@@ -46,7 +48,7 @@ int bip85_get_bip39_entropy(const struct ext_key *hdkey,
                             size_t* written)
 {
     const size_t entropy_len = get_entropy_len(num_words);
-    uint32_t path[BIP85_ENTROPY_PATH_LEN], lang_idx = 0; /* 0=English */
+    uint32_t path[BIP85_BIP39_ENTROPY_PATH_LEN], lang_idx = 0; /* 0=English */
     struct ext_key derived;
     int ret;
 
@@ -76,7 +78,7 @@ int bip85_get_bip39_entropy(const struct ext_key *hdkey,
     path[2] = lang_idx | BIP32_INITIAL_HARDENED_CHILD;
     path[3] = num_words | BIP32_INITIAL_HARDENED_CHILD;
     path[4] = index | BIP32_INITIAL_HARDENED_CHILD;
-    ret = bip32_key_from_parent_path(hdkey, path, BIP85_ENTROPY_PATH_LEN,
+    ret = bip32_key_from_parent_path(hdkey, path, BIP85_BIP39_ENTROPY_PATH_LEN,
                                      BIP32_FLAG_KEY_PRIVATE|BIP32_FLAG_SKIP_HASH,
                                      &derived);
 
@@ -93,3 +95,39 @@ int bip85_get_bip39_entropy(const struct ext_key *hdkey,
     wally_clear(&derived, sizeof(derived));
     return ret;
 }
+
+int bip85_get_rsa_entropy(const struct ext_key *hdkey, uint32_t key_bits, uint32_t index,
+                          unsigned char *bytes_out, size_t len, size_t *written)
+{
+    uint32_t path[BIP85_RSA_ENTROPY_PATH_LEN];
+    struct ext_key derived;
+    int ret;
+
+    if (written)
+        *written = 0;
+
+    if (!hdkey || key_bits & BIP32_INITIAL_HARDENED_CHILD || index & BIP32_INITIAL_HARDENED_CHILD || !bytes_out
+        || len != HMAC_SHA512_LEN || !written)
+        return WALLY_EINVAL;
+
+    /* Derive a private key from the bip85 path for bip39 mnemonic entropy */
+    path[0] = BIP85_PURPOSE;
+    path[1] = BIP85_APPLICATION_RSA;
+    path[2] = key_bits | BIP32_INITIAL_HARDENED_CHILD;
+    path[3] = index | BIP32_INITIAL_HARDENED_CHILD;
+    ret = bip32_key_from_parent_path(hdkey, path, BIP85_RSA_ENTROPY_PATH_LEN,
+                                     BIP32_FLAG_KEY_PRIVATE | BIP32_FLAG_SKIP_HASH,
+                                     &derived);
+
+    if (ret == WALLY_OK) {
+        /* HMAC-SHA512 the derived private key with the fixed bip85 key
+         * Write result directly into output buffer - 'written' indicates
+         * how much should be used. */
+        ret = wally_hmac_sha512(BIP85_ENTROPY_HMAC_KEY, BIP85_ENTROPY_HMAC_KEY_LEN, derived.priv_key + 1,
+                                sizeof(derived.priv_key) - 1, bytes_out, len);
+        if (ret == WALLY_OK)
+            *written = len;
+    }
+    wally_clear(&derived, sizeof(derived));
+    return ret;
+}
diff --git a/src/mnemonic.h b/src/mnemonic.h
@@ -18,13 +18,13 @@ char *mnemonic_from_bytes(
     size_t len);
 
 /**
- * Convert a mnemonic representation into a block of bytes.
+ * Convert a mnemonic representation into bytes.
  *
  * @w: List of words.
  * @mnemonic: Mnemonic sentence to store.
- * @bytes_out: Where to store the converted representation.
+ * @bytes_out: Destination for the resulting bytes.
  * @len: The length of @bytes_out in bytes.
- * @written: Destination for the number of bytes written.
+ * @written: Destination for the number of bytes written to ``bytes_out``.
  */
 int mnemonic_to_bytes(
     const struct words *w,
diff --git a/src/swig_java/jni_extra.java_in b/src/swig_java/jni_extra.java_in
@@ -118,6 +118,12 @@
       return trimBuffer(buf, len);
   }
 
+  public final static byte[] bip85_get_rsa_entropy(Object hdkey, long key_bits, long index) {
+      final byte[] buf = new byte[HMAC_SHA512_LEN];
+      final int len = bip85_get_rsa_entropy(hdkey, key_bits, index, buf);
+      return checkBuffer(buf, len);
+  }
+
   public final static byte[] ecdh(byte[] jarg1, byte[] jarg2) {
       return ecdh(jarg1, jarg2, null);
   }
diff --git a/src/swig_java/swig.i b/src/swig_java/swig.i
@@ -514,6 +514,7 @@ static jobjectArray create_jstringArray(JNIEnv *jenv, char **p, size_t len) {
 %returns_array_(bip39_mnemonic_to_seed512, 3, 4, BIP39_SEED_LEN_512);
 %returns_string(bip85_get_languages);
 %returns_size_t(bip85_get_bip39_entropy);
+%returns_size_t(bip85_get_rsa_entropy);
 %returns_string(wally_addr_segwit_from_bytes);
 %returns_size_t(wally_addr_segwit_get_version);
 %returns_size_t(wally_addr_segwit_n_get_version);
diff --git a/src/swig_python/python_extra.py_in b/src/swig_python/python_extra.py_in
@@ -144,6 +144,7 @@ bip38_to_private_key = _wrap_bin(bip38_to_private_key, EC_PRIVATE_KEY_LEN)
 bip39_mnemonic_to_bytes = _wrap_bin(bip39_mnemonic_to_bytes, BIP39_ENTROPY_MAX_LEN, resize=True)
 bip39_mnemonic_to_seed512 = _wrap_bin(bip39_mnemonic_to_seed512, BIP39_SEED_LEN_512)
 bip85_get_bip39_entropy = _wrap_bin(bip85_get_bip39_entropy, HMAC_SHA512_LEN, resize=True)
+bip85_get_rsa_entropy = _wrap_bin(bip85_get_rsa_entropy, HMAC_SHA512_LEN, resize=True)
 descriptor_get_key_origin_fingerprint = _wrap_bin(descriptor_get_key_origin_fingerprint, BIP32_KEY_FINGERPRINT_LEN)
 descriptor_to_script = _wrap_bin(descriptor_to_script, descriptor_to_script_get_maximum_length, resize=True)
 ec_private_key_bip341_tweak = _wrap_bin(ec_private_key_bip341_tweak, EC_PRIVATE_KEY_LEN)
diff --git a/src/test/test_bip85.py b/src/test/test_bip85.py
@@ -20,6 +20,20 @@
      'divorce twin tonight reason outdoor destroy simple truth cigar social volcano')
 ]
 
+# BIP85/RSA Vectors generated using https://github.com/akarve/bipsea/blob/main/tests/test_bip85.py#L127
+rsa_cases = [
+        ('b3415a819ba8175a7f11b949d75133725594ee3dcf6284dbec8fe6a625d0e0df757c148e576369f9405b19aec9356a848897de64202df8da4880a5f769aac297', 1024, 0),
+        ('ca1e93031427e4f086538f89b19f5f224719332c8a7b8c87db7eb81e4be935db24dcbc71873d0607ddd3876777cd158a2f061a5a5153413307df08fe5911a857', 1024, 1),
+        ('e3ff02b1f0b934357cc0952225bb0e90081005b0cc992c5ed22f6fb8e9c628a3a0f138f9324e33ed4ba7250e43dd66d725a4e4c683dcf5a3b4015b82bcf71934', 2048, 0),
+        ('b1b4d03eb9826aeb2fabc4529dc37da5eaaa9072d3e2b7e69da79862e2b9cd8131dbb5a9001612239cd96310f6be0417bd39c39500bf8a99ba5df32571866fe6', 2048, 1),
+        ('9bd8cb61fea01892ffd981b4da7aae22f32c9641e49c48104682e249a98f7911ed55035a52e085938291d64e34537e9cc0b730f42ae9183b5ddaac33a55764ea', 3072, 0),
+        ('fc49330db1352558f615651ae8d7840b083cce5c9e731e349847569d3813a3f7f605b5d66b178bf19fdd04bd7f48d2ddb07e16793703d17ee06c86e49e19a896', 3072, 1),
+        ('12a499947a142ee3ede9c0960061383f2564b5cc569327d0dd22f7887094676f2e5d5785cd4eb683990d12209ebf6f39a5c1b5e217ea66710260e99fbe4b2be3', 4096, 0),
+        ('a6fdf91d4f4a0cadaf3d20d638744b574306725aababa0ab7136f8f8b88c5a4c5ca6104646d695cd95a72ad15e6e6912e263762eab951bfcea8e9939ed7c03f4', 4096, 1),
+        ('b3a0baa54a6fa75363e2bc0809dafd20eacea8b4d0fba9ef26f9ea9c471e135c53c1f787fd6a7a02bf736bed620d44e5b4465856fae6c2ef2d620b730098f8e9', 8192, 0),
+        ('1b5f1ae261e9e36039cd7d55d25e71934a4f0a2fdd2d93b2f73fbd272d04257d6eba8f6ff6bc1ffe1d58f68b707b794e54e983e2f573991bb776b48b8ed9a1ca', 8192, 1),
+]
+
 # Additional test vectors
 extra_xpriv = 'xprv9s21ZrQH143K3pHDnUsnBxePpiB3pbhu3owZem9cVUPVQLknjYAhzDXGppVipPsLSnx8UM6cmSqh3nG6vUaPxn1EDNNqtF1eqi7XmdLt1v6'
 extra_cases = [
@@ -97,7 +111,7 @@ def test_invalid(self):
             ret, _ = bip85_get_bip39_entropy(*args)
             self.assertEqual(ret, WALLY_EINVAL)
 
-    def run_test_cases(self, master_key, cases):
+    def run_bip39_test_cases(self, master_key, cases):
         ret, all_langs = bip39_get_languages()
         all_langs = all_langs.split()
 
@@ -117,14 +131,22 @@ def run_test_cases(self, master_key, cases):
             ret = bip39_mnemonic_from_bytes(words, buf, expected_len)
             self.assertEqual(ret, (WALLY_OK, mnemonic))
 
+    def run_rsa_test_cases(self, master_key, rsa_cases):
+        buf = create_string_buffer(HMAC_SHA512_LEN)
+        for expected, key_bits, index in rsa_cases:
+            ret = bip85_get_rsa_entropy(master_key, key_bits, index, buf, HMAC_SHA512_LEN)
+            self.assertEqual(ret, (WALLY_OK, HMAC_SHA512_LEN))
+            self.assertEqual(h(buf[:HMAC_SHA512_LEN]), utf8(expected))
+
     def test_bip85_cases(self):
-        self.run_test_cases(self.master_key, cases)
+        self.run_bip39_test_cases(self.master_key, cases)
+        self.run_rsa_test_cases(self.master_key, rsa_cases)
 
     def test_additional_cases(self):
         extra_key = ext_key()
         ret = bip32_key_from_base58(utf8(extra_xpriv), byref(extra_key))
         self.assertEqual(ret, WALLY_OK)
-        self.run_test_cases(extra_key, extra_cases)
+        self.run_bip39_test_cases(extra_key, extra_cases)
 
 if __name__ == '__main__':
     unittest.main()
diff --git a/src/test/util.py b/src/test/util.py
@@ -256,6 +256,7 @@ class wally_psbt(Structure):
     ('bip39_mnemonic_validate', c_int, [c_void_p, c_char_p]),
     ('bip85_get_bip39_entropy', c_int, [POINTER(ext_key), c_char_p, c_uint32, c_uint32, c_void_p, c_size_t, c_size_t_p]),
     ('bip85_get_languages', c_int, [c_char_p_p]),
+    ('bip85_get_rsa_entropy', c_int, [POINTER(ext_key), c_uint32, c_uint32, c_void_p, c_size_t, c_size_t_p]),
     ('wally_addr_segwit_from_bytes', c_int, [c_void_p, c_size_t, c_char_p, c_uint32, c_char_p_p]),
     ('wally_addr_segwit_get_version', c_int, [c_char_p, c_char_p, c_uint32, c_size_t_p]),
     ('wally_addr_segwit_n_get_version', c_int, [c_char_p, c_size_t, c_char_p, c_size_t, c_uint32, c_size_t_p]),
diff --git a/src/wasm_package/src/functions.js b/src/wasm_package/src/functions.js
diff --git a/src/wasm_package/src/index.d.ts b/src/wasm_package/src/index.d.ts
@@ -110,6 +110,7 @@ export function bip39_mnemonic_to_seed512(mnemonic: string, passphrase: string):
 export function bip39_mnemonic_validate(w: Ref_words, mnemonic: string): void;
 export function bip85_get_bip39_entropy(hdkey: Ref_ext_key, lang: string, num_words: number, index: number): Buffer;
 export function bip85_get_languages(): string;
+export function bip85_get_rsa_entropy(hdkey: Ref_ext_key, key_bits: number, index: number): Buffer;
 export function bzero(bytes: Ref, bytes_len: number): void;
 export function cleanup(flags: number): void;
 export function coinselect_assets(values: BigUint64Array|Array<bigint>, target: bigint, attempts: bigint, io_ratio: number): Uint32Array;
diff --git a/tools/wasm_exports.sh b/tools/wasm_exports.sh
@@ -51,6 +51,7 @@ EXPORTED_FUNCTIONS="['_malloc','_free','_bip32_key_free' \
 ,'_bip39_mnemonic_validate' \
 ,'_bip85_get_bip39_entropy' \
 ,'_bip85_get_languages' \
+,'_bip85_get_rsa_entropy' \
 ,'_wally_addr_segwit_from_bytes' \
 ,'_wally_addr_segwit_get_version' \
 ,'_wally_addr_segwit_n_get_version' \

Original file line number	Diff line number	Diff line change
`@@ -212,7 +212,7 @@ WALLY_CORE_API int wally_hex_from_bytes(`
`212`	`212`	`* Convert a hexadecimal string to bytes.`
`213`	`213`	`*`
`214`	`214`	`* :param hex: String to convert.`
`215`		`- * :param bytes_out: Where to store the resulting bytes.`
	`215`	`+ * :param bytes_out: Destination for the resulting bytes.`
`216`	`216`	* :param len: The length of ``bytes_out`` in bytes.
`217`	`217`	* :param written: Destination for the number of bytes written to ``bytes_out``.
`218`	`218`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -118,6 +118,12 @@`
`118`	`118`	`return trimBuffer(buf, len);`
`119`	`119`	`}`
`120`	`120`
	`121`	`+ public final static byte[] bip85_get_rsa_entropy(Object hdkey, long key_bits, long index) {`
	`122`	`+ final byte[] buf = new byte[HMAC_SHA512_LEN];`
	`123`	`+ final int len = bip85_get_rsa_entropy(hdkey, key_bits, index, buf);`
	`124`	`+ return checkBuffer(buf, len);`
	`125`	`+ }`
	`126`	`+`
`121`	`127`	`public final static byte[] ecdh(byte[] jarg1, byte[] jarg2) {`
`122`	`128`	`return ecdh(jarg1, jarg2, null);`
`123`	`129`	`}`