feature/conn25: mint/verify TransitIPRequest tokens

Add functions to allow minting and verifying the tokens.

Updates tailscale/corp#46169

Signed-off-by: Fran Bull <fran@tailscale.com>
This commit is contained in:
Fran Bull authored and franbull committed 2026-11-02 13:23:31 -08:00
1 parent 858b53b289
commit 0a88fa1ec6
2 files changed
+248 -1

No files matched your search

+77 -1
View File
@@ -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]
}
+171
View File
@@ -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")
}
}