NPF_NCODE(9) BSD Kernel Developer's Manual NPF_NCODE(9)NAMEnpf_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.
FUNCTIONSnpf_ncode_process() performs n-code processing using data of the speci‐
fied 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 speci‐
fies 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 reg‐
ister 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 vali‐
dated (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.
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 nega‐
tive 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
operation 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". Other‐
wise, continue processing with the next instruction.
0x24 NPF_OPCODE_BNE <relative address>
Jump if the result of last comparison was "not equal". Other‐
wise, continue processing with the next instruction.
0x25 NPF_OPCODE_BGT <relative address>
Jump if the result of last comparison was "greater than". Other‐
wise, continue processing with the next instruction.
0x26 NPF_OPCODE_BLT <relative address>
Jump if the result of last comparison was "less than". Other‐
wise, 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 repre‐
sent 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 desti‐
nation 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 desti‐
nation 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, how‐
ever 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, repre‐
sented 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 ALSOnpf.conf(5), npfctl(8)HISTORY
The NPF n-code processor first appeared in NetBSD 6.0.
BSD July 1, 2012 BSD
