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:

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 arguments 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 operations 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.

Set and load operations.

Compare and jump operations.

Bitwise operations.

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 destination (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.

HISTORY

The NPF n-code processor first appeared in NetBSD 6.0.