Enable the construction of blinded routes

Blinded routes can be provided as destinations for onion messages, when the
recipient prefers to remain anonymous.

We also add supporting utilities for constructing blinded path keys, and a
ControlTlvs struct representing blinded payloads prior to being
encoded/encrypted. These utilities and struct will be re-used in upcoming
commits for sending and receiving/forwarding onion messages.

Author: valentinewallace

lightning/src/ln/onion_message.rs

@@ -8,3 +8,254 @@
 // licenses.
 
 //! Onion Messages: sending, receiving, forwarding, and ancillary utilities live here
+use bitcoin::hashes::{Hash, HashEngine};
+use bitcoin::hashes::hmac::{Hmac, HmacEngine};
+use bitcoin::hashes::sha256::Hash as Sha256;
+use bitcoin::secp256k1::{self, PublicKey, Secp256k1, SecretKey};
+use bitcoin::secp256k1::ecdh::SharedSecret;
+
+use chain::keysinterface::{KeysInterface, Sign};
+use ln::msgs::DecodeError;
+use ln::onion_utils;
+use util::chacha20poly1305rfc::{ChaCha20Poly1305RFC, ChaChaPoly1305Writer};
+use util::ser::{Readable, VecWriter, Writeable, Writer};
+
+use core::ops::Deref;
+use io::{self, Read};
+use prelude::*;
+
+/// 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.
+pub(crate) 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>,
+	}
+}
+
+impl Writeable for ControlTlvs {
+	fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
+		match self {
+			ControlTlvs::Receive { path_id } => {
+				encode_tlv_stream!(writer, {
+					(6, path_id, option)
+				});
+			},
+			ControlTlvs::Forward { next_node_id, next_blinding_override } => {
+				encode_tlv_stream!(writer, {
+					(4, next_node_id, required),
+					(8, next_blinding_override, option)
+				});
+			},
+		}
+		Ok(())
+	}
+}
+
+impl Readable for ControlTlvs {
+	fn read<R: Read>(mut r: &mut R) -> Result<Self, DecodeError> {
+		let mut _padding: Option<Vec<u8>> = Some(Vec::new());
+		let mut _short_channel_id: Option<u64> = None;
+		let mut next_node_id: Option<PublicKey> = None;
+		let mut path_id: Option<[u8; 32]> = None;
+		let mut next_blinding_override: Option<PublicKey> = None;
+		decode_tlv_stream!(&mut r, {
+			(1, _padding, vec_type),
+			(2, _short_channel_id, option),
+			(4, next_node_id, option),
+			(6, path_id, option),
+			(8, next_blinding_override, option),
+		});
+
+		let valid_fwd_fmt  = next_node_id.is_some() && path_id.is_none();
+		let valid_recv_fmt = next_node_id.is_none() && next_blinding_override.is_none();
+
+		let payload_fmt = if valid_fwd_fmt {
+			ControlTlvs::Forward {
+				next_node_id: next_node_id.unwrap(),
+				next_blinding_override,
+			}
+		} else if valid_recv_fmt {
+			ControlTlvs::Receive {
+				path_id,
+			}
+		} else {
+			return Err(DecodeError::InvalidValue)
+		};
+		Ok(payload_fmt)
+	}
+}
+
+/// 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>,
+}
+
+/// Onion messages can be sent and received to blinded routes, which serve to hide the identity of
+/// the recipient.
+pub struct BlindedRoute {
+	/// To send to a blinded route, the sender first finds a route to the unblinded
+	/// `introduction_node_id`, which can unblind its [`encrypted_payload`] to find out the onion
+	/// message's next hop and forward it along.
+	///
+	/// [`encrypted_payload`]: BlindedNode::encrypted_payload
+	pub introduction_node_id: PublicKey,
+	/// Creators of blinded routes supply the introduction node id's `blinding_point`, which the
+	/// introduction node will use in decrypting its [`encrypted_payload`] to forward the onion
+	/// message.
+	///
+	/// [`encrypted_payload`]: BlindedNode::encrypted_payload
+	pub blinding_point: PublicKey,
+	/// The blinded hops of the blinded route.
+	pub blinded_hops: Vec<BlindedNode>,
+}
+
+impl BlindedRoute {
+	/// Create a blinded route to be forwarded along `hops`. The last node pubkey in `node_pks` will
+	/// be the destination node.
+	pub fn new<Signer: Sign, K: Deref>(node_pks: Vec<PublicKey>, keys_manager: &K) -> Result<Self, ()>
+		where K::Target: KeysInterface<Signer = Signer>,
+	{
+		if node_pks.len() <= 1 { return Err(()) }
+		let secp_ctx = Secp256k1::new();
+		let blinding_secret_bytes = keys_manager.get_secure_random_bytes();
+		let blinding_secret = SecretKey::from_slice(&blinding_secret_bytes[..]).expect("RNG is busted");
+		let (mut encrypted_data_keys, mut blinded_node_pks) = construct_blinded_route_keys(&secp_ctx, &node_pks, &blinding_secret).map_err(|_| ())?;
+		let mut blinded_hops = Vec::with_capacity(node_pks.len());
+		debug_assert_eq!(encrypted_data_keys.len(), blinded_node_pks.len());
+		let mut enc_tlvs_keys = encrypted_data_keys.drain(..);
+		let mut blinded_pks = blinded_node_pks.drain(..);
+
+		for pk in node_pks.iter().skip(1) {
+			let encrypted_tlvs = ControlTlvs::Forward {
+				next_node_id: pk.clone(),
+				next_blinding_override: None,
+			};
+			blinded_hops.push(BlindedNode {
+				blinded_node_id: blinded_pks.next().unwrap(),
+				encrypted_payload: Self::encrypt_payload(encrypted_tlvs, enc_tlvs_keys.next().unwrap()),
+			});
+		}
+
+		// Add the recipient final payload.
+		let encrypted_tlvs = ControlTlvs::Receive { path_id: Some([42; 32]) };
+		blinded_hops.push(BlindedNode {
+			blinded_node_id: blinded_pks.next().unwrap(),
+			encrypted_payload: Self::encrypt_payload(encrypted_tlvs, enc_tlvs_keys.next().unwrap()),
+		});
+
+		Ok(BlindedRoute {
+			introduction_node_id: node_pks[0].clone(),
+			blinding_point: PublicKey::from_secret_key(&secp_ctx, &blinding_secret),
+			blinded_hops,
+		})
+	}
+
+	fn encrypt_payload(payload: ControlTlvs, encrypted_tlvs_ss: SharedSecret) -> Vec<u8> {
+		let mut enc_tlvs_blob = VecWriter(Vec::new());
+		let (rho, _) = onion_utils::gen_rho_mu_from_shared_secret(encrypted_tlvs_ss.as_ref());
+		let mut chacha = ChaCha20Poly1305RFC::new(&rho, &[0; 12], &[]);
+		let mut chacha_stream = ChaChaPoly1305Writer { chacha: &mut chacha, write: &mut enc_tlvs_blob };
+		payload.write(&mut chacha_stream).expect("In-memory writes cannot fail");
+		let mut tag = [0 as u8; 16];
+		chacha.finish_and_get_tag(&mut tag);
+		tag.write(&mut enc_tlvs_blob).expect("In-memory writes cannot fail");
+		enc_tlvs_blob.0
+	}
+}
+
+#[allow(unused_assignments)]
+#[inline]
+fn construct_keys_callback<T: secp256k1::Signing + secp256k1::Verification, FType: FnMut(PublicKey, SharedSecret, [u8; 32], PublicKey, SharedSecret)> (secp_ctx: &Secp256k1<T>, unblinded_path: &Vec<PublicKey>, session_priv: &SecretKey, mut callback: FType) -> Result<(), secp256k1::Error> {
+	let mut msg_blinding_point_priv = session_priv.clone();
+	let mut msg_blinding_point = PublicKey::from_secret_key(secp_ctx, &msg_blinding_point_priv);
+	let mut onion_packet_pubkey_priv = msg_blinding_point_priv.clone();
+	let mut onion_packet_pubkey = msg_blinding_point.clone();
+
+	macro_rules! build_keys {
+		($pk: expr, $blinded: expr) => {
+			let encrypted_data_ss = SharedSecret::new(&$pk, &msg_blinding_point_priv);
+
+			let hop_pk_blinding_factor = {
+				let mut hmac = HmacEngine::<Sha256>::new(b"blinded_node_id");
+				hmac.input(encrypted_data_ss.as_ref());
+				Hmac::from_engine(hmac).into_inner()
+			};
+			let blinded_hop_pk = if $blinded { $pk.clone() } else {
+				let mut unblinded_pk = $pk.clone();
+				unblinded_pk.mul_assign(secp_ctx, &hop_pk_blinding_factor)?;
+				unblinded_pk
+			};
+			let onion_packet_ss = SharedSecret::new(&blinded_hop_pk, &onion_packet_pubkey_priv);
+
+			callback(blinded_hop_pk, onion_packet_ss, hop_pk_blinding_factor, onion_packet_pubkey, encrypted_data_ss);
+
+			let msg_blinding_point_blinding_factor = {
+				let mut sha = Sha256::engine();
+				sha.input(&msg_blinding_point.serialize()[..]);
+				sha.input(encrypted_data_ss.as_ref());
+				Sha256::from_engine(sha).into_inner()
+			};
+
+			msg_blinding_point_priv.mul_assign(&msg_blinding_point_blinding_factor)?;
+			msg_blinding_point = PublicKey::from_secret_key(secp_ctx, &msg_blinding_point_priv);
+
+			let onion_packet_pubkey_blinding_factor = {
+				let mut sha = Sha256::engine();
+				sha.input(&onion_packet_pubkey.serialize()[..]);
+				sha.input(onion_packet_ss.as_ref());
+				Sha256::from_engine(sha).into_inner()
+			};
+			onion_packet_pubkey.mul_assign(secp_ctx, &onion_packet_pubkey_blinding_factor)?;
+			onion_packet_pubkey_priv.mul_assign(&onion_packet_pubkey_blinding_factor)?;
+		};
+	}
+
+	for pk in unblinded_path {
+		build_keys!(pk, false);
+	}
+	Ok(())
+}
+
+/// Construct keys for constructing a blinded route along the given `unblinded_path`.
+///
+/// Returns: `(encrypted_tlvs_keys, blinded_node_ids)`
+/// where the encrypted tlvs keys are used to encrypt the blinded route's blinded payloads and the
+/// blinded node ids are used to set the [`blinded_node_id`]s of the [`BlindedRoute`].
+fn construct_blinded_route_keys<T: secp256k1::Signing + secp256k1::Verification>(
+	secp_ctx: &Secp256k1<T>, unblinded_path: &Vec<PublicKey>, session_priv: &SecretKey
+) -> Result<(Vec<SharedSecret>, Vec<PublicKey>), secp256k1::Error> {
+	let mut encrypted_data_keys = Vec::with_capacity(unblinded_path.len());
+	let mut blinded_node_pks = Vec::with_capacity(unblinded_path.len());
+
+	construct_keys_callback(secp_ctx, unblinded_path, session_priv, |blinded_hop_pubkey, _, _, _, encrypted_data_ss| {
+		blinded_node_pks.push(blinded_hop_pubkey);
+		encrypted_data_keys.push(encrypted_data_ss);
+	})?;
+
+	Ok((encrypted_data_keys, blinded_node_pks))
+}