clightning-dumpkeys

dump clightning output descriptors
git clone git://jb55.com/clightning-dumpkeys
Log | Files | Refs | README | LICENSE

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 */