Networking

Internet module packet filtering

The Internet module provides an interface for packet filtering, allowing clients to capture packets on entry and before output. This can be used for a number of purposes, ranging from auditing through diagnostic logging, to address translation.

SWI Internet_Filter (&41223)

On entry

   R0 = reason code :
         0 = deregister filter
         1 = register filter
   R1 = address family to filter for (must be AF_INET)
   R2 = protocol hash mask for acceptable packets
   R3 = pointer to address to call
   R4 = private word to pass in R12

This SWI is used to register, or deregister a filter with the Internet module. The module checks all packets to be sent or received against the mask supplied. If it matches part of the mask, the filter will be called with the packet, and may act upon it.

Filter mask

The filter mask is a simple 4bit hash of the protocol number as supplied in the packet. To accept a protocol the relevant bit must be set within the mask word. The bit to use is calculated thus :

   (protocol EOR (protocol>>4)) AND 15

The lower 16 bits of the mask relate to input packets. The upper 16 bits of the mask relate to output packets.

In C, the masks for the filters are defined thus :

  #define IPF_PROTOMASK_INPUT(proto)  (1 << (((proto^(proto>>4)) & 15)+0) )
  #define IPF_PROTOMASK_OUTPUT(proto) (1 << (((proto^(proto>>4)) & 15)+16))

It is therefore possible to receive packets for protocols other than those requested. Clients should act appropriately in such circumstances.

Filter code

The packet filter code has the following entry and exit conditions :

On entry

   R0 = reason code:
         0 = input packet
         1 = output packet
         2 = added interface
         3 = removed interface
   R1 = pointer to interface description block
   R2 = pointer to MBuf chain (reason code 0 and 1 only)
   R3 = protocol number (reason code 0 and 1 only)

On exit

   R0 = return reason:
         bit 0-7 = type: 
               0 = pass on (packet is acceptable)
               1 = drop silently (packet is not acceptable)
               2 = drop with ICMP error
               3 = drop with TCP-RST
         bit 16-23 = ICMP code number (for type 2 only)
         bit 24-31 = ICMP type number (for type 2 only)
   R2 = updated pointer to MBuf chain

On input, the filter is called after the Internet module has performed its initial checks on the packet for IP header validity, including the checksum. The filter is called immediately prior to the built in firewall filter.

On output, the filter is called before the Internet module calculates the IP header checksum. The filter is called immediately prior to the built in firewall filter.

On interface addition and removal, the MBuf chain pointer in R2 is invalid, as is the protocol number.

For the packet filtering reason codes (input and output packets), the following fields within the IP packet will be in network byte order:

    ip_id, ip_len, ip_off

In addition, the IP checksum will be not be valid. For input packets the checksum has been checked, and for output packets it will be added if the packet is to be transmitted. The MBuf chain may be modified as necessary by the filter. If the control of the chain is to be taken by the filter, the returned MBuf chain pointer should be 0.

The protocol number may be used to perform a reject, or faster filtering operation.

Interface description block

The interface description block is used to provide a means by which the filter can filter specific interfaces more rapidly. The interface blocks will remain static once added and may be used to check for specific interfaces as necessary. Two special reason codes, documented above, are used to notify filters of the existance of interfaces. The interface description block takes the following format :

      +0         0-terminated interface name (eg 'eh')
      +16       unit number
      +20       internalinterface number
      +24       pointerto function to call to output packets on interface

The internal interface number may be used for filtering purposes as a faster reject than comparing the name and unit. The function for outputing packets allows drivers to output packets outside of the filter routines.

The API of this function is not yet defined.

Example code

A skeleton example filter module can be supplied on request. Contact your supplier for more details.

This documentation is copyright 3QD Developments Ltd 2013 and may not be reproduced or published in any form without the copyright holders permission. RISC OS is subject to continuous development and improvement as such all information is reproduced by 3QD Developments Ltd in good faith and is believed to be correct at the time of publication E&OE. 3QD Developments Ltd cannot accept any liability for any loss or damage arising from the use of any information provided as part of the RISC OS Documentation.

HTML document version 1.03 3rd November 2015