multi: handle route blinding in ProcessOnionPacket

In this commit, ProcessOnionPacket is updated to take in a blinding key
as a parameter. This key is then used in order to determine the blinding
factor necessary to decrypt the onion. This change is accompanied with a
test that tests this change against a test vector from the route
blinding spec PR.

Author: ellemouton

bench_test.go

@@ -77,7 +77,9 @@ func BenchmarkProcessPacket(b *testing.B) {
 		pkt *ProcessedPacket
 	)
 	for i := 0; i < b.N; i++ {
-		pkt, err = path[0].ProcessOnionPacket(sphinxPacket, nil, uint32(i))
+		pkt, err = path[0].ProcessOnionPacket(
+			sphinxPacket, nil, uint32(i),
+		)
 		if err != nil {
 			b.Fatalf("unable to process packet %d: %v", i, err)
 		}

crypto.go

@@ -239,17 +239,63 @@ type sharedSecretGenerator interface {
 	generateSharedSecret(dhKey *btcec.PublicKey) (Hash256, error)
 }
 
-// generateSharedSecret generates the shared secret by given ephemeral key.
-func (r *Router) generateSharedSecret(dhKey *btcec.PublicKey) (Hash256, error) {
+// generateSharedSecret generates the shared secret using the given ephemeral
+// pub key and the Router's private key. If a blindingPoint is provided then it
+// is used to tweak the Router's private key before creating the shared secret
+// with the ephemeral pub key. The blinding point is used to determine our
+// shared secret with the receiver. From that we can determine our shared
+// secret with the sender using the dhKey.
+func (r *Router) generateSharedSecret(dhKey,
+	blindingPoint *btcec.PublicKey) (Hash256, error) {
+
+	// If no blinding point is provided, then the un-tweaked dhKey can
+	// be used to derive the shared secret
+	if blindingPoint == nil {
+		return sharedSecret(r.onionKey, dhKey)
+	}
+
+	// We use the blinding point to calculate the blinding factor that the
+	// receiver used with us so that we can use it to tweak our priv key.
+	// The sender would have created their shared secret with our blinded
+	// pub key.
+	// 	* ss_receiver = H(k * E_receiver)
+	ssReceiver, err := sharedSecret(r.onionKey, blindingPoint)
+	if err != nil {
+		return Hash256{}, err
+	}
+
+	// Compute the blinding factor that the receiver would have used to
+	// blind our public key.
+	//
+	// 	* bf = HMAC256("blinded_node_id", ss_receiver)
+	blindingFactorBytes := generateKey(routeBlindingHMACKey, &ssReceiver)
+	var blindingFactor btcec.ModNScalar
+	blindingFactor.SetBytes(&blindingFactorBytes)
+
+	// Now, we want to calculate the shared secret between the sender and
+	// our blinded key. In other words we want to calculate:
+	// 	* ss_sender = H(E_sender * bf * k)
+	//
+	// Since the order in which the above multiplication happens does not
+	// matter, we will first multiply E_sender with the blinding factor:
+	blindedEphemeral := blindGroupElement(dhKey, blindingFactor)
+
+	// Finally, we compute the ECDH to get the shared secret, ss_sender:
+	return sharedSecret(r.onionKey, blindedEphemeral)
+}
+
+// sharedSecret does a ECDH operation on the passed private and public keys and
+// returns the result.
+func sharedSecret(priv SingleKeyECDH, pub *btcec.PublicKey) (Hash256, error) {
 	var sharedSecret Hash256
 
 	// Ensure that the public key is on our curve.
-	if !dhKey.IsOnCurve() {
+	if !pub.IsOnCurve() {
 		return sharedSecret, ErrInvalidOnionKey
 	}
 
-	// Compute our shared secret.
-	return r.onionKey.ECDH(dhKey)
+	// Compute the shared secret.
+	return priv.ECDH(pub)
 }
 
 // onionEncrypt obfuscates the data with compliance with BOLT#4. As we use a

obfuscation.go

@@ -13,12 +13,18 @@ type OnionErrorEncrypter struct {
 }
 
 // NewOnionErrorEncrypter creates new instance of the onion encrypter backed by
-// the passed router, with encryption to be doing using the passed
-// ephemeralKey.
-func NewOnionErrorEncrypter(router *Router,
-	ephemeralKey *btcec.PublicKey) (*OnionErrorEncrypter, error) {
+// the passed router, with encryption to be done using the passed ephemeralKey.
+func NewOnionErrorEncrypter(router *Router, ephemeralKey *btcec.PublicKey,
+	opts ...ProcessOnionOpt) (*OnionErrorEncrypter, error) {
 
-	sharedSecret, err := router.generateSharedSecret(ephemeralKey)
+	cfg := &processOnionCfg{}
+	for _, o := range opts {
+		o(cfg)
+	}
+
+	sharedSecret, err := router.generateSharedSecret(
+		ephemeralKey, cfg.blindingPoint,
+	)
 	if err != nil {
 		return nil, err
 	}

path_test.go

@@ -8,10 +8,14 @@ import (
 	"testing"
 
 	"github.com/btcsuite/btcd/btcec/v2"
+	"github.com/btcsuite/btcd/chaincfg"
 	"github.com/stretchr/testify/require"
 )
 
-const routeBlindingTestFileName = "testdata/route-blinding-test.json"
+const (
+	routeBlindingTestFileName      = "testdata/route-blinding-test.json"
+	onionRouteBlindingTestFileName = "testdata/onion-route-blinding-test.json"
+)
 
 // TestBuildBlindedRoute tests BuildBlindedRoute and decryptBlindedHopData against
 // the spec test vectors.
@@ -114,6 +118,119 @@ func TestBuildBlindedRoute(t *testing.T) {
 	}
 }
 
+// TestOnionRouteBlinding tests that an onion packet can correctly be processed
+// by a node in a blinded route.
+func TestOnionRouteBlinding(t *testing.T) {
+	t.Parallel()
+
+	// First, we'll read out the raw Json file at the target location.
+	jsonBytes, err := os.ReadFile(onionRouteBlindingTestFileName)
+	require.NoError(t, err)
+
+	// Once we have the raw file, we'll unpack it into our
+	// blindingJsonTestCase struct defined above.
+	testCase := &onionBlindingJsonTestCase{}
+	require.NoError(t, json.Unmarshal(jsonBytes, testCase))
+
+	assoc, err := hex.DecodeString(testCase.Generate.AssocData)
+	require.NoError(t, err)
+
+	// Extract the original onion packet to be processed.
+	onion, err := hex.DecodeString(testCase.Generate.Onion)
+	require.NoError(t, err)
+
+	onionBytes := bytes.NewReader(onion)
+	onionPacket := &OnionPacket{}
+	require.NoError(t, onionPacket.Decode(onionBytes))
+
+	// peelOnion is a helper closure that can be used to set up a Router
+	// and use it to process the given onion packet.
+	peelOnion := func(key *btcec.PrivateKey,
+		blindingPoint *btcec.PublicKey) *ProcessedPacket {
+
+		r := NewRouter(
+			&PrivKeyECDH{PrivKey: key}, &chaincfg.MainNetParams,
+			NewMemoryReplayLog(),
+		)
+
+		require.NoError(t, r.Start())
+		defer r.Stop()
+
+		res, err := r.ProcessOnionPacket(
+			onionPacket, assoc, 10,
+			WithBlindingPoint(blindingPoint),
+		)
+		require.NoError(t, err)
+
+		return res
+	}
+
+	hops := testCase.Decrypt.Hops
+	require.Len(t, hops, 5)
+
+	// There are some things that the processor of the onion packet will
+	// only be able to determine from the actual contents of the encrypted
+	// data it receives. These things include the next_blinding_point for
+	// the introduction point and the next_blinding_override. The decryption
+	// of this data is dependent on the encoding chosen by higher layers.
+	// The test uses TLVs. Since the extraction of this data is dependent
+	// on layers outside the scope of this library, we provide handle these
+	// cases manually for the sake of the test.
+	var (
+		introPointIndex = 2
+		firstBlinding   = pubKeyFromString(hops[1].NextBlinding)
+
+		concatIndex      = 3
+		blindingOverride = pubKeyFromString(hops[2].NextBlinding)
+	)
+
+	var blindingPoint *btcec.PublicKey
+	for i, hop := range testCase.Decrypt.Hops {
+		buff := bytes.NewBuffer(nil)
+		require.NoError(t, onionPacket.Encode(buff))
+		require.Equal(t, hop.Onion, hex.EncodeToString(buff.Bytes()))
+
+		priv := privKeyFromString(hop.NodePrivKey)
+
+		if i == introPointIndex {
+			blindingPoint = firstBlinding
+		} else if i == concatIndex {
+			blindingPoint = blindingOverride
+		}
+
+		processedPkt := peelOnion(priv, blindingPoint)
+
+		if blindingPoint != nil {
+			blindingPoint, err = NextEphemeral(
+				&PrivKeyECDH{priv}, blindingPoint,
+			)
+			require.NoError(t, err)
+		}
+		onionPacket = processedPkt.NextPacket
+	}
+}
+
+type onionBlindingJsonTestCase struct {
+	Generate generateOnionData `json:"generate"`
+	Decrypt  decryptData       `json:"decrypt"`
+}
+
+type generateOnionData struct {
+	SessionKey string `json:"session_key"`
+	AssocData  string `json:"associated_data"`
+	Onion      string `json:"onion"`
+}
+
+type decryptData struct {
+	Hops []decryptHops `json:"hops"`
+}
+
+type decryptHops struct {
+	Onion        string `json:"onion"`
+	NodePrivKey  string `json:"node_privkey"`
+	NextBlinding string `json:"next_blinding"`
+}
+
 type blindingJsonTestCase struct {
 	Generate generateData `json:"generate"`
 	Route    routeData    `json:"route"`

sphinx.go

@@ -521,20 +521,48 @@ func (r *Router) Stop() {
 	r.log.Stop()
 }
 
+// processOnionCfg is a set of config values that can be used to modify how an
+// onion is processed.
+type processOnionCfg struct {
+	blindingPoint *btcec.PublicKey
+}
+
+// ProcessOnionOpt defines the signature of a function option that can be used
+// to modify how an onion is processed.
+type ProcessOnionOpt func(cfg *processOnionCfg)
+
+// WithBlindingPoint is a function option that can be used to set the blinding
+// point to be used when processing an onion.
+func WithBlindingPoint(point *btcec.PublicKey) ProcessOnionOpt {
+	return func(cfg *processOnionCfg) {
+		cfg.blindingPoint = point
+	}
+}
+
 // ProcessOnionPacket processes an incoming onion packet which has been forward
 // to the target Sphinx router. If the encoded ephemeral key isn't on the
 // target Elliptic Curve, then the packet is rejected. Similarly, if the
-// derived shared secret has been seen before the packet is rejected.  Finally
-// if the MAC doesn't check the packet is again rejected.
+// derived shared secret has been seen before the packet is rejected. If the
+// blinded point is specified, then it will be used along with the ephemeral key
+// in the onion packet to derive the shared secret. Finally, if the MAC doesn't
+// check the packet is again rejected.
 //
 // In the case of a successful packet processing, and ProcessedPacket struct is
 // returned which houses the newly parsed packet, along with instructions on
 // what to do next.
-func (r *Router) ProcessOnionPacket(onionPkt *OnionPacket,
-	assocData []byte, incomingCltv uint32) (*ProcessedPacket, error) {
+func (r *Router) ProcessOnionPacket(onionPkt *OnionPacket, assocData []byte,
+	incomingCltv uint32, opts ...ProcessOnionOpt) (*ProcessedPacket,
+	error) {
+
+	cfg := &processOnionCfg{}
+	for _, o := range opts {
+		o(cfg)
+	}
 
 	// Compute the shared secret for this onion packet.
-	sharedSecret, err := r.generateSharedSecret(onionPkt.EphemeralKey)
+	sharedSecret, err := r.generateSharedSecret(
+		onionPkt.EphemeralKey, cfg.blindingPoint,
+	)
 	if err != nil {
 		return nil, err
 	}
@@ -546,7 +574,7 @@ func (r *Router) ProcessOnionPacket(onionPkt *OnionPacket,
 	// Continue to optimistically process this packet, deferring replay
 	// protection until the end to reduce the penalty of multiple IO
 	// operations.
-	packet, err := processOnionPacket(onionPkt, &sharedSecret, assocData, r)
+	packet, err := processOnionPacket(onionPkt, &sharedSecret, assocData)
 	if err != nil {
 		return nil, err
 	}
@@ -564,16 +592,23 @@ func (r *Router) ProcessOnionPacket(onionPkt *OnionPacket,
 //
 // NOTE: This method does not do any sort of replay protection, and should only
 // be used to reconstruct packets that were successfully processed previously.
-func (r *Router) ReconstructOnionPacket(onionPkt *OnionPacket,
-	assocData []byte) (*ProcessedPacket, error) {
+func (r *Router) ReconstructOnionPacket(onionPkt *OnionPacket, assocData []byte,
+	opts ...ProcessOnionOpt) (*ProcessedPacket, error) {
+
+	cfg := &processOnionCfg{}
+	for _, o := range opts {
+		o(cfg)
+	}
 
 	// Compute the shared secret for this onion packet.
-	sharedSecret, err := r.generateSharedSecret(onionPkt.EphemeralKey)
+	sharedSecret, err := r.generateSharedSecret(
+		onionPkt.EphemeralKey, cfg.blindingPoint,
+	)
 	if err != nil {
 		return nil, err
 	}
 
-	return processOnionPacket(onionPkt, &sharedSecret, assocData, r)
+	return processOnionPacket(onionPkt, &sharedSecret, assocData)
 }
 
 // unwrapPacket wraps a layer of the passed onion packet using the specified
@@ -640,8 +675,7 @@ func unwrapPacket(onionPkt *OnionPacket, sharedSecret *Hash256,
 // packets. The processed packets returned from this method should only be used
 // if the packet was not flagged as a replayed packet.
 func processOnionPacket(onionPkt *OnionPacket, sharedSecret *Hash256,
-	assocData []byte,
-	sharedSecretGen sharedSecretGenerator) (*ProcessedPacket, error) {
+	assocData []byte) (*ProcessedPacket, error) {
 
 	// First, we'll unwrap an initial layer of the onion packet. Typically,
 	// we'll only have a single layer to unwrap, However, if the sender has
@@ -721,18 +755,25 @@ func (r *Router) BeginTxn(id []byte, nels int) *Tx {
 // ProcessOnionPacket processes an incoming onion packet which has been forward
 // to the target Sphinx router. If the encoded ephemeral key isn't on the
 // target Elliptic Curve, then the packet is rejected. Similarly, if the
-// derived shared secret has been seen before the packet is rejected.  Finally
-// if the MAC doesn't check the packet is again rejected.
+// derived shared secret has been seen before the packet is rejected. If the
+// blinded point is specified, then it will be used along with the ephemeral key
+// in the onion packet to derive the shared secret. Finally, if the MAC doesn't
+// check the packet is again rejected.
 //
 // In the case of a successful packet processing, and ProcessedPacket struct is
 // returned which houses the newly parsed packet, along with instructions on
 // what to do next.
 func (t *Tx) ProcessOnionPacket(seqNum uint16, onionPkt *OnionPacket,
-	assocData []byte, incomingCltv uint32) error {
+	assocData []byte, incomingCltv uint32, opts ...ProcessOnionOpt) error {
+
+	cfg := &processOnionCfg{}
+	for _, o := range opts {
+		o(cfg)
+	}
 
 	// Compute the shared secret for this onion packet.
 	sharedSecret, err := t.router.generateSharedSecret(
-		onionPkt.EphemeralKey,
+		onionPkt.EphemeralKey, cfg.blindingPoint,
 	)
 	if err != nil {
 		return err
@@ -745,9 +786,7 @@ func (t *Tx) ProcessOnionPacket(seqNum uint16, onionPkt *OnionPacket,
 	// Continue to optimistically process this packet, deferring replay
 	// protection until the end to reduce the penalty of multiple IO
 	// operations.
-	packet, err := processOnionPacket(
-		onionPkt, &sharedSecret, assocData, t.router,
-	)
+	packet, err := processOnionPacket(onionPkt, &sharedSecret, assocData)
 	if err != nil {
 		return err
 	}