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

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 Config
• type HookFunc
• type Msg
• 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) SetVerdict(id uint32, verdict int) error
  • func (nfqueue *Nfqueue) SetVerdictBatch(id uint32, verdict int) error
  • func (nfqueue *Nfqueue) SetVerdictWithMark(id uint32, verdict, mark int) error

Examples

• Nfqueue.Register

Constants

const (
	AttrPacketID = iota
	AttrHook
	AttrHwProtocol
	AttrIfIndexInDev
	AttrIfIndexOutDev
	AttrIfIndexPhysInDev
	AttrIfIndexPhysOutDev
	AttrPayload
	AttrCapLen
	AttrTimestamp
	AttrHwAddr
	AttrMark
	AttrUID
	AttrGID
	AttrL2HDR
	AttrCt
	AttrCtInfo
	AttrSkbInfo
	AttrExp
	AttrSecCtx
	AttrVlanProto
	AttrVlanTCI
)

Various identifier,that can be the key of Msg map

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 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

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

Config contains options for a Conn.

type HookFunc

type HookFunc func(m Msg) int

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

type Msg

type Msg map[int]interface{}

Msg contains all the information of a connection

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

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,
	}

	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(m nfqueue.Msg) int {
		id := m[nfqueue.AttrPacketID].(uint32)
		// Just print out the id and payload of the nfqueue packet
		fmt.Printf("[%d]\t%v\n", id, m[nfqueue.AttrPayload])
		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) 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) 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