NAME
avc_init - legacy userspace SELinux AVC setup.
SYNOPSIS
#include <selinux/selinux.h>
#include <selinux/avc.h>
int avc_init(const char *msgprefix,
const struct avc_memory_callback *mem_callbacks,
const struct avc_log_callback *log_callbacks,
const struct avc_thread_callback *thread_callbacks,
const struct avc_lock_callback *lock_callbacks);
DESCRIPTION
avc_init is deprecated; please use avc_open(3) in conjunction with
selinux_set_callback(3) in all new code.
avc_init initializes the userspace AVC and must be called before any
other AVC operation can be performed. A non-NULL msgprefix will be
prepended to all audit messages produced by the userspace AVC. The
default is ‘uavc’. The remaining arguments, if non-NULL, specify
callbacks to be used by the userspace AVC.
CALLBACKS
The userspace AVC can be directed how to perform memory allocation,
logging, thread creation, and locking via callback functions passed to
avc_init. The purpose of this functionality is to allow the userspace
AVC to be smoothly integrated into existing userspace object managers.
Use an avc_memory_callback structure to specify alternate functions for
dynamic memory allocation.
struct avc_memory_callback {
void *(*func_malloc)(size_t size);
void (*func_free)(void *ptr);
};
The two fields of the structure should be pointers to functions which
behave as malloc(3) and free(3), which are used by default.
Use an avc_log_callback structure to specify alternate functions for
logging.
struct avc_log_callback {
void (*func_log)(const char *fmt, ...);
void (*func_audit)(void *auditdata,
security_class_t class,
char *msgbuf, size_t msgbufsize);
};
The func_log callback should accept a printf(3) style format and
arguments and log them as desired. The default behavior prints the
message on the standard error. The func_audit callback should
interpret the auditdata parameter for the given class, printing a
human-readable interpretation to msgbuf using no more than msgbufsize
characters. The default behavior is to ignore auditdata.
Use an avc_thread_callback structure to specify functions for starting
and manipulating threads.
struct avc_thread_callback {
void *(*func_create_thread)(void (*run)(void));
void (*func_stop_thread)(void *thread);
};
The func_create_thread callback should create a new thread and return a
pointer which references it. The thread should execute the run
argument, which does not return under normal conditions. The
func_stop_thread callback should cancel the running thread referenced
by thread. By default, threading is not used; see NETLINK NOTIFICATION
below.
Use an avc_lock_callback structure to specify functions to create,
obtain, and release locks for use by threads.
struct avc_lock_callback {
void *(*func_alloc_lock)(void);
void (*func_get_lock)(void *lock);
void (*func_release_lock)(void *lock);
void (*func_free_lock)(void *lock);
};
The func_alloc_lock callback should create a new lock, returning a
pointer which references it. The func_get_lock callback should obtain
lock, blocking if necessary. The func_release_lock callback should
release lock. The func_free_lock callback should destroy lock, freeing
any resources associated with it. The default behavior is not to
perform any locking. Note that undefined behavior may result if
threading is used without appropriate locking.
NETLINK NOTIFICATION
Beginning with version 2.6.4, the Linux kernel supports SELinux status
change notification via netlink. Two message types are currently
implemented, indicating changes to the enforcing mode and to the loaded
policy in the kernel, respectively. The userspace AVC listens for
these messages and takes the appropriate action, modifying the behavior
of avc_has_perm(3) to reflect the current enforcing mode and flushing
the cache on receipt of a policy load notification. Audit messages are
produced when netlink notifications are processed.
In the default single-threaded mode, the userspace AVC checks for new
netlink messages at the start of each permission query. If threading
and locking callbacks are passed to avc_init however, a dedicated
thread will be started to listen on the netlink socket. This may
increase performance and will ensure that log messages are generated
immediately rather than at the time of the next permission query.
RETURN VALUE
Functions with a return value return zero on success. On error, -1 is
returned and errno is set appropriately.
NOTES
The msgprefix argument to avc_init currently has a length limit of 15
characters and will be truncated if necessary.
If a provided func_malloc callback does not set errno appropriately on
error, userspace AVC calls may exhibit the same behavior.
If a netlink thread has been created and an error occurs on the socket
(such as an access error), the thread may terminate and cause the
userspace AVC to return EINVAL on all further permission checks until
avc_destroy is called.
AUTHOR
Eamon Walsh <ewalsh@tycho.nsa.gov>
SEE ALSO
avc_open(3), selinux_set_callback(3), selinux(8)
27 May 2004 avc_init(3)