Offer metadata and signing pubkey derivation

Add support for deriving a transient signing pubkey for each Offer from
an ExpandedKey and a nonce. This facilitates recipient privacy by not
tying any Offer to any other nor to the recipient's node id.

Additionally, support stateless Offer verification by setting its
metadata using an HMAC over the nonce and the remaining TLV records,
which will be later verified when receiving an InvoiceRequest.

Author: jkczyz

lightning/src/ln/inbound_payment.rs

@@ -13,7 +13,8 @@ use alloc::string::ToString;
 use bitcoin::hashes::{Hash, HashEngine};
 use bitcoin::hashes::cmp::fixed_time_eq;
 use bitcoin::hashes::hmac::{Hmac, HmacEngine};
-use bitcoin::hashes::sha256::Hash as Sha256;
+use bitcoin::hashes::sha256::{Hash as Sha256, self};
+use bitcoin::secp256k1::{PublicKey, Secp256k1, SecretKey};
 use crate::chain::keysinterface::{KeyMaterial, EntropySource};
 use crate::ln::{PaymentHash, PaymentPreimage, PaymentSecret};
 use crate::ln::msgs;
@@ -66,6 +67,59 @@ impl ExpandedKey {
 			offers_base_key,
 		}
 	}
+
+	/// Returns an [`HmacEngine`] used to construct [`Offer::metadata`].
+	///
+	/// [`Offer::metadata`]: crate::offers::offer::Offer::metadata
+	#[allow(unused)]
+	pub(crate) fn hmac_for_offer(&self, nonce: Nonce) -> HmacEngine<Sha256> {
+		let mut hmac = HmacEngine::<Sha256>::new(&self.offers_base_key);
+		hmac.input(&nonce.0);
+		hmac
+	}
+
+	/// Derives a pubkey using the given nonce for use as [`Offer::signing_pubkey`].
+	///
+	/// [`Offer::signing_pubkey`]: crate::offers::offer::Offer::signing_pubkey
+	#[allow(unused)]
+	pub(crate) fn signing_pubkey_for_offer(&self, nonce: Nonce) -> PublicKey {
+		let mut engine = sha256::Hash::engine();
+		engine.input(&self.offers_base_key);
+		engine.input(&nonce.0);
+
+		let hash = sha256::Hash::from_engine(engine);
+		let secp_ctx = Secp256k1::new();
+		SecretKey::from_slice(&hash).unwrap().public_key(&secp_ctx)
+	}
+}
+
+/// A 128-bit number used only once.
+///
+/// Needed when constructing [`Offer::metadata`] and deriving [`Offer::signing_pubkey`] from
+/// [`ExpandedKey`].
+///
+/// [`Offer::metadata`]: crate::offers::offer::Offer::metadata
+/// [`Offer::signing_pubkey`]: crate::offers::offer::Offer::signing_pubkey
+#[allow(unused)]
+#[derive(Clone, Copy)]
+pub struct Nonce(pub(crate) [u8; Self::LENGTH]);
+
+impl Nonce {
+	/// Number of bytes in the nonce.
+	pub const LENGTH: usize = 16;
+
+	/// Creates a `Nonce` from the given [`EntropySource`].
+	pub fn from_entropy_source<ES: EntropySource>(entropy_source: &ES) -> Self {
+		let mut bytes = [0u8; Self::LENGTH];
+		let rand_bytes = entropy_source.get_secure_random_bytes();
+		bytes.copy_from_slice(&rand_bytes[..Self::LENGTH]);
+		Nonce(bytes)
+	}
+
+	/// Returns a slice of the underlying bytes of size [`Nonce::LENGTH`].
+	pub fn as_slice(&self) -> &[u8] {
+		&self.0
+	}
 }
 
 enum Method {

lightning/src/offers/mod.rs

@@ -19,5 +19,7 @@ pub mod offer;
 pub mod parse;
 mod payer;
 pub mod refund;
+#[allow(unused)]
+pub(crate) mod signer;
 #[cfg(test)]
 mod test_utils;

lightning/src/offers/offer.rs

@@ -75,9 +75,11 @@ use core::str::FromStr;
 use core::time::Duration;
 use crate::io;
 use crate::ln::features::OfferFeatures;
+use crate::ln::inbound_payment::{ExpandedKey, Nonce};
 use crate::ln::msgs::MAX_VALUE_MSAT;
 use crate::offers::invoice_request::InvoiceRequestBuilder;
 use crate::offers::parse::{Bech32Encode, ParseError, ParsedMessage, SemanticError};
+use crate::offers::signer::{MetadataMaterial, DerivedPubkey};
 use crate::onion_message::BlindedPath;
 use crate::util::ser::{HighZeroBytesDroppedBigSize, WithoutLength, Writeable, Writer};
 use crate::util::string::PrintableString;
@@ -94,6 +96,7 @@ use std::time::SystemTime;
 /// [module-level documentation]: self
 pub struct OfferBuilder {
 	offer: OfferContents,
+	metadata_material: Option<MetadataMaterial>,
 }
 
 impl OfferBuilder {
@@ -108,7 +111,28 @@ impl OfferBuilder {
 			features: OfferFeatures::empty(), absolute_expiry: None, issuer: None, paths: None,
 			supported_quantity: Quantity::One, signing_pubkey,
 		};
-		OfferBuilder { offer }
+		OfferBuilder { offer, metadata_material: None }
+	}
+
+	/// Similar to [`OfferBuilder::new`] except it:
+	/// - derives the signing pubkey such that a different key can be used for each offer, and
+	/// - sets the metadata when [`OfferBuilder::build`] is called such that it can be used by
+	///   [`InvoiceRequest::verify`] to determine if the request was produced using a base
+	///   [`ExpandedKey`] from which the signing pubkey was derived.
+	///
+	/// [`InvoiceRequest::verify`]: crate::offers::invoice_request::InvoiceRequest::verify
+	/// [`ExpandedKey`]: crate::ln::inbound_payment::ExpandedKey
+	#[allow(unused)]
+	pub(crate) fn deriving_signing_pubkey(
+		description: String, signing_pubkey: DerivedPubkey
+	) -> Self {
+		let (signing_pubkey, metadata_material) = signing_pubkey.into_parts();
+		let offer = OfferContents {
+			chains: None, metadata: None, amount: None, description,
+			features: OfferFeatures::empty(), absolute_expiry: None, issuer: None, paths: None,
+			supported_quantity: Quantity::One, signing_pubkey,
+		};
+		OfferBuilder { offer, metadata_material: Some(metadata_material) }
 	}
 
 	/// Adds the chain hash of the given [`Network`] to [`Offer::chains`]. If not called,
@@ -127,12 +151,38 @@ impl OfferBuilder {
 		self
 	}
 
-	/// Sets the [`Offer::metadata`].
+	/// Sets the [`Offer::metadata`] to the given bytes.
 	///
-	/// Successive calls to this method will override the previous setting.
-	pub fn metadata(mut self, metadata: Vec<u8>) -> Self {
+	/// Successive calls to this method will override the previous setting. Errors if the builder
+	/// was constructed using a derived pubkey.
+	pub fn metadata(mut self, metadata: Vec<u8>) -> Result<Self, SemanticError> {
+		if self.metadata_material.is_some() {
+			return Err(SemanticError::UnexpectedMetadata);
+		}
+
 		self.offer.metadata = Some(metadata);
-		self
+		Ok(self)
+	}
+
+	/// Sets the [`Offer::metadata`] derived from the given `key` and any fields set prior to
+	/// calling [`OfferBuilder::build`]. Allows for stateless verification of an [`InvoiceRequest`]
+	/// when using a public node id as the [`Offer::signing_pubkey`] instead of a derived one.
+	///
+	/// Errors if already called or if the builder was constructed with
+	/// [`Self::deriving_signing_pubkey`].
+	///
+	/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+	#[allow(unused)]
+	pub(crate) fn metadata_derived(
+		mut self, key: &ExpandedKey, nonce: Nonce
+	) -> Result<Self, SemanticError> {
+		if self.metadata_material.is_some() {
+			return Err(SemanticError::UnexpectedMetadata);
+		}
+
+		self.offer.metadata = None;
+		self.metadata_material = Some(MetadataMaterial::new(nonce, key));
+		Ok(self)
 	}
 
 	/// Sets the [`Offer::amount`] as an [`Amount::Bitcoin`].
@@ -204,6 +254,16 @@ impl OfferBuilder {
 			}
 		}
 
+		// Create the metadata for stateless verification of an InvoiceRequest.
+		if let Some(mut metadata_material) = self.metadata_material {
+			debug_assert!(self.offer.metadata.is_none());
+			let mut tlv_stream = self.offer.as_tlv_stream();
+			tlv_stream.node_id = None;
+			tlv_stream.write(&mut metadata_material).unwrap();
+
+			self.offer.metadata = Some(metadata_material.into_metadata());
+		}
+
 		let mut bytes = Vec::new();
 		self.offer.write(&mut bytes).unwrap();
 
@@ -765,15 +825,15 @@ mod tests {
 	#[test]
 	fn builds_offer_with_metadata() {
 		let offer = OfferBuilder::new("foo".into(), pubkey(42))
-			.metadata(vec![42; 32])
+			.metadata(vec![42; 32]).unwrap()
 			.build()
 			.unwrap();
 		assert_eq!(offer.metadata(), Some(&vec![42; 32]));
 		assert_eq!(offer.as_tlv_stream().metadata, Some(&vec![42; 32]));
 
 		let offer = OfferBuilder::new("foo".into(), pubkey(42))
-			.metadata(vec![42; 32])
-			.metadata(vec![43; 32])
+			.metadata(vec![42; 32]).unwrap()
+			.metadata(vec![43; 32]).unwrap()
 			.build()
 			.unwrap();
 		assert_eq!(offer.metadata(), Some(&vec![43; 32]));

lightning/src/offers/signer.rs

@@ -0,0 +1,72 @@
+// This file is Copyright its original authors, visible in version control
+// history.
+//
+// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
+// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
+// You may not use this file except in accordance with one or both of these
+// licenses.
+
+//! Utilities for signing offer messages and verifying metadata.
+
+use bitcoin::hashes::{Hash, HashEngine};
+use bitcoin::hashes::hmac::{Hmac, HmacEngine};
+use bitcoin::hashes::sha256::Hash as Sha256;
+use core::convert::TryInto;
+use bitcoin::secp256k1::PublicKey;
+use crate::io;
+use crate::ln::inbound_payment::{ExpandedKey, Nonce};
+
+use crate::prelude::*;
+
+/// A pubkey derived from a base key and nonce. Used to crate metadata for a message such that it
+/// can be verified using [`verify_metadata`].
+pub(crate) struct DerivedPubkey {
+	public_key: PublicKey,
+	metadata_material: MetadataMaterial,
+}
+
+impl DerivedPubkey {
+	pub(crate) fn new(expanded_key: &ExpandedKey, nonce: Nonce) -> Self {
+		Self {
+			public_key: expanded_key.signing_pubkey_for_offer(nonce),
+			metadata_material: MetadataMaterial::new(nonce, expanded_key),
+		}
+	}
+
+	pub(super) fn into_parts(self) -> (PublicKey, MetadataMaterial) {
+		(self.public_key, self.metadata_material)
+	}
+}
+
+/// Material used to create metadata for a message. Once initialized, write the applicable data from
+/// the message into it and call [`MetadataMaterial::into_metadata`].
+pub(super) struct MetadataMaterial {
+	nonce: Nonce,
+	hmac: HmacEngine<Sha256>,
+}
+
+impl MetadataMaterial {
+	pub fn new(nonce: Nonce, expanded_key: &ExpandedKey) -> Self {
+		Self {
+			nonce,
+			hmac: expanded_key.hmac_for_offer(nonce),
+		}
+	}
+
+	pub fn into_metadata(self) -> Vec<u8> {
+		let mut bytes = self.nonce.as_slice().to_vec();
+		bytes.extend_from_slice(&Hmac::from_engine(self.hmac).into_inner());
+		bytes
+	}
+}
+
+impl io::Write for MetadataMaterial {
+	fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+		self.hmac.write(buf)
+	}
+
+	fn flush(&mut self) -> io::Result<()> {
+		self.hmac.flush()
+	}
+}