bsd/sys/kpi_socketfilter.h

7  * as defined in and that are subject to the Apple Public Source License
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
33 	For the most part, socket filters want to do three things: Filter
40 	placed in the receive socket buffer. This is done to avoid waking
42 	appended to the send socket buffer. This should cover inbound and
46 	filter may use to intercept common operations. These functions are:
49 	out could be used together to build a fairly comprehensive firewall
50 	without having to do much with individual packets.
65 		attached to all new sockets when they're created.
72 		wants to attach to all the sockets already present on the
85 	@abstract A 4 byte identifier used with the SO_NKE socket option to
86 		identify the socket filter to be attached.
93 		events related to the socket. These events cannot be prevented
95 	@constant sock_evt_connected Indicates this socket has moved to the
97 	@constant sock_evt_disconnected Indicates this socket has moved to
102 		connection have been shutdown. The param will point to an
110 	@constant sock_evt_bound Indicates this socket has moved to the
119 	sock_evt_shutdown		= 6, /* param points to an integer specifying how (read, write, or both) see man 2 shutdown */
148 	@discussion sf_unregistered_func is called to notify the filter it
151 		function calls in to your filter have completed. Once this
153 	@param handle The socket filter handle used to identify this filter.
160 	@discussion sf_attach_func is called to notify the filter it has
161 		been attached to a socket. The filter may allocate memory for
162 		this attachment and use the cookie to track it. This filter is
167 	@param cookie Used to allow the socket filter to set the cookie for
169 	@param so The socket the filter is being attached to.
171 		attached to this socket.
178 	@discussion sf_detach_func is called to notify the filter it has
184 	@param so The socket the filter is attached to.
186 		attached to this socket.
193 	@discussion sf_notify_func is called to notify the filter of various
197 	@param so The socket the filter is attached to.
207 	@discussion sf_getpeername_func is called to allow a filter to
208 		to intercept the getpeername function. When called, sa will
209 		point to a pointer to a socket address that was malloced
210 		in zone M_SONAME. If you want to replace this address, either
215 	@param so The socket the filter is attached to.
216 	@param sa A pointer to a socket address pointer.
219 		but a result of zero will be returned to the caller of
228 	@discussion sf_getsockname_func is called to allow a filter to
229 		to intercept the getsockname function. When called, sa will
230 		point to a pointer to a socket address that was malloced
231 		in zone M_SONAME. If you want to replace this address, either
236 	@param so The socket the filter is attached to.
237 	@param sa A pointer to a socket address pointer.
240 		but a result of zero will be returned to the caller of
249 	@discussion sf_data_in_func is called to filter incoming data. If your
251 		all incoming data to preserve the order of the data. Use
252 		sock_inject_data_in to later reinject this data if you return
257 	@param so The socket the filter is attached to.
261 		mbuf chain, be sure to check the mbuf types to find control
264 	@param flags Flags to indicate if this is out of band data or a
280 	@discussion sf_data_out_func is called to filter outbound data. If
282 		all outbound data to preserve the order of the data when
283 		reinjecting. Use sock_inject_data_out to later reinject this
287 	@param so The socket the filter is attached to.
291 		mbuf chain, be sure to check the mbuf types to find control
294 	@param flags Flags to indicate if this is out of band data or a
304     const struct sockaddr *to, mbuf_t *data, mbuf_t *control,
310 	@discussion sf_connect_in_func is called to filter inbound connections.
317 	@param so The socket the filter is attached to.
331 	@discussion sf_connect_out_func is called to filter outbound
336 	@param so The socket the filter is attached to.
337 	@param to The remote address of the outbound connection.
345     const struct sockaddr *to);
354 	@param so The socket the filter is attached to.
355 	@param to The local address of the socket will be bound to.
361     const struct sockaddr *to);
370 	@param so The socket the filter is attached to.
371 	@param opt The socket option to set.
387 	@param so The socket the filter is attached to.
388 	@param opt The socket option to get.
404 	@param so The socket the filter is attached to.
419 		you need to communicate with your kext using an ioctl, please
423 	@param so The socket the filter is attached to.
425 	@param argp A pointer to the ioctl parameter.
441 		utilize this callback to intercept the accepted socket
442 		in order to examine it, prior to returning the socket to
443 		the caller of accept.  Such a filter may also choose to
444 		discard the accepted socket if it wishes to do so.
447 	@param so The socket that is about to be accepted.
448 	@param local The local address of the about to be accepted socket.
449 	@param remote The remote address of the about to be accepted socket.
452 		EJUSTRETURN - The to be accepted socket will be disconnected
453 		    prior to being returned to the caller of accept.  No further
456 		    amount of impact, especially to applications which don't
458 		Anything Else - The to be accepted socket will be closed and
459 		    the error will be returned to the caller of accept.
460 		    Note that socket filter developers are advised to exercise
461 		    caution when returning non-zero values to the caller,
470 	@discussion This structure is used to define a socket filter.
471 	@field sf_handle A value used to find socket filters by
472 		applications. An application can use this value to specify that
475 	@field sf_flags Indicate whether this filter should be attached to
483 	@field sf_attach Your function for handling attaches to sockets.
500 		must initialize this to sizeof sflt_filter_ext structure.
531 	 * Initialize sf_ext_len to sizeof sflt_filter_ext structure.
548 	@param domain The protocol domain these filters will be attached to.
549 	@param type The socket type these filters will be attached to.
550 	@param protocol The protocol these filters will be attached to.
559 		socket filter from all sockets it may be attached to at the
561 		to any new sockets.
562 	@param handle The sf_handle of the socket filter to unregister.
569 	@discussion Attaches a socket filter to the specified socket. A
571 	@param socket The socket the filter should be attached to.
572 	@param handle The handle of the registered filter to be attached.
581 	@param handle The handle of the registered filter to be detached.
588  * Inject data in to the receive buffer of the socket as if it
596 	@discussion Inject data in to the receive buffer of the socket as if
598 	@param so The socket to inject the data on.
615 	@discussion Inject data in to the send buffer of the socket as if it
617 	@param so The socket to inject the data on.
618 	@param to The address the data should be sent to, only necessary on
620 		to address after sock_inject_data_out returns.
627 extern errno_t sock_inject_data_out(socket_t so, const struct sockaddr *to,
676 	@discussion Copies the data from the socket option to a buffer.
678 	@param data A pointer to the buffer to copy the data in to.
679 	@param length The number of bytes to copy.
686 	@discussion Copies the data from a buffer to a socket option.
688 	@param data A pointer to the buffer to copy the data out of.
689 	@param length The number of bytes to copy.