1 | /* |
2 | * Copyright (c) 2003,2008,2017 Apple Computer, 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_interfacefilter.h |
30 | This header defines an API to attach interface filters. Interface |
31 | filters may be attached to a specific interface. The filters can |
32 | intercept all packets in to and out of the specific interface. In |
33 | addition, the filters may intercept interface specific events and |
34 | ioctls. |
35 | */ |
36 | |
37 | #ifndef __KPI_INTERFACEFILTER__ |
38 | #define __KPI_INTERFACEFILTER__ |
39 | #include <sys/kernel_types.h> |
40 | #include <net/kpi_interface.h> |
41 | |
42 | struct kev_msg; |
43 | |
44 | __BEGIN_DECLS |
45 | |
46 | /*! |
47 | @typedef iff_input_func |
48 | |
49 | @discussion iff_input_func is used to filter incoming packets. The |
50 | interface is only valid for the duration of the filter call. If |
51 | you need to keep a reference to the interface, be sure to call |
52 | ifnet_reference and ifnet_release. The packets passed to the |
53 | inbound filter are different from those passed to the outbound |
54 | filter. Packets to the inbound filter have the frame header |
55 | passed in separately from the rest of the packet. The outbound |
56 | data filters is passed the whole packet including the frame |
57 | header. |
58 | |
59 | The frame header usually preceeds the data in the mbuf. This |
60 | ensures that the frame header will be a valid pointer as long as |
61 | the mbuf is not freed. If you need to change the frame header to |
62 | point somewhere else, the recommended method is to prepend a new |
63 | frame header to the mbuf chain (mbuf_prepend), set the header to |
64 | point to that data, then call mbuf_adj to move the mbuf data |
65 | pointer back to the start of the packet payload. |
66 | @param cookie The cookie specified when this filter was attached. |
67 | @param interface The interface the packet was recieved on. |
68 | @param protocol The protocol of this packet. If you specified a |
69 | protocol when attaching your filter, the protocol will only ever |
70 | be the protocol you specified. |
71 | @param data The inbound packet, after the frame header as determined |
72 | by the interface. |
73 | @param frame_ptr A pointer to the pointer to the frame header. The |
74 | frame header length can be found by inspecting the interface's |
75 | frame header length (ifnet_hdrlen). |
76 | @result Return: |
77 | 0 - The caller will continue with normal processing of the |
78 | packet. |
79 | EJUSTRETURN - The caller will stop processing the packet, |
80 | the packet will not be freed. |
81 | Anything Else - The caller will free the packet and stop |
82 | processing. |
83 | */ |
84 | typedef errno_t (*iff_input_func)(void *cookie, ifnet_t interface, |
85 | protocol_family_t protocol, mbuf_t *data, char **frame_ptr); |
86 | |
87 | /*! |
88 | @typedef iff_output_func |
89 | |
90 | @discussion iff_output_func is used to filter fully formed outbound |
91 | packets. The interface is only valid for the duration of the |
92 | filter call. If you need to keep a reference to the interface, |
93 | be sure to call ifnet_reference and ifnet_release. |
94 | @param cookie The cookie specified when this filter was attached. |
95 | @param interface The interface the packet is being transmitted on. |
96 | @param data The fully formed outbound packet in a chain of mbufs. |
97 | The frame header is already included. The filter function may |
98 | modify the packet or return a different mbuf chain. |
99 | @result Return: |
100 | 0 - The caller will continue with normal processing of the |
101 | packet. |
102 | EJUSTRETURN - The caller will stop processing the packet, |
103 | the packet will not be freed. |
104 | Anything Else - The caller will free the packet and stop |
105 | processing. |
106 | */ |
107 | typedef errno_t (*iff_output_func)(void *cookie, ifnet_t interface, |
108 | protocol_family_t protocol, mbuf_t *data); |
109 | |
110 | /*! |
111 | @typedef iff_event_func |
112 | |
113 | @discussion iff_event_func is used to filter interface specific |
114 | events. The interface is only valid for the duration of the |
115 | filter call. If you need to keep a reference to the interface, |
116 | be sure to call ifnet_reference and ifnet_release. |
117 | @param cookie The cookie specified when this filter was attached. |
118 | @param interface The interface the packet is being transmitted on. |
119 | @param event_msg The kernel event, may not be changed. |
120 | */ |
121 | typedef void (*iff_event_func)(void *cookie, ifnet_t interface, |
122 | protocol_family_t protocol, const struct kev_msg *event_msg); |
123 | |
124 | /*! |
125 | @typedef iff_ioctl_func |
126 | |
127 | @discussion iff_ioctl_func is used to filter ioctls sent to an |
128 | interface. The interface is only valid for the duration of the |
129 | filter call. If you need to keep a reference to the interface, |
130 | be sure to call ifnet_reference and ifnet_release. |
131 | |
132 | All undefined ioctls are reserved for future use by Apple. If |
133 | you need to communicate with your kext using an ioctl, please |
134 | use SIOCSIFKPI and SIOCGIFKPI. |
135 | @param cookie The cookie specified when this filter was attached. |
136 | @param interface The interface the packet is being transmitted on. |
137 | @param ioctl_cmd The ioctl command. |
138 | @param ioctl_arg A pointer to the ioctl argument. |
139 | @result Return: |
140 | 0 - This filter function handled the ioctl. |
141 | EOPNOTSUPP - This filter function does not understand/did not |
142 | handle this ioctl. |
143 | EJUSTRETURN - This filter function handled the ioctl, |
144 | processing should stop. |
145 | Anything Else - Processing will stop, the error will be |
146 | returned. |
147 | */ |
148 | typedef errno_t (*iff_ioctl_func)(void *cookie, ifnet_t interface, |
149 | protocol_family_t protocol, unsigned long ioctl_cmd, void *ioctl_arg); |
150 | |
151 | /*! |
152 | @typedef iff_detached_func |
153 | |
154 | @discussion iff_detached_func is called to notify the filter that it |
155 | has been detached from an interface. This is the last call to |
156 | the filter that will be made. A filter may be detached if the |
157 | interface is detached or the detach filter function is called. |
158 | In the case that the interface is being detached, your filter's |
159 | event function will be called with the interface detaching event |
160 | before the your detached function will be called. |
161 | @param cookie The cookie specified when this filter was attached. |
162 | @param interface The interface this filter was detached from. |
163 | */ |
164 | typedef void (*iff_detached_func)(void *cookie, ifnet_t interface); |
165 | |
166 | /*! |
167 | @struct iff_filter |
168 | @discussion This structure is used to define an interface filter for |
169 | use with the iflt_attach function. |
170 | @field iff_cookie A kext defined cookie that will be passed to all |
171 | filter functions. |
172 | @field iff_name A filter name used for debugging purposes. |
173 | @field iff_protocol The protocol of the packets this filter is |
174 | interested in. If you specify zero, packets from all protocols |
175 | will be passed to the filter. |
176 | @field iff_input The filter function to handle inbound packets, may |
177 | be NULL. |
178 | @field iff_output The filter function to handle outbound packets, |
179 | may be NULL. |
180 | @field iff_event The filter function to handle interface events, may |
181 | be null. |
182 | @field iff_ioctl The filter function to handle interface ioctls, may |
183 | be null. |
184 | @field iff_detached The filter function used to notify the filter that |
185 | it has been detached. |
186 | */ |
187 | |
188 | struct iff_filter { |
189 | void *iff_cookie; |
190 | const char *iff_name; |
191 | protocol_family_t iff_protocol; |
192 | iff_input_func iff_input; |
193 | iff_output_func iff_output; |
194 | iff_event_func iff_event; |
195 | iff_ioctl_func iff_ioctl; |
196 | iff_detached_func iff_detached; |
197 | }; |
198 | |
199 | /*! |
200 | @function iflt_attach |
201 | @discussion Attaches an interface filter to an interface. |
202 | @param interface The interface the filter should be attached to. |
203 | @param filter A structure defining the filter. |
204 | @param filter_ref A reference to the filter used to detach. |
205 | @result 0 on success otherwise the errno error. |
206 | */ |
207 | #ifdef KERNEL_PRIVATE |
208 | extern errno_t iflt_attach_internal(ifnet_t interface, const struct iff_filter *filter, |
209 | interface_filter_t *filter_ref); |
210 | |
211 | #define iflt_attach(interface, filter, filter_ref) \ |
212 | iflt_attach_internal((interface), (filter), (filter_ref)) |
213 | #else |
214 | extern errno_t iflt_attach(ifnet_t interface, const struct iff_filter *filter, |
215 | interface_filter_t *filter_ref); |
216 | #endif /* KERNEL_PRIVATE */ |
217 | |
218 | /*! |
219 | @function iflt_detach |
220 | @discussion Detaches an interface filter from an interface. |
221 | @param filter_ref The reference to the filter from iflt_attach. |
222 | */ |
223 | extern void iflt_detach(interface_filter_t filter_ref); |
224 | |
225 | __END_DECLS |
226 | #endif /* __KPI_INTERFACEFILTER__ */ |
227 | |