LIBNPF(3)

LIBNPF(3) | Library Functions Manual | LIBNPF(3)

# NAME

libnpf — NPF 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 configuration.
npf_config_submit(ncf, fd, errinfo)
  Submit configuration ncf to the kernel. On error, the the description is written into the structure specified by errinfo.
npf_config_export(fd, len)
  Serialize the given configuration and return binary object and 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, construct 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 ncf.

## Rule interface

npf_rule_create(name, attr, ifname)
  Create a rule with a given name, attribute and priorty. Name can be `NULL`, in which case rule has no unique identifier. Otherwise, rules shall not have duplicate names. The following attributes, which can be ORed, are available:
  `NPF_RULE_PASS`
    Decision of this rule is "pass". If this attribute is not specified, then packet "block" (drop) is the default.
  `NPF_RULE_IN`
    Match incoming packets.
  `NPF_RULE_OUT`
    Match outgoing packets.
  `NPF_RULE_FINAL`
    Indicates that on rule match, further processing of the ruleset should be stopped and this rule applied instantly.
  `NPF_RULE_STATEFUL`
    Create a state (session) on match, track the connection and therefore pass the backwards stream without 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 from the state identifier.
  `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 used with `NPF_RULE_DYNAMIC` flag set, the can be added dynamically. Otherwise rules must be added statically i.e. created with the configuration.
  `NPF_RULE_DYNAMIC`
    Indicate that the rule is dynamic.
  Interface is specified by ifname, which is a string. `NULL` indicates any interface.
npf_rule_setcode(rl, type, code, len)
  Assign compiled code for the rule specified by rl, used for filter criteria. Pointer to the binary code is specified by code, and size of the memory area by len. Type of the code is specified by type. Currently, only BPF byte-code is supported and `NPF_CODE_BPF` should be passed.
npf_rule_setkey(rl, type, key, len)
  Assign a key for the rule specified by rl. Binary key is specified by key, and its size by len. The size shall not exceed `NPF_RULE_MAXKEYLEN`. The kernel does not validate the key is unique, it is the responsibility of the caller.
npf_rule_setinfo(rl, info, len)
  Associate arbitrary information blob specified by info, and its size by len. This may be used for such purposes as byte-code annotation.
npf_rule_setprio(rl, pri)
  Set priority to the rule. Negative priorities are invalid.
  Priority is the order of the rule in the ruleset. Lower value means first to process, higher value - last to process. If multiple rules are inserted with the same priority, 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 parent rule specified by parent. If 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.

## Rule procedure interface

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

## Translation interface

npf_nat_create(type, flags, ifname, addr, af, port)
  Create a NAT translation 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) NAT rather than dynamic (stateful).
  `NPF_NAT_PORTS`
    Indicates to perform port translation. Otherwise, port translation is not performed and port is ignored.
  `NPF_NAT_PORTMAP`
    Effective only if `NPF_NAT_PORTS` flag is set. Indicates to create a port map and select a random port for translation. Otherwise, port is translated to the value specified by port is used.
  Translation address is specified by addr, and its family by af. 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 NPF table of specified type. The following types are supported:
  `NPF_TABLE_HASH`
    Indicates to use hash table for storage.
  `NPF_TABLE_TREE`
    Indicates to use red-black tree for storage. Table is identified by the name and index, which should be in the range between 1 and `NPF_MAX_TABLE_ID`.
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. Family, specified by af, must be either `AF_INET` for IPv4 or `AF_INET6` for IPv6 address.
npf_table_insert(ncf, tl)
  Insert table into set of configuration. Routine performs a check for duplicate table ID.
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.

April 19, 2015 | NetBSD 8.3