hsmd: add preapprove invoice and keysend messages

common/hsm_version.h

@@ -11,7 +11,7 @@
 #define HSM_MIN_VERSION 1
 
 /* wire/hsmd_wire.csv contents version:
- *    dd89bf9323dff42200003fb864abb6608f3aa645b636fdae3ec81d804ac05196
+ *    edd3d288fc88a5470adc2f99abcbfe4d4af29fae0c7a80b4226f28810a815524
  */
-#define HSM_MAX_VERSION 2
+#define HSM_MAX_VERSION 3
 #endif /* LIGHTNING_COMMON_HSM_VERSION_H */

common/jsonrpc_errors.h

@@ -46,6 +46,8 @@ enum jsonrpc_errcode {
 	PAY_STOPPED_RETRYING = 210,
 	PAY_STATUS_UNEXPECTED = 211,
 	PAY_INVOICE_REQUEST_INVALID = 212,
+	PAY_INVOICE_PREAPPROVAL_DECLINED = 213,
+	PAY_KEYSEND_PREAPPROVAL_DECLINED = 214,
 
 	/* `fundchannel` or `withdraw` errors */
 	FUND_MAX_EXCEEDED = 300,

doc/Makefile

@@ -75,6 +75,8 @@ MANPAGES := doc/lightning-cli.1 \
 	doc/lightning-pay.7 \
 	doc/lightning-parsefeerate.7 \
 	doc/lightning-plugin.7 \
+	doc/lightning-preapproveinvoice.7 \
+	doc/lightning-preapprovekeysend.7 \
 	doc/lightning-recoverchannel.7 \
 	doc/lightning-reserveinputs.7 \
 	doc/lightning-sendinvoice.7 \

doc/index.rst

@@ -105,6 +105,8 @@ Core Lightning Documentation
    lightning-pay <lightning-pay.7.md>
    lightning-ping <lightning-ping.7.md>
    lightning-plugin <lightning-plugin.7.md>
+   lightning-preapproveinvoice <lightning-preapproveinvoice.7.md>
+   lightning-preapprovekeysend <lightning-preapprovekeysend.7.md>
    lightning-recoverchannel <lightning-recoverchannel.7.md>
    lightning-reserveinputs <lightning-reserveinputs.7.md>
    lightning-sendcustommsg <lightning-sendcustommsg.7.md>

doc/lightning-preapproveinvoice.7.md

@@ -0,0 +1,51 @@
+lightning-preapproveinvoice -- Ask the HSM to preapprove an invoice (low-level)
+==================================================================
+
+SYNOPSIS
+--------
+
+**preapproveinvoice** *bolt11*
+
+DESCRIPTION
+-----------
+
+The **preapproveinvoice** RPC command submits the *bolt11* invoice to
+the HSM to check that it is approved for payment.
+
+Generally the **preapproveinvoice** request does not need to be made
+explicitly, it is automatically generated as part of a **pay** request.
+
+By default, the HSM will approve all **preapproveinvoice** requests.
+
+If a remote signer is being used it might decline an **preapproveinvoice**
+request because it would exceed velocity controls, is not covered by
+allowlist controls, was declined manually, or other reasons.
+
+If a remote signer declines a **preapproveinvoice** request a subsequent
+attempt to pay the invoice anyway will fail; the signer will refuse to sign
+the commitment.
+
+RETURN VALUE
+------------
+
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an empty object is returned.
+
+[comment]: # (GENERATE-FROM-SCHEMA-END)
+
+AUTHOR
+------
+
+Ken Sedgwick <<[email protected]>> is mainly responsible.
+
+SEE ALSO
+--------
+
+lightning-pay(7)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>
+
+[comment]: # ( SHA256STAMP:735dd61146b04745f1e884037ead662a386fec2c41e2de1a8698d6bb03f63540)

doc/lightning-preapprovekeysend.7.md

@@ -0,0 +1,61 @@
+lightning-preapprovekeysend -- Ask the HSM to preapprove a keysend payment (low-level)
+==================================================================
+
+SYNOPSIS
+--------
+
+**preapprovekeysend** *destination* *payment\_hash* *amount\_msat*
+
+DESCRIPTION
+-----------
+
+The **preapprovekeysend** RPC command submits the *destination*, *payment\_hash*,
+and *amount\_msat* parameters to the HSM to check that they are approved as a
+keysend payment.
+
+*destination* is a 33 byte, hex-encoded, node ID of the node that the payment should go to.
+
+*payment\_hash* is the unique identifier of a payment.
+
+*amount\_msat* is the amount to send in millisatoshi precision; it can
+be a whole number, or a whole number with suffix `msat` or `sat`, or a
+three decimal point number with suffix `sat`, or an 1 to 11 decimal
+point number suffixed by `btc`.
+
+Generally the **preapprovekeysend** request does not need to be made
+explicitly, it is automatically generated as part of a **keysend** request.
+
+By default, the HSM will approve all **preapprovekeysend** requests.
+
+If a remote signer is being used it might decline an **preapprovekeysend**
+request because it would exceed velocity controls, is not covered by
+allowlist controls, was declined manually, or other reasons.
+
+If a remote signer declines a **preapprovekeysend** request a subsequent
+attempt to pay the keysend anyway will fail; the signer will refuse to sign
+the commitment.
+
+RETURN VALUE
+------------
+
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an empty object is returned.
+
+[comment]: # (GENERATE-FROM-SCHEMA-END)
+
+AUTHOR
+------
+
+Ken Sedgwick <<[email protected]>> is mainly responsible.
+
+SEE ALSO
+--------
+
+lightning-keysend(7)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>
+
+[comment]: # ( SHA256STAMP:735dd61146b04745f1e884037ead662a386fec2c41e2de1a8698d6bb03f63540)

doc/schemas/preapproveinvoice.request.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "bolt11"
+  ],
+  "properties": {
+    "bolt11": {
+      "type": "string",
+      "added": "v23.02"
+    }
+  }
+}

doc/schemas/preapproveinvoice.schema.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {}
+}

doc/schemas/preapprovekeysend.request.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "destination",
+    "payment_hash",
+    "amount_msat"
+  ],
+  "properties": {
+    "destination": {
+      "type": "pubkey",
+      "added": "v23.02"
+    },
+    "payment_hash": {
+      "type": "hex",
+      "added": "v23.02",
+      "description": "the hash of the *payment_preimage* which will prove payment",
+      "maxLength": 64,
+      "minLength": 64
+    },
+    "amount_msat": {
+      "type": "msat",
+      "added": "v23.02"
+    }
+  }
+}

doc/schemas/preapprovekeysend.schema.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {}
+}

hsmd/hsmd.c

@@ -444,7 +444,7 @@ static struct io_plan *init_hsm(struct io_conn *conn,
 	struct secret *hsm_encryption_key;
 	struct bip32_key_version bip32_key_version;
 	u32 minversion, maxversion;
-	const u32 our_minversion = 2, our_maxversion = 2;
+	const u32 our_minversion = 2, our_maxversion = 3;
 
 	/* This must be lightningd. */
 	assert(is_lightningd(c));
@@ -668,6 +668,8 @@ static struct io_plan *handle_client(struct io_conn *conn, struct client *c)
 	case WIRE_HSMD_SIGN_MESSAGE:
 	case WIRE_HSMD_SIGN_OPTION_WILL_FUND_OFFER:
 	case WIRE_HSMD_SIGN_BOLT12:
+	case WIRE_HSMD_PREAPPROVE_INVOICE:
+	case WIRE_HSMD_PREAPPROVE_KEYSEND:
 	case WIRE_HSMD_ECDH_REQ:
 	case WIRE_HSMD_CHECK_FUTURE_SECRET:
 	case WIRE_HSMD_GET_OUTPUT_SCRIPTPUBKEY:
@@ -708,6 +710,8 @@ static struct io_plan *handle_client(struct io_conn *conn, struct client *c)
 	case WIRE_HSMD_SIGN_MESSAGE_REPLY:
 	case WIRE_HSMD_GET_OUTPUT_SCRIPTPUBKEY_REPLY:
 	case WIRE_HSMD_SIGN_BOLT12_REPLY:
+	case WIRE_HSMD_PREAPPROVE_INVOICE_REPLY:
+	case WIRE_HSMD_PREAPPROVE_KEYSEND_REPLY:
 		return bad_req_fmt(conn, c, c->msg_in,
 				   "Received an incoming message of type %s, "
 				   "which is not a request",

hsmd/hsmd_wire.csv

@@ -113,6 +113,24 @@ msgdata,hsmd_sign_invoice,hrp,u8,hrplen
 msgtype,hsmd_sign_invoice_reply,108
 msgdata,hsmd_sign_invoice_reply,sig,secp256k1_ecdsa_recoverable_signature,
 
+# Preapprove an invoice for payment
+msgtype,hsmd_preapprove_invoice,38
+msgdata,hsmd_preapprove_invoice,invstring,wirestring,
+
+# Result is true if approved, declined if false 
+msgtype,hsmd_preapprove_invoice_reply,138
+msgdata,hsmd_preapprove_invoice_reply,approved,bool,
+
+# Preapprove a keysend payment
+msgtype,hsmd_preapprove_keysend,39
+msgdata,hsmd_preapprove_keysend,destination,node_id,
+msgdata,hsmd_preapprove_keysend,payment_hash,sha256,
+msgdata,hsmd_preapprove_keysend,amount_msat,amount_msat,
+
+# Result is true if approved, declined if false 
+msgtype,hsmd_preapprove_keysend_reply,139
+msgdata,hsmd_preapprove_keysend_reply,approved,bool,
+
 # Give me ECDH(node-id-secret,point)
 msgtype,hsmd_ecdh_req,1
 msgdata,hsmd_ecdh_req,point,pubkey,

hsmd/libhsmd.c

@@ -119,6 +119,8 @@ bool hsmd_check_client_capabilities(struct hsmd_client *client,
 	case WIRE_HSMD_SIGN_MESSAGE:
 	case WIRE_HSMD_GET_OUTPUT_SCRIPTPUBKEY:
 	case WIRE_HSMD_SIGN_BOLT12:
+	case WIRE_HSMD_PREAPPROVE_INVOICE:
+	case WIRE_HSMD_PREAPPROVE_KEYSEND:
 	case WIRE_HSMD_DERIVE_SECRET:
 		return (client->capabilities & HSM_CAP_MASTER) != 0;
 
@@ -149,6 +151,8 @@ bool hsmd_check_client_capabilities(struct hsmd_client *client,
 	case WIRE_HSMD_SIGN_MESSAGE_REPLY:
 	case WIRE_HSMD_GET_OUTPUT_SCRIPTPUBKEY_REPLY:
 	case WIRE_HSMD_SIGN_BOLT12_REPLY:
+	case WIRE_HSMD_PREAPPROVE_INVOICE_REPLY:
+	case WIRE_HSMD_PREAPPROVE_KEYSEND_REPLY:
 	case WIRE_HSMD_DERIVE_SECRET_REPLY:
 		break;
 	}
@@ -659,6 +663,40 @@ static u8 *handle_sign_bolt12(struct hsmd_client *c, const u8 *msg_in)
 	return towire_hsmd_sign_bolt12_reply(NULL, &sig);
 }
 
+/*~ lightningd asks us to approve an invoice. This stub implementation
+ * is overriden by fully validating signers that need to track invoice
+ * payments. */
+static u8 *handle_preapprove_invoice(struct hsmd_client *c, const u8 *msg_in)
+{
+	char *invstring;
+	bool approved;
+	if (!fromwire_hsmd_preapprove_invoice(tmpctx, msg_in, &invstring))
+		return hsmd_status_malformed_request(c, msg_in);
+
+	/* This stub always approves */
+	approved = true;
+
+	return towire_hsmd_preapprove_invoice_reply(NULL, approved);
+}
+
+/*~ lightningd asks us to approve a keysend payment. This stub implementation
+ * is overriden by fully validating signers that need to track keysend
+ * payments. */
+static u8 *handle_preapprove_keysend(struct hsmd_client *c, const u8 *msg_in)
+{
+	struct node_id destination;
+	struct sha256 payment_hash;
+	struct amount_msat amount_msat;
+	bool approved;
+	if (!fromwire_hsmd_preapprove_keysend(msg_in, &destination, &payment_hash, &amount_msat))
+		return hsmd_status_malformed_request(c, msg_in);
+
+	/* This stub always approves */
+	approved = true;
+
+	return towire_hsmd_preapprove_keysend_reply(NULL, approved);
+}
+
 /*~ Lightning invoices, defined by BOLT 11, are signed.  This has been
  * surprisingly controversial; it means a node needs to be online to create
  * invoices.  However, it seems clear to me that in a world without
@@ -1572,6 +1610,10 @@ u8 *hsmd_handle_client_message(const tal_t *ctx, struct hsmd_client *client,
 		return handle_sign_option_will_fund_offer(client, msg);
 	case WIRE_HSMD_SIGN_BOLT12:
 		return handle_sign_bolt12(client, msg);
+	case WIRE_HSMD_PREAPPROVE_INVOICE:
+		return handle_preapprove_invoice(client, msg);
+	case WIRE_HSMD_PREAPPROVE_KEYSEND:
+		return handle_preapprove_keysend(client, msg);
 	case WIRE_HSMD_SIGN_MESSAGE:
 		return handle_sign_message(client, msg);
 	case WIRE_HSMD_GET_CHANNEL_BASEPOINTS:
@@ -1635,6 +1677,8 @@ u8 *hsmd_handle_client_message(const tal_t *ctx, struct hsmd_client *client,
 	case WIRE_HSMD_SIGN_MESSAGE_REPLY:
 	case WIRE_HSMD_GET_OUTPUT_SCRIPTPUBKEY_REPLY:
 	case WIRE_HSMD_SIGN_BOLT12_REPLY:
+	case WIRE_HSMD_PREAPPROVE_INVOICE_REPLY:
+	case WIRE_HSMD_PREAPPROVE_KEYSEND_REPLY:
 		break;
 	}
 	return hsmd_status_bad_request(client, msg, "Unknown request");

lightningd/hsm_control.c

@@ -104,6 +104,7 @@ struct ext_key *hsm_init(struct lightningd *ld)
 	}
 
 	ld->hsm_fd = fds[0];
+	u32 min_version = 3; /* payment modifiers need hsmd_preapprove_{invoice,keysend} */
 	if (!wire_sync_write(ld->hsm_fd, towire_hsmd_init(tmpctx,
 							 &chainparams->bip32_key_version,
 							 chainparams,
@@ -112,7 +113,7 @@ struct ext_key *hsm_init(struct lightningd *ld)
 							 IFDEV(ld->dev_force_bip32_seed, NULL),
 							 IFDEV(ld->dev_force_channel_secrets, NULL),
 							  IFDEV(ld->dev_force_channel_secrets_shaseed, NULL),
-							  HSM_MIN_VERSION,
+							  min_version,
 							  HSM_MAX_VERSION)))
 		err(EXITCODE_HSM_GENERIC_ERROR, "Writing init msg to hsm");