public onion utils, scid_utils, and utils for creating/peeling payment onions

Author: Evanfeenstra

lightning/src/ln/mod.rs

@@ -39,6 +39,7 @@ pub(crate) mod onion_utils;
 mod outbound_payment;
 pub mod wire;
 
+pub use onion_utils::{ForwardedPayment, PeeledPayment, ReceivedPayment, create_payment_onion, peel_payment_onion};
 // Older rustc (which we support) refuses to let us call the get_payment_preimage_hash!() macro
 // without the node parameter being mut. This is incorrect, and thus newer rustcs will complain
 // about an unnecessary mut. Thus, we silence the unused_mut warning in two test modules below.

lightning/src/ln/msgs.rs

@@ -1674,17 +1674,21 @@ pub use self::fuzzy_internal_msgs::*;
 #[cfg(not(fuzzing))]
 pub(crate) use self::fuzzy_internal_msgs::*;
 
+/// Bolt04 OnionPacket including hop data for the next peer
 #[derive(Clone)]
-pub(crate) struct OnionPacket {
-	pub(crate) version: u8,
+pub struct OnionPacket {
+	/// Bolt 04 version number
+	pub version: u8,
 	/// In order to ensure we always return an error on onion decode in compliance with [BOLT
 	/// #4](https://github.com/lightning/bolts/blob/master/04-onion-routing.md), we have to
 	/// deserialize `OnionPacket`s contained in [`UpdateAddHTLC`] messages even if the ephemeral
 	/// public key (here) is bogus, so we hold a [`Result`] instead of a [`PublicKey`] as we'd
 	/// like.
-	pub(crate) public_key: Result<PublicKey, secp256k1::Error>,
-	pub(crate) hop_data: [u8; 20*65],
-	pub(crate) hmac: [u8; 32],
+	pub public_key: Result<PublicKey, secp256k1::Error>,
+	/// 1300 bytes encrypted payload for the next hop
+	pub hop_data: [u8; 20*65],
+	/// HMAC to verify the integrity of hop_data
+	pub hmac: [u8; 32],
 }
 
 impl onion_utils::Packet for OnionPacket {

lightning/src/ln/onion_utils.rs

@@ -13,7 +13,7 @@ use crate::ln::msgs;
 use crate::ln::wire::Encode;
 use crate::routing::gossip::NetworkUpdate;
 use crate::routing::router::{BlindedTail, Path, RouteHop};
-use crate::sign::NodeSigner;
+use crate::sign::{NodeSigner, Recipient};
 use crate::util::chacha20::{ChaCha20, ChaChaReader};
 use crate::util::errors::{self, APIError};
 use crate::util::ser::{Readable, ReadableArgs, Writeable, Writer, LengthCalculatingWriter};
@@ -935,6 +935,160 @@ pub(crate) fn decode_next_payment_hop<NS: Deref>(
 	}
 }
 
+/// Build a payment onion, returning the first hop msat and cltv values as well.
+pub fn create_payment_onion<T>(
+	secp_ctx: &Secp256k1<T>, path: &Path, session_priv: &SecretKey, total_msat: u64, 
+	recipient_onion: RecipientOnionFields, starting_htlc_offset: u32, payment_hash: PaymentHash,
+	keysend_preimage: Option<PaymentPreimage>, prng_seed: [u8; 32]) -> Result<(u64, u32, msgs::OnionPacket), ()>
+where
+	T: secp256k1::Signing
+{
+	let onion_keys = construct_onion_keys(&secp_ctx, &path, &session_priv).map_err(|_| ())?;
+	let (onion_payloads, htlc_msat, htlc_cltv) = build_onion_payloads(
+        &path,
+        total_msat,
+        recipient_onion,
+        starting_htlc_offset,
+        &keysend_preimage,
+    ).map_err(|_| ())?;
+	let onion_packet = construct_onion_packet(onion_payloads, onion_keys, prng_seed, &payment_hash)?;
+	Ok((htlc_msat, htlc_cltv, onion_packet))
+}
+
+/// Forwarded Payment, including next hop details
+#[derive(Debug)]
+pub struct ForwardedPayment {
+	/// short channel id of the next hop
+	pub short_channel_id: u64,
+	/// The value, in msat, of the payment after this hop's fee is deducted.
+	pub amt_to_forward: u64,
+	/// outgoing CLTV for the next hop
+	pub outgoing_cltv_value: u32,
+	/// onion packet for the next hop
+	pub onion_packet: msgs::OnionPacket,
+}
+
+/// Received payment, of either regular or blinded type
+#[derive(Debug)]
+pub enum ReceivedPayment {
+	/// Regular (unblinded) payment
+	Regular {
+		/// payment_secret to authenticate sender to the receiver
+		payment_secret: Option<[u8; 32]>,
+		/// The total value, in msat, of the payment as received by the ultimate recipient
+		total_msat: Option<u64>,
+		/// custom payment metadata included in the payment
+		payment_metadata: Option<Vec<u8>>,
+		/// preimage used in spontaneous payment
+		keysend_preimage: Option<[u8; 32]>,
+		/// custom TLV records included in the payment
+		custom_tlvs: Vec<(u64, Vec<u8>)>,
+		/// amount received
+		amt_msat: u64,
+		/// outgoing ctlv
+		outgoing_cltv_value: u32,
+	},
+	/// Blinded payment
+	Blinded {
+		/// amount received
+		amt_msat: u64,
+		/// amount received plus fees paid
+		total_msat: u64,
+		/// outgoing cltv
+		outgoing_cltv_value: u32,
+		/// Payment secret 
+		payment_secret: [u8; 32],
+		/// The maximum total CLTV that is acceptable when relaying a payment over this hop
+		max_cltv_expiry: u32,
+		/// The minimum value, in msat, that may be accepted by the node corresponding to this hop
+		htlc_minimum_msat: u64,
+		/// Blinding point from intro node
+		intro_node_blinding_point: PublicKey,
+	}
+}
+
+impl std::convert::TryFrom<msgs::InboundOnionPayload> for ReceivedPayment {
+    type Error = ();
+    fn try_from(pld: msgs::InboundOnionPayload) -> Result<Self, Self::Error> {
+		match pld {
+			msgs::InboundOnionPayload::Forward { short_channel_id: _, amt_to_forward: _, outgoing_cltv_value: _ } => {
+				Err(())
+			},
+			msgs::InboundOnionPayload::Receive { payment_data, payment_metadata, keysend_preimage, custom_tlvs, amt_msat, outgoing_cltv_value } => {
+				let (payment_secret, total_msat) = match payment_data {
+					Some(p) => (Some(p.payment_secret.0), Some(p.total_msat)),
+					None => (None, None),
+				};
+				let keysend_preimage = keysend_preimage.map(|p| p.0);
+				Ok(Self::Regular { payment_secret, total_msat, payment_metadata, keysend_preimage, custom_tlvs, amt_msat, outgoing_cltv_value })
+			},
+			msgs::InboundOnionPayload::BlindedReceive { amt_msat, total_msat, outgoing_cltv_value, payment_secret, payment_constraints, intro_node_blinding_point } => {
+				let payment_secret = payment_secret.0;
+				let max_cltv_expiry = payment_constraints.max_cltv_expiry;
+				let htlc_minimum_msat = payment_constraints.htlc_minimum_msat;
+				Ok(Self::Blinded { amt_msat, total_msat, outgoing_cltv_value, payment_secret, max_cltv_expiry, htlc_minimum_msat, intro_node_blinding_point })
+			}
+		}
+    }
+}
+
+/// Received and decrypted onion payment, either of type Receive (for us), or Forward.
+#[derive(Debug)]
+pub enum PeeledPayment {
+	/// This onion payload was for us, not for forwarding to a next-hop.
+	Receive(ReceivedPayment),
+	/// This onion payload to be forwarded to next peer.
+	Forward(ForwardedPayment),
+}
+
+/// Unwrap one layer of an incoming HTLC, returning either or a received payment, or a another
+/// onion to forward.
+pub fn peel_payment_onion<NS: Deref>(
+	onion: &msgs::OnionPacket, payment_hash: PaymentHash, node_signer: &NS,
+	secp_ctx: &Secp256k1<secp256k1::All>
+) -> Result<PeeledPayment, ()> 
+where 
+	NS::Target: NodeSigner,
+{
+	if onion.public_key.is_err() {
+		return Err(());
+	}
+	let shared_secret = node_signer
+		.ecdh(Recipient::Node, &onion.public_key.unwrap(), None)
+		.unwrap()
+		.secret_bytes();
+
+	let hop = decode_next_payment_hop(shared_secret, &onion.hop_data[..], onion.hmac, payment_hash, node_signer).map_err(|_| ())?;
+	let peeled = match hop {
+		Hop::Forward { next_hop_data, next_hop_hmac, new_packet_bytes } => {
+			if let msgs::InboundOnionPayload::Forward{short_channel_id, amt_to_forward, outgoing_cltv_value} = next_hop_data {
+
+				let next_packet_pk = next_hop_pubkey(secp_ctx, onion.public_key.unwrap(), &shared_secret);
+
+				let onion_packet = msgs::OnionPacket {
+					version: 0,
+					public_key: next_packet_pk,
+					hop_data: new_packet_bytes,
+					hmac: next_hop_hmac,
+				};
+				PeeledPayment::Forward(ForwardedPayment{
+					short_channel_id,
+					amt_to_forward,
+					outgoing_cltv_value,
+					onion_packet,
+				})
+			} else {
+				return Err(());
+			}
+		},
+		Hop::Receive(inbound) => {
+			let payload: ReceivedPayment = inbound.try_into().map_err(|_| ())?;
+			PeeledPayment::Receive(payload)
+		},
+	};
+	Ok(peeled)
+}
+
 pub(crate) fn decode_next_untagged_hop<T, R: ReadableArgs<T>, N: NextPacketBytes>(shared_secret: [u8; 32], hop_data: &[u8], hmac_bytes: [u8; 32], read_args: T) -> Result<(R, Option<([u8; 32], N)>), OnionDecodeErr> {
 	decode_next_hop(shared_secret, hop_data, hmac_bytes, None, read_args)
 }
@@ -1235,4 +1389,103 @@ mod tests {
 			writer.write_all(&self.data[..])
 		}
 	}
+
+	#[test]
+	fn create_and_peel_payment_onion() {
+		use crate::ln::channelmanager::RecipientOnionFields;
+		use crate::ln::PaymentPreimage;
+		use std::convert::TryInto;
+		use super::{create_payment_onion, peel_payment_onion};
+		use super::{Sha256, Hash, PeeledPayment, ReceivedPayment};
+
+		let secp_ctx = Secp256k1::new();
+		let recipient_onion = RecipientOnionFields::spontaneous_empty();
+		let session_priv_bytes = [42; 32];
+		let session_priv = SecretKey::from_slice(&session_priv_bytes).unwrap();
+		let amt_msat = 1000;
+		let cur_height = 1000;
+		let preimage_bytes = [43; 32];
+		let preimage = PaymentPreimage(preimage_bytes);
+		let rhash = Sha256::hash(&preimage_bytes).to_vec();
+		let rhash_bytes: [u8; 32] = rhash.try_into().unwrap();
+		let payment_hash = PaymentHash(rhash_bytes);
+		let prng_seed = [44; 32];
+
+		// let alice = make_keys_manager(&[1; 32]);
+		let bob = make_keys_manager(&[2; 32]);
+		let bob_pk = PublicKey::from_secret_key(&secp_ctx, &bob.get_node_secret_key());
+		let charlie = make_keys_manager(&[3; 32]);
+		let charlie_pk = PublicKey::from_secret_key(&secp_ctx, &charlie.get_node_secret_key());
+
+		// make a route alice -> bob -> charlie
+		let bob_fee = 1;
+		let recipient_amount = 999;
+		let hops = vec![
+			RouteHop {
+				pubkey: bob_pk,
+				fee_msat: bob_fee,
+				cltv_expiry_delta: 0,
+				short_channel_id: 1,
+				node_features: NodeFeatures::empty(),
+				channel_features: ChannelFeatures::empty(),
+				maybe_announced_channel: false,
+			},
+			RouteHop {
+				pubkey: charlie_pk,
+				fee_msat: recipient_amount,
+				cltv_expiry_delta: 0,
+				short_channel_id: 2,
+				node_features: NodeFeatures::empty(),
+				channel_features: ChannelFeatures::empty(),
+				maybe_announced_channel: false,
+			}
+		];
+		let path = Path {
+			hops: hops,
+			blinded_tail: None,
+		};
+
+		let (_htlc_msat, _htlc_cltv, onion) = create_payment_onion(
+			&secp_ctx, &path, &session_priv, amt_msat, recipient_onion, cur_height, payment_hash, 
+			Some(preimage), prng_seed
+		).unwrap();
+
+		// bob peels to find another onion
+		let next_onion = match peel_payment_onion(&onion, payment_hash, &&bob, &secp_ctx).unwrap() {
+			PeeledPayment::Receive(_) => {
+				panic!("should not be a receive");
+			},
+			PeeledPayment::Forward(forwarded) => {
+				forwarded.onion_packet
+			},
+		};
+
+		// charlie peels to find a received payment
+		match peel_payment_onion(&next_onion, payment_hash, &&charlie, &secp_ctx).unwrap() {
+			PeeledPayment::Receive(received) => match received {
+				ReceivedPayment::Regular{amt_msat, keysend_preimage, ..} => {
+					assert_eq!(amt_msat, recipient_amount, "wrong received amount");
+					assert_eq!(Some(preimage_bytes), keysend_preimage, "wrong received preimage");
+				},
+				ReceivedPayment::Blinded{..} => {
+					panic!("should not be blinded");
+				}
+			},
+			PeeledPayment::Forward(_) => {
+				panic!("should not be a receive");
+			},
+		};
+
+	}
+
+	fn make_keys_manager(seed: &[u8; 32]) -> crate::sign::KeysManager {
+		use crate::sign::KeysManager;
+		use std::time::{SystemTime, UNIX_EPOCH};
+		let start = SystemTime::now();
+		let now = start
+			.duration_since(UNIX_EPOCH)
+			.expect("Time went backwards");
+		KeysManager::new(seed, now.as_secs(), now.subsec_nanos())
+	}
+
 }

lightning/src/onion_message/mod.rs

@@ -28,6 +28,7 @@ mod functional_tests;
 
 // Re-export structs so they can be imported with just the `onion_message::` module prefix.
 pub use self::messenger::{CustomOnionMessageHandler, DefaultMessageRouter, Destination, MessageRouter, OnionMessageContents, OnionMessagePath, OnionMessenger, PeeledOnion, PendingOnionMessage, SendError, SimpleArcOnionMessenger, SimpleRefOnionMessenger};
+pub use self::messenger::{create_onion_message, peel_onion_message};
 pub use self::offers::{OffersMessage, OffersMessageHandler};
 pub use self::packet::{Packet, ParsedOnionMessageContents};
 pub(crate) use self::packet::ControlTlvs;

lightning/src/util/mod.rs

@@ -20,6 +20,7 @@ pub mod ser;
 pub mod message_signing;
 pub mod invoice;
 pub mod persist;
+pub mod scid_utils;
 pub mod string;
 pub mod wakers;
 #[cfg(fuzzing)]
@@ -34,7 +35,6 @@ pub(crate) mod chacha20;
 pub(crate) mod poly1305;
 pub(crate) mod chacha20poly1305rfc;
 pub(crate) mod transaction_utils;
-pub(crate) mod scid_utils;
 pub(crate) mod time;
 
 pub mod indexed_map;

lightning/src/util/scid_utils.rs

@@ -7,6 +7,8 @@
 // You may not use this file except in accordance with one or both of these
 // licenses.
 
+//! Utils for constructing and parse short chan ids
+
 /// Maximum block height that can be used in a `short_channel_id`. This
 /// value is based on the 3-bytes available for block height.
 pub const MAX_SCID_BLOCK: u64 = 0x00ffffff;
@@ -22,8 +24,11 @@ pub const MAX_SCID_VOUT_INDEX: u64 = 0xffff;
 /// A `short_channel_id` construction error
 #[derive(Debug, PartialEq, Eq)]
 pub enum ShortChannelIdError {
+	/// Block too high
 	BlockOverflow,
+	/// TxIndex too high
 	TxIndexOverflow,
+	/// VoutIndex too high
 	VoutIndexOverflow,
 }
 
@@ -65,7 +70,7 @@ pub fn scid_from_parts(block: u64, tx_index: u64, vout_index: u64) -> Result<u64
 /// 2) phantom node payments, to get an scid for the phantom node's phantom channel
 /// 3) payments intended to be intercepted will route using a fake scid (this is typically used so
 ///    the forwarding node can open a JIT channel to the next hop)
-pub(crate) mod fake_scid {
+pub mod fake_scid {
 	use bitcoin::blockdata::constants::ChainHash;
 	use bitcoin::network::constants::Network;
 	use crate::sign::EntropySource;
@@ -90,9 +95,12 @@ pub(crate) mod fake_scid {
 	/// receipt, and handle the HTLC accordingly. The namespace identifier is encrypted when encoded
 	/// into the fake scid.
 	#[derive(Copy, Clone)]
-	pub(crate) enum Namespace {
+	pub enum Namespace {
+		/// Phantom short channel ids
 		Phantom,
+		/// Aliases for outbound channels
 		OutboundAlias,
+		/// Namespace for intercepted payments
 		Intercept
 	}
 
@@ -101,7 +109,7 @@ pub(crate) mod fake_scid {
 		/// between segwit activation and the current best known height, and the tx index and output
 		/// index are also selected from a "reasonable" range. We add this logic because it makes it
 		/// non-obvious at a glance that the scid is fake, e.g. if it appears in invoice route hints.
-		pub(crate) fn get_fake_scid<ES: Deref>(&self, highest_seen_blockheight: u32, chain_hash: &ChainHash, fake_scid_rand_bytes: &[u8; 32], entropy_source: &ES) -> u64
+		pub fn get_fake_scid<ES: Deref>(&self, highest_seen_blockheight: u32, chain_hash: &ChainHash, fake_scid_rand_bytes: &[u8; 32], entropy_source: &ES) -> u64
 			where ES::Target: EntropySource,
 		{
 			// Ensure we haven't created a namespace that doesn't fit into the 3 bits we've allocated for