netfilter

package module
v0.5.1 Latest Latest
Warning

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

 Go to latest Published: Oct 16, 2023 License: MIT Imports: 9 Imported by: 17

README

netfilter GoDoc builds.sr.ht status Coverage Status Go Report Card

Package netfilter provides encoding and decoding of Netlink messages into Netfilter attributes. It handles Netfilter-specific nesting of attributes, endianness, and is written around a native Netlink implementation (https://github.com/mdlayher/netlink). It is purely written in Go, without any dependency on Cgo or any C library, kernel headers or userspace tools.

The goal of this package is to be used for implementing the Netfilter family of Netlink protocols. For an example implementation, see https://github.com/ti-mo/conntrack.

Contributing

Contributions are absolutely welcome! Before starting work on large changes, please create an issue first, or join #networking on Gophers Slack to discuss the design.

If you encounter a problem implementing the library, please open a GitHub issue for help.

Documentation

Overview

Package netfilter provides encoding and decoding of Netlink messages into Netfilter attributes. It handles Netfilter-specific nesting of attributes, endianness, and is written around a native Netlink implementation (https://github.com/mdlayher/netlink). It is purely written in Go, without any dependency on Cgo or any C library, kernel headers or userspace tools.

The goal of this package is to be used for implementing the Netfilter family of Netlink protocols. For an example implementation, see https://github.com/ti-mo/conntrack.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// GroupsCT is a list of all Conntrack multicast groups.
	GroupsCT = []NetlinkGroup{GroupCTNew, GroupCTUpdate, GroupCTDestroy}
	// GroupsCTExp is a list of all Conntrack-expect multicast groups.
	GroupsCTExp = []NetlinkGroup{GroupCTExpNew, GroupCTExpUpdate, GroupCTExpDestroy}
)

Functions 

func EncodeNetlink(h Header, ae *netlink.AttributeEncoder) (netlink.Message, error)

EncodeNetlink generates a netlink.Message based on a given netfilter header h and a pre-filled netlink.AttributeEncoder ae.

func MarshalAttributes added in v0.3.0 

func MarshalAttributes(attrs []Attribute) ([]byte, error)

MarshalAttributes marshals a nested attribute structure into a byte slice. This byte slice can then be copied into a netlink.Message's Data field after the nfHeaderLen offset. 

func MarshalNetlink(h Header, attrs []Attribute) (netlink.Message, error)

MarshalNetlink takes a Netfilter Header and Attributes and returns a netlink.Message.

func NewAttributeDecoder added in v0.3.0 

func NewAttributeDecoder(b []byte) (*netlink.AttributeDecoder, error)

NewAttributeDecoder instantiates a new netlink.AttributeDecoder configured with a Big Endian byte order.

func NewAttributeEncoder added in v0.3.0 

func NewAttributeEncoder() *netlink.AttributeEncoder

NewAttributeEncoder instantiates a new netlink.AttributeEncoder configured with a Big Endian byte order.

func Uint16Bytes 

func Uint16Bytes(u uint16) []byte

Uint16Bytes gets the big-endian 2-byte representation of a uint16.

func Uint32Bytes 

func Uint32Bytes(u uint32) []byte

Uint32Bytes gets the big-endian 4-byte representation of a uint32.

func Uint64Bytes 

func Uint64Bytes(u uint64) []byte

Uint64Bytes gets the big-endian 8-byte representation of a uint64. 

func UnmarshalNetlink(msg netlink.Message) (Header, []Attribute, error)

UnmarshalNetlink unmarshals a netlink.Message into a Netfilter Header and Attributes.

Types

type Attribute 

type Attribute struct {

	// The type of this Attribute, typically matched to a constant.
	Type uint16

	// An arbitrary payload which is specified by Type.
	Data []byte

	// Whether the attribute's data contains nested attributes.
	Nested   bool
	Children []Attribute

	// Whether the attribute's data is in network (true) or native (false) byte order.
	NetByteOrder bool
}

An Attribute is a copy of a netlink.Attribute that can be nested.

func UnmarshalAttributes added in v0.3.0 

func UnmarshalAttributes(b []byte) ([]Attribute, error)

UnmarshalAttributes unmarshals a byte slice into a list of Attributes.

func (Attribute) Int32 

func (a Attribute) Int32() int32

Int32 converts the result of Uint16() to an int32.

func (Attribute) Int64 

func (a Attribute) Int64() int64

Int64 converts the result of Uint16() to an int64.

func (*Attribute) PutUint16 

func (a *Attribute) PutUint16(v uint16)

PutUint16 sets the Attribute's data field to a Uint16 encoded in net byte order.

func (*Attribute) PutUint32 

func (a *Attribute) PutUint32(v uint32)

PutUint32 sets the Attribute's data field to a Uint32 encoded in net byte order.

func (*Attribute) PutUint64 

func (a *Attribute) PutUint64(v uint64)

PutUint64 sets the Attribute's data field to a Uint64 encoded in net byte order.

func (Attribute) String 

func (a Attribute) String() string

func (Attribute) Uint16 

func (a Attribute) Uint16() uint16

Uint16 interprets a non-nested Netfilter attribute in network byte order as a uint16.

func (Attribute) Uint32 

func (a Attribute) Uint32() uint32

Uint32 interprets a non-nested Netfilter attribute in network byte order as a uint32.

func (Attribute) Uint64 

func (a Attribute) Uint64() uint64

Uint64 interprets a non-nested Netfilter attribute in network byte order as a uint64.

type Conn 

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

Conn represents a Netlink connection to the Netfilter subsystem.

func Dial 

func Dial(config *netlink.Config) (*Conn, error)

Dial opens a new Netlink connection to the Netfilter subsystem and returns it wrapped in a Conn structure.

func (*Conn) Close 

func (c *Conn) Close() error

Close closes a Conn.

func (*Conn) IsMulticast 

func (c *Conn) IsMulticast() bool

IsMulticast returns the Conn's Multicast flag. It is set by calling Listen().

func (*Conn) JoinGroups 

func (c *Conn) JoinGroups(groups []NetlinkGroup) error

JoinGroups attaches the Netlink socket to one or more Netfilter multicast groups. Marks the Conn as Multicast, meaning it can no longer be used for any queries.

func (*Conn) LeaveGroups 

func (c *Conn) LeaveGroups(groups []NetlinkGroup) error

LeaveGroups detaches the Netlink socket from one or more Netfilter multicast groups. Does not remove the Multicast flag, open a separate Conn for making queries instead.

func (*Conn) Query 

func (c *Conn) Query(nlm netlink.Message) ([]netlink.Message, error)

Query sends a Netfilter message over Netlink and validates the response. The call will fail if the Conn is marked as Multicast. Any errors returned from the underlying Netlink layer are wrapped using pkg/errors.Wrap(). Use errors.Cause() to unwrap to compare to Errno.

func (*Conn) Receive 

func (c *Conn) Receive() ([]netlink.Message, error)

Receive executes a blocking read on the underlying Netlink socket and returns a Message.

func (*Conn) SetDeadline added in v0.3.1 

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

SetDeadline sets the read and write deadlines associated with the connection.

Deadline functionality is only supported on Go 1.12+. Calling this function on older versions of Go will result in an error.

func (*Conn) SetOption 

func (c *Conn) SetOption(option netlink.ConnOption, enable bool) error

SetOption enables or disables a netlink socket option for the Conn.

func (*Conn) SetReadBuffer added in v0.3.1 

func (c *Conn) SetReadBuffer(bytes int) error

SetReadBuffer sets the size of the operating system's receive buffer associated with the Conn.

func (*Conn) SetReadDeadline added in v0.3.1 

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

SetReadDeadline sets the read deadline associated with the connection.

Deadline functionality is only supported on Go 1.12+. Calling this function on older versions of Go will result in an error.

func (*Conn) SetWriteBuffer added in v0.3.1 

func (c *Conn) SetWriteBuffer(bytes int) error

SetWriteBuffer sets the size of the operating system's transmit buffer associated with the Conn.

func (*Conn) SetWriteDeadline added in v0.3.1 

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

SetWriteDeadline sets the write deadline associated with the connection.

Deadline functionality is only supported on Go 1.12+. Calling this function on older versions of Go will result in an error. 

type Header struct {
	// Netlink header flags, to (un)marshal to a netlink Message in a single operation
	Flags netlink.HeaderFlags

	// netlink Header Type
	SubsystemID SubsystemID
	MessageType MessageType

	// nfgenmsg
	Family     ProtoFamily
	Version    uint8 // Usually NFNETLINK_V0 (Go: NFNLv0)
	ResourceID uint16
}

Header is an abstraction over the Netlink header's Type field and the Netfilter message header, also known as 'nfgenmsg'.

The Netlink header's Type field is divided into two bytes by netfilter: the most significant byte is the subsystem ID and the least significant is the message type. The significance of the MessageType field fully depends on the subsystem the message is for (eg. conntrack). This package is only responsible for splitting the field and providing a list of known SubsystemIDs. Subpackages use the MessageType field to implement subsystem-specific behaviour.

nfgenmsg holds the protocol family, version and resource ID of the Netfilter message. Family describes a protocol family that can be managed using Netfilter (eg. IPv4/6, ARP, Bridge) Version is a protocol version descriptor, and always set to 0 (NFNETLINK_V0) ResourceID is a generic field specific to the upper layer protocol (eg. CPU ID of Conntrack stats) 

func DecodeNetlink(msg netlink.Message) (Header, *netlink.AttributeDecoder, error)

DecodeNetlink returns msg's Netfilter header and an AttributeDecoder that can be used to iteratively decode all Netlink attributes contained in the message.

func (Header) String 

func (h Header) String() string

String representation of the netfilter Header/

type MessageType 

type MessageType uint8

MessageType denotes the message type specific to the subsystem. Its meaning can only be determined after decoding the Netfilter Subsystem type, because it only has meaning in that context. Possible values and string representations need to be implemented in a subsystem-specific package.

type NetlinkGroup 

type NetlinkGroup uint8

NetlinkGroup represents the multicast groups that can be joined with a Netlink socket. 

const (
	GroupNone NetlinkGroup = iota // NFNLGRP_NONE

	GroupCTNew        // NFNLGRP_CONNTRACK_NEW
	GroupCTUpdate     // NFNLGRP_CONNTRACK_UPDATE
	GroupCTDestroy    // NFNLGRP_CONNTRACK_DESTROY
	GroupCTExpNew     // NFNLGRP_CONNTRACK_EXP_NEW
	GroupCTExpUpdate  // NFNLGRP_CONNTRACK_EXP_UPDATE
	GroupCTExpDestroy // NFNLGRP_CONNTRACK_EXP_DESTROY
	GroupNFTables     // NFNLGRP_NFTABLES
	GroupAcctQuota    // NFNLGRP_ACCT_QUOTA
	GroupNFTrace      // NFNLGRP_NFTRACE
)

enum nfnetlink_groups

type ProtoFamily 

type ProtoFamily uint8

ProtoFamily represents a protocol family in the Netfilter header (nfgenmsg). 

const (
	ProtoUnspec ProtoFamily = 0  // NFPROTO_UNSPEC
	ProtoInet   ProtoFamily = 1  // NFPROTO_INET
	ProtoIPv4   ProtoFamily = 2  // NFPROTO_IPV4
	ProtoARP    ProtoFamily = 3  // NFPROTO_ARP
	ProtoNetDev ProtoFamily = 5  // NFPROTO_NETDEV
	ProtoBridge ProtoFamily = 7  // NFPROTO_BRIDGE
	ProtoIPv6   ProtoFamily = 10 // NFPROTO_IPV6
	ProtoDECNet ProtoFamily = 12 // NFPROTO_DECNET
)

anonymous enum in uapi/linux/netfilter.h

func (ProtoFamily) String 

func (i ProtoFamily) String() string

type SubsystemID 

type SubsystemID uint8

SubsystemID denotes the Netfilter Subsystem ID the message is for. It is a const that is defined in the kernel at uapi/linux/netfilter/nfnetlink.h. 

const (
	NFSubsysNone SubsystemID = iota // NFNL_SUBSYS_NONE

	NFSubsysCTNetlink        // NFNL_SUBSYS_CTNETLINK
	NFSubsysCTNetlinkExp     // NFNL_SUBSYS_CTNETLINK_EXP
	NFSubsysQueue            // NFNL_SUBSYS_QUEUE
	NFSubsysULOG             // NFNL_SUBSYS_ULOG
	NFSubsysOSF              // NFNL_SUBSYS_OSF
	NFSubsysIPSet            // NFNL_SUBSYS_IPSET
	NFSubsysAcct             // NFNL_SUBSYS_ACCT
	NFSubsysCTNetlinkTimeout // NFNL_SUBSYS_CTNETLINK_TIMEOUT
	NFSubsysCTHelper         // NFNL_SUBSYS_CTHELPER
	NFSubsysNFTables         // NFNL_SUBSYS_NFTABLES
	NFSubsysNFTCompat        // NFNL_SUBSYS_NFT_COMPAT
	NFSubsysCount            // NFNL_SUBSYS_COUNT
)

Subsystem specifiers for Netfilter Netlink messages

func (SubsystemID) String 

func (i SubsystemID) String() string

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.