htlcswitch: re-add single decode hop iterator

htlcswitch/hop/iterator.go

@@ -690,7 +690,7 @@ func (p *OnionProcessor) ReconstructHopIterator(r io.Reader, rHash []byte,
 
 	// Attempt to process the Sphinx packet. We include the payment hash of
 	// the HTLC as it's authenticated within the Sphinx packet itself as
-	// associated data in order to thwart attempts a replay attacks. In the
+	// associated data in order to thwart replay attacks. In the
 	// case of a replay, an attacker is *forced* to use the same payment
 	// hash twice, thereby losing their money entirely.
 	sphinxPacket, err := p.router.ReconstructOnionPacket(
@@ -737,6 +737,69 @@ func (r *DecodeHopIteratorResponse) Result() (Iterator, lnwire.FailCode) {
 	return r.HopIterator, r.FailCode
 }
 
+// DecodeHopIterator attempts to decode a valid sphinx packet from the passed
+// io.Reader instance using the rHash as the associated data when checking the
+// relevant MACs during the decoding process.
+func (p *OnionProcessor) DecodeHopIterator(r io.Reader, rHash []byte,
+	incomingCltv uint32, incomingAmount lnwire.MilliSatoshi,
+	blindingPoint lnwire.BlindingPointRecord) (Iterator, lnwire.FailCode) {
+
+	onionPkt := &sphinx.OnionPacket{}
+	if err := onionPkt.Decode(r); err != nil {
+		switch {
+		case errors.Is(err, sphinx.ErrInvalidOnionVersion):
+			return nil, lnwire.CodeInvalidOnionVersion
+		case errors.Is(err, sphinx.ErrInvalidOnionKey):
+			return nil, lnwire.CodeInvalidOnionKey
+		default:
+			log.Errorf("unable to decode onion packet: %v", err)
+			return nil, lnwire.CodeInvalidOnionKey
+		}
+	}
+
+	// If a blinding point was provided in the update_add_htlc message,
+	// pass it through so the sphinx router can derive the correct shared
+	// secret for blinded hops.
+	var opts []sphinx.ProcessOnionOpt
+	blindingPoint.WhenSome(func(
+		b tlv.RecordT[lnwire.BlindingPointTlvType,
+			*btcec.PublicKey]) {
+
+		opts = append(opts, sphinx.WithBlindingPoint(b.Val))
+	})
+
+	// Attempt to process the Sphinx packet. We include the payment hash of
+	// the HTLC as it's authenticated within the Sphinx packet itself as
+	// associated data in order to thwart replay attacks. In the
+	// case of a replay, an attacker is *forced* to use the same payment
+	// hash twice, thereby losing their money entirely.
+	sphinxPacket, err := p.router.ProcessOnionPacket(
+		onionPkt, rHash, incomingCltv, opts...,
+	)
+	if err != nil {
+		switch {
+		case errors.Is(err, sphinx.ErrInvalidOnionVersion):
+			return nil, lnwire.CodeInvalidOnionVersion
+		case errors.Is(err, sphinx.ErrInvalidOnionHMAC):
+			return nil, lnwire.CodeInvalidOnionHmac
+		case errors.Is(err, sphinx.ErrInvalidOnionKey):
+			return nil, lnwire.CodeInvalidOnionKey
+		default:
+			log.Errorf("unable to process onion packet: %v", err)
+			return nil, lnwire.CodeInvalidOnionKey
+		}
+	}
+
+	return makeSphinxHopIterator(p.router, onionPkt, sphinxPacket,
+		BlindingKit{
+			Processor:         p.router,
+			UpdateAddBlinding: blindingPoint,
+			IncomingAmount:    incomingAmount,
+			IncomingCltv:      incomingCltv,
+		}, rHash,
+	), lnwire.CodeNone
+}
+
 // DecodeHopIterators performs batched decoding and validation of incoming
 // sphinx packets. For the same `id`, this method will return the same iterators
 // and failcodes upon subsequent invocations.

htlcswitch/hop/iterator_test.go

@@ -103,6 +103,170 @@ func TestSphinxHopIteratorForwardingInstructions(t *testing.T) {
 	}
 }
 
+// TestDecodeHopIterator tests that DecodeHopIterator can successfully process
+// a real onion packet constructed by the sphinx library and return a valid hop
+// iterator with the correct forwarding information. It also tests various error
+// cases such as truncated packets and corrupted HMACs.
+func TestDecodeHopIterator(t *testing.T) {
+	t.Parallel()
+
+	// Generate a fresh private key for our onion processor (the
+	// "receiving" node).
+	receiverPrivKey, err := btcec.NewPrivateKey()
+	require.NoError(t, err)
+
+	sphinxRouter := sphinx.NewRouter(
+		&sphinx.PrivKeyECDH{PrivKey: receiverPrivKey},
+		sphinx.NewNoOpReplayLog(),
+	)
+	require.NoError(t, sphinxRouter.Start())
+	defer sphinxRouter.Stop()
+
+	processor := NewOnionProcessor(sphinxRouter)
+
+	// Session key used by the "sender" to construct the onion.
+	sessionKey, err := btcec.NewPrivateKey()
+	require.NoError(t, err)
+
+	// Build a TLV payload for the final hop with amount and CLTV.
+	var (
+		fwdAmt       uint64              = 500_000
+		outgoingCltv uint32              = 144
+		incomingCltv uint32              = 200
+		incomingAmt  lnwire.MilliSatoshi = 600_000
+		noBlinding   lnwire.BlindingPointRecord
+	)
+	var payloadBuf bytes.Buffer
+	tlvRecords := []tlv.Record{
+		record.NewAmtToFwdRecord(&fwdAmt),
+		record.NewLockTimeRecord(&outgoingCltv),
+	}
+	tlvStream, err := tlv.NewStream(tlvRecords...)
+	require.NoError(t, err)
+	require.NoError(t, tlvStream.Encode(&payloadBuf))
+
+	// Build a one-hop payment path to the receiver.
+	var path sphinx.PaymentPath
+	path[0] = sphinx.OnionHop{
+		NodePub: *receiverPrivKey.PubKey(),
+		HopPayload: sphinx.HopPayload{
+			Type:    sphinx.PayloadTLV,
+			Payload: payloadBuf.Bytes(),
+		},
+	}
+
+	// Create the onion packet.
+	rHash := [32]byte{0xaa, 0xbb, 0xcc}
+	onionPkt, err := sphinx.NewOnionPacket(
+		&path, sessionKey, rHash[:],
+		sphinx.DeterministicPacketFiller,
+	)
+	require.NoError(t, err)
+
+	// serializeOnion is a helper that encodes an onion packet to bytes.
+	serializeOnion := func(pkt *sphinx.OnionPacket) []byte {
+		var buf bytes.Buffer
+		require.NoError(t, pkt.Encode(&buf))
+		return buf.Bytes()
+	}
+
+	validOnionBytes := serializeOnion(onionPkt)
+
+	tests := []struct {
+		name         string
+		onionBytes   []byte
+		rHash        []byte
+		expectedFail lnwire.FailCode
+		checkPayload bool
+	}{
+		{
+			name:         "valid onion",
+			onionBytes:   validOnionBytes,
+			rHash:        rHash[:],
+			expectedFail: lnwire.CodeNone,
+			checkPayload: true,
+		},
+		{
+			name:         "truncated packet",
+			onionBytes:   validOnionBytes[:10],
+			rHash:        rHash[:],
+			expectedFail: lnwire.CodeInvalidOnionKey,
+		},
+		{
+			name:         "empty reader",
+			onionBytes:   []byte{},
+			rHash:        rHash[:],
+			expectedFail: lnwire.CodeInvalidOnionKey,
+		},
+		{
+			name: "corrupted HMAC",
+			onionBytes: func() []byte {
+				corrupted := make([]byte, len(validOnionBytes))
+				copy(corrupted, validOnionBytes)
+				// Flip a byte in the HMAC (last 32 bytes of
+				// the packet).
+				corrupted[len(corrupted)-1] ^= 0xff
+
+				return corrupted
+			}(),
+			rHash:        rHash[:],
+			expectedFail: lnwire.CodeInvalidOnionHmac,
+		},
+		{
+			name:         "wrong payment hash",
+			onionBytes:   validOnionBytes,
+			rHash:        bytes.Repeat([]byte{0xff}, 32),
+			expectedFail: lnwire.CodeInvalidOnionHmac,
+		},
+		{
+			name: "invalid version byte",
+			onionBytes: func() []byte {
+				corrupted := make([]byte, len(validOnionBytes))
+				copy(corrupted, validOnionBytes)
+				// Set an invalid version (first byte).
+				corrupted[0] = 0xff
+
+				return corrupted
+			}(),
+			rHash:        rHash[:],
+			expectedFail: lnwire.CodeInvalidOnionVersion,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			reader := bytes.NewReader(tc.onionBytes)
+			iterator, failCode := processor.DecodeHopIterator(
+				reader, tc.rHash, incomingCltv, incomingAmt,
+				noBlinding,
+			)
+
+			require.Equal(t, tc.expectedFail, failCode)
+
+			if !tc.checkPayload {
+				return
+			}
+
+			require.NotNil(t, iterator)
+
+			payload, role, err := iterator.HopPayload()
+			require.NoError(t, err)
+			require.Equal(t, RouteRoleCleartext, role)
+
+			fwdInfo := payload.ForwardingInfo()
+			require.Equal(
+				t, lnwire.MilliSatoshi(fwdAmt),
+				fwdInfo.AmountToForward,
+			)
+			require.Equal(
+				t, outgoingCltv, fwdInfo.OutgoingCTLV,
+			)
+		})
+	}
+}
+
 // TestForwardingAmountCalc tests calculation of forwarding amounts from the
 // hop's forwarding parameters.
 func TestForwardingAmountCalc(t *testing.T) {

htlcswitch/hop/log.go

@@ -2,13 +2,28 @@ package hop
 
 import (
 	"github.com/btcsuite/btclog/v2"
+	"github.com/lightningnetwork/lnd/build"
 )
 
+// Subsystem defines the logging sub system name of this package.
+const Subsystem = "HOPS"
+
 // log is a logger that is initialized with no output filters.  This
 // means the package will not perform any logging by default until the caller
 // requests it.
 var log btclog.Logger
 
+// The default amount of logging is none.
+func init() {
+	UseLogger(build.NewSubLogger(Subsystem, nil))
+}
+
+// DisableLog disables all library log output. Logging output is disabled
+// by default until UseLogger is called.
+func DisableLog() {
+	UseLogger(btclog.Disabled)
+}
+
 // UseLogger uses a specified Logger to output package logging info. This
 // function is called from the parent package htlcswitch logger initialization.
 func UseLogger(logger btclog.Logger) {

htlcswitch/mock.go

@@ -491,7 +491,8 @@ func newMockIteratorDecoder() *mockIteratorDecoder {
 }
 
 func (p *mockIteratorDecoder) DecodeHopIterator(r io.Reader, rHash []byte,
-	cltv uint32) (hop.Iterator, lnwire.FailCode) {
+	cltv uint32, _ lnwire.MilliSatoshi,
+	_ lnwire.BlindingPointRecord) (hop.Iterator, lnwire.FailCode) {
 
 	var b [4]byte
 	_, err := r.Read(b[:])
@@ -540,6 +541,7 @@ func (p *mockIteratorDecoder) DecodeHopIterators(id []byte,
 	for _, req := range reqs {
 		iterator, failcode := p.DecodeHopIterator(
 			req.OnionReader, req.RHash, req.IncomingCltv,
+			req.IncomingAmount, req.BlindingPoint,
 		)
 
 		if p.decodeFail {