bsd/net/kpi_interfacefilter.h

   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__ */