sphinx: OnionObfuscator -> OnionErrorEncrypter, OnionDeobfuscator -> OnionErrorDecrypter

Author: Roasbeef

obfuscation.go

@@ -10,56 +10,54 @@ import (
 	"github.com/roasbeef/btcd/btcec"
 )
 
-// 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,
-	data []byte) []byte {
-	obfuscatedData := make([]byte, len(data))
+// onionEncrypt obfuscates the data with compliance with BOLT#4. As we use a
+// stream cipher, calling onionEncrypt on an already encrypted piece of data
+// will decrypt it.
+func onionEncrypt(sharedSecret [sha256.Size]byte, data []byte) []byte {
+
+	p := make([]byte, len(data))
 
 	ammagKey := generateKey("ammag", sharedSecret)
 	streamBytes := generateCipherStream(ammagKey, uint(len(data)))
-	xor(obfuscatedData, data, streamBytes)
-	return obfuscatedData
+	xor(p, data, streamBytes)
+
+	return p
 }
 
-// OnionObfuscator represent serializable object which is able to convert the
-// 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.
-type OnionObfuscator struct {
+// OnionErrorEncrypter is a struct that's used to implement onion error
+// encryption as defined within BOLT0004.
+type OnionErrorEncrypter struct {
 	sharedSecret [sha256.Size]byte
 }
 
-// NewOnionObfuscator creates new instance of onion obfuscator.
-func NewOnionObfuscator(router *Router, ephemeralKey *btcec.PublicKey) (*OnionObfuscator,
-	error) {
+// NewOnionErrorEncrypter creates new instance of the onion encryper backed by
+// the passed router, with encryption to be doing using the passed
+// ephemeralKey.
+func NewOnionErrorEncrypter(router *Router,
+	ephemeralKey *btcec.PublicKey) (*OnionErrorEncrypter, error) {
 
 	sharedSecret, err := router.generateSharedSecret(ephemeralKey)
 	if err != nil {
 		return nil, err
 	}
 
-	return &OnionObfuscator{
+	return &OnionErrorEncrypter{
 		sharedSecret: sharedSecret,
 	}, nil
 }
 
-// Obfuscate is used to make data obfuscation using the generated shared secret.
+// EncryptError 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
-// obfuscating the onion failure on every node in the path we are adding
-// additional step of the security and barrier for malware nodes to retrieve
-// valuable information. The reason for using onion obfuscation is to not give
-// away to the nodes in the payment path the information about the exact failure
-// and its origin.
-func (o *OnionObfuscator) Obfuscate(initial bool, data []byte) []byte {
+// 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 obfuscating
+// the onion failure on every node in the path we are adding additional step of
+// the security and barrier for malware nodes to retrieve valuable information.
+// The reason for using onion obfuscation is to not give
+// away to the nodes in the payment path the information about the exact
+// failure and its origin.
+func (o *OnionErrorEncrypter) EncryptError(initial bool, data []byte) []byte {
 	if initial {
 		umKey := generateKey("um", o.sharedSecret)
 		hash := hmac.New(sha256.New, umKey[:])
@@ -68,9 +66,7 @@ func (o *OnionObfuscator) Obfuscate(initial bool, data []byte) []byte {
 		data = append(h, data...)
 	}
 
-	return onionObfuscation(o.sharedSecret, data)
-}
-
+	return onionEncrypt(o.sharedSecret, data)
 }
 
 // Circuit is used encapsulate the data which is needed for data deobfuscation.
@@ -145,26 +141,24 @@ func (c *Circuit) Encode(w io.Writer) error {
 	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 {
+// OnionErrorDecrypter is a struct that's used to decrypt onion errors in
+// response to failed HTLC routing attempts according to BOLT#4.
+type OnionErrorDecrypter struct {
 	circuit *Circuit
 }
 
-// NewOnionDeobfuscator creates new instance of onion deobfuscator.
-func NewOnionDeobfuscator(circuit *Circuit) *OnionDeobfuscator {
-	return &OnionDeobfuscator{
+// NewOnionErrorDecrypter creates new instance of onion decrypter.
+func NewOnionErrorDecrypter(circuit *Circuit) *OnionErrorDecrypter {
+	return &OnionErrorDecrypter{
 		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) {
+// DecryptError attempts to decrypt the passed encrypted error response. The
+// onion failure is encrypted in backward manner, starting from the node where
+// error have occurred. As a result, in order to decrypt the error we need get
+// all shared secret and apply decryption in the reverse order.
+func (o *OnionErrorDecrypter) DecryptError(encryptedData []byte) (*btcec.PublicKey, []byte, error) {
 
 	sharedSecrets := generateSharedSecrets(
 		o.circuit.PaymentPath,
@@ -196,12 +190,12 @@ func (o *OnionDeobfuscator) Deobfuscate(obfuscatedData []byte) (*btcec.PublicKey
 
 		// With the shared secret, we'll now strip off a layer of
 		// encryption from the encrypted error payload.
-		obfuscatedData = onionObfuscation(sharedSecret, obfuscatedData)
+		encryptedData = onionEncrypt(sharedSecret, encryptedData)
 
 		// Next, we'll need to separate the data, from the MAC itself
 		// so we can reconstruct and verify it.
-		expectedMac := obfuscatedData[:sha256.Size]
-		data := obfuscatedData[sha256.Size:]
+		expectedMac := encryptedData[:sha256.Size]
+		data := encryptedData[sha256.Size:]
 
 		// With the data split, we'll now re-generate the MAC using its
 		// specified key.

obfuscation_test.go

@@ -31,33 +31,33 @@ func TestOnionFailure(t *testing.T) {
 	sharedSecrets := generateSharedSecrets(paymentPath, sessionKey)
 
 	// Emulate creation of the obfuscator on node where error have occurred.
-	obfuscator := &OnionObfuscator{
+	obfuscator := &OnionErrorEncrypter{
 		sharedSecret: sharedSecrets[len(errorPath)-1],
 	}
 
 	// Emulate the situation when last hop creates the onion failure
 	// message and send it back.
-	obfuscatedData := obfuscator.Obfuscate(true, failureData)
+	obfuscatedData := obfuscator.EncryptError(true, failureData)
 
 	// Emulate that failure message is backward obfuscated on every hop.
 	for i := len(errorPath) - 2; i >= 0; i-- {
 		// Emulate creation of the obfuscator on forwarding node which
 		// propagates the onion failure.
-		obfuscator = &OnionObfuscator{
+		obfuscator = &OnionErrorEncrypter{
 			sharedSecret: sharedSecrets[i],
 		}
-		obfuscatedData = obfuscator.Obfuscate(false, obfuscatedData)
+		obfuscatedData = obfuscator.EncryptError(false, obfuscatedData)
 	}
 
 	// Emulate creation of the deobfuscator on the receiving onion error side.
-	deobfuscator := NewOnionDeobfuscator(&Circuit{
+	deobfuscator := NewOnionErrorDecrypter(&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.
-	pubKey, deobfuscatedData, err := deobfuscator.Deobfuscate(obfuscatedData)
+	pubKey, deobfuscatedData, err := deobfuscator.DecryptError(obfuscatedData)
 	if err != nil {
 		t.Fatalf("unable to de-obfuscate the onion failure: %v", err)
 	}
@@ -197,7 +197,7 @@ func TestOnionFailureSpecVector(t *testing.T) {
 			t.Fatalf("unable to decode spec shared secret: %v",
 				err)
 		}
-		obfuscator := &OnionObfuscator{
+		obfuscator := &OnionErrorEncrypter{
 			sharedSecret: sharedSecrets[len(sharedSecrets)-1-i],
 		}
 
@@ -210,35 +210,35 @@ func TestOnionFailureSpecVector(t *testing.T) {
 		if i == 0 {
 			// Emulate the situation when last hop creates the onion failure
 			// message and send it back.
-			obfuscatedData = obfuscator.Obfuscate(true, failureData)
+			obfuscatedData = obfuscator.EncryptError(true, failureData)
 		} else {
 			// Emulate the situation when forward node obfuscates
 			// the onion failure.
-			obfuscatedData = obfuscator.Obfuscate(false, obfuscatedData)
+			obfuscatedData = obfuscator.EncryptError(false, obfuscatedData)
 		}
 
 		// Decode the obfuscated data and check that it matches the
 		// specification.
-		expectedObfuscatedData, err := hex.DecodeString(test.obfuscatedData)
+		expectedEncryptErrordData, err := hex.DecodeString(test.obfuscatedData)
 		if err != nil {
 			t.Fatalf("unable to decode spec obfusacted "+
 				"data: %v", err)
 		}
-		if !bytes.Equal(expectedObfuscatedData, obfuscatedData) {
+		if !bytes.Equal(expectedEncryptErrordData, obfuscatedData) {
 			t.Fatalf("obfuscated data not match spec: expected %x, "+
-				"got %x", expectedObfuscatedData[:],
+				"got %x", expectedEncryptErrordData[:],
 				obfuscatedData[:])
 		}
 	}
 
-	deobfuscator := NewOnionDeobfuscator(&Circuit{
+	deobfuscator := NewOnionErrorDecrypter(&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.
-	pubKey, deobfuscatedData, err := deobfuscator.Deobfuscate(obfuscatedData)
+	pubKey, deobfuscatedData, err := deobfuscator.DecryptError(obfuscatedData)
 	if err != nil {
 		t.Fatalf("unable to de-obfuscate the onion failure: %v", err)
 	}