kpi_ipfilter.h Reference

Declared in
kpi_ipfilter.h

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.

Included Headers

  • <sys/kernel_types.h>

Functions

See the Overview section above for header-level documentation.

ipf_addv4

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_ipfilter.h

ipf_addv6

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_ipfilter.h

ipf_inject_input

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_ipfilter.h

ipf_inject_output

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_ipfilter.h

ipf_remove

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_ipfilter.h

Callbacks

See the Overview section above for header-level documentation.

ipf_detach_func

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_ipfilter.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_ipfilter.h

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

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_ipfilter.h

Data Types

See the Overview section above for header-level documentation.

ipf_filter

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_ipfilter.h

ipfilter_t

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_ipfilter.h

ipf_filter

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.
Declared In
kpi_ipfilter.h

opaque_ipfilter

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.