Mac Developer Library

Developer

kpi_ipfilter.h Reference

Options
Deployment Target:

On This Page

kpi_ipfilter.h Reference

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.

Included Headers

  • <sys/kernel_types.h>

Functions

  • Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

Callbacks

  • Declaration

    Objective-C

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

    Parameters

    cookie

    The cookie specified when your filter was attached.

    Discussion

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

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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

    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_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.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

Data Types

See the Overview section above for header-level documentation.

  • Declaration

    Objective-C

    typedef struct opaque_ipfilter *ipfilter_t;

    Discussion

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

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    typedef struct opaque_ipfilter *ipfilter_t;

    Discussion

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

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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.

    Availability

    Available in OS X v10.6 and later.

  • Declaration

    Objective-C

    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.