novox/mesh-controller
3
0
Fork 0
Code Issues Pull Requests 1 Releases Wiki Activity

Adopt the tunnel as a mesh fact, refuse a mismatched takeover, and rekey after enrolment

Browse Source 
Review of the ADR 0105 build (hq ADR 0105). Four things it got wrong and one
path it lacked:

- A predecessor spoke's tunnel names one peer, the hub, routed the whole
  range; recording refused it and the whole enrolment failed. Range-routed
  peers are skipped now — only the hub's peers are ever carried.
- The range and the carried peers were conditions on the node being adopted,
  so converging the hub would have renumbered the mesh and dropped the peers
  still reaching it. They are facts of the tunnel record now, mode aside; the
  takeover alone is declared to an adopted node. Converging the hub is refused
  while a carried peer has not enrolled, naming it.
- A push composed a takeover for a hub whose address or endpoint disagreed
  with the tunnel, which would have the host stop the found interface and
  raise the mesh's where no peer listens. The graph refuses to compose it,
  naming both and the placement that fixes it.
- The host's account said taken or not; "found down and the mesh's not up"
  read as not taken. Three states now, and an account on every takeover.
- A hub that enrolled before this feature holds a key of its own, and
  re-enrolling would rotate every key the mesh sealed credentials to. A node
  now rekeys in a report, signed with its identity key over the key it
  leaves, the key it takes and the tunnel; the mesh verifies against the live
  key, refuses a stale or foreign proof, records key and tunnel, and moves a
  hub to the tunnel's address. `overlay show` names the path for a hub that
  found no tunnel.

Also: a carried IPv6 peer is routed /128, and identity.ForTest exists so the
link can be tested against a real identity store.
This commit is contained in:
jschoubben
2026-09-24 00:02:07 +02:00
parent 3c836f0abb
commit 4566c5c9aa
11 changed files with 641 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files
internal/link/enrolment.go
+40 -1
View File
@@ -181,6 +181,34 @@ func (e Enrolment) Enrol(ctx context.Context, request EnrolRequest) (reply Enrol
return reply, nil
}
// rekey applies a verified rekey: the node's overlay key and tunnel are recorded as enrolment
// would have recorded them, and a hub moves to the tunnel's address.
func (e Enrolment) rekey(ctx context.Context, node inventory.Node, r Rekey) error {
if r.Tunnel == nil || r.OverlayKey == "" {
return fmt.Errorf("%s sent a rekey naming no tunnel or no key; refused", node.Name)
}
if e.Identity == nil {
return fmt.Errorf("%s sent a rekey and this mesh has no identity store to verify it against", node.Name)
}
if err := e.Identity.VerifyNode(ctx, node.ID,
RekeyProof(node.Name, r.Previous, r.OverlayKey, r.Tunnel), r.Proof); err != nil {
return fmt.Errorf("%s's rekey is not signed by %s's identity key; refused: %w", node.Name, node.Name, err)
}
peers := make([]inventory.TunnelPeer, 0, len(r.Tunnel.Peers))
for _, p := range r.Tunnel.Peers {
peers = append(peers, inventory.TunnelPeer{PublicKey: p.PublicKey, Address: p.Address})
}
err := e.Inventory.Rekey(ctx, node.ID, r.Previous, r.OverlayKey, inventory.Tunnel{
Interface: r.Tunnel.Interface, Unit: r.Tunnel.Unit, Config: r.Tunnel.Config, Port: r.Tunnel.Port,
Address: r.Tunnel.Address, Range: r.Tunnel.Range, PublicKey: r.Tunnel.PublicKey, Peers: peers,
})
if err != nil {
return fmt.Errorf("%s's rekey was not recorded: %w", node.Name, err)
}
log.Printf("%s took over the tunnel on %s: its overlay key is the tunnel's now", node.Name, r.Tunnel.Interface)
return nil
}
// claimant names the key presenting a token, so a claim can be held for it alone.
func claimant(public ed25519.PublicKey) string {
sum := sha256.Sum256(public)
@@ -246,11 +274,22 @@ func (e Enrolment) Heard(ctx context.Context, report Report) (err error) {
if report.Tunnel != nil {
if err := e.Inventory.RecordCarriedTunnel(ctx, node.ID, inventory.Carried{
Interface: report.Tunnel.Interface, Port: report.Tunnel.Port, Range: report.Tunnel.Range,
Peers: report.Tunnel.Peers, Taken: report.Tunnel.Taken, Kept: report.Tunnel.Kept,
Peers: report.Tunnel.Peers, State: report.Tunnel.State, Note: report.Tunnel.Note,
Kept: report.Tunnel.Kept,
}); err != nil {
return err
}
}
// A node taking a found tunnel's key after enrolment (novox/hq ADR 0105). Verified against the
// node's live identity key before anything is written: the broker account authenticates the
// connection, the signature proves the node itself said it. Refused outright when the proof
// does not verify or is stale — a refusal, not "not now", so the node hears why.
if report.Rekey != nil {
if err := e.rekey(ctx, node, *report.Rekey); err != nil {
return err
}
return e.Inventory.Seen(ctx, node.ID)
}
// A bare word that a node is there is not an account of what the machine did or holds: it
// moves last_seen and touches nothing else. This arrives every minute (link.AliveEvery),
internal/link/protocol.go
+43 -2
View File
@@ -8,6 +8,8 @@ package link
import (
"encoding/base64"
"strconv"
"strings"
"time"
)
@@ -161,18 +163,57 @@ type Report struct {
// 0105): the interface, its port, range and peer count, whether the found interface is down
// and the mesh's up in its place, and where the found configuration's original was kept.
Tunnel *CarriedTunnel `json:"tunnel,omitempty"`
// Rekey is a node taking a found tunnel's key as its overlay key after enrolment (novox/hq
// ADR 0105). A report carrying one is not an account of the machine: it moves the node's
// overlay key and tunnel and nothing else.
Rekey *Rekey `json:"rekey,omitempty"`
}
// CarriedTunnel is a node's account of the tunnel it took over.
// CarriedTunnel is a node's account of the tunnel it took over. State is "not-taken" (the found
// interface still up, the mesh's not), "taken" (the found one down, the mesh's up with its key) or
// "down" (the found one down and the mesh's not up: the peers reach nothing); Note is what the host
// did about it.
type CarriedTunnel struct {
Interface string `json:"interface"`
Port int `json:"port"`
Range string `json:"range"`
Peers int `json:"peers"`
Taken bool `json:"taken"`
State string `json:"state"`
Note string `json:"note,omitempty"`
Kept string `json:"kept,omitempty"`
}
// Rekey is a node saying it took a found tunnel's key as its overlay key after enrolling (novox/hq
// ADR 0105) — the path for a hub that enrolled before the mesh knew to take a tunnel over, since
// re-enrolling would rotate every key the node holds. Carried in a report, on the node's own
// authenticated connection, and signed with its identity key over RekeyProof, so a report forged
// on a stolen broker account cannot move a node's overlay key.
type Rekey struct {
// Previous is the overlay key the node holds now, as the mesh records it. A rekey naming
// another is stale — a replay, or made against a record that moved on — and is refused.
Previous string `json:"previous"`
OverlayKey string `json:"overlay_key"`
Tunnel *Tunnel `json:"tunnel"`
Proof []byte `json:"proof"`
}
// RekeyProof is what a node signs when it rekeys: the node, the key it leaves, the key it takes
// and the tunnel it took it from, so a proof cannot be moved to another node or another tunnel.
func RekeyProof(node, previous, key string, tunnel *Tunnel) []byte {
var t Tunnel
if tunnel != nil {
t = *tunnel
}
peers := make([]string, 0, len(t.Peers))
for _, p := range t.Peers {
peers = append(peers, p.PublicKey+"@"+p.Address)
}
return []byte("novox-mesh-rekey\x00" + node + "\x00" + previous + "\x00" + key + "\x00" +
t.Interface + "\x00" + t.Unit + "\x00" + t.Config + "\x00" + strconv.Itoa(t.Port) + "\x00" +
t.Address + "\x00" + t.Range + "\x00" + t.PublicKey + "\x00" + strings.Join(peers, ","))
}
// Held is one file or container found on an adopted node and kept as it was.
type Held struct {
ID string `json:"id"`
internal/link/rekey_test.go
+135
View File
@@ -0,0 +1,135 @@
package link_test
import (
"crypto/ed25519"
"strings"
"testing"
"github.com/novox/mesh-controller/internal/identity"
"github.com/novox/mesh-controller/internal/inventory"
"github.com/novox/mesh-controller/internal/link"
)
// novox/hq ADR 0105: a hub that enrolled before the mesh knew to take a tunnel over rekeys onto the
// found tunnel's key without re-enrolling — which would rotate every key it holds and remake every
// credential the mesh sealed to it. The rekey rides in a report and is signed with the node's
// identity key; the mesh verifies it against the key it recorded, and refuses one signed by
// another key or one already applied.
const (
ownKey = "THE-MESHS-OWN-KEY======================="
tunnelKey = "TUNNEL-KEY-the-found-interfaces-public-key="
)
func theTunnel() *link.Tunnel {
return &link.Tunnel{Interface: "wg0", Unit: "wg-quick@wg0", Config: "/etc/wireguard/wg0.conf",
Port: 51900, Address: "192.0.2.1/24", Range: "192.0.2.0/24", PublicKey: tunnelKey,
Peers: []link.TunnelPeer{{PublicKey: "PEER-A=", Address: "192.0.2.2/32"}}}
}
// anEnrolledHub is a hub the way it stands before the feature: adopted, placed, its overlay key its
// own, its identity key recorded — and a mesh holding both stores.
func anEnrolledHub(t *testing.T) (link.Enrolment, inventory.Node, ed25519.PrivateKey) {
t.Helper()
inv := inventory.ForTest(t)
ident := identity.ForTest(t)
ctx := t.Context()
hub, err := inv.AddNodeAs(ctx, "anchor", true)
if err != nil {
t.Fatal(err)
}
public, private, err := ed25519.GenerateKey(nil)
if err != nil {
t.Fatal(err)
}
if _, err := ident.RecordNodeKey(ctx, hub.ID, public); err != nil {
t.Fatal(err)
}
if err := inv.RecordOverlayKey(ctx, hub.ID, ownKey); err != nil {
t.Fatal(err)
}
if err := inv.SetPlace(ctx, "anchor", "anchor.example:51900", "hosting", true, "10.42.0.1"); err != nil {
t.Fatal(err)
}
return link.Enrolment{Inventory: inv, Identity: ident}, hub, private
}
func TestASignedRekeyMovesTheHubOntoItsTunnel(t *testing.T) {
e, hub, private := anEnrolledHub(t)
ctx := t.Context()
rekey := &link.Rekey{Previous: ownKey, OverlayKey: tunnelKey, Tunnel: theTunnel()}
rekey.Proof = ed25519.Sign(private, link.RekeyProof("anchor", ownKey, tunnelKey, theTunnel()))
if err := e.Heard(ctx, link.Report{Node: "anchor", Rekey: rekey}); err != nil {
t.Fatal(err)
}
placed, err := e.Inventory.Overlays(ctx)
if err != nil || len(placed) != 1 {
t.Fatal(placed, err)
}
if placed[0].Key != tunnelKey || placed[0].Address != "192.0.2.1" {
t.Fatalf("the hub is not on the tunnel's key and address: %+v", placed[0])
}
tunnel, _, adopted, err := e.Inventory.AdoptedTunnel(ctx)
if err != nil || !adopted || tunnel.Range != "192.0.2.0/24" || len(tunnel.Peers) != 1 {
t.Fatalf("the tunnel is not adopted after the rekey: %+v %t %v", tunnel, adopted, err)
}
_ = hub
// Replayed, it is stale: the previous key it names is no longer the node's.
err = e.Heard(ctx, link.Report{Node: "anchor", Rekey: rekey})
if err == nil || !strings.Contains(err.Error(), "previous overlay key") {
t.Fatalf("a replayed rekey was accepted: %v", err)
}
}
func TestARekeySignedByAnotherKeyIsRefusedAndChangesNothing(t *testing.T) {
e, _, _ := anEnrolledHub(t)
ctx := t.Context()
_, stranger, err := ed25519.GenerateKey(nil)
if err != nil {
t.Fatal(err)
}
rekey := &link.Rekey{Previous: ownKey, OverlayKey: tunnelKey, Tunnel: theTunnel()}
rekey.Proof = ed25519.Sign(stranger, link.RekeyProof("anchor", ownKey, tunnelKey, theTunnel()))
err = e.Heard(ctx, link.Report{Node: "anchor", Rekey: rekey})
if err == nil || !strings.Contains(err.Error(), "not signed by anchor's identity key") {
t.Fatalf("a rekey signed by a stranger was accepted: %v", err)
}
placed, _ := e.Inventory.Overlays(ctx)
if placed[0].Key != ownKey || placed[0].Address != "10.42.0.1" {
t.Fatalf("a refused rekey changed the record: %+v", placed[0])
}
if _, _, adopted, _ := e.Inventory.AdoptedTunnel(ctx); adopted {
t.Fatal("a refused rekey recorded a tunnel")
}
// And a proof moved to another tunnel — the signature was over one tunnel, the message names
// another — does not verify either.
moved := &link.Rekey{Previous: ownKey, OverlayKey: tunnelKey, Tunnel: theTunnel()}
other := theTunnel()
other.Port = 51820
moved.Proof = ed25519.Sign(mustPrivate(t, e, "anchor"), link.RekeyProof("anchor", ownKey, tunnelKey, other))
if err := e.Heard(ctx, link.Report{Node: "anchor", Rekey: moved}); err == nil {
t.Fatal("a proof over another tunnel was accepted")
}
}
// mustPrivate is a fresh key recorded as the node's live one, for signing in a test that needs
// the node's own signature after the fixture's key is out of scope.
func mustPrivate(t *testing.T, e link.Enrolment, node string) ed25519.PrivateKey {
t.Helper()
public, private, err := ed25519.GenerateKey(nil)
if err != nil {
t.Fatal(err)
}
n, err := e.Inventory.NodeByName(t.Context(), node)
if err != nil {
t.Fatal(err)
}
if _, err := e.Identity.RecordNodeKey(t.Context(), n.ID, public); err != nil {
t.Fatal(err)
}
return private
}