ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

kpi_ipfilter.h

Includes:

Overview

This header defines an API to attach IP filters. IP filters may be attached to intercept either IPv4 or IPv6 packets. The filters can intercept all IP packets in to and out of the host regardless of interface.

Functions

ipf_addv4
ipf_addv6
ipf_inject_input
ipf_inject_output
ipf_remove

ipf_addv4

errno_t ipf_addv4(
    const struct ipf_filter* filter,
    ipfilter_t *filter_ref);

Parameters

filter: A structure defining the filter.
filter_ref: A reference to the filter used to detach it.

Return Value

0 on success otherwise the errno error.

Discussion

Attaches an IPv4 ip filter.

ipf_addv6

errno_t ipf_addv6(
    const struct ipf_filter* filter,
    ipfilter_t *filter_ref);

Parameters

filter: A structure defining the filter.
filter_ref: A reference to the filter used to detach it.

Return Value

0 on success otherwise the errno error.

Discussion

Attaches an IPv6 ip filter.

ipf_inject_input

errno_t ipf_inject_input(
    mbuf_t data,
    ipfilter_t filter_ref);

Parameters

data: The complete IPv4 or IPv6 packet, receive interface must be set.
filter_ref: The reference to the filter injecting the data

Return Value

0 on success otherwise the errno error.

Discussion

Inject an IP packet as though it had just been reassembled in ip_input. When re-injecting a packet intercepted by the filter's ipf_input function, an IP filter can pass its reference to avoid processing the packet twice. This also prevents ip filters installed before this filter from getting a chance to process the packet. If the filter modified the packet, it should not specify the filter ref to give other filters a chance to process the new packet.

Caller is responsible for freeing mbuf chain in the event that ipf_inject_input returns an error.

ipf_inject_output

errno_t ipf_inject_output(
    mbuf_t data,
    ipfilter_t filter_ref,
    ipf_pktopts_t options);

Parameters

data: The complete IPv4 or IPv6 packet.
filter_ref: The reference to the filter injecting the data
options: Output options for the packet

Return Value

0 on success otherwise the errno error. ipf_inject_output will always free the mbuf.

Discussion

Inject an IP packet as though it had just been sent to ip_output. When re-injecting a packet intercepted by the filter's ipf_output function, an IP filter can pass its reference to avoid processing the packet twice. This also prevents ip filters installed before this filter from getting a chance to process the packet. If the filter modified the packet, it should not specify the filter ref to give other filters a chance to process the new packet.

ipf_remove

errno_t ipf_remove(
    ipfilter_t filter_ref);

Parameters

filter_ref: The reference to the filter returned from ipf_addv4 or ipf_addv6.

Return Value

0 on success otherwise the errno error.

Discussion

Detaches an IPv4 or IPv6 filter.

Typedefs

ipf_detach_func

typedef void ( *ipf_detach_func)(
    void *cookie);

Fields

cookie: The cookie specified when your filter was attached.

Discussion

ipf_detach_func is called to notify your filter that it has been detached.

ipf_filter

See Also:

ipf_filter

opaque_ipfilter

ipfilter_t

typedef struct opaque_ipfilter* ipfilter_t;

Fields

cookie: A kext defined cookie that will be passed to all filter functions.
name: A filter name used for debugging purposes.
ipf_input: The filter function to handle inbound packets.
ipf_output: The filter function to handle outbound packets.
ipf_detach: The filter function to notify of a detach.

Discussion

This structure is used to define an IP filter for use with the ipf_addv4 or ipf_addv6 function.

ipf_input_func

typedef errno_t ( *ipf_input_func)(
    void *cookie,
    mbuf_t *data,
    int offset,
    u_int8_t protocol);

Parameters

cookie: The cookie specified when your filter was attached.
data: The reassembled ip packet, data will start at the ip header.
offset: An offset to the next header (udp/tcp/icmp/esp/etc...).
protocol: The protocol type (udp/tcp/icmp/etc...) of the IP packet

Return Value

Return: 0 - The caller will continue with normal processing of the packet. EJUSTRETURN - The caller will stop processing the packet, the packet will not be freed. Anything Else - The caller will free the packet and stop processing.

Discussion

ipf_input_func is used to filter incoming ip packets. The IP filter is called for packets from all interfaces. The filter is called between when the general IP processing is handled and when the packet is passed up to the next layer protocol such as udp or tcp. In the case of encapsulation, such as UDP in ESP (IPSec), your filter will be called once for ESP and then again for UDP. This will give your filter an opportunity to process the ESP header as well as the decrypted packet. Offset and protocol are used to determine where in the packet processing is currently occuring. If you're only interested in TCP or UDP packets, just return 0 if protocol doesn't match TCP or UDP.

ipf_output_func

typedef errno_t ( *ipf_output_func)(
    void *cookie,
    mbuf_t *data,
    ipf_pktopts_t options);

Parameters

cookie: The cookie specified when your filter was attached.
data: The ip packet, will contain an IP header followed by the rest of the IP packet.

Return Value

Discussion

ipf_output_func is used to filter outbound ip packets. The IP filter is called for packets to all interfaces. The filter is called before fragmentation and IPSec processing. If you need to change the destination IP address, call ipf_inject_output and return EJUSTRETURN.

ipfilter_t

See Also:

ipf_filter

opaque_ipfilter

ipf_filter

typedef struct opaque_ipfilter* ipfilter_t;

Fields

cookie: A kext defined cookie that will be passed to all filter functions.
name: A filter name used for debugging purposes.
ipf_input: The filter function to handle inbound packets.
ipf_output: The filter function to handle outbound packets.
ipf_detach: The filter function to notify of a detach.

Discussion

This structure is used to define an IP filter for use with the ipf_addv4 or ipf_addv6 function.

Structs and Unions

ipf_filter

See Also:

opaque_ipfilter

ipf_filter

ipfilter_t

struct ipf_filter { 
    void *cookie; 
    const char* name; 
    ipf_input_func ipf_input; 
    ipf_output_func ipf_output; 
    ipf_detach_func ipf_detach; 
};

Fields

cookie: A kext defined cookie that will be passed to all filter functions.
name: A filter name used for debugging purposes.
ipf_input: The filter function to handle inbound packets.
ipf_output: The filter function to handle outbound packets.
ipf_detach: The filter function to notify of a detach.

Discussion

This structure is used to define an IP filter for use with the ipf_addv4 or ipf_addv6 function.

opaque_ipfilter

See Also:

ipf_filter

ipf_filter

ipfilter_t

struct opaque_ipfilter;

Fields

cookie: A kext defined cookie that will be passed to all filter functions.
name: A filter name used for debugging purposes.
ipf_input: The filter function to handle inbound packets.
ipf_output: The filter function to handle outbound packets.
ipf_detach: The filter function to notify of a detach.

Discussion

This structure is used to define an IP filter for use with the ipf_addv4 or ipf_addv6 function.

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-12-19