ip_fltr_in_hook, ip_fltr_out_hook, ipsec_decap_hook, inbound_fw, outbound_fw Kernel Service

Purpose

Contains hooks for IP filtering.

Syntax

#define FIREWALL_OK         0  /* Accept IP packet                     */
#define FIREWALL_NOTOK      1  /* Drop IP packet                       */
#define FIREWALL_OK_NOTSEC  2  /* Accept non-encapsulated IP packet 
                                  (ipsec_decap_hook only)       */
#include <sys/mbuf.h>
#include <net/if.h>

int (*ip_fltr_in_hook)(struct mbuf **pkt, void **arg)

int (*ipsec_decap_hook)(struct mbuf **pkt, void **arg)

int (*ip_fltr_out_hook)(struct ifnet *ifp, struct mbuf **pkt, 
int flags)
#include <sys/types.h>

#include <sys/mbuf.h>

#include <netinet/ip_var.h>

void (*inbound_fw)(struct ifnet *ifp, struct mbuf *m, 
inbound_fw_args_t *args)

void ipintr_noqueue_post_fw(struct ifnet *ifp, struct mbuf *m, 
inbound_fw_args_t *args)

inbound_fw_args_t *inbound_fw_save_args(inbound_fw_args_t *args)

int (*outbound_fw)(struct ifnet *ifp, struct mbuf *
m0, outbound_fw_args_t *args)

int ip_output_post_fw( struct ifnet *ifp, struct mbuf *m0, 
outbound_fw_args_t *args)

outbound_fw_args_t *outbound_fw_save_args(outbound_fw_args_t *args)

Parameters

Item Description
pkt Points to the mbuf chain containing the IP packet to be received (ip_fltr_in_hook, ipsec_decap_hook) or transmitted (ip_fltr_out_hook). The pkt parameter may be examined and/or changed in any of the three hook functions.
arg Is the address of a pointer to void that is locally defined in the function where ip_fltr_in_hook and ipsec_decap_hook are called. The arg parameter is initially set to NULL, but the address of this pointer is passed to the two hook functions, ip_fltr_in_hook and ipsec_decap_hook. The arg parameter may be set by either of these functions, thereby allowing a void pointer to be shared between them.
ifp Is the outgoing interface on which the IP packet will be transmitted for the ip_fltr_out_hook function.
flags Indicates the ip_output flags passed by a transport layer protocol. Valid flags are currently defined in the /usr/include/netinet/ip_var.h files. See the Flags section below.

Description

These routines provide kernel-level hooks for IP packet filtering enabling IP packets to be selectively accepted, rejected, or modified during reception, transmission, and decapsulation. These hooks are initially NULL, but are exported by the netinet kernel extension and will be invoked if assigned non-NULL values.

The ip_fltr_in_hook routine is used to filter incoming IP packets, the ip_fltr_out_hook routine filters outgoing IP packets, and the ipsec_decap_hook routine filters incoming encapsulated IP packets.

The ip_fltr_in_hook function is invoked for every IP packet received by the host, whether addressed directly to this host or not. It is called after verifying the integrity and consistency of the IP packet. The function is free to examine or change the IP packet (pkt) or the pointer shared with ipsec_decap_hook (arg). The return value of the ip_fltr_in_hook indicates whether pkt should be accepted or dropped. The return values are described in Expected Return Values below. If pkt is accepted (a return value of FIREWALL_OK) and it is addressed directly to the host, the ipsec_decap_hook function is invoked next. If pkt is accepted, but is not directly addressed to the host, it is forwarded if IP forwarding is enabled. If ip_fltr_in_hook indicates pkt should be dropped (a return value of FIREWALL_NOTOK), it is neither delivered nor forwarded.

The ipsec_decap_hook function is called after reassembly of any IP fragments (the ip_fltr_in_hook function will have examined each of the IP fragments) and is invoked only for IP packets that are directly addressed to the host. The ipsec_decap_hook function is free to examine or change the IP packet (pkt) or the pointer shared with ipsec_decap_hook (arg). The hook function should perform decapsulation if necessary, back into pkt and return the proper status so that the IP packet can be processed appropriately. See the Expected Return Values section below. For acceptable encapsulated IP packets (a return value of FIREWALL_OK), the decapsulated packet is processed again by jumping to the beginning of the IP input processing loop. Consequently, the decapsulated IP packet will be examined first by ip_fltr_in_hook and, if addressed to the host, by ipsec_decap_hook. For acceptable non-encapsulated IP packets (a return value of FIREWALL_OK_NOTSEC), IP packet delivery simply continues and pkt is processed by the transport layer. A return value of FIREWALL_NOTOK indicates that pkt should be dropped.

The ip_fltr_out_hook function is called for every IP packet to be transmitted, provided the outgoing IP packet's destination IP address is NOT an IP multicast address. If it is, it is sent immediately, bypassing the ip_fltr_out_hook function. This hook function is invoked after inserting the IP options from the upper protocol layers, constructing the complete IP header, and locating a route to the destination IP address. The ip_fltr_out_hook function may modify the outgoing IP packet (pkt), but the interface and route have already been assigned and may not be changed. The return value from the ip_fltr_out_hook function indicates whether pkt should be transmitted or dropped. See the Expected Return Values section below. If pkt is not dropped (FIREWALL_OK), it's source address is verified to be local and, if pkt is to be broadcast, the ability to broadcast is confirmed. Thereafter, pkt is enqueued on the interfaces (ifp) output queue. If pkt is dropped (FIREWALL_NOTOK), it is not transmitted and EACCES is returned to the process.

The inbound_fw and outbound_fw firewall hooks allow kernel extensions to get control of packets at the place where IP receives them. If inbound_fw is set, ipintr_noqueue, the IP input routine, calls inbound_fw and then exits. If not, ipintr_noqueue calls ipintr_noqueue_post_fw and then exits. If the inbound_fw hook routine wishes to pass the packet into IP, it can call ipintr_noqueue_post_fw. inbound_fw may copy its args parameter by calling inbound_fw_save_args, and may free its copy of its args parameter by calling inbound_fw_free_args.

Similarly, ip_output calls outbound_fw if it is set, and calls ip_output_post_fw if not. The outbound_fw hook can call ip_output_post_fw if it wants to send a packet. outbound_fw may copy its args parameter by calling outbound_fw_save_args, and later free its copy of its args parameter by calling outbound_fw_free_args.

Flags

Item Description
IP_FORWARDING Indicates that most of the IP headers exist.
IP_RAWOUTPUT Indicates that the raw IP header exists.
IP_MULTICAST_OPTS Indicates that multicast options are present.
IP_ROUTETOIF Contains bypass routing tables.
IP_ALLOWBROADCAST Provides capability to send broadcast packets.
IP_BROADCASTOPTS Contains broadcast options inside.
IP_PMTUOPTS Provides PMTU discovery options.
IP_GROUP_ROUTING Contains group routing gidlist.

Expected Return Values

Item Description
FIREWALL_OK Indicates that pkt is acceptable for any of the filtering functions. It will be delivered, forwarded, or transmitted as appropriate.
FIREWALL_NOTOK Indicates that pkt should be dropped. It will not be received (ip_fltr_in_hook, ipsec_decap_hook) or transmitted (ip_fltr_out_hook).
FIREWALL_OK_NOTSEC Indicates a return value only valid for the ipsec_decap_hook function. This indicates that pkt is acceptable according to the filtering rules, but is not encapsulated; pkt will be processed by the transport layer rather than processed as a decapsulated IP packet.