model

Documentation

Overview

Package model implements common models for the vpn data structures.

Index

• Constants
• Variables
• type Dialer
• type Direction
  • func (d Direction) String() string
• type DummyTracer
  • func (dt DummyTracer) OnDroppedPacket(Direction, NegotiationState, *Packet)
  • func (dt DummyTracer) OnIncomingPacket(*Packet, NegotiationState)
  • func (dt DummyTracer) OnOutgoingPacket(*Packet, NegotiationState, int)
  • func (dt DummyTracer) OnStateChange(NegotiationState)
  • func (dt DummyTracer) TimeNow() time.Time
• type HandshakeTracer
• type Logger
• type NegotiationState
  • func (sns NegotiationState) String() string
• type Notification
• type Opcode
  • func NewOpcodeFromString(s string) (Opcode, error)
  • func (op Opcode) IsControl() bool
  • func (op Opcode) IsData() bool
  • func (op Opcode) String() string
• type Packet
  • func NewPacket(opcode Opcode, keyID uint8, payload []byte) *Packet
  • func ParsePacket(buf []byte) (*Packet, error)
  • func (p *Packet) Bytes() ([]byte, error)
  • func (p *Packet) IsControl() bool
  • func (p *Packet) IsData() bool
  • func (p *Packet) IsPing() bool
  • func (p *Packet) Log(logger Logger, direction Direction)
• type PacketID
• type PeerID
• type SessionID
• type TestLogger
  • func NewTestLogger() *TestLogger
  • func (tl *TestLogger) Debug(msg string)
  • func (tl *TestLogger) Debugf(format string, v ...any)
  • func (tl *TestLogger) Info(msg string)
  • func (tl *TestLogger) Infof(format string, v ...any)
  • func (tl *TestLogger) Warn(msg string)
  • func (tl *TestLogger) Warnf(format string, v ...any)
• type TunnelInfo

Constants

const (
	P_CONTROL_HARD_RESET_CLIENT_V1 = Opcode(iota + 1) // 1
	P_CONTROL_HARD_RESET_SERVER_V1                    // 2
	P_CONTROL_SOFT_RESET_V1                           // 3
	P_CONTROL_V1                                      // 4
	P_ACK_V1                                          // 5
	P_DATA_V1                                         // 6
	P_CONTROL_HARD_RESET_CLIENT_V2                    // 7
	P_CONTROL_HARD_RESET_SERVER_V2                    // 8
	P_DATA_V2                                         // 9
)

OpenVPN packets opcodes.

const (
	// S_ERROR means there was some form of protocol error.
	S_ERROR = NegotiationState(iota) - 1

	// S_UNDEF is the undefined state.
	S_UNDEF

	// S_INITIAL means we're ready to begin the three-way handshake.
	S_INITIAL

	// S_PRE_START means we're waiting for acknowledgment from the remote.
	S_PRE_START

	// S_START means we've done the three-way handshake.
	S_START

	// S_SENT_KEY means we have sent the local part of the key_source2 random material.
	S_SENT_KEY

	// S_GOT_KEY means we have got the remote part of key_source2.
	S_GOT_KEY

	// S_ACTIVE means the control channel was established.
	S_ACTIVE

	// S_GENERATED_KEYS means the data channel keys have been generated.
	S_GENERATED_KEYS
)

const (
	// DirectionIncoming marks received packets.
	DirectionIncoming = Direction(iota)

	// DirectionOutgoing marks packets to be sent.
	DirectionOutgoing
)

const (
	// NotificationReset indicates that a SOFT or HARD reset occurred.
	NotificationReset = 1 << iota
)

Variables

var ErrEmptyPayload = errors.New("openvpn: empty payload")

ErrEmptyPayload indicates tha the payload of an OpenVPN control packet is empty.

var ErrMarshalPacket = errors.New("cannot marshal packet")

ErrMarshalPacket is the error returned when we cannot marshal a packet.

var ErrPacketTooShort = errors.New("openvpn: packet too short")

ErrPacketTooShort indicates that a packet is too short.

var ErrParsePacket = errors.New("openvpn: packet parse error")

ErrParsePacket is a generic packet parse error which may be further qualified.

Types

type Dialer

type Dialer interface {
	DialContext(context.Context, string, string) (net.Conn, error)
}

Dialer is a type allowing to dial network connections.

type Direction

type Direction int

Direction is one of two directions on a packet.

func (Direction) String

func (d Direction) String() string

String implements fmt.Stringer

type DummyTracer

type DummyTracer struct{}

DummyTracer is a no-op implementation of model.HandshakeTracer that does nothing but can be safely passed as a default implementation.

func (DummyTracer) OnDroppedPacket

func (dt DummyTracer) OnDroppedPacket(Direction, NegotiationState, *Packet)

OnDroppedPacket is called whenever a packet is dropped (in/out)

func (DummyTracer) OnIncomingPacket

func (dt DummyTracer) OnIncomingPacket(*Packet, NegotiationState)

OnIncomingPacket is called when a packet is received.

func (DummyTracer) OnOutgoingPacket

func (dt DummyTracer) OnOutgoingPacket(*Packet, NegotiationState, int)

OnOutgoingPacket is called when a packet is about to be sent.

func (DummyTracer) OnStateChange

func (dt DummyTracer) OnStateChange(NegotiationState)

OnStateChange is called for each transition in the state machine.

func (DummyTracer) TimeNow

func (dt DummyTracer) TimeNow() time.Time

TimeNow allows to manipulate time for deterministic tests.

type HandshakeTracer

type HandshakeTracer interface {
	// TimeNow allows to inject time for deterministic tests.
	TimeNow() time.Time

	// OnStateChange is called for each transition in the state machine.
	OnStateChange(state NegotiationState)

	// OnIncomingPacket is called when a packet is received.
	OnIncomingPacket(packet *Packet, stage NegotiationState)

	// OnOutgoingPacket is called when a packet is about to be sent.
	OnOutgoingPacket(packet *Packet, stage NegotiationState, retries int)

	// OnDroppedPacket is called whenever a packet is dropped (in/out)
	OnDroppedPacket(direction Direction, stage NegotiationState, packet *Packet)
}

HandshakeTracer allows to collect traces for a given OpenVPN handshake. A HandshakeTracer can be optionally added to the top-level TUN constructor, and it will be propagated to any layer that needs to register an event.

type Logger

type Logger interface {
	// Debug emits a debug message.
	Debug(msg string)

	// Debugf formats and emits a debug message.
	Debugf(format string, v ...any)

	// Info emits an informational message.
	Info(msg string)

	// Infof formats and emits an informational message.
	Infof(format string, v ...any)

	// Warn emits a warning message.
	Warn(msg string)

	// Warnf formats and emits a warning message.
	Warnf(format string, v ...any)
}

Logger is the generic logger definition.

type NegotiationState

type NegotiationState int

NegotiationState is the state of the session negotiation.

func (NegotiationState) String

func (sns NegotiationState) String() string

String maps a [SessionNegotiationState] to a string.

type Notification

type Notification struct {
	// Flags contains flags explaining what happened.
	Flags int64
}

Notification is a notification for a service worker.

type Opcode

type Opcode byte

Opcode is an OpenVPN packet opcode.

func NewOpcodeFromString

func NewOpcodeFromString(s string) (Opcode, error)

NewOpcodeFromString returns an opcode from a string representation, and an error if it cannot parse the opcode representation. The zero return value is invalid and always coupled with a non-nil error.

func (Opcode) IsControl

func (op Opcode) IsControl() bool

IsControl returns true when this opcode is a control opcode.

func (Opcode) IsData

func (op Opcode) IsData() bool

IsData returns true when this opcode is a data opcode.

func (Opcode) String

func (op Opcode) String() string

String returns the opcode string representation

type Packet

type Packet struct {
	// Opcode is the packet message type (a P_* constant; high 5-bits of
	// the first packet byte).
	Opcode Opcode

	// The key_id refers to an already negotiated TLS session.
	// This is the shortened version of the key-id (low 3-bits of the first
	// packet byte).
	KeyID byte

	// PeerID is the peer ID.
	PeerID PeerID

	// LocalSessionID is the local session ID.
	LocalSessionID SessionID

	// Acks contains the remote packets we're ACKing.
	ACKs []PacketID

	// RemoteSessionID is the remote session ID.
	RemoteSessionID SessionID

	// ID is the packet-id for replay protection. According to the spec: "4 or 8 bytes,
	// includes sequence number and optional time_t timestamp".
	//
	// This library does not use the timestamp.
	// TODO(ainghazal): use optional.Value (only control packets have packet id)
	ID PacketID

	// Payload is the packet's payload.
	Payload []byte
}

Packet is an OpenVPN packet.

func NewPacket

func NewPacket(opcode Opcode, keyID uint8, payload []byte) *Packet

NewPacket returns a packet from the passed arguments: opcode, keyID and a raw payload.

func ParsePacket

func ParsePacket(buf []byte) (*Packet, error)

ParsePacket produces a packet after parsing the common header. We assume that the underlying connection has already stripped out the framing.

func (*Packet) Bytes

func (p *Packet) Bytes() ([]byte, error)

Bytes returns a byte array that is ready to be sent on the wire.

func (*Packet) IsControl

func (p *Packet) IsControl() bool

IsControl returns true if the packet is any of the control types.

func (*Packet) IsData

func (p *Packet) IsData() bool

IsData returns true if the packet is of data type.

func (*Packet) IsPing

func (p *Packet) IsPing() bool

IsPing returns true if this packet matches a openvpn ping packet.

func (*Packet) Log

func (p *Packet) Log(logger Logger, direction Direction)

Log writes an entry in the passed logger with a representation of this packet.

type PacketID

type PacketID uint32

PacketID is a packet identifier.

type PeerID

type PeerID [3]byte

PeerID is the type of the P_DATA_V2 peer ID.

type SessionID

type SessionID [8]byte

SessionID is the session identifier.

type TestLogger

type TestLogger struct {
	Lines []string
}

TestLogger is a logger that can be used whenever a test needs a logger to be passed around.

func NewTestLogger

func NewTestLogger() *TestLogger

func (*TestLogger) Debug

func (tl *TestLogger) Debug(msg string)

Debug implements model.Logger

func (*TestLogger) Debugf

func (tl *TestLogger) Debugf(format string, v ...any)

Debugf implements model.Logger

func (*TestLogger) Info

func (tl *TestLogger) Info(msg string)

Info implements model.Logger

func (*TestLogger) Infof

func (tl *TestLogger) Infof(format string, v ...any)

Infof implements model.Logger

func (*TestLogger) Warn

func (tl *TestLogger) Warn(msg string)

Warn implements model.Logger

func (*TestLogger) Warnf

func (tl *TestLogger) Warnf(format string, v ...any)

Warnf implements model.Logger

type TunnelInfo

type TunnelInfo struct {
	// GW is the Route Gateway.
	GW string

	// IP is the assigned IP.
	IP string

	// MTU is the configured MTU pushed by the remote.
	MTU int

	// NetMask is the netmask configured on the TUN interface, pushed by the ifconfig command.
	NetMask string

	// PeerID is the peer-id assigned to us by the remote.
	PeerID int
}

TunnelInfo holds state about the VPN TunnelInfo that has longer duration than a given session. This information is gathered at different stages: - during the handshake (mtu). - after server pushes config options(ip, gw).