disco

Documentation

Overview

Package disco contains the discovery message types.

A discovery message is:

Header:

magic          [6]byte  // “TS💬” (0x54 53 f0 9f 92 ac)
senderDiscoPub [32]byte // nacl public key
nonce          [24]byte

The recipient then decrypts the bytes following (the nacl box) and then the inner payload structure is:

messageType     byte  (the MessageType constants below)
messageVersion  byte  (0 for now; but always ignore bytes at the end)
message-payload [...]byte

Index

• Constants
• func LooksLikeDiscoWrapper(p []byte) bool
• func MessageSummary(m Message) string
• func Source(p []byte) (src []byte, ok bool)
• func ToPCAPFrame(src netip.AddrPort, derpNodeSrc key.NodePublic, payload []byte) []byte
• type CallMeMaybe
  • func (m *CallMeMaybe) AppendMarshal(b []byte) []byte
• type Message
  • func Parse(p []byte) (Message, error)
• type MessageType
• type Ping
  • func (m *Ping) AppendMarshal(b []byte) []byte
• type Pong
  • func (m *Pong) AppendMarshal(b []byte) []byte

Constants

const (
	TypePing        = MessageType(0x01)
	TypePong        = MessageType(0x02)
	TypeCallMeMaybe = MessageType(0x03)
)

const Magic = "TS💬" // 6 bytes: 0x54 53 f0 9f 92 ac

Magic is the 6 byte header of all discovery messages.

const MessageHeaderLen = 2

MessageHeaderLen is the length of a message header, 2 bytes for type and version.

const NonceLen = 24

NonceLen is the length of the nonces used by nacl box.

const PingLen = 12 + key.NodePublicRawLen

PingLen is the length of a marshalled ping message, without the message header or padding.

Functions

func LooksLikeDiscoWrapper

func LooksLikeDiscoWrapper(p []byte) bool

LooksLikeDiscoWrapper reports whether p looks like it's a packet containing an encrypted disco message.

func MessageSummary

func MessageSummary(m Message) string

MessageSummary returns a short summary of m for logging purposes.

func Source

func Source(p []byte) (src []byte, ok bool)

Source returns the slice of p that represents the disco public key source, and whether p looks like a disco message.

func ToPCAPFrame

func ToPCAPFrame(src netip.AddrPort, derpNodeSrc key.NodePublic, payload []byte) []byte

ToPCAPFrame marshals the bytes for a pcap record that describe a disco frame.

Warning: Alloc garbage. Acceptable while capturing.

Types

type CallMeMaybe

type CallMeMaybe struct {
	// MyNumber is what the peer believes its endpoints are.
	//
	// Prior to Tailscale 1.4, the endpoints were exchanged purely
	// between nodes and the control server.
	//
	// Starting with Tailscale 1.4, clients advertise their endpoints.
	// Older clients won't use this, but newer clients should
	// use any endpoints in here that aren't included from control.
	//
	// Control might have sent stale endpoints if the client was idle
	// before contacting us. In that case, the client likely did a STUN
	// request immediately before sending the CallMeMaybe to recreate
	// their NAT port mapping, and that new good endpoint is included
	// in this field, but might not yet be in control's endpoints.
	// (And in the future, control will stop distributing endpoints
	// when clients are suitably new.)
	MyNumber []netip.AddrPort
}

CallMeMaybe is a message sent only over DERP to request that the recipient try to open up a magicsock path back to the sender.

The sender should've already sent UDP packets to the peer to open up the stateful firewall mappings inbound.

The recipient may choose to not open a path back, if it's already happy with its path. But usually it will.

func (*CallMeMaybe) AppendMarshal

func (m *CallMeMaybe) AppendMarshal(b []byte) []byte

type Message

type Message interface {
	// AppendMarshal appends the message's marshaled representation.
	AppendMarshal([]byte) []byte
}

Message a discovery message.

func Parse

func Parse(p []byte) (Message, error)

Parse parses the encrypted part of the message from inside the nacl box.

type MessageType

type MessageType byte

type Ping

type Ping struct {
	// TxID is a random client-generated per-ping transaction ID.
	TxID [12]byte

	// NodeKey is allegedly the ping sender's wireguard public key.
	// Old clients (~1.16.0 and earlier) don't send this field.
	// It shouldn't be trusted by itself, but can be combined with
	// netmap data to reduce the discokey:nodekey relation from 1:N to
	// 1:1.
	NodeKey key.NodePublic

	// Padding is the number of 0 bytes at the end of the
	// message. (It's used to probe path MTU.)
	Padding int
}

func (*Ping) AppendMarshal

func (m *Ping) AppendMarshal(b []byte) []byte

type Pong

type Pong struct {
	TxID [12]byte
	Src  netip.AddrPort // 18 bytes (16+2) on the wire; v4-mapped ipv6 for IPv4
}

Pong is a response a Ping.

It includes the sender's source IP + port, so it's effectively a STUN response.

func (*Pong) AppendMarshal

func (m *Pong) AppendMarshal(b []byte) []byte