Sending onion messages -- internal api changes

This commit covers the internal refactors needed for sending onion
messages and docs updates

Author: valentinewallace

lightning/src/ln/onion_message.rs

@@ -1,9 +1,79 @@
+/// The payload of an onion message.
+struct Payload {
+	/// Onion message payloads contain an encrypted TLV stream, containing both "control" TLVs and
+	/// sometimes user-provided custom "data" TLVs. See [`EncryptedTlvs`] for more information.
+	encrypted_tlvs: EncryptedTlvs,
+	// Coming soon:
+	// message: Message
+
+	// Coming soon: custom TLVs
+
+	// Coming soon:
+	// reply_path: BlindedRoute,
+}
+
+impl Writeable for Payload {
+	fn write<W: Writer>(&self, w: &mut W) -> Result<(), io::Error> {
+		// calls:
+		// * ChaCha20Poly1305RFC::encrypt_in_place
+	}
+}
+
+// Coming soon:
+// enum Message {
+// 	InvoiceRequest(InvoiceRequest),
+// 	Invoice(Invoice),
+//	InvoiceError(InvoiceError),
+
+/// Onion messages contain an encrypted TLV stream. This can be supplied by someone else, in the
+/// case that we're sending to a blinded route, or created by us if we're constructing payloads for
+/// unblinded hops in the onion message's path.
+enum EncryptedTlvs {
+	/// If we're sending to a blinded route, the node that constructed the blinded route has provided
+	/// our onion message's `EncryptedTlvs`, already encrypted and encoded into bytes.
+	Blinded(Vec<u8>),
+	/// If we're receiving an onion message or constructing an onion message to send through any
+	/// unblinded nodes, we'll need to construct the onion message's `EncryptedTlvs` in their
+	/// unblinded state to avoid encoding them into an intermediate `Vec`.
+	// Below will later have an additional Vec<CustomTlv>
+	Unblinded(ControlTlvs, SharedSecret),
+}
+
+/// Onion messages have "control" TLVs and "data" TLVs. Control TLVs are used to control the
+/// direction and routing of an onion message from hop to hop, whereas data TLVs contain the onion
+/// message content itself.
+enum ControlTlvs {
+	/// Control TLVs for the final recipient of an onion message.
+	Receive {
+		/// If `path_id` is `Some`, it is used to identify the blinded route that this onion message is
+		/// sending to. This is useful for receivers to check that said blinded route is being used in
+		/// the right context.
+		path_id: Option<[u8; 32]>
+	},
+	/// Control TLVs for an intermediate forwarder of an onion message.
+	Forward {
+		/// The node id of the next hop in the onion message's path.
+		next_node_id: PublicKey,
+		/// Senders of onion messages have the option of specifying an overriding [`blinding_point`]
+		/// for forwarding nodes along the path. If this field is absent, forwarding nodes will
+		/// calculate the next hop's blinding point by multiplying the blinding point that they
+		/// received by a blinding factor.
+		///
+		/// [`blinding_point`]: crate::ln::msgs::OnionMessage::blinding_point
+		next_blinding_override: Option<PublicKey>,
+	}
+}
+
 /// Used to construct the blinded hops portion of a blinded route. These hops cannot be identified
 /// by outside observers and thus can be used to hide the identity of the recipient.
 pub struct BlindedNode {
 	/// The blinded node id of this hop in a blinded route.
 	pub blinded_node_id: PublicKey,
 	/// The encrypted payload intended for this hop in a blinded route.
+	// If we're sending to this blinded route, this payload will later be encoded into the
+	// [`EncryptedTlvs`] for the hop when constructing the onion packet for sending.
+	//
+	// [`EncryptedTlvs`]: EncryptedTlvs
 	pub encrypted_payload: Vec<u8>,
 }
 
@@ -74,14 +144,36 @@ impl<Signer: Sign, K: Deref> OnionMessager<Signer, K>
 
 	/// Send an empty onion message to `recipient`, routing it through `intermediate_nodes`.
 	// NOTE: sending custom TLVs and reply paths aren't included atm
-	pub fn send_onion_message(&self, recipient: Destination, intermediate_nodes: Vec<PublicKey>) -> Result<(), APIError> {}
+	pub fn send_onion_message(&self, recipient: Destination, intermediate_nodes: Vec<PublicKey>) -> Result<(), APIError> {
+		// calls:
+		// * construct_path_keys
+		// * build_payloads
+		// * onion_utils::construct_onion_message_packet
+	}
 }
 
 impl OnionMessageHandler for OnionMessager {
 	fn handle_onion_message(&self, peer_node_id: &PublicKey, msg: &msgs::OnionMessage) {
 	}
 }
 
+/// Construct keys for sending an onion message along the given `path`.
+///
+/// Returns: `(encrypted_tlvs_keys, onion_packet_keys, blinded_node_ids)`
+/// where the encrypted tlvs keys are used to encrypt the `EncryptedTlvs` of the onion message, the
+/// onion packet keys are used to encrypt the onion packet, and the blinded node ids are used to set
+/// the [`blinded_node_id`]s if we're constructing a [`BlindedRoute`].
+///
+/// [`blinded_node_id`]: BlindedNode::blinded_node_id
+/// [`BlindedRoute`]: BlindedRoute
+fn construct_path_keys<T: secp256k1::Signing + secp256k1::Verification>(
+ secp_ctx: &Secp256k1<T>, unblinded_hops: Vec<PublicKey>, blinded_hops: Vec<PublicKey>,
+ session_priv: &SecretKey)
+-> Result<(Vec<SharedSecret>, Vec<onion_utils::OnionKeys>, Vec<PublicKey>), secp256k1::Error> {}
+
+/// Build an onion message's payloads for encoding in the onion packet.
+fn build_payloads(blinding_secret: SecretKey, intermediate_nodes: Vec<PublicKey>, destination: Destination, encrypted_data_keys: Vec<SharedSecret>) -> Vec<Payload> {}
+
 /// Useful for simplifying the parameters of [`SimpleArcChannelManager`] and
 /// [`SimpleArcPeerManager`]. See their docs for more details.
 pub type SimpleArcOnionMessager = OnionMessager<Arc<KeysManager>>;

lightning/src/ln/onion_utils.rs

@@ -208,6 +208,14 @@ pub(super) fn construct_onion_packet(payloads: Vec<msgs::OnionHopData>, onion_ke
 	construct_onion_packet_with_init_noise(payloads, onion_keys, packet_data, associated_data)
 }
 
+/// Constructs the onion routing packet for onion messages.
+//  NOTE: this could prob be DRY'd with `construct_onion_packet`, but it'd lead to a large-ish diff,
+//  and it's a small method.
+ pub(super) fn construct_onion_message_packet(payloads: Vec<onion_message::Payload>, onion_packet_keys: Vec<OnionKeys>, prng_seed: [u8; 32]) -> msgs::OnionPacket {
+	 // calls:
+	 // * construct_onion_packet_with_init_noise
+ }
+
 #[cfg(test)]
 // Used in testing to write bogus OnionHopDatas, which is otherwise not representable in
 // msgs::OnionHopData.
@@ -221,7 +229,8 @@ pub(super) fn construct_onion_packet_bogus_hopdata<HD: Writeable>(payloads: Vec<
 }
 
 /// panics if route_size_insane(paylods)
-fn construct_onion_packet_with_init_noise<HD: Writeable>(mut payloads: Vec<HD>, onion_keys: Vec<OnionKeys>, mut packet_data: [u8; ONION_DATA_LEN], associated_data: &PaymentHash) -> msgs::OnionPacket {
+ fn construct_onion_packet_with_init_noise<HD: Writeable>(mut payloads: Vec<HD>, onion_keys: Vec<OnionKeys>, mut packet_data: [u8; ONION_DATA_LEN], associated_data: Option<&PaymentHash>) -> msgs::OnionPacket {
+	// calls `onion_messages::Payload::write`
 	let filler = {
 		const ONION_HOP_DATA_LEN: usize = 65; // We may decrease this eventually after TLV is common
 		let mut res = Vec::with_capacity(ONION_HOP_DATA_LEN * (payloads.len() - 1));

lightning/src/util/chacha20poly1305rfc.rs

@@ -70,6 +70,10 @@ mod real_chachapoly {
 			self.mac.raw_result(out_tag);
 		}
 
+		pub fn encrypt_in_place(&mut self, input_output: &mut [u8], out_tag: &mut [u8]) {}
+
+		fn encrypt_inner(&mut self, input_output: &mut [u8], output: Option<&mut [u8]>, out_tag: &mut [u8]) {}
+
 		pub fn decrypt(&mut self, input: &[u8], output: &mut [u8], tag: &[u8]) -> bool {
 			assert!(input.len() == output.len());
 			assert!(self.finished == false);