sphinx: add variables for specification errors

In order to properly handle errors during decoding and parsing process
the distinct variables of errors have been created.

Author: andrewshvv

error.go

@@ -7,4 +7,17 @@ var (
 	// during processing due to being an attempted replay or probing
 	// attempt.
 	ErrReplayedPacket = fmt.Errorf("sphinx packet replay attempted")
+
+	// ErrInvalidOnionVersion is returned during decoding of the onion
+	// packet, when the received packet has an unknown version byte.
+	ErrInvalidOnionVersion = fmt.Errorf("invalid onion packet version")
+
+	// ErrInvalidOnionHMAC is returned during onion parsing process, when received
+	// mac does not corresponds to the generated one.
+	ErrInvalidOnionHMAC = fmt.Errorf("invalid mismathed mac")
+
+	// ErrInvalidOnionKey is returned during onion parsing process, when
+	// onion key is invalid.
+	ErrInvalidOnionKey = fmt.Errorf("invalid onion key: pubkey isn't on " +
+		"secp256k1 curve")
 )

obfuscation.go

@@ -1,7 +1,6 @@
 package sphinx
 
 import (
-	"bytes"
 	"crypto/hmac"
 	"crypto/sha256"
 	"errors"
@@ -11,6 +10,7 @@ import (
 )
 
 // onionObfuscation obfuscates the data with compliance with BOLT#4.
+//
 // In context of Lightning Network this function is used by sender to obfuscate
 // the onion failure and by receiver to unwrap the failure data.
 func onionObfuscation(sharedSecret [sha256.Size]byte,
@@ -23,7 +23,9 @@ func onionObfuscation(sharedSecret [sha256.Size]byte,
 }
 
 // OnionObfuscator represent serializable object which is able to convert the
-// data to the obfuscated blob.
+// data to the obfuscated blob, by applying the stream of data generated by
+// the shared secret.
+//
 // In context of Lightning Network the obfuscated data is usually a failure
 // which will be propagated back to payment sender, and obfuscated by the
 // forwarding nodes.
@@ -45,7 +47,8 @@ func NewOnionObfuscator(router *Router, ephemeralKey *btcec.PublicKey) (*OnionOb
 	}, nil
 }
 
-// Obfuscate is used to make data obfuscation.
+// Obfuscate is used to make data obfuscation using the generated shared secret.
+//
 // In context of Lightning Network is either used by the nodes in order to
 // make initial obfuscation with the creation of the hmac or by the forwarding
 // nodes for backward failure obfuscation of the onion failure blob. By
@@ -78,54 +81,18 @@ func (o *OnionObfuscator) Encode(w io.Writer) error {
 	return err
 }
 
-// OnionDeobfuscator represents the serializable object which encapsulate the
-// all necessary data to properly de-obfuscate previously obfuscated data.
-// In context of Lightning Network the data which have to be deobfuscated
-// usually is onion failure.
-type OnionDeobfuscator struct {
-	sessionKey  *btcec.PrivateKey
-	paymentPath []*btcec.PublicKey
-}
+// Circuit is used encapsulate the data which is needed for data deobfuscation.
+type Circuit struct {
+	// SessionKey is the key which have been used during generation of the
+	// shared secrets.
+	SessionKey *btcec.PrivateKey
 
-// NewOnionDeobfuscator creates new instance of onion deobfuscator.
-func NewOnionDeobfuscator(sessionKey *btcec.PrivateKey,
-	paymentPath []*btcec.PublicKey) (*OnionDeobfuscator, error) {
-	return &OnionDeobfuscator{
-		sessionKey:  sessionKey,
-		paymentPath: paymentPath,
-	}, nil
+	// PaymentPath is the pub keys of the nodes in the payment path.
+	PaymentPath []*btcec.PublicKey
 }
 
-// Deobfuscate makes data deobfuscation. The onion failure is obfuscated in
-// backward manner, starting from the node where error have occurred, so in
-// order to deobfuscate the error we need get all shared secret and apply
-// obfuscation in reverse order.
-func (o *OnionDeobfuscator) Deobfuscate(obfuscatedData []byte) (*btcec.PublicKey,
-	[]byte, error) {
-	for i, sharedSecret := range generateSharedSecrets(o.paymentPath,
-		o.sessionKey) {
-		obfuscatedData = onionObfuscation(sharedSecret, obfuscatedData)
-		umKey := generateKey("um", sharedSecret)
-
-		// Split the data and hmac.
-		expectedMac := obfuscatedData[:sha256.Size]
-		data := obfuscatedData[sha256.Size:]
-
-		// Calculate the real hmac.
-		h := hmac.New(sha256.New, umKey[:])
-		h.Write(data)
-		realMac := h.Sum(nil)
-
-		if bytes.Equal(realMac, expectedMac) {
-			return o.paymentPath[i], data, nil
-		}
-	}
-
-	return nil, nil, errors.New("unable to retrieve onion failure")
-}
-
-// Decode initializes the deobfuscator from the byte stream.
-func (o *OnionDeobfuscator) Decode(r io.Reader) error {
+// Decode initializes the circuit from the byte stream.
+func (c *Circuit) Decode(r io.Reader) error {
 	var keyLength [1]byte
 	if _, err := r.Read(keyLength[:]); err != nil {
 		return err
@@ -136,14 +103,14 @@ func (o *OnionDeobfuscator) Decode(r io.Reader) error {
 		return err
 	}
 
-	o.sessionKey, _ = btcec.PrivKeyFromBytes(btcec.S256(), sessionKeyData)
+	c.SessionKey, _ = btcec.PrivKeyFromBytes(btcec.S256(), sessionKeyData)
 	var pathLength [1]byte
 	if _, err := r.Read(pathLength[:]); err != nil {
 		return err
 	}
-	o.paymentPath = make([]*btcec.PublicKey, uint8(pathLength[0]))
+	c.PaymentPath = make([]*btcec.PublicKey, uint8(pathLength[0]))
 
-	for i := 0; i < len(o.paymentPath); i++ {
+	for i := 0; i < len(c.PaymentPath); i++ {
 		var pubKeyData [btcec.PubKeyBytesLenCompressed]byte
 		if _, err := r.Read(pubKeyData[:]); err != nil {
 			return err
@@ -153,35 +120,88 @@ func (o *OnionDeobfuscator) Decode(r io.Reader) error {
 		if err != nil {
 			return err
 		}
-		o.paymentPath[i] = pubKey
+		c.PaymentPath[i] = pubKey
 	}
 
 	return nil
 }
 
-// Encode writes converted deobfuscator in the byte stream.
-func (o *OnionDeobfuscator) Encode(w io.Writer) error {
+// Encode writes converted circuit in the byte stream.
+func (c *Circuit) Encode(w io.Writer) error {
 	var keyLength [1]byte
-	keyLength[0] = uint8(len(o.sessionKey.Serialize()))
+	keyLength[0] = uint8(len(c.SessionKey.Serialize()))
 	if _, err := w.Write(keyLength[:]); err != nil {
 		return err
 	}
 
-	if _, err := w.Write(o.sessionKey.Serialize()); err != nil {
+	if _, err := w.Write(c.SessionKey.Serialize()); err != nil {
 		return err
 	}
 
 	var pathLength [1]byte
-	pathLength[0] = uint8(len(o.paymentPath))
+	pathLength[0] = uint8(len(c.PaymentPath))
 	if _, err := w.Write(pathLength[:]); err != nil {
 		return err
 	}
 
-	for _, pubKey := range o.paymentPath {
+	for _, pubKey := range c.PaymentPath {
 		if _, err := w.Write(pubKey.SerializeCompressed()); err != nil {
 			return err
 		}
 	}
 
 	return nil
 }
+
+// OnionDeobfuscator represents the serializable object which encapsulate the
+// all necessary data to properly de-obfuscate previously obfuscated data.
+// In context of Lightning Network the data which have to be deobfuscated
+// usually is onion failure.
+type OnionDeobfuscator struct {
+	circuit *Circuit
+}
+
+// NewOnionDeobfuscator creates new instance of onion deobfuscator.
+func NewOnionDeobfuscator(circuit *Circuit) *OnionDeobfuscator {
+	return &OnionDeobfuscator{
+		circuit: circuit,
+	}
+}
+
+// Deobfuscate makes data deobfuscation. The onion failure is obfuscated in
+// backward manner, starting from the node where error have occurred, so in
+// order to deobfuscate the error we need get all shared secret and apply
+// obfuscation in reverse order.
+func (o *OnionDeobfuscator) Deobfuscate(obfuscatedData []byte) (*btcec.PublicKey,
+	[]byte, error) {
+	for i, sharedSecret := range generateSharedSecrets(o.circuit.PaymentPath,
+		o.circuit.SessionKey) {
+		obfuscatedData = onionObfuscation(sharedSecret, obfuscatedData)
+		umKey := generateKey("um", sharedSecret)
+
+		// Split the data and hmac.
+		expectedMac := obfuscatedData[:sha256.Size]
+		data := obfuscatedData[sha256.Size:]
+
+		// Calculate the real hmac.
+		h := hmac.New(sha256.New, umKey[:])
+		h.Write(data)
+		realMac := h.Sum(nil)
+
+		if hmac.Equal(realMac, expectedMac) {
+			return o.circuit.PaymentPath[i], data, nil
+		}
+	}
+
+	return nil, nil, errors.New("unable to retrieve onion failure")
+}
+
+// Decode writes converted deobfucator in the byte stream.
+func (o *OnionDeobfuscator) Decode(r io.Reader) error {
+	return o.circuit.Decode(r)
+}
+
+// Encode writes converted deobfucator in the byte stream.
+func (o *OnionDeobfuscator) Encode(w io.Writer) error {
+	return o.circuit.Encode(w)
+}

obfuscation_test.go

@@ -50,10 +50,10 @@ func TestOnionFailure(t *testing.T) {
 	}
 
 	// Emulate creation of the deobfuscator on the receiving onion error side.
-	deobfuscator := &OnionDeobfuscator{
-		sessionKey:  sessionKey,
-		paymentPath: paymentPath,
-	}
+	deobfuscator := NewOnionDeobfuscator(&Circuit{
+		SessionKey:  sessionKey,
+		PaymentPath: paymentPath,
+	})
 
 	// Emulate that sender node receive the failure message and trying to
 	// unwrap it, by applying obfuscation and checking the hmac.
@@ -124,7 +124,6 @@ var onionErrorData = []struct {
 			"1a62081df0ed46d4a3df295da0b0fe25c0115019f03f15ec86fa" +
 			"bb4c852f83449e812f141a93",
 	},
-
 	{
 		sharedSecret: "3a6b412548762f0dbccce5c7ae7bb8147d1caf9b5471c3" +
 			"4120b30bc9c04891cc",
@@ -145,7 +144,6 @@ var onionErrorData = []struct {
 			"9b8e6faa83b81fbfa6133c0af5d6b07c017f7158fa94f0d206ba" +
 			"f12dda6b68f785b773b360fd",
 	},
-
 	{
 		sharedSecret: "a6519e98832a0b179f62123b3567c106db99ee37bef036" +
 			"e783263602f3488fae",
@@ -166,7 +164,6 @@ var onionErrorData = []struct {
 			"de7084bb95b3ac2345201d624d31f4d52078aa0fa05a88b4e202" +
 			"02bd2b86ac5b52919ea305a8",
 	},
-
 	{
 		sharedSecret: "53eb63ea8a3fec3b3cd433b85cd62a4b145e1dda09391b" +
 			"348c4e1cd36a03ea66",
@@ -294,10 +291,10 @@ func TestOnionFailureSpecVector(t *testing.T) {
 		}
 	}
 
-	deobfuscator := &OnionDeobfuscator{
-		sessionKey:  sessionKey,
-		paymentPath: paymentPath,
-	}
+	deobfuscator := NewOnionDeobfuscator(&Circuit{
+		SessionKey:  sessionKey,
+		PaymentPath: paymentPath,
+	})
 
 	// Emulate that sender node receives the failure message and trying to
 	// unwrap it, by applying obfuscation and checking the hmac.

sphinx.go

@@ -6,7 +6,6 @@ import (
 	"crypto/hmac"
 	"crypto/sha256"
 	"encoding/binary"
-	"fmt"
 	"io"
 	"io/ioutil"
 	"sync"
@@ -63,6 +62,9 @@ const (
 	// encrypt payloads. Since we use SHA256 to generate the keys, the
 	// maximum length currently is 32 bytes.
 	keyLen = 32
+
+	// baseVersion represent the current supported version of onion packet.
+	baseVersion = 0
 )
 
 var (
@@ -199,6 +201,8 @@ func (hd *HopData) Decode(r io.Reader) error {
 	return nil
 }
 
+// generateSharedSecrets by the given nodes pubkeys, generates the shared
+// secrets.
 func generateSharedSecrets(paymentPath []*btcec.PublicKey,
 	sessionKey *btcec.PrivateKey) [][sha256.Size]byte {
 	// Each hop performs ECDH with our ephemeral key pair to arrive at a
@@ -319,7 +323,7 @@ func NewOnionPacket(paymentPath []*btcec.PublicKey, sessionKey *btcec.PrivateKey
 	}
 
 	return &OnionPacket{
-		Version:      0x01,
+		Version:      baseVersion,
 		EphemeralKey: sessionKey.PubKey(),
 		RoutingInfo:  mixHeader,
 		HeaderMAC:    nextHmac,
@@ -401,6 +405,12 @@ func (f *OnionPacket) Decode(r io.Reader) error {
 	}
 	f.Version = buf[0]
 
+	// If version of the onion packet protocol unknown for us than in might
+	// lead to improperly decoded data.
+	if f.Version != baseVersion {
+		return ErrInvalidOnionVersion
+	}
+
 	var ephemeral [33]byte
 	if _, err := io.ReadFull(r, ephemeral[:]); err != nil {
 		return err
@@ -636,7 +646,6 @@ func NewRouter(nodeKey *btcec.PrivateKey, net *chaincfg.Params) *Router {
 // returned which houses the newly parsed packet, along with instructions on
 // what to do next.
 func (r *Router) ProcessOnionPacket(onionPkt *OnionPacket, assocData []byte) (*ProcessedPacket, error) {
-
 	dhKey := onionPkt.EphemeralKey
 	routeInfo := onionPkt.RoutingInfo
 	headerMac := onionPkt.HeaderMAC
@@ -662,8 +671,7 @@ func (r *Router) ProcessOnionPacket(onionPkt *OnionPacket, assocData []byte) (*P
 	message := append(routeInfo[:], assocData...)
 	calculatedMac := calcMac(generateKey("mu", sharedSecret), message)
 	if !hmac.Equal(headerMac[:], calculatedMac[:]) {
-		return nil, fmt.Errorf("MAC mismatch %x != %x, rejecting "+
-			"forwarding message", headerMac, calculatedMac)
+		return nil, ErrInvalidOnionHMAC
 	}
 
 	// The MAC checks out, mark this current shared secret as processed in
@@ -732,7 +740,7 @@ func (r *Router) generateSharedSecret(dhKey *btcec.PublicKey) ([sha256.Size]byte
 
 	// Ensure that the public key is on our curve.
 	if !r.onionKey.Curve.IsOnCurve(dhKey.X, dhKey.Y) {
-		return sharedSecret, fmt.Errorf("pubkey isn't on secp256k1 curve")
+		return sharedSecret, ErrInvalidOnionKey
 	}
 
 	// Compute our shared secret.