1/*
2 * Copyright (c) 2008-2017 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#define IPPOF_NO_IFF_EXPENSIVE 0x20
61#endif /* PRIVATE */
62
63typedef struct ipf_pktopts *ipf_pktopts_t;
64
65__BEGIN_DECLS
66
67/*!
68 @typedef ipf_input_func
69
70 @discussion ipf_input_func is used to filter incoming ip packets.
71 The IP filter is called for packets from all interfaces. The
72 filter is called between when the general IP processing is
73 handled and when the packet is passed up to the next layer
74 protocol such as udp or tcp. In the case of encapsulation, such
75 as UDP in ESP (IPSec), your filter will be called once for ESP
76 and then again for UDP. This will give your filter an
77 opportunity to process the ESP header as well as the decrypted
78 packet. Offset and protocol are used to determine where in the
79 packet processing is currently occuring. If you're only
80 interested in TCP or UDP packets, just return 0 if protocol
81 doesn't match TCP or UDP.
82 @param cookie The cookie specified when your filter was attached.
83 @param data The reassembled ip packet, data will start at the ip
84 header.
85 @param offset An offset to the next header
86 (udp/tcp/icmp/esp/etc...).
87 @param protocol The protocol type (udp/tcp/icmp/etc...) of the IP packet
88 @result Return:
89 0 - The caller will continue with normal processing of the
90 packet.
91 EJUSTRETURN - The caller will stop processing the packet,
92 the packet will not be freed.
93 Anything Else - The caller will free the packet and stop
94 processing.
95*/
96typedef errno_t (*ipf_input_func)(void *cookie, mbuf_t *data, int offset,
97 u_int8_t protocol);
98
99/*!
100 @typedef ipf_output_func
101
102 @discussion ipf_output_func is used to filter outbound ip packets.
103 The IP filter is called for packets to all interfaces. The
104 filter is called before fragmentation and IPSec processing. If
105 you need to change the destination IP address, call
106 ipf_inject_output and return EJUSTRETURN.
107 @param cookie The cookie specified when your filter was attached.
108 @param data The ip packet, will contain an IP header followed by the
109 rest of the IP packet.
110 @result Return:
111 0 - The caller will continue with normal processing of the
112 packet.
113 EJUSTRETURN - The caller will stop processing the packet,
114 the packet will not be freed.
115 Anything Else - The caller will free the packet and stop
116 processing.
117*/
118typedef errno_t (*ipf_output_func)(void *cookie, mbuf_t *data,
119 ipf_pktopts_t options);
120
121/*!
122 @typedef ipf_detach_func
123
124 @discussion ipf_detach_func is called to notify your filter that it
125 has been detached.
126 @param cookie The cookie specified when your filter was attached.
127*/
128typedef void (*ipf_detach_func)(void *cookie);
129
130/*!
131 @typedef ipf_filter
132 @discussion This structure is used to define an IP filter for
133 use with the ipf_addv4 or ipf_addv6 function.
134 @field cookie A kext defined cookie that will be passed to all
135 filter functions.
136 @field name A filter name used for debugging purposes.
137 @field ipf_input The filter function to handle inbound packets.
138 @field ipf_output The filter function to handle outbound packets.
139 @field ipf_detach The filter function to notify of a detach.
140*/
141struct ipf_filter {
142 void *cookie;
143 const char *name;
144 ipf_input_func ipf_input;
145 ipf_output_func ipf_output;
146 ipf_detach_func ipf_detach;
147};
148
149struct opaque_ipfilter;
150typedef struct opaque_ipfilter *ipfilter_t;
151
152/*!
153 @function ipf_addv4
154 @discussion Attaches an IPv4 ip filter.
155 @param filter A structure defining the filter.
156 @param filter_ref A reference to the filter used to detach it.
157 @result 0 on success otherwise the errno error.
158 */
159#ifdef KERNEL_PRIVATE
160extern errno_t ipf_addv4_internal(const struct ipf_filter *filter,
161 ipfilter_t *filter_ref);
162
163#define ipf_addv4(filter, filter_ref) \
164 ipf_addv4_internal((filter), (filter_ref))
165#else
166extern errno_t ipf_addv4(const struct ipf_filter *filter,
167 ipfilter_t *filter_ref);
168#endif /* KERNEL_PRIVATE */
169
170/*!
171 @function ipf_addv6
172 @discussion Attaches an IPv6 ip filter.
173 @param filter A structure defining the filter.
174 @param filter_ref A reference to the filter used to detach it.
175 @result 0 on success otherwise the errno error.
176 */
177#ifdef KERNEL_PRIVATE
178extern errno_t ipf_addv6_internal(const struct ipf_filter *filter,
179 ipfilter_t *filter_ref);
180
181#define ipf_addv6(filter, filter_ref) \
182 ipf_addv6_internal((filter), (filter_ref))
183#else
184extern errno_t ipf_addv6(const struct ipf_filter *filter,
185 ipfilter_t *filter_ref);
186#endif /* KERNEL_PRIVATE */
187
188/*!
189 @function ipf_remove
190 @discussion Detaches an IPv4 or IPv6 filter.
191 @param filter_ref The reference to the filter returned from ipf_addv4 or
192 ipf_addv6.
193 @result 0 on success otherwise the errno error.
194 */
195extern errno_t ipf_remove(ipfilter_t filter_ref);
196
197/*!
198 @function ipf_inject_input
199 @discussion Inject an IP packet as though it had just been
200 reassembled in ip_input. When re-injecting a packet intercepted
201 by the filter's ipf_input function, an IP filter can pass its
202 reference to avoid processing the packet twice. This also
203 prevents ip filters installed before this filter from
204 getting a chance to process the packet. If the filter modified
205 the packet, it should not specify the filter ref to give other
206 filters a chance to process the new packet.
207
208 Caller is responsible for freeing mbuf chain in the event that
209 ipf_inject_input returns an error.
210 @param data The complete IPv4 or IPv6 packet, receive interface must
211 be set.
212 @param filter_ref The reference to the filter injecting the data
213 @result 0 on success otherwise the errno error.
214 */
215extern errno_t ipf_inject_input(mbuf_t data, ipfilter_t filter_ref);
216
217/*!
218 @function ipf_inject_output
219 @discussion Inject an IP packet as though it had just been sent to
220 ip_output. When re-injecting a packet intercepted by the
221 filter's ipf_output function, an IP filter can pass its
222 reference to avoid processing the packet twice. This also
223 prevents ip filters installed before this filter from getting a
224 chance to process the packet. If the filter modified the packet,
225 it should not specify the filter ref to give other filters a
226 chance to process the new packet.
227 @param data The complete IPv4 or IPv6 packet.
228 @param filter_ref The reference to the filter injecting the data
229 @param options Output options for the packet
230 @result 0 on success otherwise the errno error. ipf_inject_output
231 will always free the mbuf.
232 */
233extern errno_t ipf_inject_output(mbuf_t data, ipfilter_t filter_ref,
234 ipf_pktopts_t options);
235
236__END_DECLS
237#endif /* __KPI_IPFILTER__ */
238