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,69 @@ 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. The signing
+secret should be shared between Relay and your application.
+
+```
+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 `.` character. The signature will be in
+hexadecimal format.
+
+### Verifying signatures
+
+To verify a response signature from Relay inside your application:
+
+#### 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 pairs 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 shared 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, even when [node-locked](#node-locking).
+> In such environments, we recommend taking advantage of [audit logs](#logs) to
+> periodically audit Relay.
+
 ## Pools
 
 Relay supports a concept called "pools," where, via the `--pool` flag, licenses
@@ -401,6 +464,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
 ```

cli/testdata/server_signing_secret.test.txt

@@ -0,0 +1,39 @@
+# add the license
+exec relay add --file license.lic --key 9E32DD-D8CC22-771926-C2D834-C506DC-V3 --public-key e8601e48b69383ba520245fd07971e983d06d22c4257cfd82304601479cee788
+
+# set a port as environment variable
+env PORT=65041
+
+# start the server without signing secret
+exec relay serve --port $PORT &server_process_test_1&
+
+# wait for the server to start
+exec sleep 1
+
+# claim a license
+exec curl -s -D headers.txt -o /dev/null -w "%{http_code}" -X PUT http://localhost:$PORT/v1/nodes/test_fingerprint
+
+# expect no signature header
+stdout '201'
+! exec grep 'Relay-Signature:' headers.txt
+
+# kill the server
+kill server_process_test_1
+
+# restart the server with signing secret
+env PORT=65042
+
+exec relay serve --port $PORT --signing-secret hunter2 -vvvv &server_process_test_2&
+
+# wait for the server to start
+exec sleep 1
+
+# claim a license
+exec curl -s -D headers.txt -o /dev/null -w "%{http_code}" -X PUT http://localhost:$PORT/v1/nodes/test_fingerprint
+
+# expect a signature header
+stdout '202'
+exec grep 'Relay-Signature:' headers.txt
+
+# kill the server
+kill server_process_test_2

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/handler_test.go

@@ -2,10 +2,15 @@ package server_test
 
 import (
 	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
 	"encoding/json"
 	"errors"
+	"fmt"
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"testing"
 	"time"
 
@@ -237,3 +242,108 @@ func TestReleaseLicense_InternalServerError(t *testing.T) {
 	assert.Equal(t, http.StatusInternalServerError, rr.Code)
 	assert.Contains(t, rr.Body.String(), "failed to release license")
 }
+
+func TestClaimLicense_Signature_Enabled(t *testing.T) {
+	secret := "test_secret"
+
+	cfg := server.NewConfig()
+	cfg.SigningSecret = &secret
+
+	srv := testutils.NewMockServer(
+		cfg,
+		&testutils.FakeManager{
+			ClaimLicenseFn: func(ctx context.Context, pool *string, fingerprint string) (*licenses.LicenseOperationResult, error) {
+				return &licenses.LicenseOperationResult{
+					License: &db.License{
+						File: []byte("test_license_file"),
+						Key:  "test_license_key",
+					},
+					Status: licenses.OperationStatusCreated,
+				}, nil
+			},
+		},
+	)
+
+	handler := server.NewHandler(srv)
+
+	req := httptest.NewRequest(http.MethodPut, "/v1/nodes/test_fingerprint", nil)
+	rr := httptest.NewRecorder()
+
+	router := mux.NewRouter()
+	router.Use(server.SigningMiddleware(cfg))
+	handler.RegisterRoutes(router)
+	router.ServeHTTP(rr, req)
+
+	sig := rr.Header().Get("Relay-Signature")
+	clock := rr.Header().Get("Relay-Clock")
+
+	assert.NotEmpty(t, sig)
+	assert.NotEmpty(t, clock)
+
+	assert.True(t, verifySignature(secret, sig, rr.Body.String()))
+}
+
+func TestClaimLicense_Signature_Disabled(t *testing.T) {
+	cfg := server.NewConfig()
+	srv := testutils.NewMockServer(
+		cfg,
+		&testutils.FakeManager{
+			ClaimLicenseFn: func(ctx context.Context, pool *string, fingerprint string) (*licenses.LicenseOperationResult, error) {
+				return &licenses.LicenseOperationResult{
+					License: &db.License{
+						File: []byte("test_license_file"),
+						Key:  "test_license_key",
+					},
+					Status: licenses.OperationStatusCreated,
+				}, nil
+			},
+		},
+	)
+
+	handler := server.NewHandler(srv)
+
+	req := httptest.NewRequest(http.MethodPut, "/v1/nodes/test_fingerprint", nil)
+	rr := httptest.NewRecorder()
+
+	router := mux.NewRouter()
+	router.Use(server.SigningMiddleware(cfg))
+	handler.RegisterRoutes(router)
+	router.ServeHTTP(rr, req)
+
+	sig := rr.Header().Get("Relay-Signature")
+	clock := rr.Header().Get("Relay-Clock")
+
+	assert.Empty(t, sig)
+	assert.NotEmpty(t, clock)
+}
+
+func verifySignature(secret string, header string, body string) bool {
+	var t, v1 string
+
+	for _, part := range strings.Split(header, ",") {
+		kv := strings.SplitN(strings.TrimSpace(part), "=", 2)
+		if len(kv) != 2 {
+			continue
+		}
+
+		switch kv[0] {
+		case "t":
+			t = kv[1]
+		case "v1":
+			v1 = kv[1]
+		}
+	}
+
+	if t == "" || v1 == "" {
+		return false
+	}
+
+	mac := hmac.New(sha256.New, []byte(secret))
+	msg := fmt.Sprintf("%s.%s", t, body)
+	mac.Write([]byte(msg))
+
+	expected := make([]byte, hex.EncodedLen(mac.Size()))
+	hex.Encode(expected, mac.Sum(nil))
+
+	return hmac.Equal(expected, []byte(v1))
+}