add response signatures

Author: ezekg

Makefile

@@ -43,6 +43,10 @@ ifdef BUILD_NODE_LOCKED
 	ifdef BUILD_NODE_LOCKED_PORT
 		BUILD_LDFLAGS += -X $(PACKAGE_NAME)/internal/locker.Port=$(BUILD_NODE_LOCKED_PORT)
 	endif
+
+	ifdef BUILD_NODE_LOCKED_SIGNING_SECRET
+		BUILD_LDFLAGS += -X $(PACKAGE_NAME)/internal/locker.SigningSecret=$(BUILD_NODE_LOCKED_SIGNING_SECRET)
+	endif
 endif
 
 ifdef DEBUG

README.md

@@ -247,6 +247,67 @@ Accepts a `fingerprint`, the node fingerprint used for the lease.
 Returns `204 No Content` with no content. If a lease does not exist for the
 node, the server will return a `404 Not Found`.
 
+## Signatures
+
+Relay supports response signatures, useful for detecting simple clock tampering
+and spoofing attempts. When the `--signing-secret` flag is provided, all API
+responses will be cryptographically signed using HMAC-SHA256.
+
+```
+Relay-Signature:
+  t=1764949490,
+  v1=cc22398a143ebbfc709812fdc2328ca727ed913e5e45250cfb6f3b5dfad2e72d
+```
+
+> [!NOTE]
+> We provide newlines for clarity, but a real `Relay-Signature` header is on a
+> single line.
+
+The signature `v1` is computed over the concatenation of the timestamp `t` with
+the raw response body, delimited by `.`. The signature will be in hexadecimal
+format.
+
+### Verifying signatures
+
+To verify a response signature from Relay:
+
+#### Step 1: Extract the timestamp and signature
+
+Split the `Relay-Signature` header on the `,` character to get its parts. Then
+split each part on `=` to obtain key–value pairs.
+
+The value for `t` is the timestamp, and the value for `v1` is the signature.
+Discard all other parts to avoid downgrade attacks.
+
+#### Step 2: Prepare the signing data
+
+Construct the signed payload by concatenating:
+
+- The unix timestamp `t` (as a string)
+- The character `.`
+- The raw response body (as a string)
+
+Relay uses a literal period character (`.`) as the delimiter between the
+timestamp and the raw response body.
+
+#### Step 3: Compute the signature
+
+Compute an HMAC using the SHA256 hash function, using your signing secret as
+the key. The message is from Step 2. Hex-encode the result.
+
+#### Step 4: Compare the signatures
+
+Compare the received `v1` signature to the signature from Step 3. Before
+accepting the signature, ensure the timestamp is within your allowed tolerance
+window, e.g. 5 minutes, to avoid replay attacks. In addition, it's recommended
+to use a constant-time comparison function to avoid timing attacks.
+
+> [!WARNING]
+> Because all signing secrets are ultimately stored locally and Relay is being
+> run in an untrusted offline environment, there remains the possibility of a
+> bad actor obtaining the signing secrets and spoofing Relay. In such cases,
+> we recommend taking advantage of [audit logs](#logs).
+
 ## Pools
 
 Relay supports a concept called "pools," where, via the `--pool` flag, licenses
@@ -401,6 +462,9 @@ export BUILD_NODE_LOCKED_ADDR='0.0.0.0'
 # Relay port (optional)
 export BUILD_NODE_LOCKED_PORT='6349'
 
+# Signing secret (optional)
+export BUILD_NODE_LOCKED_SIGNING_SECRET="hunter2"
+
 # Build the node-locked binary using the above constraints
 BUILD_NODE_LOCKED=1 make build-linux-amd64
 ```

VERSION

@@ -1 +1 @@
-1.2.0-beta.2
+1.3.0-beta.1

internal/cmd/serve.go

@@ -31,6 +31,7 @@ func ServeCmd(srv server.Server) *cobra.Command {
 		return nil
 	})
 
+	router.Use(server.SigningMiddleware(cfg))
 	router.Use(server.LoggingMiddleware)
 
 	// Mount the router to the server
@@ -52,13 +53,19 @@ func ServeCmd(srv server.Server) *cobra.Command {
 				cfg.EnabledHeartbeat = !disableHeartbeats
 			}
 
-			// workaround for lack of support for nullable string flags
+			// workarounds for lack of support for nullable string flags
 			if p, err := cmd.Flags().GetString("pool"); err == nil {
 				if p != "" {
 					cfg.Pool = &p
 				}
 			}
 
+			if s, err := cmd.Flags().GetString("signing-secret"); err == nil {
+				if s != "" {
+					cfg.SigningSecret = &s
+				}
+			}
+
 			srv.Manager().Config().Strategy = string(cfg.Strategy)
 			srv.Manager().Config().ExtendOnHeartbeat = cfg.EnabledHeartbeat
 
@@ -99,6 +106,12 @@ func ServeCmd(srv server.Server) *cobra.Command {
 		cmd.Flags().IntVarP(&cfg.ServerPort, "port", "p", try.Try(try.EnvInt("RELAY_PORT"), try.EnvInt("PORT"), try.Static(cfg.ServerPort)), "port to run the relay server on [$RELAY_PORT=6349]")
 	}
 
+	if locker.LockedSigningSecret() {
+		cfg.SigningSecret = &locker.SigningSecret
+	} else {
+		cmd.Flags().String("signing-secret", try.Try(try.Env("RELAY_SIGNING_SECRET"), try.Static("")), "secret for signing responses [$RELAY_SIGNING_SECRET=hunter2]")
+	}
+
 	cmd.Flags().DurationVar(&cfg.TTL, "ttl", try.Try(try.EnvDuration("RELAY_LEASE_TTL"), try.Static(cfg.TTL)), "time-to-live for leases [$RELAY_LEASE_TTL=60s]")
 	cmd.Flags().Bool("no-heartbeats", try.Try(try.EnvBool("RELAY_NO_HEARTBEATS"), try.Static(false)), "disable node heartbeat monitoring and culling as well as lease extensions [$RELAY_NO_HEARTBEAT=1]")
 	cmd.Flags().Var(&cfg.Strategy, "strategy", `strategy for license distribution e.g. "fifo", "lifo", or "rand" [$RELAY_STRATEGY=rand]`)

internal/locker/locker.go

@@ -14,13 +14,14 @@ import (
 // locks Relay to a specific machine, depending on provided attributes. Relay will
 // error on mismatch, e.g. underlying IP address is different than expected IP.
 var (
-	PublicKey   string // required
-	Fingerprint string // required
-	Platform    string // optional
-	Hostname    string // optional
-	IP          string // optional
-	Addr        string // optional
-	Port        string // optional
+	PublicKey     string // required
+	Fingerprint   string // required
+	Platform      string // optional
+	Hostname      string // optional
+	IP            string // optional
+	Addr          string // optional
+	Port          string // optional
+	SigningSecret string // optional
 )
 
 func init() {
@@ -63,6 +64,11 @@ func LockedPort() bool {
 	return Port != ""
 }
 
+// LockedSigningSecret returns a boolean whether or not Relay's signing secret is locked
+func LockedSigningSecret() bool {
+	return SigningSecret != ""
+}
+
 // Unlock attempts to unlock Relay via a machine file and license key using the
 // current machine's fingerprint
 func Unlock(config Config) (*keygen.MachineFileDataset, error) {

internal/server/config.go

@@ -48,6 +48,7 @@ type Config struct {
 	Strategy         StrategyType
 	CullInterval     time.Duration
 	Pool             *string
+	SigningSecret    *string
 }
 
 func NewConfig() *Config {

internal/server/middleware.go

@@ -1,6 +1,9 @@
 package server
 
 import (
+	"bytes"
+	"encoding/hex"
+	"fmt"
 	"net/http"
 	"time"
 
@@ -27,19 +30,70 @@ func (lrw *loggingResponseWriter) WriteHeader(code int) {
 
 func LoggingMiddleware(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-
+		ww := wrapResponseWriter(w)
 		start := time.Now()
-		wrappedResponse := wrapResponseWriter(w)
 
-		next.ServeHTTP(wrappedResponse, r)
+		next.ServeHTTP(ww, r)
 
 		logger.Info("HTTP request",
 			"method", r.Method,
 			"path", r.URL.Path,
-			"status", wrappedResponse.Status(),
+			"status", ww.Status(),
 			"remote_addr", r.RemoteAddr,
 			"user_agent", r.UserAgent(),
 			"duration", time.Since(start),
 		)
 	})
 }
+
+// signingResponseWriter captures the response body for signing
+type signingResponseWriter struct {
+	http.ResponseWriter
+	body       *bytes.Buffer
+	statusCode int
+}
+
+func (srw *signingResponseWriter) Write(b []byte) (int, error) {
+	return srw.body.Write(b)
+}
+
+func (srw *signingResponseWriter) WriteHeader(code int) {
+	srw.statusCode = code
+}
+
+// SigningMiddleware creates a middleware that signs response bodies with HMAC-SHA256.
+// The signature is added as a Relay-Signature header in the format: t=<timestamp>,v1=<signature>
+func SigningMiddleware(cfg *Config) func(http.Handler) http.Handler {
+	var signer *Signer
+
+	return func(next http.Handler) http.Handler {
+		if signer == nil {
+			signer = NewSigner(*cfg.SigningSecret)
+		}
+
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			t := time.Now().Unix()
+			w.Header().Set("Relay-Clock", fmt.Sprintf("%d", t))
+
+			if !signer.Enabled() {
+				next.ServeHTTP(w, r)
+
+				return
+			}
+
+			ww := &signingResponseWriter{
+				ResponseWriter: w,
+				body:           &bytes.Buffer{},
+				statusCode:     http.StatusOK,
+			}
+
+			next.ServeHTTP(ww, r)
+
+			sig := signer.Sign(t, ww.body.Bytes())
+			w.Header().Set("Relay-Signature", fmt.Sprintf("t=%d,v1=%s", t, hex.EncodeToString(sig)))
+
+			w.WriteHeader(ww.statusCode)
+			w.Write(ww.body.Bytes())
+		})
+	}
+}

internal/server/signer.go

@@ -0,0 +1,34 @@
+package server
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"fmt"
+)
+
+type Signer struct {
+	secret []byte
+}
+
+func NewSigner(secret string) *Signer {
+	return &Signer{
+		secret: []byte(secret),
+	}
+}
+
+// Sign generates an HMAC-SHA256 signature for the given response body
+// returning a signature in the format: t=<timestamp>,v1=<signature>
+// where the signature is computed over "<timestamp>.<message>"
+func (s *Signer) Sign(timestamp int64, message []byte) []byte {
+	data := fmt.Sprintf("%d.%s", timestamp, message)
+
+	mac := hmac.New(sha256.New, s.secret)
+	mac.Write([]byte(data))
+
+	return mac.Sum(nil)
+}
+
+// Enabled returns true if the signer has a secret configured
+func (s *Signer) Enabled() bool {
+	return len(s.secret) > 0
+}