darwinpacket

README

packet

Package darwinpacket provides access to MacOS sockets via BPF.

It provides a net.PacketConn interface that can be used, in particular, with github.com/mdlayher/arp.

Golang GOOS targets:

• darwin

Usage

conn, err := darwinpacket.Listen(iface, protocol, &darwinpacket.Config{})

History

github.com/mdlayher has specifically said that github.com/mdlayher/packet will only support Linux and recommended that we create variants for any other operating systems that we are interested in (in this case, MacOS).

This package is based on github.com/synfinatic/packet, but this version specifically limits support to MacOS in keeping with github.com/mdlayher's design wishes.

Documentation

Overview

Package darwinpacket provides access to MacOS packet sockets using BPF.

Index

• type Addr
  • func (a *Addr) Network() string
  • func (a *Addr) String() string
• type Config
• type Conn
  • func Listen(ifi *net.Interface, protocol int, cfg *Config) (*Conn, error)
  • func (c *Conn) Close() error
  • func (c *Conn) LocalAddr() net.Addr
  • func (c *Conn) ReadFrom(b []byte) (int, net.Addr, error)
  • func (c *Conn) SetBPF(filter []bpf.RawInstruction) error
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetPromiscuous(enable bool) error
  • func (c *Conn) SetReadDeadline(t time.Time) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) Stats() (*Stats, error)
  • func (c *Conn) SyscallConn() (syscall.RawConn, error)
  • func (c *Conn) WriteTo(b []byte, addr net.Addr) (int, error)
• type Direction
• type Stats

Types

type Addr

type Addr struct {
	HardwareAddr net.HardwareAddr
}

An Addr is a physical-layer address.

func (*Addr) Network

func (a *Addr) Network() string

Network returns the address's network name, "packet".

func (*Addr) String

func (a *Addr) String() string

String returns the string representation of an Addr.

type Config

type Config struct {
	// Filter is an optional assembled BPF filter which can be applied to the
	// Conn before bind(2) is called.
	//
	// The Conn.SetBPF method serves the same purpose once a Conn has already
	// been opened, but setting Filter applies the BPF filter before the Conn is
	// bound. This ensures that unexpected packets will not be captured before
	// the Conn is opened.
	Filter []bpf.RawInstruction

	// devices support setting the direction to listen to packets on
	Direction Direction
}

Config contains options for a Conn.

type Conn

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

A Conn is an Linux packet sockets (AF_PACKET) implementation of a net.PacketConn.

func Listen

func Listen(ifi *net.Interface, protocol int, cfg *Config) (*Conn, error)

Listen opens a packet sockets connection on the specified interface, using the given protocol value.

The Config specifies optional configuration for the Conn. A nil *Config applies the default configuration.

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection.

func (*Conn) LocalAddr

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

LocalAddr returns the local network address. The Addr returned is shared by all invocations of LocalAddr, so do not modify it.

func (*Conn) ReadFrom

func (c *Conn) ReadFrom(b []byte) (int, net.Addr, error)

ReadFrom implements the net.PacketConn ReadFrom method.

func (*Conn) SetBPF

func (c *Conn) SetBPF(filter []bpf.RawInstruction) error

SetBPF attaches an assembled BPF program to the Conn.

func (*Conn) SetDeadline

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

SetDeadline implements the net.PacketConn SetDeadline method.

func (*Conn) SetPromiscuous

func (c *Conn) SetPromiscuous(enable bool) error

SetPromiscuous enables or disables promiscuous mode on the Conn, allowing it to receive traffic that is not addressed to the Conn's network interface.

func (*Conn) SetReadDeadline

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

SetReadDeadline implements the net.PacketConn SetReadDeadline method.

func (*Conn) SetWriteDeadline

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

SetWriteDeadline implements the net.PacketConn SetWriteDeadline method.

func (*Conn) Stats

func (c *Conn) Stats() (*Stats, error)

Stats retrieves statistics about the Conn from the Linux kernel.

Note that calling Stats will reset the kernel's internal counters for this Conn. If you want to maintain cumulative statistics by polling Stats over time, you must do so in your calling code.

func (*Conn) SyscallConn

func (c *Conn) SyscallConn() (syscall.RawConn, error)

SyscallConn returns a raw network connection. This implements the syscall.Conn interface.

func (*Conn) WriteTo

func (c *Conn) WriteTo(b []byte, addr net.Addr) (int, error)

WriteTo implements the net.PacketConn WriteTo method.

type Direction

type Direction int

Clone PCAP_D_* values from pcap/pcap.h

const (
	DirectionInOut Direction = iota
	DirectionIn
	DirectionOut
)

type Stats

type Stats struct {
	// The total number of packets received.
	Packets uint32

	// The number of packets dropped.
	Drops uint32

	// The total number of times that a receive queue is frozen. May be zero if
	// the Linux kernel is not new enough to support TPACKET_V3 statistics.
	FreezeQueueCount uint32
}

Stats contains statistics about a Conn reported by the Linux kernel.