controlbase

Documentation

Overview

Package controlbase implements the base transport of the Tailscale 2021 control protocol.

The base transport implements Noise IK, instantiated with Curve25519, ChaCha20Poly1305 and BLAKE2s.

Index

• type Conn
  • func Client(ctx context.Context, conn net.Conn, machineKey key.MachinePrivate, ...) (*Conn, error)
  • func Server(ctx context.Context, conn net.Conn, controlKey key.MachinePrivate, ...) (*Conn, error)
  • func (c *Conn) Close() error
  • func (c *Conn) HandshakeHash() [blake2s.Size]byte
  • func (c *Conn) LocalAddr() net.Addr
  • func (c *Conn) Peer() key.MachinePublic
  • func (c *Conn) ProtocolVersion() int
  • func (c *Conn) Read(bs []byte) (int, error)
  • func (c *Conn) RemoteAddr() net.Addr
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetReadDeadline(t time.Time) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) Write(bs []byte) (n int, err error)
• type HandshakeContinuation
  • func ClientDeferred(machineKey key.MachinePrivate, controlKey key.MachinePublic, ...) (initialHandshake []byte, continueHandshake HandshakeContinuation, err error)

Types

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

A Conn is a secured Noise connection. It implements the net.Conn interface, with the unusual trait that any write error (including a SetWriteDeadline induced i/o timeout) causes all future writes to fail.

func Client

func Client(ctx context.Context, conn net.Conn, machineKey key.MachinePrivate, controlKey key.MachinePublic, protocolVersion uint16) (*Conn, error)

Client wraps ClientDeferred and immediately invokes the returned continuation with conn.

This is a helper for when you don't need the fancy continuation-style handshake, and just want to synchronously upgrade a net.Conn to a secure transport.

func Server

func Server(ctx context.Context, conn net.Conn, controlKey key.MachinePrivate, optionalInit []byte) (*Conn, error)

Server initiates a control server handshake, returning the resulting control connection.

optionalInit can be the client's initial handshake message as returned by ClientDeferred, or nil in which case the initial message is read from conn.

The context deadline, if any, covers the entire handshaking process.

func (*Conn) Close

func (c *Conn) Close() error

Close implements io.Closer.

func (*Conn) HandshakeHash

func (c *Conn) HandshakeHash() [blake2s.Size]byte

HandshakeHash returns the Noise handshake hash for the connection, which can be used to bind other messages to this connection (i.e. to ensure that the message wasn't replayed from a different connection).

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() net.Addr

func (*Conn) Peer

func (c *Conn) Peer() key.MachinePublic

Peer returns the peer's long-term public key.

func (*Conn) ProtocolVersion

func (c *Conn) ProtocolVersion() int

ProtocolVersion returns the protocol version that was used to establish this Conn.

func (*Conn) Read

func (c *Conn) Read(bs []byte) (int, error)

Read implements io.Reader.

func (*Conn) RemoteAddr

func (c *Conn) RemoteAddr() net.Addr

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

func (*Conn) Write

func (c *Conn) Write(bs []byte) (n int, err error)

Write implements io.Writer.

type HandshakeContinuation

type HandshakeContinuation func(context.Context, net.Conn) (*Conn, error)

HandshakeContinuation upgrades a net.Conn to a Conn. The net.Conn is assumed to have already sent the client>server handshake initiation message.

func ClientDeferred

func ClientDeferred(machineKey key.MachinePrivate, controlKey key.MachinePublic, protocolVersion uint16) (initialHandshake []byte, continueHandshake HandshakeContinuation, err error)

ClientDeferred initiates a control client handshake, returning the initial message to send to the server and a continuation to finalize the handshake.

ClientDeferred is split in this way for RTT reduction: we run this protocol after negotiating a protocol switch from HTTP/HTTPS. If we completely serialized the negotiation followed by the handshake, we'd pay an extra RTT to transmit the handshake initiation after protocol switching. By splitting the handshake into an initial message and a continuation, we can embed the handshake initiation into the HTTP protocol switching request and avoid a bit of delay.