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/msgs.rs

@@ -934,27 +934,27 @@ mod fuzzy_internal_msgs {
 	// These types aren't intended to be pub, but are exposed for direct fuzzing (as we deserialize
 	// them from untrusted input):
 	#[derive(Clone)]
-	pub(crate) struct FinalOnionHopData {
+	pub(crate) struct FinalOnionPayload {
 		pub(crate) payment_secret: PaymentSecret,
 		/// The total value, in msat, of the payment as received by the ultimate recipient.
 		/// Message serialization may panic if this value is more than 21 million Bitcoin.
 		pub(crate) total_msat: u64,
 	}
 
-	pub(crate) enum OnionHopDataFormat {
+	pub(crate) enum OnionPayloadFormat {
 		Legacy { // aka Realm-0
 			short_channel_id: u64,
 		},
-		NonFinalNode {
+		Forward {
 			short_channel_id: u64,
 		},
-		FinalNode {
+		Receive {
 			payment_data: Option<FinalOnionHopData>,
 			keysend_preimage: Option<PaymentPreimage>,
 		},
 	}
 
-	pub struct OnionHopData {
+	pub struct OnionPayload {
 		pub(crate) format: OnionHopDataFormat,
 		/// The value, in msat, of the payment after this hop's fee is deducted.
 		/// Message serialization may panic if this value is more than 21 million Bitcoin.
@@ -963,6 +963,27 @@ mod fuzzy_internal_msgs {
 		// 12 bytes of 0-padding for Legacy format
 	}
 
+	pub(crate) enum OnionMsgPayloadFormat {
+		Forward {
+			/// 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>,
+			/// The node id of the next hop in the onion message's path.
+			next_node_id: PublicKey,
+		},
+		Receive {
+			custom_tlvs: Vec<CustomTlv>,
+		}
+	}
+
+	pub struct OnionMsgPayload {
+		pub(crate) format: OnionMsgPayloadFormat,
+	}
+
 	pub struct DecodedOnionErrorPacket {
 		pub(crate) hmac: [u8; 32],
 		pub(crate) failuremsg: Vec<u8>,
@@ -1427,6 +1448,15 @@ impl Readable for OnionHopData {
 	}
 }
 
+/// Writes of `OnionMsgPayload`s are parameterized by the `rho` of a `SharedSecret`, which is used
+/// to encrypt the onion message's `encrypted_data` field.
+impl Writeable for (OnionMsgPayload, [u8; 32]) {
+	fn write<W: Writer>(&self, w: &mut W) -> Result<(), io::Error> {
+		// calls:
+		// * ChaCha20Poly1305RFC::encrypt_in_place
+	}
+}
+
 impl Writeable for Ping {
 	fn write<W: Writer>(&self, w: &mut W) -> Result<(), io::Error> {
 		self.ponglen.write(w)?;

lightning/src/ln/onion_message.rs

@@ -45,7 +45,12 @@ impl<Signer: Sign, K: Deref> OnionMessager<Signer, K>
 	/// LDK will not make peer connections for you, so you must be connected to the first hop of
 	/// `intermediate_nodes` for sending to work.
 	// NOTE: sending custom TLVs, reply paths, and sending to blinded routes aren't included atm
- 	pub fn send_onion_message(&self, recipient: PublicKey, intermediate_nodes: Vec<PublicKey>) -> Result<(), APIError> {}
+ 	pub fn send_onion_message(&self, recipient: PublicKey, intermediate_nodes: Vec<PublicKey>) -> Result<(), APIError> {
+		// calls:
+		// * onion_utils::construct_onion_message_keys
+		// * onion_utils::build_onion_message_payloads
+		// * onion_utils::construct_onion_message_packet
+	}
 }
 
 impl OnionMessageHandler for OnionMessager {

lightning/src/ln/onion_utils.rs

@@ -73,14 +73,31 @@ pub(super) fn gen_ammag_from_shared_secret(shared_secret: &[u8]) -> [u8; 32] {
 	Hmac::from_engine(hmac).into_inner()
 }
 
+/// Used in the construction of keys to build the onion routing packet for payments and onion
+/// messages, in `construct_onion_keys_callback`.
+///
+/// `construct_onion_keys_callback` needs to be able to take a path of `RouteHop`s, as we use the
+/// information in the `RouteHop` in processing onion faiilures. However, for onion messages, we
+/// don't have a `RouteHop` and instead only a list of node ids for the path. Thus this enum allows
+/// `construct_onion_keys_callback` to accommodate both use cases.
+pub(super) enum Hop {
+	PublicKey(&PublicKey),
+	Routing(&RouteHop),
+}
+
+impl Hop {
+	/// Retrieve the `Hop`'s node id.
+	fn pubkey(&self) -> &PublicKey {}
+}
+
 // can only fail if an intermediary hop has an invalid public key or session_priv is invalid
 #[inline]
-pub(super) fn construct_onion_keys_callback<T: secp256k1::Signing, FType: FnMut(SharedSecret, [u8; 32], PublicKey, &RouteHop, usize)> (secp_ctx: &Secp256k1<T>, path: &Vec<RouteHop>, session_priv: &SecretKey, mut callback: FType) -> Result<(), secp256k1::Error> {
+fn construct_onion_keys_callback<T: secp256k1::Signing, FType: FnMut(SharedSecret, [u8; 32], PublicKey, &Hop, usize)> (secp_ctx: &Secp256k1<T>, path: &Vec<Hop>, session_priv: &SecretKey, mut callback: FType) -> Result<(), secp256k1::Error> {
 	let mut blinded_priv = session_priv.clone();
 	let mut blinded_pub = PublicKey::from_secret_key(secp_ctx, &blinded_priv);
 
 	for (idx, hop) in path.iter().enumerate() {
-		let shared_secret = SharedSecret::new(&hop.pubkey, &blinded_priv);
+		let shared_secret = SharedSecret::new(hop.pubkey(), &blinded_priv);
 
 		let mut sha = Sha256::engine();
 		sha.input(&blinded_pub.serialize()[..]);
@@ -98,11 +115,20 @@ pub(super) fn construct_onion_keys_callback<T: secp256k1::Signing, FType: FnMut(
 	Ok(())
 }
 
+/// Construct keys for sending an onion message along the given `path`.
+///
+/// Returns keys for encrypting the `encrypted_data` field of the onion message and keys for
+/// encrypting the onion message's onion routing packet.
+pub(super) fn construct_onion_message_keys<T: secp256k1::Signing + secp256k1::Verification>(secp_ctx: &Secp256k1<T>, path: Vec<&PublicKey>, session_priv: &SecretKey) -> Result<(Vec<[u8; 32]>, Vec<OnionKeys>), secp256k1::Error> {
+	// calls `construct_onion_keys_callback`
+}
+
 // can only fail if an intermediary hop has an invalid public key or session_priv is invalid
 pub(super) fn construct_onion_keys<T: secp256k1::Signing>(secp_ctx: &Secp256k1<T>, path: &Vec<RouteHop>, session_priv: &SecretKey) -> Result<Vec<OnionKeys>, secp256k1::Error> {
 	let mut res = Vec::with_capacity(path.len());
 
-	construct_onion_keys_callback(secp_ctx, path, session_priv, |shared_secret, _blinding_factor, ephemeral_pubkey, _, _| {
+	let hops = path.iter().map(|hop| Hop::Routing(&hop));
+	construct_onion_keys_callback(secp_ctx, hops, session_priv, |shared_secret, _blinding_factor, ephemeral_pubkey, _, _| {
 		let (rho, mu) = gen_rho_mu_from_shared_secret(&shared_secret[..]);
 
 		res.push(OnionKeys {
@@ -119,6 +145,10 @@ pub(super) fn construct_onion_keys<T: secp256k1::Signing>(secp_ctx: &Secp256k1<T
 	Ok(res)
 }
 
+/// Builds an onion message payload for each hop in the `path`, ready to be encoded in the onion
+/// routing packet.
+pub(super) fn build_onion_message_payloads(mut path: Vec<PublicKey>) -> Result<Vec<msgs::OnionMsgPayload>, APIError> {}
+
 /// returns the hop data, as well as the first-hop value_msat and CLTV value we should send.
 pub(super) fn build_onion_payloads(path: &Vec<RouteHop>, total_msat: u64, payment_secret_option: &Option<PaymentSecret>, starting_htlc_offset: u32, keysend_preimage: &Option<PaymentPreimage>) -> Result<(Vec<msgs::OnionHopData>, u64, u32), APIError> {
 	let mut cur_value_msat = 0u64;
@@ -199,6 +229,8 @@ pub(super) fn route_size_insane(payloads: &Vec<msgs::OnionHopData>) -> bool {
 }
 
 /// panics if route_size_insane(paylods)
+// NOTE: I believe since onion messages can be variable size, we'll have to remove the panic
+// mentioned above^
 pub(super) fn construct_onion_packet(payloads: Vec<msgs::OnionHopData>, onion_keys: Vec<OnionKeys>, prng_seed: [u8; 32], associated_data: &PaymentHash) -> msgs::OnionPacket {
 	let mut packet_data = [0; ONION_DATA_LEN];
 
@@ -208,6 +240,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<msgs::OnionMsgPayload>, encrypted_data_keys: Vec<[u8; 32]>, 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 +261,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 `msgs::OnionMsgPayload::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));
@@ -507,7 +548,7 @@ pub(super) fn process_onion_failure<T: secp256k1::Signing, L: Deref>(secp_ctx: &
 }
 
 /// Data decrypted from the onion payload.
-pub(crate) enum Hop {
+pub(crate) enum HopPayload {
 	/// This onion payload was for us, not for forwarding to a next-hop. Contains information for
 	/// verifying the incoming payment.
 	Receive(msgs::OnionHopData),

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);