LIBNPF(3) Library Functions Manual LIBNPF(3)

NAME

libnpfNPF packet filter library

LIBRARY

NPF Packet Filter Library (libnpf, -lnpf)

SYNOPSIS

#include <npf.h>
nl_config_t *
npf_config_create(void);
int
npf_config_submit(nl_config_t *ncf, int fd, nl_error_t *errinfo);
nl_config_t *
npf_config_retrieve(int fd, bool *active, bool *loaded);
int
npf_config_flush(int fd);
void
npf_config_export(const nl_config_t *ncf, size_t *len);
nl_config_t *
npf_config_import(const void *blob, size_t len);
bool
npf_config_active_p(nl_config_t *ncf);
void
npf_config_destroy(nl_config_t *ncf);
nl_rule_t *
npf_rule_create(char *name, uint32_t attr, const char *ifname);
int
npf_rule_setcode(nl_rule_t *rl, int type, const void *code, size_t len);
int
npf_rule_setkey(nl_rule_t *rl, int type, const void *code, size_t len);
int
npf_rule_setinfo(nl_rule_t *rl, const void *info, size_t len);
bool
npf_rule_exists_p(nl_config_t *ncf, const char *name);
int
npf_rule_setprio(nl_rule_t *rl, int pri);
int
npf_rule_setproc(nl_config_t *ncf, nl_rule_t *rl, const char *name);
int
npf_rule_insert(nl_config_t *ncf, nl_rule_t *parent, nl_rule_t *rl);
void *
npf_rule_export(nl_rule_t *rl, size_t *length);
void
npf_rule_destroy(nl_rule_t *rl);
nl_rproc_t *
npf_rproc_create(char *name);
bool
npf_rproc_exists_p(nl_config_t *ncf, const char *name);
int
npf_rproc_insert(nl_config_t *ncf, nl_rproc_t *rp);
nl_nat_t *
npf_nat_create(int type, u_int flags, const char *ifname, npf_addr_t *addr, int af, in_port_t port);
int
npf_nat_insert(nl_config_t *ncf, nl_nat_t *nt, pri_t pri);
nl_table_t *
npf_table_create(const char *name, u_int id, int type);
int
npf_table_add_entry(nl_table_t *tl, int af, in_addr_t addr, in_addr_t mask);
int
npf_table_insert(nl_config_t *ncf, nl_table_t *tl);
void
npf_table_destroy(nl_table_t *tl);

DESCRIPTION

The libnpf library provides an interface to create an NPF configuration having rules, tables, procedures, or translation policies. The configuration can be submitted to the kernel.

FUNCTIONS

Configuration

 
 
npf_config_create()
Create a new configuration object.
 
 
npf_config_submit(ncf, fd, errinfo)
Submit the configuration object, specified by ncf, to the kernel. On failure, the error information is written into the structure specified by errinfo.
 
 
npf_config_export(fd, len)
Serialize the current configuration and return the binary object as well as its length in len parameter. The binary object is dynamically allocated and should be destroyed using free(3).
 
 
npf_config_import(blob, len)
Read the configuration from a binary object of the specified length, unserialize, and return the configuration object.
 
 
npf_config_flush(fd)
Flush the current configuration.
 
 
npf_config_retrieve(fd, active, loaded)
Retrieve and return the loaded configuration from the kernel.
 
 
npf_config_active_p(ncf)
Indicate whether the retrieved configuration is active (true if yes and false otherwise).
 
 
npf_config_destroy(ncf)
Destroy the configuration object, specified by ncf.

Rule interface

 
 
npf_rule_create(name, attr, ifname)
Create a rule with a given name, attribute and priorty. If the name is specified, then it should be unique within the configuration object. Otherwise, the name can be NULL, in which case the rule will have no identifier. The following attributes, which can be ORed, are available:
 
 
NPF_RULE_PASS
The decision of this rule shall be "pass". If this attribute is not specified, then "block" (drop the packet) is the default.
 
 
NPF_RULE_IN
Match the incoming packets.
 
 
NPF_RULE_OUT
Match the outgoing packets.
 
 
NPF_RULE_FINAL
Indicate that on rule match, further processing of the ruleset should be stopped and this rule should be applied instantly.
 
 
NPF_RULE_STATEFUL
Create a state (session) on match, track the connection and pass the backwards stream (the returning packets) without the ruleset inspection. The state is uniquely identified by a 5-tuple (source and destination IP addresses, port numbers and an interface identifier).
 
 
NPF_RULE_MULTIENDS
Exclude the interface identifier from the state key i.e. use a 4-tuple.
 
 
NPF_RULE_RETRST
Return TCP RST packet in a case of packet block.
 
 
NPF_RULE_RETICMP
Return ICMP destination unreachable in a case of packet block.
 
 
NPF_RULE_GROUP
Allow this rule to have sub-rules. If this flag is used with the NPF_RULE_DYNAMIC flag set, then it is a dynamic group. The sub-rules can be added dynamically to a dynamic group, also meaning that the sub-rules must have the NPF_RULE_DYNAMIC flag set. Otherwise rules must be added statically i.e. created with the configuration.
 
 
NPF_RULE_DYNAMIC
Indicate that the rule is dynamic. Such rules can only be added to the dynamic groups.
The interface is specified by the ifname string. NULL indicates any interface.
 
 
npf_rule_setcode(rl, type, code, len)
Assign the code for the rule specified by rl. The code is used to implement the filter criteria. The pointer to the binary code is specified by code, the size of the memory area by len, and the type of the code is specified by type. Currently, only the BPF byte-code is supported and the NPF_CODE_BPF constant should be passed.
 
 
npf_rule_setkey(rl, type, key, len)
Assign a key for the rule specified by rl. The binary key is specified by key, and its size by len. The size shall not exceed NPF_RULE_MAXKEYLEN. The kernel does not check whether key is unique, therefore it is the responsibility of the caller.
 
 
npf_rule_setinfo(rl, info, len)
Associate an arbitrary information blob specified by info, and its size by len. This may be used for such purposes as the byte-code annotation.
 
 
npf_rule_setprio(rl, pri)
Set priority to the rule. Negative priorities are invalid.
The priority is the order of the rule in the ruleset. The lower value means first to process, the higher value - last to process. If multiple rules are inserted with the same priority, then the order is unspecified.
The special constants NPF_PRI_FIRST and NPF_PRI_LAST can be passed to indicate that the rule should be inserted into the beginning or the end of the priority level 0 in the ruleset. All rules inserted using these constants will have the priority 0 assigned and will share this level in the ordered way.
 
 
npf_rule_setproc(ncf, rl, name)
Set a procedure for the specified rule.
 
 
npf_rule_insert(ncf, parent, rl)
Insert the rule into the set of the parent rule specified by parent. If the value of parent is NULL, then insert into the main ruleset.
 
 
npf_rule_export(rl, length)
Serialize the rule (including the byte-code), return a binary object and set its length. The binary object is dynamically allocated and should be destroyed using free(3).
 
 
npf_rule_destroy(rl)
Destroy the given rule object.

Rule procedure interface

 
 
npf_rproc_create(name)
Create a rule procedure with a given name. Thr name must be unique for each procedure.
 
 
npf_rproc_insert(ncf, rp)
Insert the rule procedure into the specified configuration object.

Translation interface

 
 
npf_nat_create(type, flags, ifname, addr, af, port)
Create a NAT policy of a specified type. There are two types:
 
 
NPF_NATIN
Inbound NAT policy (rewrite destination).
 
 
NPF_NATOUT
Outbound NAT policy (rewrite source).
A bi-directional NAT is obtained by combining two policies. The following flags are supported:
 
 
NPF_NAT_STATIC
Perform static (stateless) translation rather than dynamic (stateful).
 
 
NPF_NAT_PORTS
Perform the port translation. If this flag is not specified, then the port translation is not performed and the port parameter is ignored.
 
 
NPF_NAT_PORTMAP
Create a port map and select a random port for translation. If enabled, then the value specified by the port parameter is ignored. This flag is effective only if the NPF_NAT_PORTS flag is set.
The translation address is specified by addr, and its family by af. The family must be either AF_INET for IPv4 or AF_INET6 for IPv6 address.
 
 
npf_nat_setalgo(nt, algo)
Set a particular NAT algorithm. Currently, only NPF_ALGO_NPT66 algorithm is supported for NPTv6 (RFC 6296).
 
 
npf_nat_insert(ncf, nt, pri)
Insert NAT policy, its rule, into the specified configuration.

Table interface

 
 
npf_table_create(name, index, type)
Create an NPF table of a specified type. The table is identified by the name and index, which should be in the range between 1 and NPF_MAX_TABLE_ID.
The following types are supported:
 
 
NPF_TABLE_HASH
Indicates to use a hash table for storage.
 
 
NPF_TABLE_TREE
Indicates to use a tree for storage, supporting the longest prefix match.
 
 
NPF_TABLE_CDB
Indicates to use constant database for storage, typically using a perfect hash table. In such case, the database produced by cdbw(3) should be set using the npf_table_setdata() function.
 
 
npf_table_add_entry(tl, af, addr, mask)
Add an entry of IP address and mask, specified by addr and mask, to the table specified by tl. The family, specified by af, must be either AF_INET for IPv4 or AF_INET6 for IPv6 address.
 
 
npf_table_insert(ncf, tl)
Add the table to the configuration object. This routine performs a check for duplicate table IDs.
 
 
npf_table_destroy(tl)
Destroy the specified table.

SEE ALSO

bpf(4), npf(7), npfctl(8)

HISTORY

The NPF library first appeared in NetBSD 6.0.
December 7, 2017 NetBSD 8.99