[apple/xnu.git] / bsd / netinet / kpi_ipfilter.h

/*
 * Copyright (c) 2008-2017 Apple Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 *
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */
/*!
 *       @header kpi_ipfilter.h
 *       This header defines an API to attach IP filters. IP filters may be
 *       attached to intercept either IPv4 or IPv6 packets. The filters can
 *       intercept all IP packets in to and out of the host regardless of
 *       interface.
 */

#ifndef __KPI_IPFILTER__
#define __KPI_IPFILTER__

#ifndef PRIVATE
#include <Availability.h>
#define __NKE_API_DEPRECATED __API_DEPRECATED("Network Kernel Extension KPI is deprecated", macos(10.4, 10.15))
#else
#define __NKE_API_DEPRECATED
#endif /* PRIVATE */

/*
 * ipf_pktopts
 *
 * Options for outgoing packets. The options need to be preserved when
 * re-injecting a packet.
 */
struct ipf_pktopts {
	u_int32_t                       ippo_flags;
	ifnet_t                         ippo_mcast_ifnet;
	int                             ippo_mcast_loop;
	u_int8_t                        ippo_mcast_ttl;
};
#define IPPOF_MCAST_OPTS            0x1
#ifdef PRIVATE
#define IPPOF_BOUND_IF              0x2
#define IPPOF_NO_IFT_CELLULAR       0x4
#define IPPOF_SELECT_SRCIF          0x8
#define IPPOF_BOUND_SRCADDR         0x10
#define IPPOF_SHIFT_IFSCOPE         16
#define IPPOF_NO_IFF_EXPENSIVE      0x20
#define IPPOF_NO_IFF_CONSTRAINED    0x40
#endif /* PRIVATE */

typedef struct ipf_pktopts *ipf_pktopts_t;

__BEGIN_DECLS

/*!
 *       @typedef ipf_input_func
 *
 *       @discussion ipf_input_func is used to filter incoming ip packets.
 *               The IP filter is called for packets from all interfaces. The
 *               filter is called between when the general IP processing is
 *               handled and when the packet is passed up to the next layer
 *               protocol such as udp or tcp. In the case of encapsulation, such
 *               as UDP in ESP (IPsec), your filter will be called once for ESP
 *               and then again for UDP. This will give your filter an
 *               opportunity to process the ESP header as well as the decrypted
 *               packet. Offset and protocol are used to determine where in the
 *               packet processing is currently occuring. If you're only
 *               interested in TCP or UDP packets, just return 0 if protocol
 *               doesn't match TCP or UDP.
 *       @param cookie The cookie specified when your filter was attached.
 *       @param data The reassembled ip packet, data will start at the ip
 *               header.
 *       @param offset An offset to the next header
 *               (udp/tcp/icmp/esp/etc...).
 *       @param protocol The protocol type (udp/tcp/icmp/etc...) of the IP packet
 *       @result Return:
 *               0 - The caller will continue with normal processing of the
 *                       packet.
 *               EJUSTRETURN - The caller will stop processing the packet,
 *                       the packet will not be freed.
 *               Anything Else - The caller will free the packet and stop
 *                       processing.
 */
typedef errno_t (*ipf_input_func)(void *cookie, mbuf_t *data, int offset,
    u_int8_t protocol);

/*!
 *       @typedef ipf_output_func
 *
 *       @discussion ipf_output_func is used to filter outbound ip packets.
 *               The IP filter is called for packets to all interfaces. The
 *               filter is called before fragmentation and IPsec processing. If
 *               you need to change the destination IP address, call
 *               ipf_inject_output and return EJUSTRETURN.
 *       @param cookie The cookie specified when your filter was attached.
 *       @param data The ip packet, will contain an IP header followed by the
 *               rest of the IP packet.
 *       @result Return:
 *               0 - The caller will continue with normal processing of the
 *                       packet.
 *               EJUSTRETURN - The caller will stop processing the packet,
 *                       the packet will not be freed.
 *               Anything Else - The caller will free the packet and stop
 *                       processing.
 */
typedef errno_t (*ipf_output_func)(void *cookie, mbuf_t *data,
    ipf_pktopts_t options);

/*!
 *       @typedef ipf_detach_func
 *
 *       @discussion ipf_detach_func is called to notify your filter that it
 *               has been detached.
 *       @param cookie The cookie specified when your filter was attached.
 */
typedef void (*ipf_detach_func)(void *cookie);

/*!
 *       @typedef ipf_filter
 *       @discussion This structure is used to define an IP filter for
 *               use with the ipf_addv4 or ipf_addv6 function.
 *       @field cookie A kext defined cookie that will be passed to all
 *               filter functions.
 *       @field name A filter name used for debugging purposes.
 *       @field ipf_input The filter function to handle inbound packets.
 *       @field ipf_output The filter function to handle outbound packets.
 *       @field ipf_detach The filter function to notify of a detach.
 */
struct ipf_filter {
	void            *cookie;
	const char      *name;
	ipf_input_func  ipf_input;
	ipf_output_func ipf_output;
	ipf_detach_func ipf_detach;
};

struct opaque_ipfilter;
typedef struct opaque_ipfilter *ipfilter_t;

/*!
 *       @function ipf_addv4
 *       @discussion Attaches an IPv4 ip filter.
 *       @param filter A structure defining the filter.
 *       @param filter_ref A reference to the filter used to detach it.
 *       @result 0 on success otherwise the errno error.
 */
#ifdef KERNEL_PRIVATE
extern errno_t ipf_addv4_internal(const struct ipf_filter *filter,
    ipfilter_t *filter_ref);

#define ipf_addv4(filter, filter_ref) \
    ipf_addv4_internal((filter), (filter_ref))
#else
extern errno_t ipf_addv4(const struct ipf_filter *filter,
    ipfilter_t *filter_ref)
__NKE_API_DEPRECATED;
#endif /* KERNEL_PRIVATE */

/*!
 *       @function ipf_addv6
 *       @discussion Attaches an IPv6 ip filter.
 *       @param filter A structure defining the filter.
 *       @param filter_ref A reference to the filter used to detach it.
 *       @result 0 on success otherwise the errno error.
 */
#ifdef KERNEL_PRIVATE
extern errno_t ipf_addv6_internal(const struct ipf_filter *filter,
    ipfilter_t *filter_ref);

#define ipf_addv6(filter, filter_ref) \
    ipf_addv6_internal((filter), (filter_ref))
#else
extern errno_t ipf_addv6(const struct ipf_filter *filter,
    ipfilter_t *filter_ref)
__NKE_API_DEPRECATED;
#endif /* KERNEL_PRIVATE */

/*!
 *       @function ipf_remove
 *       @discussion Detaches an IPv4 or IPv6 filter.
 *       @param filter_ref The reference to the filter returned from ipf_addv4 or
 *               ipf_addv6.
 *       @result 0 on success otherwise the errno error.
 */
extern errno_t ipf_remove(ipfilter_t filter_ref)
__NKE_API_DEPRECATED;

/*!
 *       @function ipf_inject_input
 *       @discussion Inject an IP packet as though it had just been
 *               reassembled in ip_input. When re-injecting a packet intercepted
 *               by the filter's ipf_input function, an IP filter can pass its
 *               reference to avoid processing the packet twice. This also
 *               prevents ip filters installed before this filter from
 *               getting a chance to process the packet. If the filter modified
 *               the packet, it should not specify the filter ref to give other
 *               filters a chance to process the new packet.
 *
 *               Caller is responsible for freeing mbuf chain in the event that
 *               ipf_inject_input returns an error.
 *       @param data The complete IPv4 or IPv6 packet, receive interface must
 *               be set.
 *       @param filter_ref The reference to the filter injecting the data
 *       @result 0 on success otherwise the errno error.
 */
extern errno_t ipf_inject_input(mbuf_t data, ipfilter_t filter_ref)
__NKE_API_DEPRECATED;

/*!
 *       @function ipf_inject_output
 *       @discussion Inject an IP packet as though it had just been sent to
 *               ip_output. When re-injecting a packet intercepted by the
 *               filter's ipf_output function, an IP filter can pass its
 *               reference to avoid processing the packet twice. This also
 *               prevents ip filters installed before this filter from getting a
 *               chance to process the packet. If the filter modified the packet,
 *               it should not specify the filter ref to give other filters a
 *               chance to process the new packet.
 *       @param data The complete IPv4 or IPv6 packet.
 *       @param filter_ref The reference to the filter injecting the data
 *       @param options Output options for the packet
 *       @result 0 on success otherwise the errno error. ipf_inject_output
 *               will always free the mbuf.
 */
extern errno_t ipf_inject_output(mbuf_t data, ipfilter_t filter_ref,
    ipf_pktopts_t options)
__NKE_API_DEPRECATED;

__END_DECLS
#endif /* __KPI_IPFILTER__ */
Commit	Line	Data
91447636	1	/*
5ba3f43e	2	* Copyright (c) 2008-2017 Apple Inc. All rights reserved.
91447636	3	*
2d21ac55	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
0a7de745	5	*
2d21ac55 A	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.
0a7de745	14	*
2d21ac55 A	15	* Please obtain a copy of the License at
2d21ac55 A	16	* http://www.opensource.apple.com/apsl/ and read it before using this file.
0a7de745	17	*
2d21ac55 A	18	* The Original Code and all software distributed under the License are
2d21ac55 A	19	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
8f6c56a5 A	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
8f6c56a5 A	21	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
2d21ac55 A	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.
0a7de745	25	*
2d21ac55	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
91447636 A	27	*/
91447636 A	28	/*!
0a7de745 A	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.
91447636 A	34	*/
	35
	36	#ifndef __KPI_IPFILTER__
	37	#define __KPI_IPFILTER__
	38
cb323159 A	39	#ifndef PRIVATE
	40	#include <Availability.h>
	41	#define __NKE_API_DEPRECATED __API_DEPRECATED("Network Kernel Extension KPI is deprecated", macos(10.4, 10.15))
	42	#else
	43	#define __NKE_API_DEPRECATED
	44	#endif /* PRIVATE */
91447636 A	45
	46	/*
	47	* ipf_pktopts
	48	*
0a7de745	49	* Options for outgoing packets. The options need to be preserved when
91447636 A	50	* re-injecting a packet.
	51	*/
	52	struct ipf_pktopts {
0a7de745 A	53	u_int32_t ippo_flags;
	54	ifnet_t ippo_mcast_ifnet;
	55	int ippo_mcast_loop;
	56	u_int8_t ippo_mcast_ttl;
91447636	57	};
cb323159	58	#define IPPOF_MCAST_OPTS 0x1
6d2010ae	59	#ifdef PRIVATE
cb323159 A	60	#define IPPOF_BOUND_IF 0x2
	61	#define IPPOF_NO_IFT_CELLULAR 0x4
	62	#define IPPOF_SELECT_SRCIF 0x8
	63	#define IPPOF_BOUND_SRCADDR 0x10
	64	#define IPPOF_SHIFT_IFSCOPE 16
	65	#define IPPOF_NO_IFF_EXPENSIVE 0x20
	66	#define IPPOF_NO_IFF_CONSTRAINED 0x40
6d2010ae	67	#endif /* PRIVATE */
91447636	68
b0d623f7	69	typedef struct ipf_pktopts *ipf_pktopts_t;
91447636	70
2d21ac55 A	71	__BEGIN_DECLS
2d21ac55 A	72
91447636	73	/*!
0a7de745 A	74	* @typedef ipf_input_func
	75	*
	76	* @discussion ipf_input_func is used to filter incoming ip packets.
	77	* The IP filter is called for packets from all interfaces. The
	78	* filter is called between when the general IP processing is
	79	* handled and when the packet is passed up to the next layer
	80	* protocol such as udp or tcp. In the case of encapsulation, such
cb323159	81	* as UDP in ESP (IPsec), your filter will be called once for ESP
0a7de745 A	82	* and then again for UDP. This will give your filter an
	83	* opportunity to process the ESP header as well as the decrypted
	84	* packet. Offset and protocol are used to determine where in the
	85	* packet processing is currently occuring. If you're only
	86	* interested in TCP or UDP packets, just return 0 if protocol
	87	* doesn't match TCP or UDP.
	88	* @param cookie The cookie specified when your filter was attached.
	89	* @param data The reassembled ip packet, data will start at the ip
	90	* header.
	91	* @param offset An offset to the next header
	92	* (udp/tcp/icmp/esp/etc...).
	93	* @param protocol The protocol type (udp/tcp/icmp/etc...) of the IP packet
	94	* @result Return:
	95	* 0 - The caller will continue with normal processing of the
	96	* packet.
	97	* EJUSTRETURN - The caller will stop processing the packet,
	98	* the packet will not be freed.
	99	* Anything Else - The caller will free the packet and stop
	100	* processing.
	101	*/
	102	typedef errno_t (ipf_input_func)(void cookie, mbuf_t *data, int offset,
b0d623f7	103	u_int8_t protocol);
91447636 A	104
91447636 A	105	/*!
0a7de745 A	106	* @typedef ipf_output_func
	107	*
	108	* @discussion ipf_output_func is used to filter outbound ip packets.
	109	* The IP filter is called for packets to all interfaces. The
cb323159	110	* filter is called before fragmentation and IPsec processing. If
0a7de745 A	111	* you need to change the destination IP address, call
	112	* ipf_inject_output and return EJUSTRETURN.
	113	* @param cookie The cookie specified when your filter was attached.
	114	* @param data The ip packet, will contain an IP header followed by the
	115	* rest of the IP packet.
	116	* @result Return:
	117	* 0 - The caller will continue with normal processing of the
	118	* packet.
	119	* EJUSTRETURN - The caller will stop processing the packet,
	120	* the packet will not be freed.
	121	* Anything Else - The caller will free the packet and stop
	122	* processing.
	123	*/
	124	typedef errno_t (ipf_output_func)(void cookie, mbuf_t *data,
b0d623f7	125	ipf_pktopts_t options);
91447636 A	126
91447636 A	127	/*!
0a7de745 A	128	* @typedef ipf_detach_func
	129	*
	130	* @discussion ipf_detach_func is called to notify your filter that it
	131	* has been detached.
	132	* @param cookie The cookie specified when your filter was attached.
	133	*/
	134	typedef void (ipf_detach_func)(void cookie);
91447636 A	135
91447636 A	136	/*!
0a7de745 A	137	* @typedef ipf_filter
	138	* @discussion This structure is used to define an IP filter for
	139	* use with the ipf_addv4 or ipf_addv6 function.
	140	* @field cookie A kext defined cookie that will be passed to all
	141	* filter functions.
	142	* @field name A filter name used for debugging purposes.
	143	* @field ipf_input The filter function to handle inbound packets.
	144	* @field ipf_output The filter function to handle outbound packets.
	145	* @field ipf_detach The filter function to notify of a detach.
	146	*/
91447636	147	struct ipf_filter {
0a7de745 A	148	void *cookie;
	149	const char *name;
	150	ipf_input_func ipf_input;
	151	ipf_output_func ipf_output;
	152	ipf_detach_func ipf_detach;
91447636 A	153	};
	154
	155	struct opaque_ipfilter;
0a7de745	156	typedef struct opaque_ipfilter *ipfilter_t;
91447636 A	157
91447636 A	158	/*!
0a7de745 A	159	* @function ipf_addv4
	160	* @discussion Attaches an IPv4 ip filter.
	161	* @param filter A structure defining the filter.
	162	* @param filter_ref A reference to the filter used to detach it.
	163	* @result 0 on success otherwise the errno error.
91447636	164	*/
5ba3f43e A	165	#ifdef KERNEL_PRIVATE
	166	extern errno_t ipf_addv4_internal(const struct ipf_filter *filter,
	167	ipfilter_t *filter_ref);
	168
	169	#define ipf_addv4(filter, filter_ref) \
	170	ipf_addv4_internal((filter), (filter_ref))
	171	#else
b0d623f7	172	extern errno_t ipf_addv4(const struct ipf_filter *filter,
cb323159 A	173	ipfilter_t *filter_ref)
cb323159 A	174	__NKE_API_DEPRECATED;
5ba3f43e	175	#endif /* KERNEL_PRIVATE */
91447636 A	176
91447636 A	177	/*!
0a7de745 A	178	* @function ipf_addv6
	179	* @discussion Attaches an IPv6 ip filter.
	180	* @param filter A structure defining the filter.
	181	* @param filter_ref A reference to the filter used to detach it.
	182	* @result 0 on success otherwise the errno error.
91447636	183	*/
5ba3f43e A	184	#ifdef KERNEL_PRIVATE
	185	extern errno_t ipf_addv6_internal(const struct ipf_filter *filter,
	186	ipfilter_t *filter_ref);
	187
	188	#define ipf_addv6(filter, filter_ref) \
	189	ipf_addv6_internal((filter), (filter_ref))
	190	#else
b0d623f7	191	extern errno_t ipf_addv6(const struct ipf_filter *filter,
cb323159 A	192	ipfilter_t *filter_ref)
cb323159 A	193	__NKE_API_DEPRECATED;
5ba3f43e	194	#endif /* KERNEL_PRIVATE */
91447636 A	195
91447636 A	196	/*!
0a7de745 A	197	* @function ipf_remove
	198	* @discussion Detaches an IPv4 or IPv6 filter.
	199	* @param filter_ref The reference to the filter returned from ipf_addv4 or
	200	* ipf_addv6.
	201	* @result 0 on success otherwise the errno error.
91447636	202	*/
cb323159 A	203	extern errno_t ipf_remove(ipfilter_t filter_ref)
cb323159 A	204	__NKE_API_DEPRECATED;
91447636 A	205
91447636 A	206	/*!
0a7de745 A	207	* @function ipf_inject_input
	208	* @discussion Inject an IP packet as though it had just been
	209	* reassembled in ip_input. When re-injecting a packet intercepted
	210	* by the filter's ipf_input function, an IP filter can pass its
	211	* reference to avoid processing the packet twice. This also
	212	* prevents ip filters installed before this filter from
	213	* getting a chance to process the packet. If the filter modified
	214	* the packet, it should not specify the filter ref to give other
	215	* filters a chance to process the new packet.
	216	*
	217	* Caller is responsible for freeing mbuf chain in the event that
	218	* ipf_inject_input returns an error.
	219	* @param data The complete IPv4 or IPv6 packet, receive interface must
	220	* be set.
	221	* @param filter_ref The reference to the filter injecting the data
	222	* @result 0 on success otherwise the errno error.
91447636	223	*/
cb323159 A	224	extern errno_t ipf_inject_input(mbuf_t data, ipfilter_t filter_ref)
cb323159 A	225	__NKE_API_DEPRECATED;
91447636 A	226
91447636 A	227	/*!
0a7de745 A	228	* @function ipf_inject_output
	229	* @discussion Inject an IP packet as though it had just been sent to
	230	* ip_output. When re-injecting a packet intercepted by the
	231	* filter's ipf_output function, an IP filter can pass its
	232	* reference to avoid processing the packet twice. This also
	233	* prevents ip filters installed before this filter from getting a
	234	* chance to process the packet. If the filter modified the packet,
	235	* it should not specify the filter ref to give other filters a
	236	* chance to process the new packet.
	237	* @param data The complete IPv4 or IPv6 packet.
	238	* @param filter_ref The reference to the filter injecting the data
	239	* @param options Output options for the packet
	240	* @result 0 on success otherwise the errno error. ipf_inject_output
	241	* will always free the mbuf.
91447636	242	*/
b0d623f7	243	extern errno_t ipf_inject_output(mbuf_t data, ipfilter_t filter_ref,
cb323159 A	244	ipf_pktopts_t options)
cb323159 A	245	__NKE_API_DEPRECATED;
91447636	246
2d21ac55	247	__END_DECLS
91447636	248	#endif /* __KPI_IPFILTER__ */