netutils

README

go-netutils

Network utilities in Golang

• TCP assembly stream for dns packets
• Generic IP defrag function
• Generate BPF filter: (ip4 || ip6) && (tcp || udp) && port == int
• Get EBPF program to inject in kernel (XDP DNS filter)
• Easy config for TLS
• String IPv4/v6 CIDR parser to net.IPMask

Build eBPF bytecode

Install prerequisites

sudo apt install llvm clang
sudo apt-get install gcc-multilib

Update libpbf library and generate vmlinux.h

cd ebpf/headers
./update.sh

Compiles a C source file into eBPF bytecode

cd xdp/
go generate .

Running tests

$ go test -cover -v

Examples

String CIDR parser

v4Mask, err = netutils.ParseCIDRMask("10.0.0.0/8")
if err != nil {
   fmt.Println(err)
}
// v4Mask == net.CIDRMask(8, 32)

Documentation

Index

• Constants
• Variables
• func AcceptConnections(listener net.Listener, acceptChan chan<- net.Conn)
• func ApplyBpfFilter(filter []bpf.Instruction, fd int) (err error)
• func Close(conn io.Closer, reset bool) error
• func ConvertIP4(ip uint32) net.IP
• func ConvertIP6(ip [4]uint32) net.IP
• func GetBpfFilterPort(port int) []bpf.Instruction
• func GetIPAddress[T uint32 | [4]uint32](ip T, mapper func(T) net.IP) net.IP
• func GetPeerName(peerAddr string) string
• func Htons(v uint16) int
• func IPDefragger(ipInput chan gopacket.Packet, udpOutput chan gopacket.Packet, ...)
• func IsClosedConnectionError(err error) bool
• func IsValidTLS(mode string) bool
• func LoadBpfObjects(obj interface{}, opts *ebpf.CollectionOptions) error
• func ParseCIDRMask(mask string) (net.IPMask, error)
• func RemoveBpfFilter(fd int) (err error)
• func SetSockRCVBUF(conn net.Conn, desired int, isTLS bool) (int, int, error)
• func StartToListen(listenIP string, listenPort int, sockPath string, tlsSupport bool, ...) (net.Listener, error)
• func TCPAssembler(tcpInput chan gopacket.Packet, dnsOutput chan DNSPacket, portFilter int)
• func TLSClientConfig(options TLSOptions) (*tls.Config, error)
• func UDPProcessor(udpInput chan gopacket.Packet, dnsOutput chan DNSPacket, portFilter int)
• type BpfObjects
  • func (o *BpfObjects) Close() error
• type BpfPktEvent
• type DNSPacket
• type DNSStreamFactory
  • func (s *DNSStreamFactory) New(net, transport gopacket.Flow) tcpassembly.Stream
• type IPDefragmenter
  • func NewIPDefragmenter() *IPDefragmenter
  • func (d *IPDefragmenter) DefragIP(in gopacket.Packet) (gopacket.Packet, error)
  • func (d *IPDefragmenter) DiscardOlderThan(t time.Time) int
• type NetDecoder
  • func (d *NetDecoder) Decode(data []byte, p gopacket.PacketBuilder) error
• type TLSOptions

Constants

const (
	ProtoInet  = "INET"
	ProtoInet6 = "INET6"
	ProtoIPv6  = "IPv6"
	ProtoIPv4  = "IPv4"

	ProtoUDP = "UDP"
	ProtoTCP = "TCP"

	SocketTCP  = "tcp"
	SocketUDP  = "udp"
	SocketUnix = "unix"
	SocketTLS  = "tcp+tls"
)

const (
	TLSV10 = "1.0"
	TLSV11 = "1.1"
	TLSV12 = "1.2"
	TLSV13 = "1.3"
)

const (
	IPv6MinimumFragmentSize    = 1280
	IPv6MaximumSize            = 65535
	IPv6MaximumFragmentOffset  = 8189
	IPv6MaximumFragmentListLen = 52

	IPv4MinimumFragmentSize    = 8     // Minimum size of a single fragment
	IPv4MaximumSize            = 65535 // Maximum size of a fragment (2^16)
	IPv4MaximumFragmentOffset  = 8183  // Maximum offset of a fragment
	IPv4MaximumFragmentListLen = 8192  // Back out if we get more than this many fragments
)

const (
	IPv4ProtocolTCP      = layers.IPProtocolTCP
	IPv4ProtocolUDP      = layers.IPProtocolUDP
	IPv6ProtocolTCP      = layers.IPProtocolTCP
	IPv6ProtocolUDP      = layers.IPProtocolUDP
	IPv6ProtocolFragment = layers.IPProtocolIPv6Fragment
)

Variables

var (
	IPVersion = map[string]string{
		ProtoInet:  ProtoIPv4,
		ProtoInet6: ProtoIPv6,
	}

	IPToInet = map[string]string{
		ProtoIPv4: ProtoInet,
		ProtoIPv6: ProtoInet6,
	}
)

var (
	TLSVersion = map[string]uint16{
		TLSV10: tls.VersionTLS10,
		TLSV11: tls.VersionTLS11,
		TLSV12: tls.VersionTLS12,
		TLSV13: tls.VersionTLS13,
	}
)

Functions

func AcceptConnections

func AcceptConnections(listener net.Listener, acceptChan chan<- net.Conn)

func ApplyBpfFilter

func ApplyBpfFilter(filter []bpf.Instruction, fd int) (err error)

func Close

func Close(conn io.Closer, reset bool) error

thanks to https://stackoverflow.com/questions/28967701/golang-tcp-socket-cant-close-after-get-file, call conn.CloseRead() before calling conn.Close()

func ConvertIP4

func ConvertIP4(ip uint32) net.IP

func ConvertIP6

func ConvertIP6(ip [4]uint32) net.IP

func GetBpfFilterPort

func GetBpfFilterPort(port int) []bpf.Instruction

func GetIPAddress

func GetIPAddress[T uint32 | [4]uint32](ip T, mapper func(T) net.IP) net.IP

func GetPeerName

func GetPeerName(peerAddr string) string

GetPeerName returns the hostname associated with the given peer address. If the peer address cannot be split into IP and port or if the hostname lookup fails, it returns the peer address or IP itself.

func Htons

func Htons(v uint16) int

Convert a uint16 to host byte order (big endian)

func IPDefragger

func IPDefragger(ipInput chan gopacket.Packet, udpOutput chan gopacket.Packet, tcpOutput chan gopacket.Packet, port int)

func IsClosedConnectionError

func IsClosedConnectionError(err error) bool

func IsValidTLS

func IsValidTLS(mode string) bool

func LoadBpfObjects

func LoadBpfObjects(obj interface{}, opts *ebpf.CollectionOptions) error

loadBpfObjects loads bpf and converts it into a struct.

The following types are suitable as obj argument:

*bpfObjects
*bpfPrograms
*bpfMaps

See ebpf.CollectionSpec.LoadAndAssign documentation for details.

func ParseCIDRMask

func ParseCIDRMask(mask string) (net.IPMask, error)

func RemoveBpfFilter

func RemoveBpfFilter(fd int) (err error)

func SetSockRCVBUF

func SetSockRCVBUF(conn net.Conn, desired int, isTLS bool) (int, int, error)

Configure SO_RCVBUF, thanks to https://github.com/dmachard/go-dns-collector/issues/61#issuecomment-1201199895

func StartToListen

func StartToListen(listenIP string, listenPort int, sockPath string, tlsSupport bool, tlsMin uint16, certFile, keyFile string) (net.Listener, error)

func TCPAssembler

func TCPAssembler(tcpInput chan gopacket.Packet, dnsOutput chan DNSPacket, portFilter int)

func TLSClientConfig

func TLSClientConfig(options TLSOptions) (*tls.Config, error)

func UDPProcessor

func UDPProcessor(udpInput chan gopacket.Packet, dnsOutput chan DNSPacket, portFilter int)

Types

type BpfObjects

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

bpfObjects contains all objects after they have been loaded into the kernel.

It can be passed to loadBpfObjects or ebpf.CollectionSpec.LoadAndAssign.

func (*BpfObjects) Close

func (o *BpfObjects) Close() error

type BpfPktEvent

type BpfPktEvent struct {
	Timestamp     uint64
	PktLen        uint32
	PktOffset     uint32
	IpVersion     uint16
	IpProto       uint16
	PayloadOffset uint16
	SrcAddr       uint32
	SrcAddr6      [4]uint32
	SrcPort       uint16
	DstAddr       uint32
	DstAddr6      [4]uint32
	DstPort       uint16
}

type DNSPacket

type DNSPacket struct {
	// DNS payload
	Payload []byte
	// IP layer
	IPLayer gopacket.Flow
	// Transport layer
	TransportLayer gopacket.Flow
	// Timestamp
	Timestamp time.Time
	// IP Defragmented
	IPDefragmented bool
	// TCP reassembly
	TCPReassembled bool
}

DefragPacket is a struct that holds DNS data

type DNSStreamFactory

type DNSStreamFactory struct {
	// Channel to send reassembled DNS data
	Reassembled    chan DNSPacket
	IPDefragmented bool
}

func (*DNSStreamFactory) New

func (s *DNSStreamFactory) New(net, transport gopacket.Flow) tcpassembly.Stream

type IPDefragmenter

type IPDefragmenter struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

func NewIPDefragmenter

func NewIPDefragmenter() *IPDefragmenter

func (*IPDefragmenter) DefragIP

func (d *IPDefragmenter) DefragIP(in gopacket.Packet) (gopacket.Packet, error)

func (*IPDefragmenter) DiscardOlderThan

func (d *IPDefragmenter) DiscardOlderThan(t time.Time) int

type NetDecoder

type NetDecoder struct{}

func (*NetDecoder) Decode

func (d *NetDecoder) Decode(data []byte, p gopacket.PacketBuilder) error

type TLSOptions

type TLSOptions struct {
	CAFile             string
	CertFile           string
	KeyFile            string
	InsecureSkipVerify bool
	MinVersion         string
}