From 0a88fa1ec652627740a95b3de93b5dbbd260df84 Mon Sep 17 00:00:00 2001 From: Fran Bull Date: Fri, 30 Oct 2026 09:40:12 -0700 Subject: [PATCH] feature/conn25: mint/verify TransitIPRequest tokens Add functions to allow minting and verifying the tokens. Updates tailscale/corp#46169 Signed-off-by: Fran Bull --- feature/conn25/token.go | 78 +++++++++++++++- feature/conn25/token_test.go | 171 +++++++++++++++++++++++++++++++++++ 2 files changed, 248 insertions(+), 1 deletion(-) diff --git a/feature/conn25/token.go b/feature/conn25/token.go index 4c094b20c..e9c873afd 100644 --- a/feature/conn25/token.go +++ b/feature/conn25/token.go @@ -3,16 +3,92 @@ package conn25 -import "crypto/rand" +import ( + "crypto/hmac" + "crypto/rand" + "crypto/sha256" + "encoding/binary" + "fmt" + "math" + "net/netip" +) // tokenSecretLen is the length in bytes of the connector's token secret. It is // the recommended key size for HMAC-SHA-256, which is used to mint and verify // destination IP tokens. const tokenSecretLen = 32 +// tokenVersion1 is the version byte of the first token format. +const tokenVersion1 = 1 + +// tokenMACLen is the number of bytes of HMAC-SHA-256 output kept in a token. The +// full 32-byte MAC is truncated to save bytes on the wire. +const tokenMACLen = 16 + // newTokenSecret returns a fresh random token secret. func newTokenSecret() [tokenSecretLen]byte { var secret [tokenSecretLen]byte rand.Read(secret[:]) return secret } + +// mintToken returns an opaque token authenticating that this connector served +// dst in a DNS answer for app. The client stores it and echoes it back +// in a later TransitIPRequest, which this connector verifies by recomputing the +// MAC over the same inputs. +func (c *connector) mintToken(app string, dst netip.Addr) ([]byte, error) { + if len(app) > math.MaxUint16 { + return nil, fmt.Errorf("conn25: app name too long to mint token: %d bytes", len(app)) + } + + c.mu.Lock() + secret := c.tokenSecret + c.mu.Unlock() + + token := make([]byte, 0, 1+tokenMACLen) + token = append(token, tokenVersion1) + token = append(token, tokenMAC(secret, app, dst)...) + return token, nil +} + +// verifyToken reports whether token is a valid [tokenVersion1] token minted by +// this connector for exactly app, and dst. +func (c *connector) verifyToken(token []byte, app string, dst netip.Addr) bool { + if len(token) != 1+tokenMACLen || token[0] != tokenVersion1 { + return false + } + if len(app) > math.MaxUint16 { + return false + } + + c.mu.Lock() + secret := c.tokenSecret + c.mu.Unlock() + + return hmac.Equal(token[1:], tokenMAC(secret, app, dst)) +} + +// tokenMAC returns the truncated HMAC-SHA-256 that authenticates a token's +// inputs. +// +// The token is version(1) | mac(16), where mac is +// +// HMAC-SHA-256(tokenSecret, version | uint16(len(app)) | app | dst) +// +// truncated to [tokenMACLen] bytes. dst is canonicalized to its 16-byte form so +// that the IPv4 and IPv4-in-IPv6 representations of the same address produce the +// same token. app is length-prefixed because it is the only variable-width +// input, which keeps the concatenation unambiguous. An app name longer than the +// uint16 length prefix can hold is rejected rather than minted, since a +// truncated prefix would reintroduce that ambiguity. +func tokenMAC(secret [tokenSecretLen]byte, app string, dst netip.Addr) []byte { + mac := hmac.New(sha256.New, secret[:]) + mac.Write([]byte{tokenVersion1}) + var appLen [2]byte + binary.BigEndian.PutUint16(appLen[:], uint16(len(app))) + mac.Write(appLen[:]) + mac.Write([]byte(app)) + dstCanon := dst.Unmap().As16() + mac.Write(dstCanon[:]) + return mac.Sum(nil)[:tokenMACLen] +} diff --git a/feature/conn25/token_test.go b/feature/conn25/token_test.go index 338689633..21337bd42 100644 --- a/feature/conn25/token_test.go +++ b/feature/conn25/token_test.go @@ -4,6 +4,10 @@ package conn25 import ( + "bytes" + "math" + "net/netip" + "strings" "testing" "tailscale.com/types/logger" @@ -37,3 +41,170 @@ func TestConnectorResetRotatesTokenSecret(t *testing.T) { t.Fatal("token secret unchanged after reset, expected rotation") } } + +var ( + testTokenAddr = netip.MustParseAddr("1.2.3.4") + testTokenOtherAddr = netip.MustParseAddr("1.2.3.5") +) + +func mustMint(t *testing.T, c *connector, app string, dst netip.Addr) []byte { + t.Helper() + tok, err := c.mintToken(app, dst) + if err != nil { + t.Fatalf("mintToken(%q): unexpected error: %v", app, err) + } + return tok +} + +func TestConnectorMintTokenDeterministic(t *testing.T) { + c := newConn25(logger.Discard).connector + a := mustMint(t, c, "app", testTokenAddr) + b := mustMint(t, c, "app", testTokenAddr) + if !bytes.Equal(a, b) { + t.Fatalf("mintToken not deterministic: %x != %x", a, b) + } +} + +func TestConnectorMintTokenVersionAndLength(t *testing.T) { + c := newConn25(logger.Discard).connector + tok := mustMint(t, c, "app", testTokenAddr) + if got, want := len(tok), 1+16; got != want { + t.Fatalf("token length = %d, want %d", got, want) + } + if tok[0] != tokenVersion1 { + t.Fatalf("token version byte = %d, want %d", tok[0], tokenVersion1) + } +} + +func TestConnectorMintTokenDistinctInputs(t *testing.T) { + c := newConn25(logger.Discard).connector + base := mustMint(t, c, "app", testTokenAddr) + + cases := []struct { + name string + tok []byte + }{ + {"different app", mustMint(t, c, "other", testTokenAddr)}, + {"different dst", mustMint(t, c, "app", testTokenOtherAddr)}, + } + for _, tc := range cases { + if bytes.Equal(base, tc.tok) { + t.Errorf("%s: token matched base token, expected a different MAC", tc.name) + } + } + + // A rotated secret must change the MAC for otherwise-identical inputs. + c.reset() + if rotated := mustMint(t, c, "app", testTokenAddr); bytes.Equal(base, rotated) { + t.Error("token unchanged after secret rotation, expected a different MAC") + } +} + +func TestConnectorMintTokenCanonicalizesDst(t *testing.T) { + c := newConn25(logger.Discard).connector + v4 := testTokenAddr + v4in6 := netip.AddrFrom16(v4.As16()) // the ::ffff:1.2.3.4 form + if v4 == v4in6 { + t.Fatal("test setup: expected distinct v4 and v4-in-6 representations") + } + if a, b := mustMint(t, c, "app", v4), mustMint(t, c, "app", v4in6); !bytes.Equal(a, b) { + t.Fatalf("v4 and v4-in-6 dst minted different tokens: %x != %x", a, b) + } +} + +func TestConnectorMintTokenAppTooLong(t *testing.T) { + c := newConn25(logger.Discard).connector + // An app name that fits in the uint16 length prefix must succeed. + if _, err := c.mintToken(strings.Repeat("a", math.MaxUint16), testTokenAddr); err != nil { + t.Fatalf("mintToken with max-length app: unexpected error: %v", err) + } + // One byte past the uint16 limit must fail closed rather than mint an + // ambiguously-framed token. + tok, err := c.mintToken(strings.Repeat("a", math.MaxUint16+1), testTokenAddr) + if err == nil { + t.Fatal("mintToken with over-length app: got nil error, want failure") + } + if tok != nil { + t.Fatalf("mintToken with over-length app: got token %x, want nil", tok) + } +} + +func TestConnectorVerifyTokenRoundTrip(t *testing.T) { + c := newConn25(logger.Discard).connector + tok := mustMint(t, c, "app", testTokenAddr) + if !c.verifyToken(tok, "app", testTokenAddr) { + t.Fatal("verifyToken rejected a freshly minted token for its own inputs") + } +} + +func TestConnectorVerifyTokenCanonicalizesDst(t *testing.T) { + c := newConn25(logger.Discard).connector + v4 := testTokenAddr + v4in6 := netip.AddrFrom16(v4.As16()) // the ::ffff:1.2.3.4 form + tok := mustMint(t, c, "app", v4) + if !c.verifyToken(tok, "app", v4in6) { + t.Fatal("verifyToken rejected a token minted for the v4-in-6 form of its dst") + } +} + +func TestConnectorVerifyTokenRejectsWrongInputs(t *testing.T) { + c := newConn25(logger.Discard).connector + tok := mustMint(t, c, "app", testTokenAddr) + cases := []struct { + name string + app string + dst netip.Addr + }{ + {"wrong app", "other", testTokenAddr}, + {"wrong dst", "app", testTokenOtherAddr}, + } + for _, tc := range cases { + if c.verifyToken(tok, tc.app, tc.dst) { + t.Errorf("%s: verifyToken accepted token for mismatched inputs", tc.name) + } + } +} + +func TestConnectorVerifyTokenRejectsRotatedSecret(t *testing.T) { + c := newConn25(logger.Discard).connector + tok := mustMint(t, c, "app", testTokenAddr) + c.reset() + if c.verifyToken(tok, "app", testTokenAddr) { + t.Fatal("verifyToken accepted a token minted under the pre-rotation secret") + } +} + +func TestConnectorVerifyTokenRejectsMalformed(t *testing.T) { + c := newConn25(logger.Discard).connector + tok := mustMint(t, c, "app", testTokenAddr) + + cases := []struct { + name string + tok []byte + }{ + {"nil", nil}, + {"empty", []byte{}}, + {"too short", tok[:len(tok)-1]}, + {"too long", append(append([]byte{}, tok...), 0)}, + {"wrong version", append([]byte{tokenVersion1 + 1}, tok[1:]...)}, + {"flipped mac bit", func() []byte { + bad := append([]byte{}, tok...) + bad[len(bad)-1] ^= 0x01 + return bad + }()}, + } + for _, tc := range cases { + if c.verifyToken(tc.tok, "app", testTokenAddr) { + t.Errorf("%s: verifyToken accepted a malformed token", tc.name) + } + } +} + +func TestConnectorVerifyTokenAppTooLong(t *testing.T) { + c := newConn25(logger.Discard).connector + tok := mustMint(t, c, "app", testTokenAddr) + + if c.verifyToken(tok, strings.Repeat("a", math.MaxUint16+1), testTokenAddr) { + t.Fatal("verifyToken accepted an app name too long to have ever minted a token") + } +}