Receiving/forwarding onion messages -- internal api changes

This commit covers the internal refactors needed for receiving and
forwarding onion messages, and docs updates.

Note that we support receiving custom TLVs, just not sending them.

lightning/src/ln/channelmanager.rs

@@ -2097,21 +2097,9 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 			},
 			onion_utils::Hop::Forward { next_hop_data, next_hop_hmac, new_packet_bytes } => {
 				let mut new_pubkey = msg.onion_routing_packet.public_key.unwrap();
-
-				let blinding_factor = {
-					let mut sha = Sha256::engine();
-					sha.input(&new_pubkey.serialize()[..]);
-					sha.input(&shared_secret);
-					Sha256::from_engine(sha).into_inner()
-				};
-
-				let public_key = if let Err(e) = new_pubkey.mul_assign(&self.secp_ctx, &blinding_factor[..]) {
-					Err(e)
-				} else { Ok(new_pubkey) };
-
 				let outgoing_packet = msgs::OnionPacket {
 					version: 0,
-					public_key,
+					public_key: onion_utils::next_hop_packet_pubkey(&new_pubkey, &shared_secret),
 					hop_data: new_packet_bytes,
 					hmac: next_hop_hmac.clone(),
 				};

lightning/src/ln/msgs.rs

@@ -1457,6 +1457,15 @@ impl Writeable for (OnionMsgPayload, [u8; 32]) {
 	}
 }
 
+/// Reads of `OnionMsgPayload`s are parameterized by the `rho` of a `SharedSecret`, which is used to
+/// decrypt the onion message's `encrypted_data` field.
+impl ReadableArgs<[u8; 32]> for OnionMsgPayload {
+	fn read<R: Read>(mut r: &mut R, encrypted_data_ss: [u8; 32]) -> Result<Self, DecodeError> {
+		// calls:
+		// * ChaCha20Poly1305RFC::decrypt_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

@@ -55,6 +55,9 @@ impl<Signer: Sign, K: Deref> OnionMessager<Signer, K>
 
 impl OnionMessageHandler for OnionMessager {
 	fn handle_onion_message(&self, peer_node_id: &PublicKey, msg: &msgs::OnionMessage) {
+		// calls:
+		// * onion_utils::decode_next_hop
+		// * onion_utils::next_hop_packet_pubkey
 	}
 }
 

lightning/src/ln/onion_utils.rs

@@ -73,6 +73,8 @@ pub(super) fn gen_ammag_from_shared_secret(shared_secret: &[u8]) -> [u8; 32] {
 	Hmac::from_engine(hmac).into_inner()
 }
 
+pub(super) fn next_hop_packet_pubkey(packet_pubkey: &PublicKey, packet_shared_secret: &SharedSecret) -> Result<PublicKey, secp256k1::Error> {}
+
 /// Used in the construction of keys to build the onion routing packet for payments and onion
 /// messages, in `construct_onion_keys_callback`.
 ///
@@ -547,15 +549,25 @@ pub(super) fn process_onion_failure<T: secp256k1::Signing, L: Deref>(secp_ctx: &
 	} else { unreachable!(); }
 }
 
+/// Used in the decoding of inbound payments' and onion messages' routing packets. This enum allows
+/// us to use `decode_next_hop` for returning the payloads and next hop packet bytes of both
+/// payments and onion messages.
+pub(crate) enum Payload {
+	/// This payload was for an incoming payment.
+	Payment(msgs::OnionPayload),
+	/// This payload was for an incoming onion message.
+	Message(msgs::OnionMsgPayload),
+}
+
 /// Data decrypted from the onion payload.
 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),
+	/// This onion payload was for us, not for forwarding to a next-hop. If we're receiving a payment,
+	/// this contains information for verifying the incoming payment.
+	Receive(Payload),
 	/// This onion payload needs to be forwarded to a next-hop.
 	Forward {
-		/// Onion payload data used in forwarding the payment.
-		next_hop_data: msgs::OnionHopData,
+		/// Onion payload data used in forwarding the payment or onion message.
+		next_hop_data: Payload,
 		/// HMAC of the next hop's onion packet.
 		next_hop_hmac: [u8; 32],
 		/// Bytes of the onion packet we're forwarding.
@@ -577,7 +589,18 @@ pub(crate) enum OnionDecodeErr {
 	},
 }
 
-pub(crate) fn decode_next_hop(shared_secret: [u8; 32], hop_data: &[u8], hmac_bytes: [u8; 32], payment_hash: PaymentHash) -> Result<Hop, OnionDecodeErr> {
+/// Used in the decoding of inbound payments' and onion messages' routing packets. This enum
+/// indicates whether the incoming packet corresponds to a payment or an onion message.
+pub(crate) enum Onion {
+	/// We're receiving an inbound payment, so the payment hash is provided as associated data for
+	/// calculating the packet hmac.
+	Payment(PaymentHash),
+	/// We're receiving an inbound onion message, so the `rho` is provided for decrypting the onion
+	/// message's `encrypted_data` field.
+	Message([u8; 32],
+}
+
+ pub(crate) fn decode_next_hop(shared_secret: [u8; 32], hop_data: &[u8], hmac_bytes: [u8; 32], onion_type: Onion) -> Result<Hop, OnionDecodeErr> {
 	let (rho, mu) = gen_rho_mu_from_shared_secret(&shared_secret);
 	let mut hmac = HmacEngine::<Sha256>::new(&mu);
 	hmac.input(hop_data);

lightning/src/util/chacha20poly1305rfc.rs

@@ -96,6 +96,10 @@ mod real_chachapoly {
 				false
 			}
 		}
+
+		pub fn decrypt_in_place(&mut self, input_output: &mut [u8], tag: &[u8]) -> bool {}
+
+		fn decrypt_inner(&mut self, input: &mut [u8], output: Option<&mut [u8]>, tag: &[u8]) -> bool {}
 	}
 }
 #[cfg(not(fuzzing))]

lightning/src/util/ser_macros.rs

@@ -165,6 +165,10 @@ macro_rules! decode_tlv {
 	}};
 }
 
+/// Decode a TLV stream that contains custom TLVs that are unknown to LDK but may be known to the
+/// user.
+macro_rules! decode_tlv_stream_with_custom {}
+
 macro_rules! decode_tlv_stream {
 	($stream: expr, {$(($type: expr, $field: ident, $fieldty: tt)),* $(,)*}) => { {
 		use ln::msgs::DecodeError;
@@ -231,6 +235,8 @@ macro_rules! decode_tlv_stream {
 	} }
 }
 
+macro_rules! decode_tlv_stream_inner {}
+
 macro_rules! impl_writeable_msg {
 	($st:ident, {$($field:ident),* $(,)*}, {$(($type: expr, $tlvfield: ident, $fieldty: tt)),* $(,)*}) => {
 		impl ::util::ser::Writeable for $st {