1avc_init(3) SELinux API documentation avc_init(3)
2
6 avc_init - legacy userspace SELinux AVC setup
7
9 #include <selinux/selinux.h>
10 #include <selinux/avc.h>
11 int avc_init(const char *msgprefix,
13 const struct avc_memory_callback *mem_callbacks,
14 const struct avc_log_callback *log_callbacks,
15 const struct avc_thread_callback *thread_callbacks,
16 const struct avc_lock_callback *lock_callbacks);
17
19 avc_init() is deprecated; please use avc_open(3) in conjunction with
20 selinux_set_callback(3) in all new code.
21 avc_init() initializes the userspace AVC and must be called before any
23 other AVC operation can be performed. A non-NULL msgprefix will be
24 prepended to all audit messages produced by the userspace AVC. The de‐
25 fault is `uavc'. The remaining arguments, if non-NULL, specify call‐
26 backs to be used by the userspace AVC.
27
29 The userspace AVC can be directed how to perform memory allocation,
30 logging, thread creation, and locking via callback functions passed to
31 avc_init(). The purpose of this functionality is to allow the
32 userspace AVC to be smoothly integrated into existing userspace object
33 managers.
34 Use an avc_memory_callback structure to specify alternate functions for
36 dynamic memory allocation.
37 struct avc_memory_callback {
39 void *(*func_malloc)(size_t size);
40 void (*func_free)(void *ptr);
41 };
42 The two fields of the structure should be pointers to functions which
44 behave as malloc(3) and free(3), which are used by default.
45 Use an avc_log_callback structure to specify alternate functions for
47 logging.
48 struct avc_log_callback {
50 void (*func_log)(const char *fmt, ...);
51 void (*func_audit)(void *auditdata,
52 security_class_t class,
53 char *msgbuf, size_t msgbufsize);
54 };
55 The func_log callback should accept a printf(3) style format and argu‐
57 ments and log them as desired. The default behavior prints the message
58 on the standard error. The func_audit callback should interpret the
59 auditdata parameter for the given class, printing a human-readable in‐
60 terpretation to msgbuf using no more than msgbufsize characters. The
61 default behavior is to ignore auditdata.
62 Use an avc_thread_callback structure to specify functions for starting
64 and manipulating threads.
65 struct avc_thread_callback {
67 void *(*func_create_thread)(void (*run)(void));
68 void (*func_stop_thread)(void *thread);
69 };
70 The func_create_thread callback should create a new thread and return a
72 pointer which references it. The thread should execute the run argu‐
73 ment, which does not return under normal conditions. The
74 func_stop_thread callback should cancel the running thread referenced
75 by thread. By default, threading is not used; see KERNEL STATUS PAGE
76 and NETLINK NOTIFICATION below.
77 Use an avc_lock_callback structure to specify functions to create, ob‐
79 tain, and release locks for use by threads.
80 struct avc_lock_callback {
82 void *(*func_alloc_lock)(void);
83 void (*func_get_lock)(void *lock);
84 void (*func_release_lock)(void *lock);
85 void (*func_free_lock)(void *lock);
86 };
87 The func_alloc_lock callback should create a new lock, returning a
89 pointer which references it. The func_get_lock callback should obtain
90 lock, blocking if necessary. The func_release_lock callback should re‐
91 lease lock. The func_free_lock callback should destroy lock, freeing
92 any resources associated with it. The default behavior is not to per‐
93 form any locking. Note that undefined behavior may result if threading
94 is used without appropriate locking.
95
97 Linux kernel version 2.6.37 supports the SELinux kernel status page,
98 enabling userspace applications to mmap(2) SELinux status state in
99 read-only mode to avoid system calls during the cache hit code path.
100 avc_init() calls selinux_status_open(3) to initialize the selinux sta‐
102 tus state. If successfully initialized, the userspace AVC will default
103 to single-threaded mode and ignore the func_create_thread and
104 func_stop_thread callbacks. All callbacks set via selinux_set_call‐
105 back(3) will still be honored.
106 avc_has_perm(3) and selinux_check_access(3) both check for status up‐
108 dates through calls to selinux_status_updated(3) at the start of each
109 permission query and take the appropriate action.
110 Two status types are currently implemented. setenforce events will
112 change the effective enforcing state used within the AVC, and policy‐
113 load events will result in a cache flush.
114
116 In the event that the kernel status page is not successfully mmap(2)'ed
117 the AVC will default to the netlink fallback mechanism, which opens a
118 netlink socket for receiving status updates. setenforce and policyload
119 events will have the same results as for the status page implementa‐
120 tion, but all status update checks will now require a system call.
121 By default, avc_open(3) does not set threading or locking callbacks. In
123 the fallback case, the userspace AVC checks for new netlink messages at
124 the start of each permission query. If threading and locking callbacks
125 are passed to avc_init(), a dedicated thread will be started to listen
126 on the netlink socket. This may increase performance in the absence of
127 the status page and will ensure that log messages are generated immedi‐
128 ately rather than at the time of the next permission query.
129
131 Functions with a return value return zero on success. On error, -1 is
132 returned and errno is set appropriately.
133
135 The msgprefix argument to avc_init() currently has a length limit of 15
136 characters and will be truncated if necessary.
137 If a provided func_malloc callback does not set errno appropriately on
139 error, userspace AVC calls may exhibit the same behavior.
140 If a netlink thread has been created and an error occurs on the socket
142 (such as an access error), the thread may terminate and cause the
143 userspace AVC to return EINVAL on all further permission checks until
144 avc_destroy is called.
145
147 Eamon Walsh <ewalsh@tycho.nsa.gov>
148
150 avc_open(3), selinux_status_open(3), selinux_status_updated(3),
151 selinux_set_callback(3), selinux(8)
152 27 May 2004 avc_init(3)