[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__

#include <sys/kernel_types.h>

/*
 * 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
#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);
#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);
#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);

/*!
	@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);

/*!
	@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);

__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@
91447636	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.
8f6c56a5	14	*
2d21ac55 A	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
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.
8f6c56a5	25	*
2d21ac55	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
91447636 A	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	*/
	47	struct ipf_pktopts {
	48	u_int32_t ippo_flags;
	49	ifnet_t ippo_mcast_ifnet;
b0d623f7	50	int ippo_mcast_loop;
91447636 A	51	u_int8_t ippo_mcast_ttl;
91447636 A	52	};
6d2010ae A	53	#define IPPOF_MCAST_OPTS 0x1
	54	#ifdef PRIVATE
	55	#define IPPOF_BOUND_IF 0x2
	56	#define IPPOF_NO_IFT_CELLULAR 0x4
316670eb A	57	#define IPPOF_SELECT_SRCIF 0x8
316670eb A	58	#define IPPOF_BOUND_SRCADDR 0x10
6d2010ae	59	#define IPPOF_SHIFT_IFSCOPE 16
fe8ab488	60	#define IPPOF_NO_IFF_EXPENSIVE 0x20
6d2010ae	61	#endif /* PRIVATE */
91447636	62
b0d623f7	63	typedef struct ipf_pktopts *ipf_pktopts_t;
91447636	64
2d21ac55 A	65	__BEGIN_DECLS
2d21ac55 A	66
91447636 A	67	/*!
91447636 A	68	@typedef ipf_input_func
b0d623f7	69
91447636 A	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:
b0d623f7 A	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.
91447636	95	*/
b0d623f7 A	96	typedef errno_t (ipf_input_func)(void cookie, mbuf_t *data, int offset,
b0d623f7 A	97	u_int8_t protocol);
91447636 A	98
	99	/*!
	100	@typedef ipf_output_func
b0d623f7	101
91447636 A	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:
b0d623f7 A	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.
91447636	117	*/
b0d623f7 A	118	typedef errno_t (ipf_output_func)(void cookie, mbuf_t *data,
b0d623f7 A	119	ipf_pktopts_t options);
91447636 A	120
	121	/*!
	122	@typedef ipf_detach_func
b0d623f7	123
91447636 A	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	*/
b0d623f7	128	typedef void (ipf_detach_func)(void cookie);
91447636 A	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	*/
	141	struct ipf_filter {
b0d623f7 A	142	void *cookie;
b0d623f7 A	143	const char *name;
91447636 A	144	ipf_input_func ipf_input;
	145	ipf_output_func ipf_output;
	146	ipf_detach_func ipf_detach;
	147	};
	148
	149	struct opaque_ipfilter;
b0d623f7	150	typedef struct opaque_ipfilter *ipfilter_t;
91447636 A	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	*/
5ba3f43e A	159	#ifdef KERNEL_PRIVATE
	160	extern 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
b0d623f7 A	166	extern errno_t ipf_addv4(const struct ipf_filter *filter,
b0d623f7 A	167	ipfilter_t *filter_ref);
5ba3f43e	168	#endif /* KERNEL_PRIVATE */
91447636 A	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	*/
5ba3f43e A	177	#ifdef KERNEL_PRIVATE
	178	extern 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
b0d623f7 A	184	extern errno_t ipf_addv6(const struct ipf_filter *filter,
b0d623f7 A	185	ipfilter_t *filter_ref);
5ba3f43e	186	#endif /* KERNEL_PRIVATE */
91447636 A	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	*/
b0d623f7	195	extern errno_t ipf_remove(ipfilter_t filter_ref);
91447636 A	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.
b0d623f7	207
91447636 A	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	*/
b0d623f7	215	extern errno_t ipf_inject_input(mbuf_t data, ipfilter_t filter_ref);
91447636 A	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	*/
b0d623f7 A	233	extern errno_t ipf_inject_output(mbuf_t data, ipfilter_t filter_ref,
b0d623f7 A	234	ipf_pktopts_t options);
91447636	235
2d21ac55	236	__END_DECLS
91447636	237	#endif /* __KPI_IPFILTER__ */