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 */ 47struct 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 62typedef 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*/ 95typedef 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*/ 117typedef 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*/ 127typedef 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*/ 140struct 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 148struct opaque_ipfilter; 149typedef 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 */ 158extern 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 */ 168extern 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 */ 178extern 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 */ 198extern 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 */ 216extern 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__ */ 221