Architecture

The SELinux pseudo-filesystem includes a file access which is used to obtain policy decisions from the kernel. The libselinux routine security_compute_av encapsulates this functionality. However, this routine has the overhead of a kernel trap on each call.

The userspace AVC is essentially a cache built on top of security_compute_av. It provides a cleaner interface to the caller, including:

After initialization, a userspace program passes security contexts to avc_context_to_sid to obtain SIDs. SIDs are reference-counted; in addition to avc_context_to_sid, which increments the reference count, the functions sidget and sidput increment and decrement the count, respectively. The function avc_sid_to_context returns a copy of the context corresponding to a given SID.

Policy decisions are determined using avc_has_perm, which takes subject and object SIDs, the object class, and the requested access permissions. The return value of avc_has_perm is zero on grant, nonzero (with errno set) otherwise. The function also takes a cache entry reference that speeds cache lookups on repeated queries, and a pointer to supplementary audit data associated with the security class. avc_has_perm makes a call to avc_audit; use avc_has_perm_noaudit if you wish to separate these two actions.

avc_audit prints the familiar avc "denied" messages on a policy denial. The default is to print them on standard error. However, userspace programs can provide a printf-style callback to handle the messages themselves — via syslog, for example. Userspace programs can also provide a callback to interpret the extra auditing data passed to avc_has_perm and avc_audit. This can make the audit messages easier to track and interpret.

Starting with version 2.6.4, the Linux kernel supports netlink notification of policy and enforcing-mode changes. The userspace AVC listens for these notifications and takes the appropriate action (e.g. cache flush) automatically. In the default, single-threaded mode, the userspace AVC must check the netlink socket during each call to avc_has_perm*. Performance-critical programs can provide threading and locking callbacks to the userspace AVC which will be used to start a dedicated thread to wait on the socket. The example code below shows how to set up the threading callbacks using the pthread library.

The userspace AVC provides three functions for obtaining statistics. The first two, avc_av_stats and avc_sid_stats, produce audit messages that indicate the status of the hash tables storing access vectors and SID's, respectively. The messages contain the number of entries, number of hash buckets used, and longest chain of entries in a single bucket. The third statistics function, avc_cache_stats, populates an avc_cache_stats structure whose fields describe access vector cache activity (number of lookups performed, hit rate, etc.)