Technical Reference: Kernel and Subsystems, Volume 1

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

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

Expected Return Values

Related Information

See Network Kernel Services AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.