Skip to content

Agent Mesh

controlplane: refresh biscuits are single-use; document challenge units

Antonio Ojeaaaaf4a91949d
diff --git a/api/sam.pb.go b/api/sam.pb.go
index deed7a67..8812a24c 100644
--- a/api/sam.pb.go
+++ b/api/sam.pb.go
@@ -1674,11 +1674,13 @@ func (x *KeysResponse) GetPublicKeys() [][]byte {
}
type TokenRefreshRequest struct {
- state protoimpl.MessageState `protogen:"open.v1"`
- ChallengeSignature []byte `protobuf:"bytes,1,opt,name=challenge_signature,json=challengeSignature,proto3" json:"challenge_signature,omitempty"`
- Timestamp int64 `protobuf:"varint,2,opt,name=timestamp,proto3" json:"timestamp,omitempty"`
- unknownFields protoimpl.UnknownFields
- sizeCache protoimpl.SizeCache
+ state protoimpl.MessageState `protogen:"open.v1"`
+ // Signature over the decimal string form of timestamp, made with the node key.
+ ChallengeSignature []byte `protobuf:"bytes,1,opt,name=challenge_signature,json=challengeSignature,proto3" json:"challenge_signature,omitempty"`
+ // Unix milliseconds. Must be within the control plane's freshness window.
+ Timestamp int64 `protobuf:"varint,2,opt,name=timestamp,proto3" json:"timestamp,omitempty"`
+ unknownFields protoimpl.UnknownFields
+ sizeCache protoimpl.SizeCache
}
func (x *TokenRefreshRequest) Reset() {
diff --git a/api/sam.proto b/api/sam.proto
index 458cd895..4c8b3bac 100644
--- a/api/sam.proto
+++ b/api/sam.proto
@@ -215,7 +215,9 @@ message KeysResponse {
}
message TokenRefreshRequest {
+ // Signature over the decimal string form of timestamp, made with the node key.
bytes challenge_signature = 1;
+ // Unix milliseconds. Must be within the control plane's freshness window.
int64 timestamp = 2;
}
diff --git a/internal/controlplane/server.go b/internal/controlplane/server.go
index 853bafec..f9c6b2df 100644
--- a/internal/controlplane/server.go
+++ b/internal/controlplane/server.go
@@ -697,6 +697,16 @@ func (s *Server) HandleRefresh(w http.ResponseWriter, r *http.Request) {
return
}
+ // Rotation with reuse detection: every issuance path persists the latest
+ // biscuit, so only that one token is redeemable. A replayed refresh
+ // presents an already-rotated biscuit and is refused; a node that lost the
+ // rotated token recovers through its re-enrollment fallback.
+ if subtle.ConstantTimeCompare(currentBiscuitBytes, nodeRecord.Biscuit) != 1 {
+ logger.Warnw("Refresh presented an already-rotated biscuit (possible replay)", "peer_id", nodeRecord.PeerID)
+ http.Error(w, "Biscuit already rotated: only the latest issued token can be refreshed, re-enroll instead", http.StatusUnauthorized)
+ return
+ }
+
// Fetch current signing private key and policy config
privKey, _, err := s.store.GetCurrentKey(ctx)
if err != nil {
diff --git a/internal/controlplane/server_test.go b/internal/controlplane/server_test.go
index 543c7fea..e7e8d538 100644
--- a/internal/controlplane/server_test.go
+++ b/internal/controlplane/server_test.go
@@ -925,16 +925,11 @@ func TestEnrollmentWorkflow(t *testing.T) {
}
}
-func TestHandleRefresh_RejectsStaleTimestamp(t *testing.T) {
- t.Parallel()
-
- srv, store, cpURL := setupTestServer(t, "")
- defer func() {
- _ = srv.Close()
- _ = store.Close()
- }()
+// enrollRefreshTestNode enrolls a bootstrap node directly in the store and
+// returns its key and currently issued biscuit, ready to drive /refresh.
+func enrollRefreshTestNode(t *testing.T, ctx context.Context, store storage.Store) (crypto.PrivKey, []byte) {
+ t.Helper()
- ctx := context.Background()
cpPriv, _, err := store.GetCurrentKey(ctx)
if err != nil {
t.Fatalf("GetCurrentKey: %v", err)
@@ -976,28 +971,37 @@ func TestHandleRefresh_RejectsStaleTimestamp(t *testing.T) {
}); err != nil {
t.Fatalf("EnrollNode: %v", err)
}
+ return priv, biscuitBytes
+}
+
+// signedRefreshRequest builds a marshaled /refresh body for the given timestamp.
+func signedRefreshRequest(t *testing.T, priv crypto.PrivKey, timestamp int64) []byte {
+ t.Helper()
- staleTimestamp := time.Now().Add(-2 * time.Hour).UnixMilli()
- challengeData := []byte(fmt.Sprintf("%d", staleTimestamp))
- challengeSig, err := priv.Sign(challengeData)
+ sig, err := priv.Sign([]byte(fmt.Sprintf("%d", timestamp)))
if err != nil {
t.Fatalf("Sign: %v", err)
}
-
- refreshReq := &api.TokenRefreshRequest{
- ChallengeSignature: challengeSig,
- Timestamp: staleTimestamp,
- }
- refreshData, err := proto.Marshal(refreshReq)
+ data, err := proto.Marshal(&api.TokenRefreshRequest{
+ ChallengeSignature: sig,
+ Timestamp: timestamp,
+ })
if err != nil {
t.Fatalf("Marshal: %v", err)
}
+ return data
+}
- req, err := http.NewRequest(http.MethodPost, cpURL+"/refresh", bytes.NewReader(refreshData))
+// doRefresh posts a prebuilt /refresh body under the given biscuit and returns
+// the response status and body.
+func doRefresh(t *testing.T, cpURL string, biscuit, body []byte) (int, []byte) {
+ t.Helper()
+
+ req, err := http.NewRequest(http.MethodPost, cpURL+"/refresh", bytes.NewReader(body))
if err != nil {
t.Fatalf("NewRequest: %v", err)
}
- req.Header.Set("Authorization", "Bearer "+base64.StdEncoding.EncodeToString(biscuitBytes))
+ req.Header.Set("Authorization", "Bearer "+base64.StdEncoding.EncodeToString(biscuit))
req.Header.Set("Content-Type", "application/x-protobuf")
resp, err := http.DefaultClient.Do(req)
@@ -1005,10 +1009,90 @@ func TestHandleRefresh_RejectsStaleTimestamp(t *testing.T) {
t.Fatalf("Do: %v", err)
}
defer func() { _ = resp.Body.Close() }()
+ respBody, _ := io.ReadAll(resp.Body)
+ return resp.StatusCode, respBody
+}
- if resp.StatusCode != http.StatusUnauthorized {
- body, _ := io.ReadAll(resp.Body)
- t.Fatalf("expected stale-timestamp refresh to be rejected with 401, got %s: %s", resp.Status, body)
+// TestHandleRefresh_TimestampFreshness walks the challenge timestamp across
+// the ±5m freshness window. Each case enrolls its own node because a
+// successful refresh rotates the biscuit and would bleed into the next case.
+func TestHandleRefresh_TimestampFreshness(t *testing.T) {
+ t.Parallel()
+
+ srv, store, cpURL := setupTestServer(t, "")
+ defer func() {
+ _ = srv.Close()
+ _ = store.Close()
+ }()
+
+ ctx := context.Background()
+
+ cases := []struct {
+ name string
+ timestamp func() int64
+ wantStatus int
+ }{
+ {"fresh", func() int64 { return time.Now().UnixMilli() }, http.StatusOK},
+ {"within window past", func() int64 { return time.Now().Add(-4 * time.Minute).UnixMilli() }, http.StatusOK},
+ {"within window future", func() int64 { return time.Now().Add(4 * time.Minute).UnixMilli() }, http.StatusOK},
+ {"stale", func() int64 { return time.Now().Add(-2 * time.Hour).UnixMilli() }, http.StatusUnauthorized},
+ {"far future", func() int64 { return time.Now().Add(2 * time.Hour).UnixMilli() }, http.StatusUnauthorized},
+ {"seconds instead of milliseconds", func() int64 { return time.Now().Unix() }, http.StatusUnauthorized},
+ {"zero", func() int64 { return 0 }, http.StatusBadRequest},
+ {"negative", func() int64 { return -1 }, http.StatusBadRequest},
+ }
+
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ priv, biscuitBytes := enrollRefreshTestNode(t, ctx, store)
+ status, body := doRefresh(t, cpURL, biscuitBytes, signedRefreshRequest(t, priv, tc.timestamp()))
+ if status != tc.wantStatus {
+ t.Errorf("got status %d, want %d (body: %s)", status, tc.wantStatus, body)
+ }
+ })
+ }
+}
+
+// TestHandleRefresh_BiscuitIsSingleUse pins refresh-token rotation: a biscuit
+// can be redeemed exactly once, so a captured request replayed inside the
+// freshness window mints nothing, while the rotated token keeps refreshing.
+func TestHandleRefresh_BiscuitIsSingleUse(t *testing.T) {
+ t.Parallel()
+
+ srv, store, cpURL := setupTestServer(t, "")
+ defer func() {
+ _ = srv.Close()
+ _ = store.Close()
+ }()
+
+ ctx := context.Background()
+ priv, biscuitBytes := enrollRefreshTestNode(t, ctx, store)
+
+ refreshData := signedRefreshRequest(t, priv, time.Now().UnixMilli())
+
+ status, body := doRefresh(t, cpURL, biscuitBytes, refreshData)
+ if status != http.StatusOK {
+ t.Fatalf("first refresh: got %d: %s", status, body)
+ }
+ var refreshResp api.TokenRefreshResponse
+ if err := proto.Unmarshal(body, &refreshResp); err != nil {
+ t.Fatalf("unmarshal TokenRefreshResponse: %v", err)
+ }
+ if bytes.Equal(refreshResp.BiscuitToken, biscuitBytes) {
+ t.Fatal("refresh returned the same biscuit instead of rotating it")
+ }
+
+ // Byte-identical replay of the captured request: the timestamp is still
+ // fresh, but the presented biscuit has been rotated.
+ status, body = doRefresh(t, cpURL, biscuitBytes, refreshData)
+ if status != http.StatusUnauthorized {
+ t.Fatalf("expected replayed refresh to be rejected with 401, got %d: %s", status, body)
+ }
+
+ // The rotated token is the one redeemable credential.
+ status, body = doRefresh(t, cpURL, refreshResp.BiscuitToken, signedRefreshRequest(t, priv, time.Now().UnixMilli()))
+ if status != http.StatusOK {
+ t.Fatalf("refresh with rotated biscuit: got %d: %s", status, body)
}
}