NPF_NCODE(9) BSD Kernel Developer's Manual NPF_NCODE(9)
NAME
npf_ncode -- NPF n-code processor
SYNOPSIS
#include <net/npf_ncode.h>
int
npf_ncode_process(npf_cache_t *npc, const void *ncode, nbuf_t *nbuf, int layer);
int
npf_ncode_validate(const void *ncode, size_t sz, int *errat);
DESCRIPTION
The NPF n-code processor is a general purpose engine to inspect network packets, which are abstracted as chained buffers.
FUNCTIONS
npf_ncode_process() performs n-code processing using data of the specified packet. ncode is the address to a validated n-code memory block.
N-code memory addresses should be 32-bit word aligned. nbuf is an opaque network buffer on which the n-code processor will operate. layer
specifies at which network layer the buffer is passed, it can be either NPF_LAYER_L2 or NPF_LAYER_L3. This value is initially set in the R0
register and can be checked by the n-code. The contents of other registers are unspecified.
npf_ncode_process() returns a value from the n-code.
npf_ncode_validate() performs n-code validation. ncode is the address to an n-code memory block. sz is the size of the memory block. errat
is the word number in the n-code where the error is detected. If no error is found, this value is undefined.
On successful validation, the npf_ncode_validate() function returns 0. Otherwise, it may return one of the following error codes:
[NPF_ERR_OPCODE] Invalid instruction (unknown opcode).
[NPF_ERR_JUMP] Invalid jump, e.g. not to the instruction or out of range.
[NPF_ERR_REG] Invalid register, i.e. incorrect index number.
[NPF_ERR_INVAL] Invalid argument value.
[NPF_ERR_RANGE] Processing out of range, e.g. missing return path.
Any untrusted n-code, for example generated by userspace, should be validated (once) before allowing to process it.
PROCESSING
There are two instruction sets: RISC-like and CISC-like. Processing is done in words, therefore both instructions (their codes) and argu-
ments are always 32-bit long words.
There are four general purpose registers: R0, R1, R2, R3. Each can store 32-bit long words. Registers are mainly to store values for opera-
tions using RISC-like instructions. CISC-like instructions, however, use them to store return values.
Processing begins from the first word until it reaches an NPF_OPCODE_RET instruction with a return value. The instruction pointer can be
changed using jump operations, which always take relative addresses, in words. The result of last comparison is tracked internally and jump
operations should be performed immediately after comparison or certain CISC-like instructions.
CISC-like instructions and NPF_OPCODE_LOAD can be used to load data from network buffers. They operate at the current network buffer offset,
which is initially at the beginning of the network buffer. The NPF_OPCODE_ADVR instruction can be used to advance the current network buffer
offset.
CACHING
Various packet data is cached during execution of CISC-like instructions and further instruction calls may retrieve information from the
cache. If n-code changes the packet data, information in the cache might no longer reflect the changes. In such case, it is n-code's
responsibility to invalidate the cache (if necessary) by executing the NPF_OPCODE_INVL instruction.
INSTRUCTIONS
Return, advance, jump, and tag operations.
0x00 NPF_OPCODE_RET <return value>
Finish processing and return passed value.
0x01 NPF_OPCODE_ADVR <register>
Advance current network buffer offset by a value, passed in the specified register. Value represents bytes and cannot be negative or
zero.
0x02 NPF_OPCODE_J <relative address>
Jump processor to a relative address (from this instruction). The address value is the amount of words forwards or backwards. It
can point only to a valid instruction, at valid boundaries.
0x03 NPF_OPCODE_INVL
Invalidate all data in the packet cache.
0x04 NPF_OPCODE_TAG <key> <value>
Add a tag with specified key and value to the primary network buffer (nbuf).
Set and load operations.
0x10 NPF_OPCODE_MOVE <value>, <register>
Set the specified value to a register.
0x11 NPF_OPCODE_LW <length>, <register>
Load specified length of packet data into the register. The data is read starting from the current network buffer offset. The oper-
ation does not advance the offset after read, however. The value of length represents bytes and must be in the range from 1 to 4.
Returned data is in network byte order.
Compare and jump operations.
0x21 NPF_OPCODE_CMP <value>, <register>
Compare the specified value and value in a register. The result is stored internally and can be tested by jump instructions.
0x22 NPF_OPCODE_CMPR <register>, <register>
Compare values of two registers. The result is stored internally and can be tested by jump instructions.
0x23 NPF_OPCODE_BEQ <relative address>
Jump if the result of the last comparison was "equal". Otherwise, continue processing with the next instruction.
0x24 NPF_OPCODE_BNE <relative address>
Jump if the result of last comparison was "not equal". Otherwise, continue processing with the next instruction.
0x25 NPF_OPCODE_BGT <relative address>
Jump if the result of last comparison was "greater than". Otherwise, continue processing with the next instruction.
0x26 NPF_OPCODE_BLT <relative address>
Jump if the result of last comparison was "less than". Otherwise, continue processing with the next instruction.
Bitwise operations.
0x41 NPF_OPCODE_AND <value>, <register>
Perform bitwise AND with a specified value and the value in the register. The result is stored in the register.
CISC-like n-code instructions.
0x80 NPF_OPCODE_ETHER <s/d>, <_reserved>, <ether type>
Read Ethernet type in the frame, handle possible VLAN and match with the value passed in the argument. Return value to advance to
layer 3 header in R3.
0x81 NPF_OPCODE_PROTO <protocol>
Match the IP address length and the protocol. The values for both are represented by lower 16 bits. The higher 8 bits represent IP
address length. If zero is specified, the length is not matched. The lower 8 bits represent the protocol. If 0xff is specified,
the protocol is not matched.
0x90 NPF_OPCODE_IP4MASK <s/d>, <network address>, <subnet>
Match passed network address with subnet against source or destination address in the IPv4 header. Address and mask should be in
network byte order. Value of first argument indicates whether source (if 0x1) or destination (if 0x0) address should be matched.
0x91 NPF_OPCODE_TABLE <s/d>, <table id>
Match the source or destination address with NPF table contents specified by table ID. Value of the first argument indicates whether
source (if 0x1) or destination (if 0x0) address should be matched.
0x92 NPF_OPCODE_ICMP4 <type/code>
Match that packet is ICMP and compare type and code values, if required. Highest 32nd and 31st bits indicate whether the type and
code values, accordingly, should be compared. If comparison is required, the type and code values are represented by lower 16 bits.
The higher 8 bits represent type, and the lower 8 bits code number.
0x93 NPF_OPCODE_IP6MASK <s/d>, <network address>, <subnet>
Match passed network address with subnet against source or destination address in the IPv6 header. Address and mask should be in
network byte order. Value of first argument indicates whether source (if 0x1) or destination (if 0x0) address should be matched.
0xa0 NPF_OPCODE_TCP_PORTS <s/d>, <port range>
Match the TCP source or destination port with a specified port range. The higher 16 bits of the second argument represent the "from"
and the lower 16 bits represent the "to" values of the range. The 32-bit port range value is in host byte order, however the actual
"from" and "to" values should be in network byte order. The value of the first argument indicates whether source (if 0x1) or desti-
nation (if 0x0) port should be matched.
0xa1 NPF_OPCODE_UDP_PORTS <s/d>, <port range>
Equivalent of NPF_OPCODE_TCP_PORT, but for UDP protocol.
0xa2 NPF_OPCODE_TCP_FLAGS <fl/mask>
Match the TCP flags with the a specified flags and mask, represented by the lower 16 bits. The higher 8 bits represent flags and the
lower 8 bits mask to apply.
CODE REFERENCES
The npf_ncode is implemented within the file sys/net/npf/npf_processor.c.
SEE ALSO
npf.conf(5), npfctl(8)
HISTORY
The NPF n-code processor first appeared in NetBSD 6.0.
BSD
July 1, 2012 BSD