#include <sys/kpi_socketfilter.h>
sys/kpi_socketfilter.h
@header kpi_socketfilter.h
This header defines an API for intercepting communications at the
socket layer.
For the most part, socket filters want to do three things: Filter
data in and out, watch for state changes, and intercept a few calls
for security. The number of function pointers supplied by a socket
filter has been significantly reduced. The filter no longer has any
knowledge of socket buffers. The filter no longer intercepts nearly
every internal socket call. There are two data filters, an in
filter, and an out filter. The in filter occurs before data is
placed in the receive socket buffer. This is done to avoid waking
the process unnecessarily. The out filter occurs before the data is
appended to the send socket buffer. This should cover inbound and
outbound data. For monitoring state changes, we've added a notify
function that will be called when various events that the filter can
not intercept occur. In addition, we've added a few functions that a
filter may use to intercept common operations. These functions are:
connect (inbound), connect (outbound), bind, set socket option,
get socket option, and listen. Bind, listen, connect in, and connect
out could be used together to build a fairly comprehensive firewall
without having to do much with individual packets.
enum(anonymous)
@enum sflt_flags
@abstract Constants defining mbuf flags. Only the flags listed below
can be set or retrieved.
@constant SFLT_GLOBAL Indicates this socket filter should be
attached to all new sockets when they're created.
@constant SFLT_PROG Indicates this socket filter should be attached
only when request by the application using the SO_NKE socket
option.
@constant SFLT_EXTENDED Indicates that this socket filter utilizes
the extended fields within the sflt_filter structure.
@constant SFLT_EXTENDED_REGISTRY Indicates that this socket filter
wants to attach to all the sockets already present on the
system. It will also receive notifications for these sockets.
| SFLT_GLOBAL | 1 | |
| SFLT_PROG | 2 | |
| SFLT_EXTENDED | 4 | |
| SFLT_EXTENDED_REGISTRY | 8 |
typedefsflt_flags
typedef u_int32_t sflt_flags
typedefsflt_handle
@typedef sflt_handle
@abstract A 4 byte identifier used with the SO_NKE socket option to
identify the socket filter to be attached.
typedef u_int32_t sflt_handle
enum(anonymous)
@enum sflt_event_t
@abstract Events notify a filter of state changes and other various
events related to the socket. These events cannot be prevented
or intercepted, only observed.
@constant sock_evt_connected Indicates this socket has moved to the
connected state.
@constant sock_evt_disconnected Indicates this socket has moved to
the disconnected state.
@constant sock_evt_flush_read The read socket buffer has been
flushed.
@constant sock_evt_shutdown The read and or write side(s) of the
connection have been shutdown. The param will point to an
integer that indicates the direction that has been shutdown. See
'man 2 shutdown' for more information.
@constant sock_evt_cantrecvmore Indicates the socket cannot receive
more data.
@constant sock_evt_cantsendmore Indicates the socket cannot send
more data.
@constant sock_evt_closing Indicates the socket is closing.
@constant sock_evt_bound Indicates this socket has moved to the
bound state (only for PF_INET/PF_INET6 domain).
| sock_evt_connecting | 1 | |
| sock_evt_connected | 2 | |
| sock_evt_disconnecting | 3 | |
| sock_evt_disconnected | 4 | |
| sock_evt_flush_read | 5 | |
| sock_evt_shutdown | 6 | param points to an integer specifying how (read, write, or both) see man 2 shutdown |
| sock_evt_cantrecvmore | 7 | |
| sock_evt_cantsendmore | 8 | |
| sock_evt_closing | 9 | |
| sock_evt_bound | 10 |
typedefsflt_event_t
typedef u_int32_t sflt_event_t
enum(anonymous)
@enum sflt_data_flag_t
@abstract Inbound and outbound data filters may handle many
different types of incoming and outgoing data. These flags help
distinguish between normal data, out-of-band data, and records.
@constant sock_data_filt_flag_oob Indicates this data is out-of-band
data.
@constant sock_data_filt_flag_record Indicates this data is a
record. This flag is only ever seen on inbound data.
| sock_data_filt_flag_oob | 1 | |
| sock_data_filt_flag_record | 2 |
typedefsflt_data_flag_t
typedef u_int32_t sflt_data_flag_t
typedefsf_unregistered_func
@typedef sf_unregistered_func
@discussion sf_unregistered_func is called to notify the filter it
has been unregistered. This is the last function the stack will
call and this function will only be called once all other
function calls in to your filter have completed. Once this
function has been called, your kext may safely unload.
@param handle The socket filter handle used to identify this filter.
typedef void (*sf_unregistered_func)(sflt_handle handle)
typedefsf_attach_func
@typedef sf_attach_func
@discussion sf_attach_func is called to notify the filter it has
been attached to a socket. The filter may allocate memory for
this attachment and use the cookie to track it. This filter is
called in one of two cases:
1) You've installed a global filter and a new socket was created.
2) Your non-global socket filter is being attached using the SO_NKE
socket option.
@param cookie Used to allow the socket filter to set the cookie for
this attachment.
@param so The socket the filter is being attached to.
@result If you return a non-zero value, your filter will not be
attached to this socket.
typedef errno_t (*sf_attach_func)(void **cookie, socket_t so)
typedefsf_detach_func
@typedef sf_detach_func
@discussion sf_detach_func is called to notify the filter it has
been detached from a socket. If the filter allocated any memory
for this attachment, it should be freed. This function will
be called when the socket is disposed of.
@param cookie Cookie value specified when the filter attach was
called.
@param so The socket the filter is attached to.
@discussion If you return a non-zero value, your filter will not be
attached to this socket.
typedef void (*sf_detach_func)(void *cookie, socket_t so)
typedefsf_notify_func
@typedef sf_notify_func
@discussion sf_notify_func is called to notify the filter of various
state changes and other events occuring on the socket.
@param cookie Cookie value specified when the filter attach was
called.
@param so The socket the filter is attached to.
@param event The type of event that has occurred.
@param param Additional information about the event.
typedef void (*)(void *, socket_t, sflt_event_t, void *) sf_notify_func;
typedefsf_getpeername_func
@typedef sf_getpeername_func
@discussion sf_getpeername_func is called to allow a filter to
to intercept the getpeername function. When called, sa will
point to a pointer to a socket address that was malloced
in zone M_SONAME. If you want to replace this address, either
modify the currenty copy or allocate a new one and free the
old one.
@param cookie Cookie value specified when the filter attach was
called.
@param so The socket the filter is attached to.
@param sa A pointer to a socket address pointer.
@result If you return a non-zero value, processing will stop. If
you return EJUSTRETURN, no further filters will be called
but a result of zero will be returned to the caller of
getpeername.
typedef int (*)(void *, socket_t, struct sockaddr **) sf_getpeername_func;
typedefsf_getsockname_func
@typedef sf_getsockname_func
@discussion sf_getsockname_func is called to allow a filter to
to intercept the getsockname function. When called, sa will
point to a pointer to a socket address that was malloced
in zone M_SONAME. If you want to replace this address, either
modify the currenty copy or allocate a new one and free the
old one.
@param cookie Cookie value specified when the filter attach was
called.
@param so The socket the filter is attached to.
@param sa A pointer to a socket address pointer.
@result If you return a non-zero value, processing will stop. If
you return EJUSTRETURN, no further filters will be called
but a result of zero will be returned to the caller of
getsockname.
typedef int (*)(void *, socket_t, struct sockaddr **) sf_getsockname_func;
typedefsf_data_in_func
@typedef sf_data_in_func
@discussion sf_data_in_func is called to filter incoming data. If your
filter intercepts data for later reinjection, it must queue
all incoming data to preserve the order of the data. Use
sock_inject_data_in to later reinject this data if you return
EJUSTRETURN. Warning: This filter is on the data path. Do not
spend excesive time. Do not wait for data on another socket.
@param cookie Cookie value specified when the filter attach was
called.
@param so The socket the filter is attached to.
@param from The addres the data is from, may be NULL if the socket
is connected.
@param data The data being received. Control data may appear in the
mbuf chain, be sure to check the mbuf types to find control
data.
@param control Control data being passed separately from the data.
@param flags Flags to indicate if this is out of band data or a
record.
@result Return:
0 - The caller will continue with normal processing of the data.
EJUSTRETURN - The caller will stop processing the data, the
data will not be freed.
Anything Else - The caller will free the data and stop
processing.
typedef errno_t (*)(void *, socket_t, const struct sockaddr *, mbuf_t *, mbuf_t *, sflt_data_flag_t) sf_data_in_func;
typedefsf_data_out_func
@typedef sf_data_out_func
@discussion sf_data_out_func is called to filter outbound data. If
your filter intercepts data for later reinjection, it must queue
all outbound data to preserve the order of the data when
reinjecting. Use sock_inject_data_out to later reinject this
data.
@param cookie Cookie value specified when the filter attach was
called.
@param so The socket the filter is attached to.
@param to The address the data is to, may be NULL if the socket
is connected.
@param data The data being received. Control data may appear in the
mbuf chain, be sure to check the mbuf types to find control
data.
@param control Control data being passed separately from the data.
@param flags Flags to indicate if this is out of band data or a
record.
@result Return:
0 - The caller will continue with normal processing of the data.
EJUSTRETURN - The caller will stop processing the data,
the data will not be freed.
Anything Else - The caller will free the data and stop
processing.
typedef errno_t (*)(void *, socket_t, const struct sockaddr *, mbuf_t *, mbuf_t *, sflt_data_flag_t) sf_data_out_func;
typedefsf_connect_in_func
@typedef sf_connect_in_func
@discussion sf_connect_in_func is called to filter inbound connections.
A protocol will call this before accepting an incoming
connection and placing it on the queue of completed connections.
Warning: This filter is on the data path. Do not spend excesive
time. Do not wait for data on another socket.
@param cookie Cookie value specified when the filter attach was
called.
@param so The socket the filter is attached to.
@param from The address the incoming connection is from.
@result Return:
0 - The caller will continue with normal processing of the
connection.
Anything Else - The caller will rejecting the incoming
connection.
typedef errno_t (*)(void *, socket_t, const struct sockaddr *) sf_connect_in_func;
typedefsf_connect_out_func
@typedef sf_connect_out_func
@discussion sf_connect_out_func is called to filter outbound
connections. A protocol will call this before initiating an
outbound connection.
@param cookie Cookie value specified when the filter attach was
called.
@param so The socket the filter is attached to.
@param to The remote address of the outbound connection.
@result Return:
0 - The caller will continue with normal processing of the
connection.
EJUSTRETURN - The caller will return with a value of 0 (no error)
from that point without further processing the connect command. The
protocol layer will not see the call.
Anything Else - The caller will rejecting the outbound
connection.
typedef errno_t (*)(void *, socket_t, const struct sockaddr *) sf_connect_out_func;
typedefsf_bind_func
@typedef sf_bind_func
@discussion sf_bind_func is called before performing a bind
operation on a socket.
@param cookie Cookie value specified when the filter attach was
called.
@param so The socket the filter is attached to.
@param to The local address of the socket will be bound to.
@result Return:
0 - The caller will continue with normal processing of the bind.
EJUSTRETURN - The caller will return with a value of 0 (no error)
from that point without further processing the bind command. The
protocol layer will not see the call.
Anything Else - The caller will rejecting the bind.
typedef errno_t (*)(void *, socket_t, const struct sockaddr *) sf_bind_func;
typedefsf_setoption_func
@typedef sf_setoption_func
@discussion sf_setoption_func is called before performing setsockopt
on a socket.
@param cookie Cookie value specified when the filter attach was
called.
@param so The socket the filter is attached to.
@param opt The socket option to set.
@result Return:
0 - The caller will continue with normal processing of the
setsockopt.
EJUSTRETURN - The caller will return with a value of 0 (no error)
from that point without further propagating the set option
command. The socket and protocol layers will not see the call.
Anything Else - The caller will stop processing and return
this error.
typedef errno_t (*sf_setoption_func)(void *cookie, socket_t so, sockopt_t opt)
typedefsf_getoption_func
@typedef sf_getoption_func
@discussion sf_getoption_func is called before performing getsockopt
on a socket.
@param cookie Cookie value specified when the filter attach was
called.
@param so The socket the filter is attached to.
@param opt The socket option to get.
@result Return:
0 - The caller will continue with normal processing of the
getsockopt.
EJUSTRETURN - The caller will return with a value of 0 (no error)
from that point without further propagating the get option
command. The socket and protocol layers will not see the call.
Anything Else - The caller will stop processing and return
this error.
typedef errno_t (*sf_getoption_func)(void *cookie, socket_t so, sockopt_t opt)
typedefsf_listen_func
@typedef sf_listen_func
@discussion sf_listen_func is called before performing listen
on a socket.
@param cookie Cookie value specified when the filter attach was
called.
@param so The socket the filter is attached to.
@result Return:
0 - The caller will continue with normal processing of listen.
EJUSTRETURN - The caller will return with a value of 0 (no error)
from that point without further processing the listen command. The
protocol will not see the call.
Anything Else - The caller will stop processing and return
this error.
typedef errno_t (*sf_listen_func)(void *cookie, socket_t so)
typedefsf_ioctl_func
@typedef sf_ioctl_func
@discussion sf_ioctl_func is called before performing an ioctl
on a socket.
All undefined ioctls are reserved for future use by Apple. If
you need to communicate with your kext using an ioctl, please
use SIOCSIFKPI and SIOCGIFKPI.
@param cookie Cookie value specified when the filter attach was
called.
@param so The socket the filter is attached to.
@param request The ioctl name.
@param argp A pointer to the ioctl parameter.
@result Return:
0 - The caller will continue with normal processing of
this ioctl.
EJUSTRETURN - The caller will return with a value of 0 (no error)
from that point without further processing or propogating
the ioctl.
Anything Else - The caller will stop processing and return
this error.
typedef errno_t (*)(void *, socket_t, unsigned long, const char *) sf_ioctl_func;
typedefsf_accept_func
@typedef sf_accept_func
@discussion sf_accept_func is called after a socket is dequeued
off the completed (incoming) connection list and before
the file descriptor is associated with it. A filter can
utilize this callback to intercept the accepted socket
in order to examine it, prior to returning the socket to
the caller of accept. Such a filter may also choose to
discard the accepted socket if it wishes to do so.
@param cookie Cookie value specified when the filter attach was called.
@param so_listen The listening socket.
@param so The socket that is about to be accepted.
@param local The local address of the about to be accepted socket.
@param remote The remote address of the about to be accepted socket.
@result Return:
0 - The caller will continue with normal processing of accept.
EJUSTRETURN - The to be accepted socket will be disconnected
prior to being returned to the caller of accept. No further
control or data operations on the socket will be allowed.
This is the recommended return value as it has the least
amount of impact, especially to applications which don't
check the error value returned by accept.
Anything Else - The to be accepted socket will be closed and
the error will be returned to the caller of accept.
Note that socket filter developers are advised to exercise
caution when returning non-zero values to the caller,
since some applications don't check the error value
returned by accept and therefore risk breakage.
typedef errno_t (*)(void *, socket_t, socket_t, const struct sockaddr *, const struct sockaddr *) sf_accept_func;
structsflt_filter
@struct sflt_filter
@discussion This structure is used to define a socket filter.
@field sf_handle A value used to find socket filters by
applications. An application can use this value to specify that
this filter should be attached when using the SO_NKE socket
option.
@field sf_flags Indicate whether this filter should be attached to
all new sockets or just those that request the filter be
attached using the SO_NKE socket option. If this filter
utilizes the socket filter extension fields, it must also
set SFLT_EXTENDED.
@field sf_name A name used for debug purposes.
@field sf_unregistered Your function for being notified when your
filter has been unregistered.
@field sf_attach Your function for handling attaches to sockets.
@field sf_detach Your function for handling detaches from sockets.
@field sf_notify Your function for handling events. May be null.
@field sf_data_in Your function for handling incoming data. May be
null.
@field sf_data_out Your function for handling outgoing data. May be
null.
@field sf_connect_in Your function for handling inbound
connections. May be null.
@field sf_connect_out Your function for handling outbound
connections. May be null.
@field sf_bind Your function for handling binds. May be null.
@field sf_setoption Your function for handling setsockopt. May be null.
@field sf_getoption Your function for handling getsockopt. May be null.
@field sf_listen Your function for handling listen. May be null.
@field sf_ioctl Your function for handling ioctls. May be null.
@field sf_len Length of socket filter extension structure; developers
must initialize this to sizeof sflt_filter_ext structure.
This field and all fields following it will only be valid
if SFLT_EXTENDED flag is set in sf_flags field.
@field sf_ext_accept Your function for handling inbound connections
at accept time. May be null.
@field sf_ext_rsvd Reserved for future use; you must initialize
the reserved fields with zeroes.
| sflt_handle | sf_handle | |
| int | sf_flags | |
| char * | sf_name | |
| sf_unregistered_func | sf_unregistered | |
| sf_attach_func | sf_attach | |
| sf_detach_func | sf_detach | |
| sf_notify_func | sf_notify | |
| sf_getpeername_func | sf_getpeername | |
| sf_getsockname_func | sf_getsockname | |
| sf_data_in_func | sf_data_in | |
| sf_data_out_func | sf_data_out | |
| sf_connect_in_func | sf_connect_in | |
| sf_connect_out_func | sf_connect_out | |
| sf_bind_func | sf_bind | |
| sf_setoption_func | sf_setoption | |
| sf_getoption_func | sf_getoption | |
| sf_listen_func | sf_listen | |
| sf_ioctl_func | sf_ioctl | |
| struct sflt_filter_ext | sf_ext | The following are valid only if SFLT_EXTENDED flag is set. Initialize sf_ext_len to sizeof sflt_filter_ext structure. Filters must also initialize reserved fields with zeroes. |
macrosf_len
#define sf_len sf_ext.sf_ext_len
macrosf_accept
#define sf_accept sf_ext.sf_ext_accept
functionsflt_register
__NKE_API_DEPRECATED extern errno_t sflt_register( const struct sflt_filter *filter, int domain, int type, int protocol )
deprecated
@function sflt_register
@discussion Registers a socket filter. See 'man 2 socket' for a
desciption of domain, type, and protocol.
@param filter A structure describing the filter.
@param domain The protocol domain these filters will be attached to.
Only PF_INET & PF_INET6 domains are supported.
@param type The socket type these filters will be attached to.
@param protocol The protocol these filters will be attached to.
@result 0 on success otherwise the errno error.
functionsflt_unregister
__NKE_API_DEPRECATED extern errno_t sflt_unregister(sflt_handle handle)
deprecated
@function sflt_unregister
@discussion Unregisters a socket filter. This will not detach the
socket filter from all sockets it may be attached to at the
time, it will just prevent the socket filter from being attached
to any new sockets.
@param handle The sf_handle of the socket filter to unregister.
@result 0 on success otherwise the errno error.
functionsflt_attach
__NKE_API_DEPRECATED extern errno_t sflt_attach(socket_t socket, sflt_handle handle)
deprecated
@function sflt_attach
@discussion Attaches a socket filter to the specified socket. A
filter must be registered before it can be attached.
@param socket The socket the filter should be attached to.
@param handle The handle of the registered filter to be attached.
@result 0 on success otherwise the errno error.
functionsflt_detach
__NKE_API_DEPRECATED extern errno_t sflt_detach(socket_t socket, sflt_handle handle)
deprecated
@function sflt_detach
@discussion Detaches a socket filter from a specified socket.
@param socket The socket the filter should be detached from.
@param handle The handle of the registered filter to be detached.
@result 0 on success otherwise the errno error.
functionsock_inject_data_in
__NKE_API_DEPRECATED extern errno_t sock_inject_data_in( socket_t so, const struct sockaddr *from, mbuf_t data, mbuf_t control, sflt_data_flag_t flags )
deprecated
@function sock_inject_data_in
@discussion Inject data in to the receive buffer of the socket as if
it had come from the network.
@param so The socket to inject the data on.
@param from The address the data is from, only necessary on
un-connected sockets. A copy of the address will be made, caller
is responsible for freeing the address after calling this
function.
@param data The data and possibly control mbufs.
@param control The separate control mbufs.
@param flags Flags indicating the type of data.
@result 0 on success otherwise the errno error. If the function
returns an error, the caller is responsible for freeing the
mbuf.
functionsock_inject_data_out
__NKE_API_DEPRECATED extern errno_t sock_inject_data_out( socket_t so, const struct sockaddr *to, mbuf_t data, mbuf_t control, sflt_data_flag_t flags )
deprecated
@function sock_inject_data_out
@discussion Inject data in to the send buffer of the socket as if it
had come from the client.
@param so The socket to inject the data on.
@param to The address the data should be sent to, only necessary on
un-connected sockets. The caller is responsible for freeing the
to address after sock_inject_data_out returns.
@param data The data and possibly control mbufs.
@param control The separate control mbufs.
@param flags Flags indicating the type of data.
@result 0 on success otherwise the errno error. The data and control
values are always freed regardless of return value.
enum(anonymous)
| sockopt_get | 1 | |
| sockopt_set | 2 |
typedefsockopt_dir
typedef u_int8_t sockopt_dir
functionsockopt_direction
__NKE_API_DEPRECATED extern sockopt_dir sockopt_direction(sockopt_t sopt)
deprecated
@function sockopt_direction
@discussion Retrieves the direction of the socket option (Get or
Set).
@param sopt The socket option.
@result sock_opt_get or sock_opt_set.
functionsockopt_level
__NKE_API_DEPRECATED extern int sockopt_level(sockopt_t sopt)
deprecated
@function sockopt_level
@discussion Retrieves the socket option level. (SOL_SOCKET, etc).
@param sopt The socket option.
@result The socket option level. See man 2 setsockopt
functionsockopt_name
__NKE_API_DEPRECATED extern int sockopt_name(sockopt_t sopt)
deprecated
@function sockopt_name
@discussion Retrieves the socket option name. (SO_SNDBUF, etc).
@param sopt The socket option.
@result The socket option name. See man 2 setsockopt
functionsockopt_valsize
__NKE_API_DEPRECATED extern size_t sockopt_valsize(sockopt_t sopt)
deprecated
@function sockopt_valsize
@discussion Retrieves the size of the socket option data.
@param sopt The socket option.
@result The length, in bytes, of the data.
functionsockopt_copyin
__NKE_API_DEPRECATED extern errno_t sockopt_copyin( sockopt_t sopt, void *__sized_by(length) data, size_t length )
deprecated
@function sockopt_copyin
@discussion Copies the data from the socket option to a buffer.
@param sopt The socket option.
@param data A pointer to the buffer to copy the data in to.
@param length The number of bytes to copy.
@result An errno error or zero upon success.
functionsockopt_copyout
__NKE_API_DEPRECATED extern errno_t sockopt_copyout( sockopt_t sopt, void *__sized_by(length) data, size_t length )
deprecated
@function sockopt_copyout
@discussion Copies the data from a buffer to a socket option.
@param sopt The socket option.
@param data A pointer to the buffer to copy the data out of.
@param length The number of bytes to copy.
@result An errno error or zero upon success.