1avc_init(3) SE Linux API documentation avc_init(3)
2
6 avc_init, avc_destroy, avc_reset, avc_cleanup - userspace SELinux AVC
7 setup and teardown.
8
10 #include <selinux/selinux.h>
11 #include <selinux/avc.h>
13 int avc_init(const char *msgprefix,
15 const struct avc_memory_callback *mem_callbacks,
16 const struct avc_log_callback *log_callbacks,
18 const struct avc_thread_callback *thread_callbacks,
20 const struct avc_lock_callback *lock_callbacks);
22 void avc_destroy(void);
24 int avc_reset(void);
26 void avc_cleanup(void);
28
30 avc_init initializes the userspace AVC and must be called before any
31 other AVC operation can be performed. A non-NULL msgprefix will be
32 prepended to all audit messages produced by the userspace AVC. The
33 default is `uavc'. The remaining arguments, if non-NULL, specify call‐
34 backs to be used by the userspace AVC. See CALLBACKS below.
35 avc_destroy destroys the userspace AVC, freeing all internal memory
37 structures. After this call has been made, avc_init must be called
38 again before any AVC operations can be performed.
39 avc_reset flushes the userspace AVC, causing it to forget any cached
41 access decisions. The userspace AVC normally calls this function auto‐
42 matically when needed, see NETLINK NOTIFICATION below.
43 avc_cleanup forces the userspace AVC to search for and free all unused
45 SID's and any access decision entries that refer to them. Normally,
46 the userspace AVC lazily reclaims unused SID's.
47
50 The userspace AVC can be directed how to perform memory allocation,
51 logging, thread creation, and locking via callback functions passed to
52 avc_init. The purpose of this functionality is to allow the userspace
53 AVC to be smoothly integrated into existing userspace object managers.
54 Use an avc_memory_callback structure to specify alternate functions for
56 dynamic memory allocation.
57 struct avc_memory_callback {
59 void *(*func_malloc)(size_t size);
60 void (*func_free)(void *ptr);
61 };
62 The two fields of the structure should be pointers to functions which
64 behave as malloc(3) and free(3), which are used by default.
65 Use an avc_log_callback structure to specify alternate functions for
67 logging.
68 struct avc_log_callback {
70 void (*func_log)(const char *fmt, ...);
71 void (*func_audit)(void *auditdata,
72 security_class_t class,
73 char *msgbuf, size_t msgbufsize);
74 };
75 The func_log callback should accept a printf(3) style format and argu‐
77 ments and log them as desired. The default behavior prints the message
78 on the standard error. The func_audit callback should interpret the
79 auditdata parameter for the given class, printing a human-readable
80 interpretation to msgbuf using no more than msgbufsize characters. The
81 default behavior is to ignore auditdata.
82 Use an avc_thread_callback structure to specify functions for starting
84 and manipulating threads.
85 struct avc_thread_callback {
87 void *(*func_create_thread)(void (*run)(void));
88 void (*func_stop_thread)(void *thread);
89 };
90 The func_create_thread callback should create a new thread and return a
92 pointer which references it. The thread should execute the run argu‐
93 ment, which does not return under normal conditions. The
94 func_stop_thread callback should cancel the running thread referenced
95 by thread. By default, threading is not used; see NETLINK NOTIFICATION
96 below.
97 Use an avc_lock_callback structure to specify functions to create,
99 obtain, and release locks for use by threads.
100 struct avc_lock_callback {
102 void *(*func_alloc_lock)(void);
103 void (*func_get_lock)(void *lock);
104 void (*func_release_lock)(void *lock);
105 void (*func_free_lock)(void *lock);
106 };
107 The func_alloc_lock callback should create a new lock, returning a
109 pointer which references it. The func_get_lock callback should obtain
110 lock, blocking if necessary. The func_release_lock callback should
111 release lock. The func_free_lock callback should destroy lock, freeing
112 any resources associated with it. The default behavior is not to per‐
113 form any locking. Note that undefined behavior may result if threading
114 is used without appropriate locking.
115
118 Beginning with version 2.6.4, the Linux kernel supports SELinux status
119 change notification via netlink. Two message types are currently
120 implemented, indicating changes to the enforcing mode and to the loaded
121 policy in the kernel, respectively. The userspace AVC listens for
122 these messages and takes the appropriate action, modifying the behavior
123 of avc_has_perm(3) to reflect the current enforcing mode and flushing
124 the cache on receipt of a policy load notification. Audit messages are
125 produced when netlink notifications are processed.
126 In the default single-threaded mode, the userspace AVC checks for new
128 netlink messages at the start of each permission query. If threading
129 and locking callbacks are passed to avc_init however, a dedicated
130 thread will be started to listen on the netlink socket. This may
131 increase performance and will ensure that log messages are generated
132 immediately rather than at the time of the next permission query.
133
136 Functions with a return value return zero on success. On error, -1 is
137 returned and errno is set appropriately.
138
141 The msgprefix argument to avc_init currently has a length limit of 15
142 characters and will be truncated if necessary.
143 If a provided func_malloc callback does not set errno appropriately on
145 error, userspace AVC calls may exhibit the same behavior.
146 If a netlink thread has been created and an error occurs on the socket
148 (such as an access error), the thread may terminate and cause the
149 userspace AVC to return EINVAL on all further permission checks until
150 avc_destroy is called.
151
154 Eamon Walsh <ewalsh@epoch.ncsc.mil>
155
158 avc_has_perm(3), avc_context_to_sid(3), avc_cache_stats(3),
159 avc_add_callback(3), security_compute_av(3) selinux(8)
160 27 May 2004 avc_init(3)