lib/libnpf/libnpf.3

.\"	$NetBSD: libnpf.3,v 1.5 2017/12/07 00:22:06 rmind Exp $
.\"
.\" Copyright (c) 2011-2017 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This material is based upon work partially supported by The
.\" NetBSD Foundation under a contract with Mindaugas Rasiukevicius.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd December 7, 2017
.Dt LIBNPF 3
.Os
.Sh NAME
.Nm libnpf
.Nd NPF packet filter library
.Sh LIBRARY
.Lb libnpf
.Sh SYNOPSIS
.In npf.h
.\" ---
.Ft nl_config_t *
.Fn npf_config_create "void"
.Ft int
.Fn npf_config_submit "nl_config_t *ncf" "int fd" "nl_error_t *errinfo"
.Ft nl_config_t *
.Fn npf_config_retrieve "int fd" "bool *active" "bool *loaded"
.Ft int
.Fn npf_config_flush "int fd"
.Ft void
.Fn npf_config_export "const nl_config_t *ncf" "size_t *len"
.Ft nl_config_t *
.Fn npf_config_import "const void *blob" "size_t len"
.Ft bool
.Fn npf_config_active_p "nl_config_t *ncf"
.Ft void
.Fn npf_config_destroy "nl_config_t *ncf"
.\" ---
.Ft nl_rule_t *
.Fn npf_rule_create "char *name" "uint32_t attr" "const char *ifname"
.Ft int
.Fn npf_rule_setcode "nl_rule_t *rl" "int type" "const void *code" "size_t len"
.Ft int
.Fn npf_rule_setkey "nl_rule_t *rl" "int type" "const void *code" "size_t len"
.Ft int
.Fn npf_rule_setinfo "nl_rule_t *rl" "const void *info" "size_t len"
.Ft bool
.Fn npf_rule_exists_p "nl_config_t *ncf" "const char *name"
.Ft int
.Fn npf_rule_setprio "nl_rule_t *rl" "int pri"
.Ft int
.Fn npf_rule_setproc "nl_config_t *ncf" "nl_rule_t *rl" "const char *name"
.Ft int
.Fn npf_rule_insert "nl_config_t *ncf" "nl_rule_t *parent" "nl_rule_t *rl"
.Ft void *
.Fn npf_rule_export "nl_rule_t *rl" "size_t *length"
.Ft void
.Fn npf_rule_destroy "nl_rule_t *rl"
.\" ---
.Ft nl_rproc_t *
.Fn npf_rproc_create "char *name"
.Ft bool
.Fn npf_rproc_exists_p "nl_config_t *ncf" "const char *name"
.Ft int
.Fn npf_rproc_insert "nl_config_t *ncf" "nl_rproc_t *rp"
.\" ---
.Ft nl_nat_t *
.Fn npf_nat_create "int type" "u_int flags" "const char *ifname" \
"npf_addr_t *addr" "int af" "in_port_t port"
.Ft int
.Fn npf_nat_insert "nl_config_t *ncf" "nl_nat_t *nt" "pri_t pri"
.\" ---
.Ft nl_table_t *
.Fn npf_table_create "const char *name" "u_int id" "int type"
.Ft int
.Fn npf_table_add_entry "nl_table_t *tl" "int af" \
"in_addr_t addr" "in_addr_t mask"
.Ft int
.Fn npf_table_insert "nl_config_t *ncf" "nl_table_t *tl"
.Ft void
.Fn npf_table_destroy "nl_table_t *tl"
.\" -----
.Sh DESCRIPTION
The
.Nm
library provides an interface to create an NPF configuration having rules,
tables, procedures, or translation policies.
The configuration can be submitted to the kernel.
.\" -----
.Sh FUNCTIONS
.Ss Configuration
.Bl -tag -width 4n
.It Fn npf_config_create
Create a new configuration object.
.It Fn npf_config_submit "ncf" "fd" "errinfo"
Submit the configuration object, specified by
.Fa ncf ,
to the kernel.
On failure, the error information is written into the structure
specified by
.Fa errinfo .
.It Fn npf_config_export "fd" "len"
Serialize the current configuration and return the binary object as
well as its length in
.Fa len
parameter.
The binary object is dynamically allocated and should be destroyed using
.Xr free 3 .
.It Fn npf_config_import "blob" "len"
Read the configuration from a binary object of the specified length,
unserialize, and return the configuration object.
.It Fn npf_config_flush "fd"
Flush the current configuration.
.It Fn npf_config_retrieve "fd" "active" "loaded"
Retrieve and return the loaded configuration from the kernel.
.It Fn npf_config_active_p "ncf"
Indicate whether the retrieved configuration is active (true if yes
and false otherwise).
.It Fn npf_config_destroy "ncf"
Destroy the configuration object, specified by
.Fa ncf .
.El
.\" ---
.Ss Rule interface
.Bl -tag -width 4n
.It Fn 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
.Dv NULL ,
in which case the rule will have no identifier.
The following attributes, which can be ORed, are available:
.Bl -tag -width indent
.It Dv 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.
.It Dv NPF_RULE_IN
Match the incoming packets.
.It Dv NPF_RULE_OUT
Match the outgoing packets.
.It Dv NPF_RULE_FINAL
Indicate that on rule match, further processing of the ruleset should
be stopped and this rule should be applied instantly.
.It Dv 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).
.It Dv NPF_RULE_MULTIENDS
Exclude the interface identifier from the state key i.e. use a 4-tuple.
.It Dv NPF_RULE_RETRST
Return TCP RST packet in a case of packet block.
.It Dv NPF_RULE_RETICMP
Return ICMP destination unreachable in a case of packet block.
.It Dv NPF_RULE_GROUP
Allow this rule to have sub-rules.
If this flag is used with the
.Dv 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
.Dv NPF_RULE_DYNAMIC
flag set.
Otherwise rules must be added statically i.e. created with the configuration.
.It Dv NPF_RULE_DYNAMIC
Indicate that the rule is dynamic.
Such rules can only be added to the dynamic groups.
.El
.Pp
The interface is specified by the
.Fa ifname
string.
.Dv NULL
indicates any interface.
.\" ---
.It Fn npf_rule_setcode "rl" "type" "code" "len"
Assign the code for the rule specified by
.Fa rl .
The code is used to implement the filter criteria.
The pointer to the binary code is specified by
.Fa code ,
the size of the memory area by
.Fa len ,
and the type of the code is specified by
.Fa type .
Currently, only the BPF byte-code is supported and the
.Dv NPF_CODE_BPF
constant should be passed.
.\" ---
.It Fn npf_rule_setkey "rl" "type" "key" "len"
Assign a key for the rule specified by
.Fa rl .
The binary key is specified by
.Fa key ,
and its size by
.Fa len .
The size shall not exceed
.Dv NPF_RULE_MAXKEYLEN .
The kernel does not check whether key is unique, therefore it is the
responsibility of the caller.
.\" ---
.It Fn npf_rule_setinfo "rl" "info" "len"
Associate an arbitrary information blob specified by
.Fa info ,
and its size by
.Fa len .
This may be used for such purposes as the byte-code annotation.
.\" ---
.It Fn npf_rule_setprio "rl" "pri"
Set priority to the rule.
Negative priorities are invalid.
.Pp
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.
.Pp
The special constants
.Dv NPF_PRI_FIRST
and
.Dv 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.
.\" ---
.It Fn npf_rule_setproc "ncf" "rl" "name"
Set a procedure for the specified rule.
.\" ---
.It Fn npf_rule_insert "ncf" "parent" "rl"
Insert the rule into the set of the parent rule specified by
.Fa parent .
If the value of
.Fa parent
is
.Dv NULL ,
then insert into the main ruleset.
.\" ---
.It Fn npf_rule_export "rl" "length"
Serialize the rule (including the byte-code), return a binary object
and set its
.Fa length .
The binary object is dynamically allocated and should be destroyed using
.Xr free 3 .
.\" ---
.It Fn npf_rule_destroy "rl"
Destroy the given rule object.
.El
.\" -----
.Ss Rule procedure interface
.Bl -tag -width 4n
.It Fn npf_rproc_create "name"
Create a rule procedure with a given
.Fa name .
Thr name must be unique for each procedure.
.It Fn npf_rproc_insert "ncf" "rp"
Insert the rule procedure into the specified configuration object.
.El
.\" -----
.Ss Translation interface
.Bl -tag -width 4n
.It Fn npf_nat_create "type" "flags" "ifname" "addr" "af" "port"
Create a NAT policy of a specified type.
There are two types:
.Bl -tag -width "NPF_NAT_PORTMAP "
.It Dv NPF_NATIN
Inbound NAT policy (rewrite destination).
.It Dv NPF_NATOUT
Outbound NAT policy (rewrite source).
.El
.Pp
A bi-directional NAT is obtained by combining two policies.
The following
.Fa flags
are supported:
.Bl -tag -width "NPF_NAT_PORTMAP "
.It Dv NPF_NAT_STATIC
Perform static (stateless) translation rather than dynamic (stateful).
.It Dv NPF_NAT_PORTS
Perform the port translation.
If this flag is not specified, then the port translation is not performed
and the
.Fa port
parameter is ignored.
.It Dv NPF_NAT_PORTMAP
Create a port map and select a random port for translation.
If enabled, then the value specified by the
.Fa port
parameter is ignored.
This flag is effective only if the
.Dv NPF_NAT_PORTS
flag is set.
.El
.Pp
The translation address is specified by
.Fa addr ,
and its family by
.Fa af .
The family must be either
.Dv AF_INET
for IPv4 or
.Dv AF_INET6
for IPv6 address.
.\" ---
.It Fn npf_nat_setalgo "nt" "algo"
Set a particular NAT algorithm.
Currently, only
.Dv NPF_ALGO_NPT66
algorithm is supported for NPTv6 (RFC 6296).
.\" ---
.It Fn npf_nat_insert "ncf" "nt" "pri"
Insert NAT policy, its rule, into the specified configuration.
.El
.\" -----
.Ss Table interface
.Bl -tag -width 4n
.It Fn npf_table_create "name" "index" "type"
Create an NPF table of a specified type.
The table is identified by the
.Fa name
and
.Fa index ,
which should be in the range between 1 and
.Dv NPF_MAX_TABLE_ID .
.Pp
The following types are supported:
.Bl -tag -width "NPF_TABLE_HASH"
.It Dv NPF_TABLE_HASH
Indicates to use a hash table for storage.
.It Dv NPF_TABLE_TREE
Indicates to use a tree for storage, supporting the longest
prefix match.
.It Dv NPF_TABLE_CDB
Indicates to use constant database for storage, typically using
a perfect hash table.
In such case, the database produced by
.Xr cdbw 3
should be set using the
.Fn npf_table_setdata
function.
.El
.\" ---
.It Fn npf_table_add_entry "tl" "af" "addr" "mask"
Add an entry of IP address and mask, specified by
.Fa addr
and
.Fa mask ,
to the table specified by
.Fa tl .
The family, specified by
.Fa af ,
must be either
.Dv AF_INET
for IPv4 or
.Dv AF_INET6
for IPv6 address.
.It Fn npf_table_insert "ncf" "tl"
Add the table to the configuration object.
This routine performs a check for duplicate table IDs.
.\" ---
.It Fn npf_table_destroy "tl"
Destroy the specified table.
.El
.\" -----
.Sh SEE ALSO
.Xr bpf 4 ,
.Xr npf 7 ,
.Xr npfctl 8
.Sh HISTORY
The NPF library first appeared in
.Nx 6.0 .