1avc_init(3)               SE Linux API documentation               avc_init(3)
2
3
4

NAME

6       avc_init,  avc_destroy,  avc_reset, avc_cleanup - userspace SELinux AVC
7       setup and teardown.
8

SYNOPSIS

10       #include <selinux/selinux.h>
11
12       #include <selinux/avc.h>
13
14       int avc_init(const char *msgprefix,
15                    const struct avc_memory_callback *mem_callbacks,
16
17                    const struct avc_log_callback *log_callbacks,
18
19                    const struct avc_thread_callback *thread_callbacks,
20
21                    const struct avc_lock_callback *lock_callbacks);
22
23       void avc_destroy(void);
24
25       int avc_reset(void);
26
27       void avc_cleanup(void);
28

DESCRIPTION

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
36       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
40       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
44       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
48

CALLBACKS

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
55       Use an avc_memory_callback structure to specify alternate functions for
56       dynamic memory allocation.
57
58              struct avc_memory_callback {
59                  void  *(*func_malloc)(size_t size);
60                  void  (*func_free)(void *ptr);
61              };
62
63       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
66       Use  an  avc_log_callback  structure to specify alternate functions for
67       logging.
68
69              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
76       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
83       Use  an avc_thread_callback structure to specify functions for starting
84       and manipulating threads.
85
86              struct avc_thread_callback {
87                  void  *(*func_create_thread)(void (*run)(void));
88                  void  (*func_stop_thread)(void *thread);
89              };
90
91       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
98       Use  an  avc_lock_callback  structure  to  specify functions to create,
99       obtain, and release locks for use by threads.
100
101              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
108       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
116
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
127       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
134

RETURN VALUE

136       Functions with a return value return zero on success.  On error, -1  is
137       returned and errno is set appropriately.
138
139

NOTES

141       The  msgprefix  argument to avc_init currently has a length limit of 15
142       characters and will be truncated if necessary.
143
144       If a provided func_malloc callback does not set errno appropriately  on
145       error, userspace AVC calls may exhibit the same behavior.
146
147       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
152

AUTHOR

154       Eamon Walsh <ewalsh@epoch.ncsc.mil>
155
156

SEE ALSO

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
161
162
163
164                                  27 May 2004                      avc_init(3)
Impressum