tcpoverdns

package
v0.0.0-...-c19d3f1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 1, 2025 License: MPL-2.0 Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	StateEmpty       = State(0)
	StateSynReceived = State(1)
	StatePeerAck     = State(2)
	StateEstablished = State(3)
	StatePeerClosed  = State(4)
	StateClosed      = State(100)
)
View Source 
const (
	FlagHandshakeSyn = Flag(1 << 0)
	FlagHandshakeAck = Flag(1 << 1)
	FlagAckOnly      = Flag(1 << 2)
	FlagKeepAlive    = Flag(1 << 3)
	// FlagReset asks the peer to close/terminate, as the local side also does.
	// The misleading name was inspired by TCP reset.
	FlagReset     = Flag(1 << 4)
	FlagMalformed = Flag(1 << 5)
)
View Source 
const (
	// BusyWaitInterval specifies a short duration in between consecutive
	// busy-wait operations.
	BusyWaitInterval = 5 * time.Millisecond
	// SegmentDataTimeout specifies the timeout between the arrival of a segment
	// header and the segment data.
	SegmentDataTimeout = 10 * time.Second
	//MaxSegmentDataLen is the maximum permissible segment length.
	MaxSegmentDataLen = 8192
)
View Source 
const (
	// InitiatorConfigLen is the length of the serialised InitiatorConfig.
	InitiatorConfigLen = 28
)
View Source 
const (
	// SegmentHeaderLen is the total length of a segment header.
	SegmentHeaderLen = 16
)

Variables

This section is empty.

Functions

func CheckTC 

func CheckTC(t testingstub.T, tc *TransmissionControl, timeoutSec int, wantState State, wantInputSeq, wantInputAck, wantOutputSeq int, wantInputBuf, wantOutputBuf []byte)

func CheckTCError 

func CheckTCError(t testingstub.T, tc *TransmissionControl, timeoutSec int, wantOngoingTransmission, wantInputTransportErrors, wantOutputTransportErrors int)

func CompressBytes 

func CompressBytes(original []byte) (compressed []byte)

CompressBytes compresses the input byte array using a scheme with the best compress ratio.

func DecompressBytes 

func DecompressBytes(compressed []byte) (original []byte, err error)

DecompressBytes recovers a byte array compressed by the CompressBytes function.

func ParseBase62Mod 

func ParseBase62Mod(s string) ([]byte, error)

ParseBase62Mod recovers the original content from a Base62Mod-encoded string.

func ToBase62Mod 

func ToBase62Mod(content []byte) string

ToBase62Mod encodes [1, input...] in a Base62-encoded string.

Types

type Flag 

type Flag uint16

Flag is transmitted with each segment, it is the data type of an individual flag bit while also used to represent an entire collection of flags. Transmission control and its peer use flags to communicate transition between states.

func (Flag) Has 

func (flag Flag) Has(f Flag) bool

func (Flag) String 

func (flag Flag) String() string

type InitiatorConfig 

type InitiatorConfig struct {
	// SetConfig instructs the responder to configure itself according to the
	// parameters specified here.
	SetConfig bool
	// MaxSegmentLenExclHeader is the maximum length of the data portion in an
	// outgoing segment, the length excludes the headers.
	MaxSegmentLenExclHeader int
	// Debug enables verbose logging for IO activities.
	Debug bool
	// Timing configures the transmission control's timing
	// characteristics.
	Timing TimingConfig
}

InitiatorConfig is a small piece of binary data inserted into the initiator's handshake segment during the handshake. The parameters help configure the responding transmission control.

func DeserialiseInitiatorConfig 

func DeserialiseInitiatorConfig(in []byte) *InitiatorConfig

DeserialiseInitiatorConfig decodes configuration parameters from the input byte array.

func (*InitiatorConfig) Bytes 

func (conf *InitiatorConfig) Bytes() []byte

Bytes returns the binary data representation of the configuration parameters.

func (*InitiatorConfig) Config 

func (conf *InitiatorConfig) Config(tc *TransmissionControl)

Config copies the configuration parameters into the transmission control.

type Segment 

type Segment struct {
	// Flags is a bitmap of individual control bits that help the stream to
	// transition between its states.
	Flags Flag
	// ID is the ID of the transmission control that constructed this segment.
	ID uint16
	// SeqNum is the sequence number of the first byte of data of the segment.
	SeqNum uint32
	// AckNum differs from the way it works in TCP. Over here it is the sequence
	// number of the latest byte arrived, whereas in TCP it is the next sequence
	// number expected from peer - oops!
	AckNum uint32
	// Reserved is a two-byte integer. It is currently used to inject a small
	// amount of randomness into the segment.
	Reserved uint16
	Data     []byte
}

Segment is a unit of data transported by TransmissionControl. A stream of longer data length is broken down into individual segments before they are transported.

func ReadSegmentHeaderData 

func ReadSegmentHeaderData(t testingstub.T, ctx context.Context, in io.Reader) Segment

func SegmentFromDNSName 

func SegmentFromDNSName(numDomainNameLabels int, query string) Segment

SegmentFromDNSName decodes a segment from a DNS name, for example, the name of a query, or a CNAME from a response.

func SegmentFromDNSText 

func SegmentFromDNSText(entries []string) Segment

SegmentFromDNSName decodes a segment from a DNS name, for example, the name of a query, or a CNAME from a response.

func SegmentFromPacket 

func SegmentFromPacket(packet []byte) Segment

SegmentFromPacket decodes a segment from a byte array and returns the decoded segment.

func (*Segment) CompressAndEncode 

func (seg *Segment) CompressAndEncode() string

CompressAndEncode compresses and encodes the segment into a string.

func (*Segment) DNSName 

func (seg *Segment) DNSName(prefix, domainName string) string

DNSName converts the binary representation of this segment into a DNS name - "prefix.seg.seg.seg...domainName". The return string does not have a suffix period. The function does not check whether the segment is sufficiently small for the DNS protocol.

func (*Segment) DNSText 

func (seg *Segment) DNSText() []string

DNSText converts the binary representation of this segment into DNS text entries. The function does not restrict the maximum size of the text entries.

func (*Segment) Equals 

func (seg *Segment) Equals(other Segment) bool

func (*Segment) Packet 

func (seg *Segment) Packet() (ret []byte)

Packet serialises the segment into bytes and returns them.

func (Segment) String 

func (seg Segment) String() string

Stringer returns a human-readable representation of the segment for debug logging.

type SegmentBuffer 

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

SegmentBuffer is keeps a small backlog of segments transported in a single direction, and performs de-duplication and other optimisations as more segments arrive.

func NewSegmentBuffer 

func NewSegmentBuffer(logger *lalog.Logger, debug bool, maxSegLen int) *SegmentBuffer

NewSegmentBuffer returns a newly initialised segment buffer.

func (*SegmentBuffer) Absorb 

func (buf *SegmentBuffer) Absorb(seg Segment)

Absorb places the segment into the backlog and optimises adjacent segments where possible.

func (*SegmentBuffer) First 

func (buf *SegmentBuffer) First() (seg Segment, exists bool)

First returns the first (oldest) segment, without removing it from the backlog.

func (*SegmentBuffer) Latest 

func (buf *SegmentBuffer) Latest() (seg Segment, exists bool)

Latest returns the latest segment without removing it from the backlog.

func (*SegmentBuffer) Pop 

func (buf *SegmentBuffer) Pop() (seg Segment, exists bool)

Pop returns the first segment and removes it from the backlog.

func (*SegmentBuffer) SetParameters 

func (buf *SegmentBuffer) SetParameters(segLen int, debug bool)

SetParameters sets the max segment length and debug parameters.

type State 

type State int

State is the transmission control stream's state.

type TimingConfig 

type TimingConfig struct {
	// SlidingWindowWaitDuration is a short duration to wait the peer's
	// acknowledgement before this transmission control sends more data to the
	// output transport, including during consecutive retransmissions.
	// In practice, the duration should be higher than the initial
	// KeepAliveInterval.
	SlidingWindowWaitDuration time.Duration
	// RetransmissionInterval is a short duration to wait before re-transmitting
	// the unacknowledged outbound segments (if any). Subsequent retransmissions
	// occur at the interval of SlidingWindowWaitDuration.
	RetransmissionInterval time.Duration
	// AckDelay is a short delay between receiving the latest segment and
	// sending an outbound acknowledgement-only segment.
	// It should shorter than the retransmission interval by a magnitude.
	AckDelay time.Duration
	// KeepAliveInterval is a short duration to wait before transmitting an
	// outbound ack segment in the absence of outbound data.
	// This internal must be longer than the peer's retransmission interval.
	KeepAliveInterval time.Duration
	// ReadTimeout specifies a time limit for the Read function.
	ReadTimeout time.Duration
	// WriteTimeout specifies a time limit for the Write function.
	WriteTimeout time.Duration
}

TimingConfig has the timing characteristics of a transmission control.

func (*TimingConfig) DoubleInterval 

func (conf *TimingConfig) DoubleInterval()

DoubleInterval doubles all interval timing attributes.

func (*TimingConfig) HalfInterval 

func (conf *TimingConfig) HalfInterval()

HalfInterval divides all interval timing attributes by half.

type TransmissionControl 

type TransmissionControl struct {
	net.Conn
	// ID is a file descriptor-like number that identifies all outgoing segments
	// as well as used for logging.
	ID uint16
	// Debug enables verbose logging for IO activities.
	Debug bool
	// Logger is used to log IO activities when verbose logging is enabled.
	Logger *lalog.Logger
	// LogTag is a string that shows up in all log entries.
	LogTag string

	// Initiator determines whether this transmission control will initiate
	// the handshake sequence with the peer.
	// Otherwise, this transmission control remains passive at the start.
	Initiator bool
	// InitiatorConfig is an optional set of configuration parameters that this
	// transmission control will invite the peer to use.
	InitiatorConfig InitiatorConfig
	// InitiatorSegmentData is an optional byte array carried by initiator's
	// handshake (SYN) segment. It must be shorter than MaxSegmentLenExclHeader
	// minus InitiatorConfigLen.
	InitiatorSegmentData []byte
	// InitialTiming has the initial timing characteristics of this transmission
	// control without runtime adjustments.
	InitialTiming TimingConfig
	// InitialTiming has the live timing characteristics of this transmission
	// control including runtime adjustments.
	LiveTiming TimingConfig

	// MaxSegmentLenExclHeader is the maximum length of the data portion in an
	// outgoing segment, the length excludes the headers.
	MaxSegmentLenExclHeader int
	// InputTransport transports inbound segments.
	InputTransport io.Reader
	// OutputTransport transports outbound segments.
	OutputTransport io.Writer
	// OutputSegmentCallback (optional) is invoked for each outbound segment as
	// they are written to output transport.
	OutputSegmentCallback func(Segment)
	// PostHandshakeCallback (optional) is invoked immediately after the
	// initiator config is applied in this transmission control.
	PostConfigCallback func()

	// MaxSlidingWindow is the maximum length of data buffered in the outgoing
	// direction without receiving acknowledge from the peer.
	// This number is comparable to the TCP flow control sliding window.
	MaxSlidingWindow uint32
	// MaxRetransmissions is the maximum number of retransmissions that can be
	// made for handshake and data segments before the transmission control is
	// irreversably closed.
	MaxRetransmissions int
	// MaxTransportErrors is the maximum number of consecutive errors to
	// tolerate from input and output transports before closing down the
	// transmission control.
	MaxTransportErrors int
	// MaxLifetime is the maximum lifetime of the transmission control. After
	// the lifetime elapses, the transmission control will be unconditionally
	// closed/terminated.
	// This is used as a safeguard against transmission control going stale
	// without being properly closed/terminated.
	MaxLifetime time.Duration
	// contains filtered or unexported fields
}

TransmissionControl provides TCP-like features for duplex transportation of data between an initiator and a responder, with flow sliding window control, customisable segment size, and guaranteed in-order delivery. The behaviour is inspired by (though not compatible with) the Internet standard TCP.

Transmission control is intended to be used as the transport of a data stream that would otherwise be transported over TCP,

func (*TransmissionControl) Close 

func (tc *TransmissionControl) Close() error

Close immediately terminates/closes this transmission control, and writes a single output segment to instruct the peer to terminate itself as well.

func (*TransmissionControl) CloseAfterDrained 

func (tc *TransmissionControl) CloseAfterDrained()

closeAfterDrained irreversibly sets an internal flag to signal the transmission control to terminate/close after completely draining the output buffer to its transport.

func (*TransmissionControl) DecreaseTimingInterval 

func (tc *TransmissionControl) DecreaseTimingInterval()

DecreaseTimingInterval decreases the timing interval numbers to half. In the context of TCP-over-DNS tunneling, this means an increase of the throughput of the TCP-over-DNS proxy client.

func (*TransmissionControl) DumpState 

func (tc *TransmissionControl) DumpState()

func (*TransmissionControl) IncreaseTimingInterval 

func (tc *TransmissionControl) IncreaseTimingInterval()

IncreaseTimingInterval increases the timing interval numbers by doubling them. In the context of TCP-over-DNS tunneling, this means a decrease of the throughput of the TCP-over-DNS proxy client.

func (*TransmissionControl) InputSeq 

func (tc *TransmissionControl) InputSeq() uint32

InputSeq returns the input sequence number.

func (*TransmissionControl) LiveTimingInterval 

func (tc *TransmissionControl) LiveTimingInterval() TimingConfig

LiveTimingInterval returns the live timing interval characteristics.

func (*TransmissionControl) LocalAddr 

func (tc *TransmissionControl) LocalAddr() net.Addr

LocalAddr always returns nil.

func (*TransmissionControl) OutputSeq 

func (tc *TransmissionControl) OutputSeq() uint32

OutputSeq returns the output sequence number.

func (*TransmissionControl) Read 

func (tc *TransmissionControl) Read(buf []byte) (int, error)

func (*TransmissionControl) RemoteAddr 

func (tc *TransmissionControl) RemoteAddr() net.Addr

RemoteAddr always returns nil.

func (*TransmissionControl) SetDeadline 

func (tc *TransmissionControl) SetDeadline(t time.Time) error

SetDeadline always returns nil.

func (*TransmissionControl) SetReadDeadline 

func (tc *TransmissionControl) SetReadDeadline(t time.Time) error

SetReadDeadline always returns nil.

func (*TransmissionControl) SetWriteDeadline 

func (tc *TransmissionControl) SetWriteDeadline(t time.Time) error

SetWriteDeadline always returns nil.

func (*TransmissionControl) Start 

func (tc *TransmissionControl) Start(ctx context.Context)

Start initialises the internal state of the transmission control. Start may not be called after the transmission control is stopped.

func (*TransmissionControl) State 

func (tc *TransmissionControl) State() State

State returns the current state of the transmission control.

func (*TransmissionControl) WaitState 

func (tc *TransmissionControl) WaitState(ctx context.Context, want State) bool

WaitState blocks the caller until the transmission control reaches the specified state, or the context is cancelled. It returns true only if the state has been reached while the context is not cancelled.

func (*TransmissionControl) Write 

func (tc *TransmissionControl) Write(buf []byte) (int, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.