bip32.h (7774B)
1 2 #ifndef LIBWALLY_CORE_BIP32_H 3 #define LIBWALLY_CORE_BIP32_H 4 5 #include <stdint.h> 6 #include "secp256k1.h" 7 8 /** The required lengths of entropy for `bip32_key_from_seed` */ 9 #define BIP32_ENTROPY_LEN_128 16 10 #define BIP32_ENTROPY_LEN_256 32 11 #define BIP32_ENTROPY_LEN_512 64 12 13 /** Length of an ext_key serialized using BIP32 format */ 14 #define BIP32_SERIALIZED_LEN 78 15 16 /** Child number of the first hardened child */ 17 #define BIP32_INITIAL_HARDENED_CHILD 0x80000000 18 19 /** Indicate that we want to derive a private key in `bip32_key_from_parent` */ 20 #define BIP32_FLAG_KEY_PRIVATE 0x0 21 /** Indicate that we want to derive a public key in `bip32_key_from_parent` */ 22 #define BIP32_FLAG_KEY_PUBLIC 0x1 23 /** Indicate that we want to skip hash calculation when deriving a key in `bip32_key_from_parent` */ 24 #define BIP32_FLAG_SKIP_HASH 0x2 25 26 /** Version codes for extended keys */ 27 #define BIP32_VER_MAIN_PUBLIC 0x0488B21E 28 #define BIP32_VER_MAIN_PRIVATE 0x0488ADE4 29 #define BIP32_VER_TEST_PUBLIC 0x043587CF 30 #define BIP32_VER_TEST_PRIVATE 0x04358394 31 32 /** An extended key */ 33 struct ext_key { 34 /** The chain code for this key */ 35 unsigned char chain_code[32]; 36 /** The Hash160 of this keys parent */ 37 unsigned char parent160[20]; 38 /** The depth of this key */ 39 uint8_t depth; 40 unsigned char pad1[10]; 41 /** The private key with prefix byte 0 */ 42 unsigned char priv_key[33]; 43 /** The child number of the parent key that this key represents */ 44 uint32_t child_num; 45 /** The Hash160 of this key */ 46 unsigned char hash160[20]; 47 /** The version code for this key indicating main/testnet and private/public */ 48 uint32_t version; 49 unsigned char pad2[3]; 50 /** The public key with prefix byte 0x2 or 0x3 */ 51 unsigned char pub_key[33]; 52 }; 53 54 /** 55 * Free a key allocated by `bip32_key_from_seed_alloc` 56 * or `bip32_key_unserialize_alloc`. 57 * 58 * :param hdkey: Key to free. 59 */ 60 int bip32_key_free(const struct ext_key *hdkey); 61 62 /** 63 */ 64 65 int bip32_key_init_alloc( 66 const secp256k1_context *ctx, 67 uint32_t version, uint32_t depth, uint32_t child_num, 68 const unsigned char *chain_code, size_t chain_code_len, 69 const unsigned char *pub_key, size_t pub_key_len, 70 const unsigned char *priv_key, size_t priv_key_len, 71 const unsigned char *hash160, size_t hash160_len, 72 const unsigned char *parent160, size_t parent160_len, 73 struct ext_key **output 74 ); 75 76 77 /** 78 * Create a new master extended key from entropy. 79 * 80 * This creates a new master key, i.e. the root of a new HD tree. 81 * The entropy passed in may produce an invalid key. If this happens, 82 * WALLY_ERROR will be returned and the caller should retry with 83 * new entropy. 84 * 85 * :param bytes: Entropy to use. 86 * :param bytes_len: Size of ``bytes`` in bytes. Must be one of ``BIP32_ENTROPY_LEN_128``, 87 *| ``BIP32_ENTROPY_LEN_256`` or ``BIP32_ENTROPY_LEN_512``. 88 * :param version: Either ``BIP32_VER_MAIN_PRIVATE`` or ``BIP32_VER_TEST_PRIVATE``, 89 *| indicating mainnet or testnet/regtest respectively. 90 * :param flags: Either ``BIP32_FLAG_SKIP_HASH`` to skip hash160 calculation, or 0. 91 * :param output: Destination for the resulting master extended key. 92 */ 93 int bip32_key_from_seed( 94 const secp256k1_context *ctx, 95 const unsigned char *bytes, 96 size_t bytes_len, 97 uint32_t version, 98 uint32_t flags, 99 struct ext_key *output); 100 101 /** 102 * As per `bip32_key_from_seed`, but allocates the key. 103 * 104 * .. note:: The returned key should be freed with `bip32_key_free`. 105 */ 106 int bip32_key_from_seed_alloc( 107 const secp256k1_context *ctx, 108 const unsigned char *bytes, 109 size_t bytes_len, 110 uint32_t version, 111 uint32_t flags, 112 struct ext_key **output); 113 114 /** 115 * Serialize an extended key to memory using BIP32 format. 116 * 117 * :param hdkey: The extended key to serialize. 118 * :param flags: BIP32_FLAG_KEY_ Flags indicating which key to serialize. You can not 119 *| serialize a private extended key from a public extended key. 120 * :param bytes_out: Destination for the serialized key. 121 * :param len: Size of ``bytes_out`` in bytes. Must be ``BIP32_SERIALIZED_LEN``. 122 */ 123 int bip32_key_serialize( 124 const struct ext_key *hdkey, 125 uint32_t flags, 126 unsigned char *bytes_out, 127 size_t len); 128 129 130 /** 131 * Un-serialize an extended key from memory. 132 * 133 * :param bytes: Storage holding the serialized key. 134 * :param bytes_len: Size of ``bytes`` in bytes. Must be ``BIP32_SERIALIZED_LEN``. 135 * :param output: Destination for the resulting extended key. 136 */ 137 int bip32_key_unserialize( 138 const secp256k1_context *ctx, 139 const unsigned char *bytes, 140 size_t bytes_len, 141 struct ext_key *output); 142 143 /** 144 * As per `bip32_key_unserialize`, but allocates the key. 145 * 146 * .. note:: The returned key should be freed with `bip32_key_free`. 147 */ 148 int bip32_key_unserialize_alloc( 149 const secp256k1_context *ctx, 150 const unsigned char *bytes, 151 size_t bytes_len, 152 struct ext_key **output); 153 154 /** 155 * Create a new child extended key from a parent extended key. 156 * 157 * :param hdkey: The parent extended key. 158 * :param child_num: The child number to create. Numbers greater 159 *| than or equal to ``BIP32_INITIAL_HARDENED_CHILD`` represent 160 *| hardened keys that cannot be created from public parent 161 *| extended keys. 162 * :param flags: BIP32_FLAG_KEY_ Flags indicating the type of derivation wanted. 163 *| You can not derive a private child extended key from a public 164 *| parent extended key. 165 * :param output: Destination for the resulting child extended key. 166 */ 167 int bip32_key_from_parent( 168 const secp256k1_context *ctx, 169 const struct ext_key *hdkey, 170 uint32_t child_num, 171 uint32_t flags, 172 struct ext_key *output); 173 174 /** 175 * As per `bip32_key_from_parent`, but allocates the key. 176 * 177 * .. note:: The returned key should be freed with `bip32_key_free`. 178 */ 179 int bip32_key_from_parent_alloc( 180 const secp256k1_context *ctx, 181 const struct ext_key *hdkey, 182 uint32_t child_num, 183 uint32_t flags, 184 struct ext_key **output); 185 186 /** 187 * Create a new child extended key from a parent extended key and a path. 188 * 189 * :param hdkey: The parent extended key. 190 * :param child_path: The path of child numbers to create. 191 * :param child_path_len: The number of child numbers in ``child_path``. 192 * :param flags: BIP32_KEY_ Flags indicating the type of derivation wanted. 193 * :param output: Destination for the resulting child extended key. 194 */ 195 int bip32_key_from_parent_path( 196 const secp256k1_context *ctx, 197 const struct ext_key *hdkey, 198 const uint32_t *child_path, 199 size_t child_path_len, 200 uint32_t flags, 201 struct ext_key *output); 202 203 /** 204 * As per `bip32_key_from_parent_path`, but allocates the key. 205 * 206 * .. note:: The returned key should be freed with `bip32_key_free`. 207 */ 208 int bip32_key_from_parent_path_alloc( 209 const secp256k1_context *ctx, 210 const struct ext_key *hdkey, 211 const uint32_t *child_path, 212 size_t child_path_len, 213 uint32_t flags, 214 struct ext_key **output); 215 216 /** 217 * Convert an extended key to base58. 218 * 219 * :param hdkey: The extended key. 220 * :param flags: BIP32_FLAG_KEY_ Flags indicating which key to serialize. You can not 221 *| serialize a private extended key from a public extended key. 222 * :param output: Destination for the resulting key in bas58. 223 */ 224 int bip32_key_to_base58( 225 const struct ext_key *hdkey, 226 uint32_t flags, 227 char **output); 228 229 /** 230 * Convert a base58 encoded extended key to an extended key. 231 * 232 * :param wif: The extended key in base58. 233 * :param output: Destination for the resulting extended key. 234 */ 235 236 int bip32_key_from_base58( 237 const secp256k1_context *ctx, 238 const char *base58, 239 struct ext_key *output); 240 241 /** 242 * As per `bip32_key_from_base58`, but allocates the key. 243 * 244 * .. note:: The returned key should be freed with `bip32_key_free`. 245 */ 246 int bip32_key_from_base58_alloc( 247 const secp256k1_context *ctx, 248 const char *base58, struct ext_key **output); 249 250 #endif /* LIBWALLY_CORE_BIP32_H */