bsd/netinet/kpi_ipfilter.h

   1 /*
   2  * Copyright (c) 2003-2004 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22 /*!
  23         @header kpi_ipfilter.h
  24         This header defines an API to attach IP filters. IP filters may be
  25         attached to intercept either IPv4 or IPv6 packets. The filters can
  26         intercept all IP packets in to and out of the host regardless of
  27         interface.
  28  */
  29
  30 #ifndef __KPI_IPFILTER__
  31 #define __KPI_IPFILTER__
  32
  33 #include <sys/kernel_types.h>
  34
  35 /*
  36  * ipf_pktopts
  37  *
  38  * Options for outgoing packets. The options need to be preserved when
  39  * re-injecting a packet.
  40  */
  41 struct ipf_pktopts {
  42         u_int32_t                       ippo_flags;
  43         ifnet_t                         ippo_mcast_ifnet;
  44         int                                     ippo_mcast_loop;
  45         u_int8_t                        ippo_mcast_ttl;
  46 };
  47 #define IPPOF_MCAST_OPTS 0x1
  48
  49 typedef struct ipf_pktopts* ipf_pktopts_t;
  50
  51 /*!
  52         @typedef ipf_input_func
  53
  54         @discussion ipf_input_func is used to filter incoming ip packets.
  55                 The IP filter is called for packets from all interfaces. The
  56                 filter is called between when the general IP processing is
  57                 handled and when the packet is passed up to the next layer
  58                 protocol such as udp or tcp. In the case of encapsulation, such
  59                 as UDP in ESP (IPSec), your filter will be called once for ESP
  60                 and then again for UDP. This will give your filter an
  61                 opportunity to process the ESP header as well as the decrypted
  62                 packet. Offset and protocol are used to determine where in the
  63                 packet processing is currently occuring. If you're only
  64                 interested in TCP or UDP packets, just return 0 if protocol
  65                 doesn't match TCP or UDP.
  66         @param cookie The cookie specified when your filter was attached.
  67         @param data The reassembled ip packet, data will start at the ip
  68                 header.
  69         @param offset An offset to the next header
  70                 (udp/tcp/icmp/esp/etc...).
  71         @param protocol The protocol type (udp/tcp/icmp/etc...) of the IP packet
  72         @result Return:
  73                 0 - The caller will continue with normal processing of the packet.
  74                 EJUSTRETURN - The caller will stop processing the packet, the packet will not be freed.
  75                 Anything Else - The caller will free the packet and stop processing.
  76 */
  77 typedef errno_t (*ipf_input_func)(void* cookie, mbuf_t *data, int offset, u_int8_t protocol);
  78
  79 /*!
  80         @typedef ipf_output_func
  81
  82         @discussion ipf_output_func is used to filter outbound ip packets.
  83                 The IP filter is called for packets to all interfaces. The
  84                 filter is called before fragmentation and IPSec processing. If
  85                 you need to change the destination IP address, call
  86                 ipf_inject_output and return EJUSTRETURN.
  87         @param cookie The cookie specified when your filter was attached.
  88         @param data The ip packet, will contain an IP header followed by the
  89                 rest of the IP packet.
  90         @result Return:
  91                 0 - The caller will continue with normal processing of the packet.
  92                 EJUSTRETURN - The caller will stop processing the packet, the packet will not be freed.
  93                 Anything Else - The caller will free the packet and stop processing.
  94 */
  95 typedef errno_t (*ipf_output_func)(void* cookie, mbuf_t *data, ipf_pktopts_t options);
  96
  97 /*!
  98         @typedef ipf_detach_func
  99
 100         @discussion ipf_detach_func is called to notify your filter that it
 101                 has been detached.
 102         @param cookie The cookie specified when your filter was attached.
 103 */
 104 typedef void (*ipf_detach_func)(void* cookie);
 105
 106 /*!
 107         @typedef ipf_filter
 108         @discussion This structure is used to define an IP filter for
 109                 use with the ipf_addv4 or ipf_addv6 function.
 110         @field cookie A kext defined cookie that will be passed to all
 111                 filter functions.
 112         @field name A filter name used for debugging purposes.
 113         @field ipf_input The filter function to handle inbound packets.
 114         @field ipf_output The filter function to handle outbound packets.
 115         @field ipf_detach The filter function to notify of a detach.
 116 */
 117 struct ipf_filter {
 118         void*           cookie;
 119         const char*     name;
 120         ipf_input_func  ipf_input;
 121         ipf_output_func ipf_output;
 122         ipf_detach_func ipf_detach;
 123 };
 124
 125 struct opaque_ipfilter;
 126 typedef struct opaque_ipfilter* ipfilter_t;
 127
 128 /*!
 129         @function ipf_addv4
 130         @discussion Attaches an IPv4 ip filter.
 131         @param filter A structure defining the filter.
 132         @param filter_ref A reference to the filter used to detach it.
 133         @result 0 on success otherwise the errno error.
 134  */
 135 errno_t ipf_addv4(const struct ipf_filter* filter, ipfilter_t *filter_ref);
 136
 137 /*!
 138         @function ipf_addv6
 139         @discussion Attaches an IPv6 ip filter.
 140         @param filter A structure defining the filter.
 141         @param filter_ref A reference to the filter used to detach it.
 142         @result 0 on success otherwise the errno error.
 143  */
 144 errno_t ipf_addv6(const struct ipf_filter* filter, ipfilter_t *filter_ref);
 145
 146 /*!
 147         @function ipf_remove
 148         @discussion Detaches an IPv4 or IPv6 filter.
 149         @param filter_ref The reference to the filter returned from ipf_addv4 or
 150                 ipf_addv6.
 151         @result 0 on success otherwise the errno error.
 152  */
 153 errno_t ipf_remove(ipfilter_t filter_ref);
 154
 155 /*!
 156         @function ipf_inject_input
 157         @discussion Inject an IP packet as though it had just been
 158                 reassembled in ip_input. When re-injecting a packet intercepted
 159                 by the filter's ipf_input function, an IP filter can pass its
 160                 reference to avoid processing the packet twice. This also
 161                 prevents ip filters installed before this filter from
 162                 getting a chance to process the packet. If the filter modified
 163                 the packet, it should not specify the filter ref to give other
 164                 filters a chance to process the new packet.
 165
 166                 Caller is responsible for freeing mbuf chain in the event that
 167                 ipf_inject_input returns an error.
 168         @param data The complete IPv4 or IPv6 packet, receive interface must
 169                 be set.
 170         @param filter_ref The reference to the filter injecting the data
 171         @result 0 on success otherwise the errno error.
 172  */
 173 errno_t ipf_inject_input(mbuf_t data, ipfilter_t filter_ref);
 174
 175 /*!
 176         @function ipf_inject_output
 177         @discussion Inject an IP packet as though it had just been sent to
 178                 ip_output. When re-injecting a packet intercepted by the
 179                 filter's ipf_output function, an IP filter can pass its
 180                 reference to avoid processing the packet twice. This also
 181                 prevents ip filters installed before this filter from getting a
 182                 chance to process the packet. If the filter modified the packet,
 183                 it should not specify the filter ref to give other filters a
 184                 chance to process the new packet.
 185         @param data The complete IPv4 or IPv6 packet.
 186         @param filter_ref The reference to the filter injecting the data
 187         @param options Output options for the packet
 188         @result 0 on success otherwise the errno error. ipf_inject_output
 189                 will always free the mbuf.
 190  */
 191 errno_t ipf_inject_output(mbuf_t data, ipfilter_t filter_ref, ipf_pktopts_t options);
 192
 193 #endif /* __KPI_IPFILTER__ */