nfqueue

README

go-nfqueue

This is go-nfqueue and it is written in golang. It provides a C-binding free API to the netfilter based queue subsystem of the Linux kernel.

Privileges

This package processes information directly from the kernel and therefore it requires special privileges. You can provide this privileges by adjusting the CAP_NET_ADMIN capabilities.

	setcap 'cap_net_admin=+ep' /your/executable

For documentation and more examples please take a look at documentation.

Requirements

• A version of Go that is supported by upstream

Documentation

Overview

Package nfqueue provides an API to interact with the nfqueue subsystem of the netfilter family from the linux kernel.

This package processes information directly from the kernel and therefore it requires special privileges. You can provide this privileges by adjusting the CAP_NET_ADMIN capabilities.

setcap 'cap_net_admin=+ep' /your/executable

Index

• Constants
• Variables
• type Attribute
• type Config
• type ErrorFunc
• type HookFunc
• type Nfqueue
  • func Open(config *Config) (*Nfqueue, error)
  • func (nfqueue *Nfqueue) Close() error
  • func (nfqueue *Nfqueue) Register(ctx context.Context, fn HookFunc) error
  • func (nfqueue *Nfqueue) RegisterWithErrorFunc(ctx context.Context, fn HookFunc, errfn ErrorFunc) error
  • func (nfqueue *Nfqueue) SetVerdict(id uint32, verdict int) error
  • func (nfqueue *Nfqueue) SetVerdictBatch(id uint32, verdict int) error
  • func (nfqueue *Nfqueue) SetVerdictModPacket(id uint32, verdict int, packet []byte) error
  • func (nfqueue *Nfqueue) SetVerdictModPacketWithMark(id uint32, verdict, mark int, packet []byte) error
  • func (nfqueue *Nfqueue) SetVerdictWithMark(id uint32, verdict, mark int) error

Examples

• Nfqueue.Register

Constants

const (
	NfQaCfgFlagFailOpen  = (1 << iota)
	NfQaCfgFlagConntrack = (1 << iota)
	NfQaCfgFlagGSO       = (1 << iota)
	NfQaCfgFlagUIDGid    = (1 << iota)
	NfQaCfgFlagSecCx     = (1 << iota)
)

Various configuration flags

const (
	NfQnlCopyNone = iota
	NfQnlCopyMeta
	NfQnlCopyPacket
)

copy modes

const (
	NfDrop = iota
	NfAccept
	NfStolen
	NfQeueue
	NfRepeat
)

Verdicts

Variables

var (
	ErrRecvMsg        = errors.New("received error message")
	ErrUnexpMsg       = errors.New("received unexpected message from kernel")
	ErrInvFlag        = errors.New("invalid Flag")
	ErrNotLinux       = errors.New("not implemented for OS other than linux")
	ErrInvalidVerdict = errors.New("invalid verdict")
)

Various errors

Types

type Attribute

type Attribute struct {
	PacketID   *uint32
	Hook       *uint8
	Timestamp  *time.Time
	Mark       *uint32
	InDev      *uint32
	PhysInDev  *uint32
	OutDev     *uint32
	PhysOutDev *uint32
	Payload    *[]byte
	CapLen     *uint32
	UID        *uint32
	GID        *uint32
	SecCtx     *string
	L2Hdr      *[]byte
	HwAddr     *[]byte
	HwProtocol *uint16
	Ct         *[]byte
	CtInfo     *uint32
	SkbInfo    *[]byte
	Exp        *[]byte
}

Attribute contains various elements for nfqueue elements. As not every value is contained in every nfqueue message, the elements inside Attribute are pointers to these values or nil, if not present.

type Config

type Config struct {
	// Network namespace the Nfqueue needs to operate in. If set to 0 (default),
	// no network namespace will be entered.
	NetNS int

	// Queue this Nfqueue socket will be assigned to
	NfQueue uint16
	// Maximum number of packages within the Nfqueue.
	MaxQueueLen uint32

	// Only used in combination with NfQnlCopyPacket.
	MaxPacketLen uint32

	// Specifies how the kernel handles a packet in the nfqueue queue.
	Copymode uint8

	// Optional flags for this Nfqueue socket.
	Flags uint32

	// AfFamily for this Nfqueue socket.
	AfFamily uint8

	// Deprecated: Cancel the context passed to RegisterWithErrorFunc() or Register()
	// to remove the hook from the nfqueue gracefully.
	ReadTimeout time.Duration

	// Time till a write action times out - only available for Go >= 1.12
	WriteTimeout time.Duration

	// Interface to log internals.
	Logger *log.Logger
}

Config contains options for a Conn.

type ErrorFunc

type ErrorFunc func(e error) int

ErrorFunc is a function that receives all errors that happen while reading from a Netlinkgroup. To stop receiving messages return something different than 0.

type HookFunc

type HookFunc func(a Attribute) int

HookFunc is a function, that receives events from a Netlinkgroup To stop receiving messages on this HookFunc, return something different than 0.

type Nfqueue

type Nfqueue struct {
	// Con is the pure representation of a netlink socket
	Con *netlink.Conn
	// contains filtered or unexported fields
}

Nfqueue represents a netfilter queue handler

func Open

func Open(config *Config) (*Nfqueue, error)

Open a connection to the netfilter queue subsystem

func (*Nfqueue) Close

func (nfqueue *Nfqueue) Close() error

Close the connection to the netfilter queue subsystem

func (*Nfqueue) Register

func (nfqueue *Nfqueue) Register(ctx context.Context, fn HookFunc) error

Register your own function as callback for a netfilter queue.

The registered callback will stop receiving data if an error happened. To handle errors and continue receiving data with the registered callback use RegisterWithErrorFunc() instead.

Deprecated: Use RegisterWithErrorFunc() instead.

Example

package main

import (
	"context"
	"fmt"
	"time"

	nfqueue "github.com/florianl/go-nfqueue"
)

func main() {
	// Send outgoing pings to nfqueue queue 100
	// # sudo iptables -I OUTPUT -p icmp -j NFQUEUE --queue-num 100

	// Set configuration options for nfqueue
	config := nfqueue.Config{
		NfQueue:      100,
		MaxPacketLen: 0xFFFF,
		MaxQueueLen:  0xFF,
		Copymode:     nfqueue.NfQnlCopyPacket,
		WriteTimeout: 15 * time.Millisecond,
	}

	nf, err := nfqueue.Open(&config)
	if err != nil {
		fmt.Println("could not open nfqueue socket:", err)
		return
	}
	defer nf.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	fn := func(a nfqueue.Attribute) int {
		id := *a.PacketID
		// Just print out the id and payload of the nfqueue packet
		fmt.Printf("[%d]\t%v\n", id, *a.Payload)
		nf.SetVerdict(id, nfqueue.NfAccept)
		return 0
	}

	// Register your function to listen on nflqueue queue 100
	err = nf.Register(ctx, fn)
	if err != nil {
		fmt.Println(err)
		return
	}

	// Block till the context expires
	<-ctx.Done()
}

func (*Nfqueue) RegisterWithErrorFunc

func (nfqueue *Nfqueue) RegisterWithErrorFunc(ctx context.Context, fn HookFunc, errfn ErrorFunc) error

RegisterWithErrorFunc attaches a callback function to a netfilter queue and allows custom error handling for errors encountered when reading from the underlying netlink socket.

func (*Nfqueue) SetVerdict

func (nfqueue *Nfqueue) SetVerdict(id uint32, verdict int) error

SetVerdict signals the kernel the next action for a specified package id

func (*Nfqueue) SetVerdictBatch

func (nfqueue *Nfqueue) SetVerdictBatch(id uint32, verdict int) error

SetVerdictBatch signals the kernel the next action for a batch of packages till id

func (*Nfqueue) SetVerdictModPacket

func (nfqueue *Nfqueue) SetVerdictModPacket(id uint32, verdict int, packet []byte) error

SetVerdictModPacket signals the kernel the next action for an altered packet

func (*Nfqueue) SetVerdictModPacketWithMark

func (nfqueue *Nfqueue) SetVerdictModPacketWithMark(id uint32, verdict, mark int, packet []byte) error

SetVerdictModPacketWithMark signals the kernel the next action and mark for an altered packet

func (*Nfqueue) SetVerdictWithMark

func (nfqueue *Nfqueue) SetVerdictWithMark(id uint32, verdict, mark int) error

SetVerdictWithMark signals the kernel the next action and the mark for a specified package id