33b678d7e0
- Add NPF_OPCODE_PROTO to match the address and/or protocol only. - Update parser to support arbitrary "pass proto <name/number>". - Fix IPv6 address and protocol handling (add a regression test). - Fix few theorethical races in session handling module. - Misc fixes, simplifications and some clean up.
291 lines
11 KiB
Groff
291 lines
11 KiB
Groff
.\" $NetBSD: npf_ncode.9,v 1.9 2012/07/01 23:21:06 rmind Exp $
|
|
.\"
|
|
.\" Copyright (c) 2009-2012 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 July 1, 2012
|
|
.Dt NPF_NCODE 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm npf_ncode
|
|
.Nd NPF n-code processor
|
|
.Sh SYNOPSIS
|
|
.In net/npf_ncode.h
|
|
.Ft int
|
|
.Fn npf_ncode_process \
|
|
"npf_cache_t *npc" "const void *ncode" "nbuf_t *nbuf" "int layer"
|
|
.Ft int
|
|
.Fn npf_ncode_validate "const void *ncode" "size_t sz" "int *errat"
|
|
.\" -----
|
|
.Sh DESCRIPTION
|
|
The NPF n-code processor is a general purpose engine to inspect network
|
|
packets, which are abstracted as chained buffers.
|
|
.Sh FUNCTIONS
|
|
.Fn npf_ncode_process
|
|
performs n-code processing using data of the specified packet.
|
|
.Fa ncode
|
|
is the address to a validated n-code memory block.
|
|
N-code memory addresses should be 32-bit word aligned.
|
|
.Fa nbuf
|
|
is an opaque network buffer on which the n-code processor will operate.
|
|
.Fa layer
|
|
specifies at which network layer the buffer is passed, it can be either
|
|
.Dv NPF_LAYER_L2
|
|
or
|
|
.Dv 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.
|
|
.Pp
|
|
.Fn npf_ncode_process
|
|
returns a value from the n-code.
|
|
.Pp
|
|
.Fn npf_ncode_validate
|
|
performs n-code validation.
|
|
.Fa ncode
|
|
is the address to an n-code memory block.
|
|
.Fa sz
|
|
is the size of the memory block.
|
|
.Fa errat
|
|
is the word number in the n-code where the error is detected.
|
|
If no error is found, this value is undefined.
|
|
.Pp
|
|
On successful validation, the
|
|
.Fn npf_ncode_validate
|
|
function returns 0.
|
|
Otherwise, it may return one of the following error codes:
|
|
.Bl -tag -width [NPF_ERR_OPCODE]
|
|
.It Bq Er NPF_ERR_OPCODE
|
|
Invalid instruction (unknown opcode).
|
|
.It Bq Er NPF_ERR_JUMP
|
|
Invalid jump, e.g. not to the instruction or out of range.
|
|
.It Bq Er NPF_ERR_REG
|
|
Invalid register, i.e. incorrect index number.
|
|
.It Bq Er NPF_ERR_INVAL
|
|
Invalid argument value.
|
|
.It Bq Er NPF_ERR_RANGE
|
|
Processing out of range, e.g. missing return path.
|
|
.El
|
|
.Pp
|
|
Any untrusted n-code, for example generated by userspace, should be
|
|
validated (once) before allowing to process it.
|
|
.\" -----
|
|
.Sh 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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
Processing begins from the first word until it reaches an
|
|
.Dv 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.
|
|
.Pp
|
|
CISC-like instructions and
|
|
.Dv 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
|
|
.Dv NPF_OPCODE_ADVR
|
|
instruction can be used to advance the current network buffer offset.
|
|
.\" -----
|
|
.Sh 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
|
|
.Dv NPF_OPCODE_INVL
|
|
instruction.
|
|
.\" -----
|
|
.Sh INSTRUCTIONS
|
|
Return, advance, jump, and tag operations.
|
|
.Bl -tag -width indent
|
|
.It Sy 0x00 NPF_OPCODE_RET <return value>
|
|
Finish processing and return passed value.
|
|
.It Sy 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.
|
|
.It Sy 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.
|
|
.It Sy 0x03 NPF_OPCODE_INVL
|
|
Invalidate all data in the packet cache.
|
|
.It Sy 0x04 NPF_OPCODE_TAG <key> <value>
|
|
Add a tag with specified key and value to the primary network buffer (nbuf).
|
|
.El
|
|
.Pp
|
|
.\" ---
|
|
Set and load operations.
|
|
.Bl -tag -width indent
|
|
.It Sy 0x10 NPF_OPCODE_MOVE <value>, <register>
|
|
Set the specified value to a register.
|
|
.It Sy 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
|
|
.Fa length
|
|
represents bytes and must be in the range from 1 to 4.
|
|
Returned data is in network byte order.
|
|
.El
|
|
.Pp
|
|
.\" ---
|
|
Compare and jump operations.
|
|
.Bl -tag -width indent
|
|
.It Sy 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.
|
|
.It Sy 0x22 NPF_OPCODE_CMPR <register>, <register>
|
|
Compare values of two registers.
|
|
The result is stored internally and can be tested by jump instructions.
|
|
.It Sy 0x23 NPF_OPCODE_BEQ <relative address>
|
|
Jump if the result of the last comparison was "equal".
|
|
Otherwise, continue processing with the next instruction.
|
|
.It Sy 0x24 NPF_OPCODE_BNE <relative address>
|
|
Jump if the result of last comparison was "not equal".
|
|
Otherwise, continue processing with the next instruction.
|
|
.It Sy 0x25 NPF_OPCODE_BGT <relative address>
|
|
Jump if the result of last comparison was "greater than".
|
|
Otherwise, continue processing with the next instruction.
|
|
.It Sy 0x26 NPF_OPCODE_BLT <relative address>
|
|
Jump if the result of last comparison was "less than".
|
|
Otherwise, continue processing with the next instruction.
|
|
.El
|
|
.Pp
|
|
.\" ---
|
|
.\" Arithmetic operations.
|
|
.\" .Bl -tag -width indent
|
|
.\" .It Sy 0x30 NPF_OPCODE_ADD
|
|
.\" .It Sy 0x31 NPF_OPCODE_SUB
|
|
.\" .It Sy 0x32 NPF_OPCODE_MULT
|
|
.\" .It Sy 0x33 NPF_OPCODE_DIV
|
|
.\" .El
|
|
.\" .Pp
|
|
.\" ---
|
|
Bitwise operations.
|
|
.Bl -tag -width indent
|
|
.\" .It Sy 0x40 NPF_OPCODE_NOT
|
|
.It Sy 0x41 NPF_OPCODE_AND <value>, <register>
|
|
Perform bitwise
|
|
.Dv AND
|
|
with a specified value and the value in the register.
|
|
The result is stored in the register.
|
|
.\" .It Sy 0x42 NPF_OPCODE_OR
|
|
.\" .It Sy 0x43 NPF_OPCODE_XOR
|
|
.\" .It Sy 0x44 NPF_OPCODE_SLL
|
|
.\" .It Sy 0x45 NPF_OPCODE_SRL
|
|
.El
|
|
.Pp
|
|
.\" -----
|
|
CISC-like n-code instructions.
|
|
.Bl -tag -width indent
|
|
.It Sy 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.
|
|
.\" -
|
|
.It Sy 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.
|
|
.\" -
|
|
.It Sy 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.
|
|
.It Sy 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.
|
|
.\" -
|
|
.It Sy 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.
|
|
.\" -
|
|
.It Sy 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.
|
|
.\" -
|
|
.It Sy 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.
|
|
.\" -
|
|
.It Sy 0xa1 NPF_OPCODE_UDP_PORTS <s/d>, <port range>
|
|
Equivalent of
|
|
.Dv NPF_OPCODE_TCP_PORT ,
|
|
but for UDP protocol.
|
|
.\" -
|
|
.It Sy 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.
|
|
.El
|
|
.\" -----
|
|
.Sh CODE REFERENCES
|
|
The
|
|
.Nm
|
|
is implemented within the file
|
|
.Pa sys/net/npf/npf_processor.c .
|
|
.Sh SEE ALSO
|
|
.Xr npf.conf 5 ,
|
|
.Xr npfctl 8
|
|
.Sh HISTORY
|
|
The NPF n-code processor first appeared in
|
|
.Nx 6.0 .
|