nft

Netlink messages

nftables communicates with the kernel using Netlink messages. To reduce the work needed by nftables to support bpfilter the same communication mechanism is used. Hence, bpfilter will receive Netlink messages from nftables and will send Netlink messages to nftables.

This file provides a set of functions to create, parse, and manipulate Netlink messages. It also provides a set of Netlink validation policies for the different Netlink attributes used by nftables.

All the functions defined in this file are dedicated to Netfilter Netlink messages and are not suitable for generic Netlink communication.

Messages

bf_nfmsg is a structure used to represent Netlink messages. It is an opaque structure, so the user must go through the dedicated API to create, parse, and manipulate Netlink messages.

Netlink attributes can be pushed into the message using the generic function bf_nfmsg_attr_push. However, for common types, convenience macros are provided to push a string, a uint8_t, a uint16_t, a uint32_t, or a uint64_t attribute.

Attributes

bf_nfattr is a structure used to represent Netlink attributes. It is an opaque structure, so the user must go through the dedicated API to create, parse, and manipulate Netlink attributes.

Nested attributes

bf_nfnest represent a virtual stack of nested attributes. It is used to create and close nested attributes within a Netlink message.

bf_nfmsg_nest_init declares a new nested attribute within a bf_nfmsg. Every attribute added to the message after calling this function will be pushed within the nested attribute. When complete, bf_nfnest_cleanup must be called to close the nested attribute.

The nested attribute is a stack, so it is possible to have nested attributes within nested attributes.

Defines

_cleanup_bf_nfmsg_

Cleanup attribute for a bf_nfmsg variable.

bf_nfmsg_attr_push_or_jmp(msg, type, data, size)

Convenience macro to push a new attribute into a Netfilter Netlink message, but jump to a label on failure.

If the attribute push fails, this macro jumps to the label bf_nfmsg_push_failure.

Parameters:

• msg – Message to push the attribute to. Can’t be NULL.

• type – Attribute type.

• data – Attribute data. Can’t be NULL.

• size – Attribute data length.

bf_nfmsg_push_str(msg, attr, data)

Convenience macro to push a new string attribute into a Netfilter Netlink message. See bf_nfmsg_attr_push for more details.

bf_nfmsg_push_str_or_jmp(part, attr, value)

Convenience macro to push a new string attribute into a Netfilter Netlink message, and jump to a label on failure. See bf_nfmsg_attr_push_or_jmp for more details.

bf_nfmsg_push_u8(msg, attr, data)

Convenience macro to push a new uint8_t attribute into a Netfilter Netlink message. See bf_nfmsg_attr_push for more details.

bf_nfmsg_push_u8_or_jmp(msg, attr, data)

Convenience macro to push a new uint8_t attribute into a Netfilter Netlink message, and jump to a label on failure. See bf_nfmsg_attr_push_or_jmp for more details.

bf_nfmsg_push_u16(msg, attr, data)

Convenience macro to push a new uint16_t attribute into a Netfilter Netlink message. See bf_nfmsg_attr_push for more details.

bf_nfmsg_push_u16_or_jmp(msg, attr, data)

Convenience macro to push a new uint16_t attribute into a Netfilter Netlink message, and jump to a label on failure. See bf_nfmsg_attr_push_or_jmp for more details.

bf_nfmsg_push_u32(msg, attr, data)

Convenience macro to push a new uint32_t attribute into a Netfilter Netlink message. See bf_nfmsg_attr_push for more details.

bf_nfmsg_push_u32_or_jmp(msg, attr, data)

Convenience macro to push a new uint32_t attribute into a Netfilter Netlink message, and jump to a label on failure. See bf_nfmsg_attr_push_or_jmp for more details.

bf_nfmsg_push_u64(msg, attr, data)

Convenience macro to push a new uint64_t attribute into a Netfilter Netlink message. See bf_nfmsg_attr_push for more details.

bf_nfmsg_push_u64_or_jmp(msg, attr, data)

Convenience macro to push a new uint64_t attribute into a Netfilter Netlink message, and jump to a label on failure. See bf_nfmsg_attr_push_or_jmp for more details.

bf_nfattr_get_str(attr)

Get a Netlink attribute’s data as a string.

Parameters:

• attr – Attribute to get the data from. Can’t be NULL.

Returns:

Pointer to the attribute’s data.

bf_nfattr_get_u8(attr)

Get a Netlink attribute’s data as a uint8_t.

Parameters:

• attr – Attribute to get the data from. Can’t be NULL.

Returns:

Pointer to the attribute’s data.

bf_nfattr_get_s8(attr)

Get a Netlink attribute’s data as a int8_t.

Parameters:

• attr – Attribute to get the data from. Can’t be NULL.

Returns:

Pointer to the attribute’s data.

bf_nfattr_get_u16(attr)

Get a Netlink attribute’s data as a uint16_t.

Parameters:

• attr – Attribute to get the data from. Can’t be NULL.

Returns:

Pointer to the attribute’s data.

bf_nfattr_get_s16(attr)

Get a Netlink attribute’s data as a int16_t.

Parameters:

• attr – Attribute to get the data from. Can’t be NULL.

Returns:

Pointer to the attribute’s data.

bf_nfattr_get_u32(attr)

Get a Netlink attribute’s data as a uint32_t.

Parameters:

• attr – Attribute to get the data from. Can’t be NULL.

Returns:

Pointer to the attribute’s data.

bf_nfattr_get_s32(attr)

Get a Netlink attribute’s data as a int32_t.

Parameters:

• attr – Attribute to get the data from. Can’t be NULL.

Returns:

Pointer to the attribute’s data.

bf_nfattr_get_u64(attr)

Get a Netlink attribute’s data as a uint64_t.

Parameters:

• attr – Attribute to get the data from. Can’t be NULL.

Returns:

Pointer to the attribute’s data.

bf_nfattr_get_s64(attr)

Get a Netlink attribute’s data as a int64_t.

Parameters:

• attr – Attribute to get the data from. Can’t be NULL.

Returns:

Pointer to the attribute’s data.

_cleanup_bf_nfnest_

Cleanup attribute for a bf_nfnest variable.

bf_nfnest_or_jmp(parent, type)

Convenience macro to create a new nested attribute context or jump to bf_nfmsg_push_failure on failure.

Parameters:

• parent – bf_nfmsg to create the nested attribute into. Can’t be NULL.

• type – Type of the nested attribute.

Returns:

0 on success, or negative errno value on error.

Typedefs

typedef struct nlattr bf_nfattr

typedef struct nla_policy bf_nfpolicy

Functions

int bf_nfmsg_new(struct bf_nfmsg **msg, uint8_t command, uint32_t seqnr)

Create a new Netfilter Netlink message.

Parameters:

• msg – The new message to allocate and initialise. Can’t be NULL.

• command – Command to send, can be any of nf_tables_msg_types.

• seqnr – Sequence number for the message.

Returns:

0 on success, or negative errno value on failure.

int bf_nfmsg_new_done(struct bf_nfmsg **msg)

Create a new Netfilter Netlink NLMSG_DONE message.

Parameters:

• msg – The new message to allocate and initialise. Can’t be NULL.

Returns:

0 on success, or negative errno value on failure.

int bf_nfmsg_new_from_nlmsghdr(struct bf_nfmsg **msg, struct nlmsghdr *nlh)

Create a new Netfilter Netlink message from an existing Netlink message.

The provided nlmsghdr must be a valid Netlink message targeted to the NFNL_SUBSYS_NFTABLES subsystem, and containing a nfgenmsg header.

Parameters:

• msg – The new message to allocate and initialise. Can’t be NULL.

• nlh – Netlink message to create the Netfilter Netlink message from. Can’t be NULL.

Returns:

0 on success, or negative errno value on failure.

void bf_nfmsg_free(struct bf_nfmsg **msg)

Free a Netfilter Netlink message.

If msg is NULL, this function has no effect. Before returning, msg is set to NULL.

Parameters:

• msg – Message to free. Must be non-NULL.

struct nlmsghdr *bf_nfmsg_hdr(const struct bf_nfmsg *msg)

Get the Netlink message header for a Netfilter Netlink message.

Parameters:

• msg – Message to get the header from. Must be non-NULL.

Returns:

The Netlink message header.

size_t bf_nfmsg_len(const struct bf_nfmsg *msg)

Get a Netfilter Netlink message’s size, including header and padding.

Parameters:

• msg – Message to get the size of. Can’t be NULL.

Returns:

Message’s size, including header and padding.

size_t bf_nfmsg_data_len(const struct bf_nfmsg *msg)

Get a Netfilter Netlink message’s payload size, including padding.

Parameters:

• msg – Message to get the payload size of. Can’t be NULL.

Returns:

Message’s payload size, including padding.

uint8_t bf_nfmsg_command(const struct bf_nfmsg *msg)

Get a Netfilter Netlink message’s command.

Parameters:

• msg – Message to get the command from. Can’t be NULL.

Returns:

The message’s command.

uint32_t bf_nfmsg_seqnr(const struct bf_nfmsg *msg)

Get a Netfilter Netlink message’s sequence number.

Parameters:

• msg – Message to get the sequence number from. Can’t be NULL.

Returns:

The message’s sequence number.

int bf_nfmsg_attr_push(struct bf_nfmsg *msg, uint16_t type, const void *data, size_t len)

Push a new attribute into a Netfilter Netlink message.

Parameters:

• msg – Message to push the attribute to. Can’t be NULL.

• type – Attribute type.

• data – Attribute data. Can’t be NULL.

• len – Attribute data length.

Returns:

0 on success, or negative errno value on failure.

int bf_nfmsg_parse(const struct bf_nfmsg *msg, bf_nfattr **attrs, int maxtype, const bf_nfpolicy *policy)

Parse attributes from a Netfilter Netlink message.

All the attributes contained in the message are parsed and stored in the attrs array. Nested attributes (attributes contained within other) are not parsed, see bf_nfattr_parse instead.

Parameters:

• msg – Message to parse the attributes from. Can’t be NULL.

• attrs – Array of attributes to parse. Can’t be NULL.

• maxtype – Maximum attribute type to parse.

• policy – Netlink validation policy to use. Can’t be NULL.

Returns:

0 on success, or negative errno value on failure.

int bf_nfattr_parse(bf_nfattr *attr, bf_nfattr **attrs, int maxtype, const bf_nfpolicy *policy)

Parse attributes nested within a Netlink attribute.

All the attributes contained in the attr are parsed and stored in the attrs array.

Parameters:

• attr – Attribute to parse the nested attributes from. Can’t be NULL.

• attrs – Array of attributes to parse. Can’t be NULL.

• maxtype – Maximum attribute type to parse.

• policy – Netlink validation policy to use. Can’t be NULL.

Returns:

0 on success, or negative errno value on failure.

void *bf_nfattr_data(bf_nfattr *attr)

Get the data of a Netlink attribute.

Parameters:

• attr – Attribute to get the data from. Can’t be NULL.

Returns:

Pointer to the attribute’s data.

size_t bf_nfattr_data_len(bf_nfattr *attr)

Get a Netlink attribute’s payload size, including padding.

Parameters:

• attr – Attribute the get the payload size of. Can’t be NULL.

Returns:

Attribute’s payload size, including padding.

bool bf_nfattr_is_ok(bf_nfattr *attr, size_t remaining)

Check if a Netlink attribute (and its payload) is valid.

If the function returns false, the attribute and its content can’t be accessed safely.

Parameters:

• attr – Attribute to validate. Can’t be NULL.

• remaining – Remaining bytes in the parent message or attribute. Can’t be negative.

Returns:

true if the attribute is valid, false otherwise.

bf_nfattr *bf_nfattr_next(bf_nfattr *attr, size_t *remaining)

Get the next Netlink attribute in a message or in a nested attribute.

Parameters:

• attr – Attribute to get the next attribute from. Can’t be NULL.

• remaining – Remaining bytes in the parent message or attribute. Can’t be NULL. When the function succeeds, it is updated with the remaining bytes in the parent message or attribute.

Returns:

Pointer to the next attribute, or NULL if there are no more

int bf_nfmsg_nest_init(struct bf_nfnest *nest, struct bf_nfmsg *parent, uint16_t type)

Declares a new nested attribute within parent.

Once a nested attribute has been defined, all the attributes added to the part (parent here) will be added within the nested attribute, until it is closed (bf_nfnest_cleanup).

Parameters:

• nest – Pointer to the nested attribute. Must be an allocated bf_nfnest structure. Can’t be NULL.

• parent – bf_nfmsg containing the nested attribute.

• type – Type of the nested attribute.

Returns:

0 on success, negative errno value on error.

void bf_nfnest_cleanup(struct bf_nfnest *nest)

Close a nested attribute.

Parameters:

• nest – Nested attribute to close. Can’t be NULL.

Variables

const bf_nfpolicy *bf_nf_table_policy

Netlink validation policy for nft_table_attributes.

const bf_nfpolicy *bf_nf_chain_policy

Netlink validation policy for nft_chain_attributes.

const bf_nfpolicy *bf_nf_hook_policy

Netlink validation policy for nft_hook_attributes.

const bf_nfpolicy *bf_nf_rule_policy

Netlink validation policy for nft_rule_attributes.

const bf_nfpolicy *bf_nf_expr_policy

Netlink validation policy for nft_expr_attributes.

const bf_nfpolicy *bf_nf_counter_policy

Netlink validation policy for nft_counter_attributes.

const bf_nfpolicy *bf_nf_payload_policy

Netlink validation policy for nft_payload_attributes.

const bf_nfpolicy *bf_nf_cmp_policy

Netlink validation policy for nft_cmp_attributes.

const bf_nfpolicy *bf_nf_immediate_policy

Netlink validation policy for nft_immediate_attributes.

const bf_nfpolicy *bf_nf_data_policy

Netlink validation policy for nft_data_attributes.

const bf_nfpolicy *bf_nf_verdict_policy

Netlink validation policy for nft_verdict_attributes.

struct bf_nfnest

#include <bpfilter/xlate/nft/nfmsg.h>

Public Members

struct bf_nfmsg *parent

bf_nfattr *attr

Messages groups

Netlink allows data to be sent in multipart messages, which is a stream of multiple Netlink messages (each with its own header), flagged with NLM_F_MULTI and ending with a final message of type NLMSG_DONE

bf_nfgroup is an abstraction to represent multipart messages. It contains a list of bf_nfmsg, each of which is a Netlink message.

The messages group can be converted into a single bf_response, which is a contiguous buffer containing all the messages in the group.

Defines

_cleanup_bf_nfgroup_

Cleanup function for bf_nfgroup.

Functions

int bf_nfgroup_new(struct bf_nfgroup **group)

Create a new Netlink messages group.

Parameters:

• group – Pointer to the new messages group. Must not be NULL. Will be allocated and initialised by this function. Can’t be NULL.

Returns:

0 on success, or negative errno value on error.

int bf_nfgroup_new_from_stream(struct bf_nfgroup **group, struct nlmsghdr *nlh, size_t length)

Create a new Netlink messages group from a stream of nlmsghdr.

Parameters:

• group – Pointer to the new message group. Must not be NULL. Will be allocated and initialised by this function.

• nlh – Pointer to the first nlmsghdr in the stream. Must not be NULL.

• length – Total length of the stream.

Returns:

0 on success, or negative errno value on error.

void bf_nfgroup_free(struct bf_nfgroup **group)

Free a Netlink messages group.

Parameters:

• group – Pointer to the messages group to free. If msg is NULL, nothing is done.

const bf_list *bf_nfgroup_messages(const struct bf_nfgroup *group)

Get the list of messages in the Netlink messages group.

Parameters:

• group – Netlink messages group to get the list from. Can’t be NULL.

Returns:

bf_list containing the bf_nfmsg

size_t bf_nfgroup_size(const struct bf_nfgroup *group)

Get the total Netlink message size.

The total size of the Netlink message is the sum of the size of all the messages, including padding.

Parameters:

• group – Netlink messages group to get the size of. Can’t be NULL.

Returns:

Total size of the Netlink messages group.

bool bf_nfgroup_is_empty(const struct bf_nfgroup *group)

Test if a Netlink message group is empty.

Parameters:

• group – Netlink message to check. Can’t be NULL.

Returns:

True if the Netlink message is empty (no messages), false otherwise.

int bf_nfgroup_add_message(struct bf_nfgroup *group, struct bf_nfmsg *msg)

Add a Netlink message to the Netlink messages group.

Parameters:

• group – Netlink messages group to add the message to. Can’t be NULL.

• msg – Message to add to the messages group. Can’t be NULL. The Netlink messages group takes onwership of the message.

Returns:

0 on success, or negative errno value on error.

int bf_nfgroup_add_new_message(struct bf_nfgroup *group, struct bf_nfmsg **msg, uint16_t command, uint16_t seqnr)

Create a new Netfilter Netlink message and add it to a Netlink messages group.

The new Netfilter Netlink message is owned by the messages group and should not be freed by the caller.

Parameters:

• group – Netlink messages group to add the message to. Can’t be NULL.

• msg – Pointer to the new message. Once the function succeeds, this pointer will be set to the new message. Can be NULL, in which case the caller won’t have access to the new message.

• command – Netlink message command.

• seqnr – Netlink message sequence number.

Returns:

0 on success, or negative errno value on error.

int bf_nfgroup_to_response(const struct bf_nfgroup *group, struct bf_response **resp)

Convert a Netlink messages group into a bf_response.

All the Netfilter Netlink messages contained in the group will written contiguously in the payload of a single bf_response .

If only one message is present in the group, the response will contain only the message payload. If more than one message is present, the response will contain a multipart message, with the NLM_F_MULTI flag set on all the messages and a final NLMSG_DONE message.

If the group is empty, the reponse will contain a single NLMSG_DONE message.

Parameters:

• group – Netlink messages group to convert. Can’t be NULL.

• resp – Pointer to the new response. Can’t be NULL. A new response will be allocated by this function and the caller will be responsible for freeing it.

Returns:

0 on success, or negative errno value on error.