avc_init(3)

💖 avc_init 💖 — the legacy userspace SELinux AVC setup, straight out of the SELinux API documentation

okay so bestie, welcome to avc_init(3) — yes it's section 3, yes it's an SELinux API page, and yes it's lowkey a relic but we're gonna get through it together 🫶

---

✨ 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 🦋

girl. listen. avc_init() is deprecated. Not "kinda old", not "vintage aesthetic" — deprecated. In all new code you want avc_open(3) hanging out with selinux_set_callback(3). periodt. 💅

Now for the ✨lore✨: avc_init() initializes the userspace AVC, and it has to be called before any other AVC operation can happen. Like, it's the first one at the party, nobody gets in before it. 🎀

A non-NULL msgprefix gets prepended to all audit messages the userspace AVC produces. The default is uavc. And the rest of the arguments? If they're non-NULL, they're callbacks the userspace AVC should use. That's it, that's the whole vibe.

---

🧚 CALLBACKS 🧚

So the userspace AVC can be told how to do memory allocation, logging, thread creation and locking — via callback functions you hand to avc_init(). Why tho? Because the whole point is letting the userspace AVC slide smoothly into existing userspace object managers. It's giving "team player". 👑

💜 memory callbacks

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 should be pointers to functions that behave like malloc(3) and free(3) — and those two are what get used by default. 💖

💜 log callbacks

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 take a printf(3)-style format plus arguments and log them however you want. Default behavior? Prints the message on standard error. 🗣️

The func_audit callback should interpret the auditdata parameter for the given class, printing a human-readable interpretation into msgbuf using no more than msgbufsize characters. Default behavior is to just... ignore auditdata. 🙈

💜 thread callbacks

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 that references it. The thread should execute the run argument — which, heads up, 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 KERNEL STATUS PAGE and NETLINK NOTIFICATION below. 👀

💜 lock callbacks

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);
};

• func_alloc_lock should create a new lock, returning a pointer that references it.
• func_get_lock should obtain lock, blocking if necessary.
• func_release_lock should release lock.
• func_free_lock should destroy lock, freeing any resources associated with it.

The default behavior is not to perform any locking. 🫠

⚠️ real talk: undefined behavior may result if threading is used without appropriate locking. Not a vibe. Do not skip the locking.

---

👑 KERNEL STATUS PAGE 👑

Linux kernel version 2.6.37 supports the SELinux kernel status page, which lets userspace applications mmap(2) SELinux status state in read-only mode so they can avoid system calls during the cache hit code path. iconically efficient, honestly. ✨

avc_init() calls selinux_status_open(3) to initialize the selinux status state. If that succeeds, the userspace AVC will default to single-threaded mode and ignore the func_create_thread and func_stop_thread callbacks. All callbacks set via selinux_set_callback(3) will still be honored though — no one's getting ghosted. 💜

avc_has_perm(3) and selinux_check_access(3) both check for status updates through calls to selinux_status_updated(3) at the start of each permission query, and then take the appropriate action.

Two status types are currently implemented:

1. setenforce events will change the effective enforcing state used within the AVC.
2. policyload events will result in a cache flush. 🧹

---

🌈 NETLINK NOTIFICATION 🌈

In the event that the kernel status page is not successfully mmap(2)'ed, the AVC defaults to the netlink fallback mechanism, which opens a netlink socket for receiving status updates. setenforce and policyload events will have the same results as for the status page implementation, but now all status update checks require a system call. 💀

By default, avc_open(3) does not set threading or locking callbacks. In the fallback case, the userspace AVC checks for new netlink messages at the start of each permission query. But if threading and locking callbacks are passed to avc_init(), a dedicated thread gets started to listen on the netlink socket. This may increase performance in the absence of the status page, and it ensures log messages are generated immediately rather than at the time of the next permission query. main character thread behavior. 🎀

---

⭐ RETURN VALUE ⭐

Functions with a return value return zero on success. On error, -1 is returned and errno is set appropriately. classic. 🫶

---

💅 NOTES 💅

• The msgprefix argument to avc_init() currently has a length limit of 15 characters and will be truncated if necessary. keep it short bestie ✂️
• 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. this one is rough, no cap. 😭

---

🎀 AUTHOR 🎀

Eamon Walsh <ewalsh@tycho.nsa.gov> — thank you for your service, legend 🫡💖

---

🔥 SEE ALSO 🔥

avc_open(3), selinux_status_open(3), selinux_status_updated(3), selinux_set_callback(3), selinux(8)

---

and that's the whole page bestie, we ate 💅✨ this one's dated 27 May 2004 and it comes to you from the SELinux API documentation — go forth, use avc_open(3) instead, and stan secure code 🌸🦋👑