From 2b879a6e957ff054e6eb01a8a8aa207bfbad36d8 Mon Sep 17 00:00:00 2001 From: Simon Law Date: Thu, 4 Jun 2026 18:10:30 -0700 Subject: [PATCH] cmd/tailscale/tslockjsonv1: export structs to unmarshal JSON for `tailscale lock` This patch exports the structs used to unmarshal the JSON output of the `tailscale lock` subcommand. Updates #17613 Change-Id: I615723ff9dbc631e452dbf6bbdeab7b97e96dbb3 Signed-off-by: Simon Law --- cmd/tailscale/cli/tailnet-lock_test.go | 29 ++++- .../tslockjsonv1/tailnet-lock-log.go | 35 +++--- .../tslockjsonv1/tailnet-lock-status.go | 82 ++++++-------- cmd/tailscale/tslockjsonv1/tka.go | 103 +++++++++++------- 4 files changed, 140 insertions(+), 109 deletions(-) diff --git a/cmd/tailscale/cli/tailnet-lock_test.go b/cmd/tailscale/cli/tailnet-lock_test.go index 2be4ce33a..6e0814e9b 100644 --- a/cmd/tailscale/cli/tailnet-lock_test.go +++ b/cmd/tailscale/cli/tailnet-lock_test.go @@ -306,7 +306,6 @@ func TestTailnetLockStatusOutput(t *testing.T) { "NodeKey": "nodekey:0101010101010101010101010101010101010101010101010101010101010101", "Head": "WYIVHDR7JUIXBWAJT5UPSCAILEXB7OMINDFEFEPOPNTUCNXMY2KA", "NodeKeySigned": false, - "NodeKeySignature": null, "TrustedKeys": [ { "Kind": "25519", @@ -350,6 +349,34 @@ func TestTailnetLockStatusOutput(t *testing.T) { ], "State": 98989898 } +`, + }, + { + Name: "tailnet-lock-enabled-but-empty", + Status: ipnstate.NetworkLockStatus{ + Enabled: true, + Head: &head, + PublicKey: nlPub, + NodeKey: &nodeKey1, + NodeKeySigned: false, + NodeKeySignature: nil, + TrustedKeys: nil, + VisiblePeers: nil, + FilteredPeers: nil, + StateID: 98989898, + }, + Want: `{ + "SchemaVersion": "1", + "Enabled": true, + "PublicKey": "tlpub:0404040404040404040404040404040404040404040404040404040404040404", + "NodeKey": "nodekey:0101010101010101010101010101010101010101010101010101010101010101", + "Head": "WYIVHDR7JUIXBWAJT5UPSCAILEXB7OMINDFEFEPOPNTUCNXMY2KA", + "NodeKeySigned": false, + "TrustedKeys": [], + "VisiblePeers": [], + "FilteredPeers": [], + "State": 98989898 +} `, }, } { diff --git a/cmd/tailscale/tslockjsonv1/tailnet-lock-log.go b/cmd/tailscale/tslockjsonv1/tailnet-lock-log.go index 4f31fa09a..cbf15c892 100644 --- a/cmd/tailscale/tslockjsonv1/tailnet-lock-log.go +++ b/cmd/tailscale/tslockjsonv1/tailnet-lock-log.go @@ -26,7 +26,7 @@ import ( // - the raw AUM as base64-encoded bytes // - the expanded AUM, which prints named fields for consumption by other tools func PrintTailnetLockLogJSONV1(out io.Writer, updates []ipnstate.TailnetLockUpdate) error { - messages := make([]logMessageV1, len(updates)) + messages := make([]LogMessage, len(updates)) for i, update := range updates { var aum tka.AUM @@ -43,10 +43,7 @@ func PrintTailnetLockLogJSONV1(out io.Writer, updates []ipnstate.TailnetLockUpda messages[i] = toLogMessageV1(aum, update) } - result := struct { - jsonoutput.ResponseEnvelope - Messages []logMessageV1 - }{ + result := LogResponse{ ResponseEnvelope: jsonoutput.ResponseEnvelope{ SchemaVersion: "1", }, @@ -58,10 +55,16 @@ func PrintTailnetLockLogJSONV1(out io.Writer, updates []ipnstate.TailnetLockUpda return enc.Encode(result) } +// LogResponse is the full Tailnet Lock log output collected from the local Tailscale daemon. +type LogResponse struct { + jsonoutput.ResponseEnvelope + Messages []LogMessage +} + // toLogMessageV1 converts a [tka.AUM] and [ipnstate.TailnetLockUpdate] to the // JSON output returned by the CLI. -func toLogMessageV1(aum tka.AUM, update ipnstate.TailnetLockUpdate) logMessageV1 { - expandedAUM := expandedAUMV1{} +func toLogMessageV1(aum tka.AUM, update ipnstate.TailnetLockUpdate) LogMessage { + expandedAUM := AUM{} expandedAUM.MessageKind = aum.MessageKind.String() if len(aum.PrevAUMHash) > 0 { expandedAUM.PrevAUMHash = aum.PrevAUMHash.String() @@ -73,7 +76,7 @@ func toLogMessageV1(aum tka.AUM, update ipnstate.TailnetLockUpdate) logMessageV1 expandedAUM.KeyID = fmt.Sprintf("tlpub:%x", keyID) } if state := aum.State; state != nil { - expandedState := expandedStateV1{} + expandedState := TKAState{} if h := state.LastAUMHash; h != nil { expandedState.LastAUMHash = h.String() } @@ -92,31 +95,31 @@ func toLogMessageV1(aum tka.AUM, update ipnstate.TailnetLockUpdate) logMessageV1 } expandedAUM.Meta = aum.Meta for _, signature := range aum.Signatures { - expandedAUM.Signatures = append(expandedAUM.Signatures, expandedSignatureV1{ + expandedAUM.Signatures = append(expandedAUM.Signatures, Signature{ KeyID: fmt.Sprintf("tlpub:%x", signature.KeyID), Signature: base64.URLEncoding.EncodeToString(signature.Signature), }) } - return logMessageV1{ + return LogMessage{ Hash: aum.Hash().String(), AUM: expandedAUM, Raw: base64.URLEncoding.EncodeToString(update.Raw), } } -// logMessageV1 is the JSON representation of an AUM as both raw bytes and +// LogMessage is the JSON representation of a [tka.AUM] as both raw bytes and // in its expanded form, and the CLI output is a list of these entries. -type logMessageV1 struct { - // The BLAKE2s digest of the CBOR-encoded AUM. This is printed as a +type LogMessage struct { + // The BLAKE2s digest of the CBOR-encoded [tka.AUM]. This is printed as a // base32-encoded string, e.g. KCE…XZQ Hash string - // The expanded form of the AUM, which presents the fields in a more + // The expanded form of the [tka.AUM], which presents the fields in a more // accessible format than doing a CBOR decoding. - AUM expandedAUMV1 + AUM AUM - // The raw bytes of the CBOR-encoded AUM, encoded as base64. + // The raw bytes of the CBOR-encoded [tka.AUM], encoded as base64. // This is useful for verifying the AUM hash. Raw string } diff --git a/cmd/tailscale/tslockjsonv1/tailnet-lock-status.go b/cmd/tailscale/tslockjsonv1/tailnet-lock-status.go index 9a7e35101..09e20af01 100644 --- a/cmd/tailscale/tslockjsonv1/tailnet-lock-status.go +++ b/cmd/tailscale/tslockjsonv1/tailnet-lock-status.go @@ -21,23 +21,13 @@ func PrintTailnetLockStatusJSONV1(out io.Writer, status *ipnstate.TailnetLockSta SchemaVersion: "1", } - var result any + var result StatusResponse if status.Enabled { - result = struct { - jsonoutput.ResponseEnvelope - tailnetLockEnabledStatusV1 - }{ - ResponseEnvelope: responseEnvelope, - tailnetLockEnabledStatusV1: toTailnetLockEnabledStatusV1(status), - } + result = toTailnetLockEnabledStatusV1(status) + result.ResponseEnvelope = responseEnvelope } else { - result = struct { - jsonoutput.ResponseEnvelope - tailnetLockDisabledStatusV1 - }{ - ResponseEnvelope: responseEnvelope, - tailnetLockDisabledStatusV1: toTailnetLockDisabledStatusV1(status), - } + result = toTailnetLockDisabledStatusV1(status) + result.ResponseEnvelope = responseEnvelope } enc := jsonv1.NewEncoder(out) @@ -45,11 +35,9 @@ func PrintTailnetLockStatusJSONV1(out io.Writer, status *ipnstate.TailnetLockSta return enc.Encode(result) } -func toTailnetLockDisabledStatusV1(status *ipnstate.TailnetLockStatus) tailnetLockDisabledStatusV1 { - out := tailnetLockDisabledStatusV1{ - tailnetLockStatusV1Base: tailnetLockStatusV1Base{ - Enabled: status.Enabled, - }, +func toTailnetLockDisabledStatusV1(status *ipnstate.TailnetLockStatus) StatusResponse { + out := StatusResponse{ + Enabled: status.Enabled, } if !status.PublicKey.IsZero() { out.PublicKey = status.PublicKey.CLIString() @@ -60,11 +48,9 @@ func toTailnetLockDisabledStatusV1(status *ipnstate.TailnetLockStatus) tailnetLo return out } -func toTailnetLockEnabledStatusV1(status *ipnstate.TailnetLockStatus) tailnetLockEnabledStatusV1 { - out := tailnetLockEnabledStatusV1{ - tailnetLockStatusV1Base: tailnetLockStatusV1Base{ - Enabled: status.Enabled, - }, +func toTailnetLockEnabledStatusV1(status *ipnstate.TailnetLockStatus) StatusResponse { + out := StatusResponse{ + Enabled: status.Enabled, } if status.Head != nil { @@ -79,19 +65,19 @@ func toTailnetLockEnabledStatusV1(status *ipnstate.TailnetLockStatus) tailnetLoc if nk := status.NodeKey; nk != nil { out.NodeKey = nk.String() } - out.NodeKeySigned = status.NodeKeySigned + out.NodeKeySigned = &status.NodeKeySigned if sig := status.NodeKeySignature; sig != nil { out.NodeKeySignature = toTKANodeKeySignatureV1(sig) } + out.TrustedKeys = []Key{} // never omit this field when enabled for _, key := range status.TrustedKeys { out.TrustedKeys = append(out.TrustedKeys, ipnTKAKeytoTKAKeyV1(&key)) } + out.VisiblePeers = []TrustedPeer{} // never omit this field when enabled for _, vp := range status.VisiblePeers { - out.VisiblePeers = append(out.VisiblePeers, tkaTrustedPeerV1{ - tkaPeerV1: toTKAPeerV1(vp), - NodeKeySignature: toTKANodeKeySignatureV1(&vp.NodeKeySignature), - }) + out.VisiblePeers = append(out.VisiblePeers, toTrustedTKAPeerV1(vp)) } + out.FilteredPeers = []Peer{} // never omit this field when enabled for _, fp := range status.FilteredPeers { out.FilteredPeers = append(out.FilteredPeers, toTKAPeerV1(fp)) } @@ -100,52 +86,46 @@ func toTailnetLockEnabledStatusV1(status *ipnstate.TailnetLockStatus) tailnetLoc return out } -type tailnetLockStatusV1Base struct { +// StatusResponse is the full Tailnet Lock Status output collected from the local Tailscale daemon. +type StatusResponse struct { + jsonoutput.ResponseEnvelope + // Enabled is true if Tailnet Lock is enabled. Enabled bool // PublicKey describes the node's tailnet-lock public key. - PublicKey string `json:"PublicKey,omitzero"` + PublicKey string `json:",omitzero"` // NodeKey describes the node's current node-key. This field is not // populated if the node is not operating (i.e. waiting for a login). - NodeKey string `json:"NodeKey,omitzero"` -} + NodeKey string `json:",omitzero"` -// tailnetLockDisabledStatusV1 is the JSON representation of the Tailnet Lock status -// when Tailnet Lock is disabled. -type tailnetLockDisabledStatusV1 struct { - tailnetLockStatusV1Base -} - -// tailnetLockEnabledStatusV1 is the JSON representation of the Tailnet Lock status. -type tailnetLockEnabledStatusV1 struct { - tailnetLockStatusV1Base + ////////////////////////////////////////////////////////////////// + // The following fields are only present when Tailnet Lock is enabled. // Head describes the AUM hash of the leaf AUM. - Head string `json:"Head,omitzero"` + Head string `json:",omitzero"` // NodeKeySigned is true if our node is authorized by Tailnet Lock. - NodeKeySigned bool + NodeKeySigned *bool `json:",omitzero"` // NodeKeySignature is the current signature of this node's key. - NodeKeySignature *tkaNodeKeySignatureV1 + NodeKeySignature *NodeKeySignature `json:",omitzero"` // TrustedKeys describes the keys currently trusted to make changes // to tailnet-lock. - TrustedKeys []tkaKeyV1 + TrustedKeys []Key `json:",omitzero"` // VisiblePeers describes peers which are visible in the netmap that // have valid Tailnet Lock signatures. - VisiblePeers []tkaTrustedPeerV1 + VisiblePeers []TrustedPeer `json:",omitzero"` // FilteredPeers describes peers which were removed from the netmap // (i.e. no connectivity) because they failed Tailnet Lock // checks. - FilteredPeers []tkaPeerV1 + FilteredPeers []Peer `json:",omitzero"` // StateID is a nonce associated with the Tailnet Lock authority, - // generated upon enablement. This field is empty if Tailnet Lock - // is disabled. + // generated upon enablement. StateID uint64 `json:"State,omitzero"` } diff --git a/cmd/tailscale/tslockjsonv1/tka.go b/cmd/tailscale/tslockjsonv1/tka.go index 297a18288..5ad008d83 100644 --- a/cmd/tailscale/tslockjsonv1/tka.go +++ b/cmd/tailscale/tslockjsonv1/tka.go @@ -13,37 +13,37 @@ import ( "tailscale.com/tka" ) -// expandedAUMV1 is the expanded version of a [tka.AUM], designed so external tools +// AUM is the expanded version of a [tka.AUM], designed so external tools // can read the AUM without knowing our CBOR definitions. -type expandedAUMV1 struct { +type AUM struct { MessageKind string - PrevAUMHash string `json:"PrevAUMHash,omitzero"` + PrevAUMHash string `json:",omitzero"` // Key encodes a public key to be added to the key authority. // This field is used for AddKey AUMs. - Key tkaKeyV1 `json:"Key,omitzero"` + Key Key `json:",omitzero"` // KeyID references a public key which is part of the key authority. // This field is used for RemoveKey and UpdateKey AUMs. - KeyID string `json:"KeyID,omitzero"` + KeyID string `json:",omitzero"` // State describes the full state of the key authority. // This field is used for Checkpoint AUMs. - State expandedStateV1 `json:"State,omitzero"` + State TKAState `json:",omitzero"` // Votes and Meta describe properties of a key in the key authority. // These fields are used for UpdateKey AUMs. - Votes uint `json:"Votes,omitzero"` - Meta map[string]string `json:"Meta,omitzero"` + Votes uint `json:",omitzero"` + Meta map[string]string `json:",omitzero"` // Signatures lists the signatures over this AUM. - Signatures []expandedSignatureV1 `json:"Signatures,omitzero"` + Signatures []Signature `json:",omitzero"` } -// tkaKeyV1 is the expanded version of a [tka.Key], which describes +// Key is the expanded version of a [tka.Key], which describes // the public components of a key known to tailnet-lock. -type tkaKeyV1 struct { - Kind string `json:"Kind,omitzero"` +type Key struct { + Kind string `json:",omitzero"` // Votes describes the weight applied to signatures using this key. Votes uint @@ -53,13 +53,13 @@ type tkaKeyV1 struct { // Meta describes arbitrary metadata about the key. This could be // used to store the name of the key, for instance. - Meta map[string]string `json:"Meta,omitzero"` + Meta map[string]string `json:",omitzero"` } // ipnTKAKeytoTKAKeyV1 converts an [ipnstate.TKAKey] to the JSON output returned // by the CLI. -func ipnTKAKeytoTKAKeyV1(key *ipnstate.TKAKey) tkaKeyV1 { - return tkaKeyV1{ +func ipnTKAKeytoTKAKeyV1(key *ipnstate.TKAKey) Key { + return Key{ Kind: key.Kind, Votes: key.Votes, Public: key.Key.CLIString(), @@ -69,8 +69,8 @@ func ipnTKAKeytoTKAKeyV1(key *ipnstate.TKAKey) tkaKeyV1 { // toTKAKeyV1 converts a [tka.Key] to the JSON output returned // by the CLI. -func toTKAKeyV1(key *tka.Key) tkaKeyV1 { - return tkaKeyV1{ +func toTKAKeyV1(key *tka.Key) Key { + return Key{ Kind: key.Kind.String(), Votes: key.Votes, Public: fmt.Sprintf("tlpub:%x", key.Public), @@ -78,20 +78,20 @@ func toTKAKeyV1(key *tka.Key) tkaKeyV1 { } } -// tkaNodeKeySignatureV1 is the JSON representation of a [tka.NodeKeySignature], +// NodeKeySignature is the JSON representation of a [tka.NodeKeySignature], // which describes a signature that authorizes a specific node key. -type tkaNodeKeySignatureV1 struct { +type NodeKeySignature struct { // SigKind identifies the variety of signature. SigKind string // PublicKey identifies the key.NodePublic which is being authorized. // SigCredential signatures do not use this field. - PublicKey string `json:"PublicKey,omitzero"` + PublicKey string `json:",omitzero"` // KeyID identifies which key in the tailnet key authority should // be used to verify this signature. Only set for SigDirect and // SigCredential signature kinds. - KeyID string `json:"KeyID,omitzero"` + KeyID string `json:",omitzero"` // Signature is the packed (R, S) ed25519 signature over all other // fields of the structure. @@ -99,15 +99,15 @@ type tkaNodeKeySignatureV1 struct { // Nested describes a NodeKeySignature which authorizes the node-key // used as Pubkey. Only used for SigRotation signatures. - Nested *tkaNodeKeySignatureV1 `json:"Nested,omitzero"` + Nested *NodeKeySignature `json:",omitzero"` // WrappingPubkey specifies the ed25519 public key which must be used // to sign a Signature which embeds this one. - WrappingPublicKey string `json:"WrappingPublicKey,omitzero"` + WrappingPublicKey string `json:",omitzero"` } -func toTKANodeKeySignatureV1(sig *tka.NodeKeySignature) *tkaNodeKeySignatureV1 { - out := tkaNodeKeySignatureV1{ +func toTKANodeKeySignatureV1(sig *tka.NodeKeySignature) *NodeKeySignature { + out := NodeKeySignature{ SigKind: sig.SigKind.String(), } if len(sig.Pubkey) > 0 { @@ -126,10 +126,10 @@ func toTKANodeKeySignatureV1(sig *tka.NodeKeySignature) *tkaNodeKeySignatureV1 { return &out } -// tkaPeerV1 is the JSON representation of an [ipnstate.TKAPeer], which describes +// Peer is the JSON representation of an [ipnstate.TKAPeer], which describes // a peer and its Tailnet Lock details. -type tkaPeerV1 struct { - // Stable ID, i.e. [tailcfg.StableNodeID] +type Peer struct { + // Stable ID, i.e. [tailscale.com/tailcfg.StableNodeID] ID string // DNS name @@ -142,17 +142,27 @@ type tkaPeerV1 struct { NodeKey string } -// tkaPeerV1 is the JSON representation of a trusted [ipnstate.TKAPeer], which -// has a node key signature. -type tkaTrustedPeerV1 struct { - tkaPeerV1 +// TrustedPeer is the JSON representation of a trusted [ipnstate.TKAPeer], which +// has a node key signature in addition to [Peer]. +type TrustedPeer struct { + // Stable ID, i.e. [tailscale.com/tailcfg.StableNodeID] + ID string + + // DNS name + DNSName string + + // Tailscale IP(s) assigned to this node + TailscaleIPs []string + + // The node's public key + NodeKey string // The node's key signature - NodeKeySignature *tkaNodeKeySignatureV1 `json:"NodeKeySignature,omitzero"` + NodeKeySignature *NodeKeySignature `json:",omitzero"` } -func toTKAPeerV1(peer *ipnstate.TKAPeer) tkaPeerV1 { - out := tkaPeerV1{ +func toTKAPeerV1(peer *ipnstate.TKAPeer) Peer { + out := Peer{ DNSName: peer.Name, ID: string(peer.StableID), } @@ -164,19 +174,30 @@ func toTKAPeerV1(peer *ipnstate.TKAPeer) tkaPeerV1 { return out } -// expandedSignatureV1 is the expanded form of a [tka.Signature], which +func toTrustedTKAPeerV1(peer *ipnstate.TKAPeer) TrustedPeer { + out := toTKAPeerV1(peer) + return TrustedPeer{ + DNSName: out.DNSName, + ID: out.ID, + TailscaleIPs: out.TailscaleIPs, + NodeKey: out.NodeKey, + NodeKeySignature: toTKANodeKeySignatureV1(&peer.NodeKeySignature), + } +} + +// Signature is the expanded form of a [tka.Signature], which // describes a signature over an AUM. This signature can be verified // using the key referenced by KeyID. -type expandedSignatureV1 struct { +type Signature struct { KeyID string Signature string } -// expandedStateV1 is the expanded version of a [tka.State], which describes +// TKAState is the expanded version of a [tka.TKAState], which describes // Tailnet Key Authority state at an instant in time. -type expandedStateV1 struct { +type TKAState struct { // LastAUMHash is the blake2s digest of the last-applied AUM. - LastAUMHash string `json:"LastAUMHash,omitzero"` + LastAUMHash string `json:",omitzero"` // DisablementValues are KDF-derived values used to verify that a caller // possesses a valid DisablementSecret. These values are used during the @@ -190,7 +211,7 @@ type expandedStateV1 struct { // // 1. The signing nodes currently trusted by the TKA. // 2. Ephemeral keys that were used to generate pre-signed auth keys. - Keys []tkaKeyV1 + Keys []Key // StateID's are nonces, generated on enablement and fixed for // the lifetime of the Tailnet Key Authority.