1 #ifndef LIGHTNING_HSMD_LIBHSMD_H 2 #define LIGHTNING_HSMD_LIBHSMD_H 3 4 #include <common/node_id.h> 5 #include <common/status_levels.h> 6 #include <hsmd/hsmd_wiregen.h> 7 8 /*~ A struct that holds some context about the origin of an 9 * incoming request. It can either be a main daemon client, which is 10 * not associated with a peer or channel, or a peer client, which does 11 * have an association. */ 12 struct hsmd_client { 13 /*~ Useful for logging, but also used to derive the per-channel seed. */ 14 struct node_id id; 15 16 /*~ This is a unique value handed to us from lightningd, used for 17 * per-channel seed generation (a single id may have multiple channels 18 * over time). 19 * 20 * It's actually zero for the initial lightningd client connection and 21 * the ones for gossipd and connectd, which don't have channels 22 * associated. */ 23 u64 dbid; 24 25 /* What is this client allowed to ask for? */ 26 u64 capabilities; 27 28 /* Params to apply to all transactions for this client */ 29 const struct chainparams *chainparams; 30 31 /* A pointer to extra context that is to be passed around with 32 * the request. Used in `hsmd` to determine which connection 33 * originated the request. It is passed to the `hsmd_status_*` 34 * functions to allow reporting errors to the client. */ 35 void *extra; 36 }; 37 38 /* Given the (unencrypted) base secret, intialize all derived secrets. 39 * 40 * While we ensure that the memory the internal secrets are stored in 41 * is secure (mlock), the caller must make sure that the `hsm_secret` 42 * argument is handled securely before this call to avoid potential 43 * issues. The function copies the secret, so the caller can free the 44 * secret after the call. 45 * 46 * Returns the `hsmd_init_reply` with the information required by 47 * `lightningd`. 48 */ 49 u8 *hsmd_init(struct secret hsm_secret, 50 struct bip32_key_version bip32_key_version); 51 52 struct hsmd_client *hsmd_client_new_main(const tal_t *ctx, u64 capabilities, 53 void *extra); 54 55 struct hsmd_client *hsmd_client_new_peer(const tal_t *ctx, u64 capabilities, 56 u64 dbid, 57 const struct node_id *peer_id, 58 void *extra); 59 60 /* Handle an incoming request with the provided context. Upon 61 * successful processing we return a response message that is 62 * allocated off of `ctx`. Failures return a `NULL` pointer, and the 63 * failure details were passed to `hsmd_failed`. */ 64 u8 *hsmd_handle_client_message(const tal_t *ctx, struct hsmd_client *client, 65 const u8 *msg); 66 67 /* Functions to report debugging information or errors. These must be 68 * implemented by the user of the library. */ 69 u8 *hsmd_status_bad_request(struct hsmd_client *client, const u8 *msg, 70 const char *error); 71 72 /* Send a printf-style debugging trace. */ 73 void hsmd_status_fmt(enum log_level level, 74 const struct node_id *peer, 75 const char *fmt, ...) 76 PRINTF_FMT(3,4); 77 78 #define hsmd_status_debug(...) \ 79 hsmd_status_fmt(LOG_DBG, NULL, __VA_ARGS__) 80 #define hsmd_status_broken(...) \ 81 hsmd_status_fmt(LOG_BROKEN, NULL, __VA_ARGS__) 82 83 void hsmd_status_failed(enum status_failreason code, 84 const char *fmt, ...) PRINTF_FMT(2,3); 85 86 /* Given a message type and a client that sent the message, determine 87 * whether the client was permitted to send such a message. */ 88 bool hsmd_check_client_capabilities(struct hsmd_client *client, 89 enum hsmd_wire t); 90 91 #endif /* LIGHTNING_HSMD_LIBHSMD_H */ 92