[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Kernel and Subsystems Technical Reference, Volume 1

ip_fltr_in_hook, ip_fltr_out_hook, ipsec_decap_hook Kernel Service

Purpose

Contains hooks for IP filtering.

Syntax

#define FIREWALL_OK         0  /* Accept IP packet                     */
#define FIREWALL_NOTOR      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)

Parameters

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 interface's (ifp) output queue. If pkt is dropped (FIREWALL_NOTOK), it is not transmitted and EACCES is returned to the process.

Flags

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

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.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

See Network Kernel Services AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts.


[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]