bsd/netinet/kpi_ipfilter.h

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