1avc_init(3)                SELinux API documentation               avc_init(3)
2
3
4

NAME

6       avc_init - legacy userspace SELinux AVC setup
7

SYNOPSIS

9       #include <selinux/selinux.h>
10       #include <selinux/avc.h>
11
12       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

DESCRIPTION

19       avc_init()  is  deprecated;  please use avc_open(3) in conjunction with
20       selinux_set_callback(3) in all new code.
21
22       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
25       default is `uavc'.  The remaining arguments, if non-NULL, specify call‐
26       backs to be used by the userspace AVC.
27

CALLBACKS

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
35       Use an avc_memory_callback structure to specify alternate functions for
36       dynamic memory allocation.
37
38              struct avc_memory_callback {
39                  void  *(*func_malloc)(size_t size);
40                  void  (*func_free)(void *ptr);
41              };
42
43       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
46       Use an avc_log_callback structure to specify  alternate  functions  for
47       logging.
48
49              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
56       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
60       interpretation to msgbuf using no more than msgbufsize characters.  The
61       default behavior is to ignore auditdata.
62
63       Use an avc_thread_callback structure to specify functions for  starting
64       and manipulating threads.
65
66              struct avc_thread_callback {
67                  void  *(*func_create_thread)(void (*run)(void));
68                  void  (*func_stop_thread)(void *thread);
69              };
70
71       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 NETLINK NOTIFICATION
76       below.
77
78       Use an avc_lock_callback structure  to  specify  functions  to  create,
79       obtain, and release locks for use by threads.
80
81              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
88       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
91       release 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       Beginning  with version 2.6.4, the Linux kernel supports SELinux status
98       change notification via  netlink.   Two  message  types  are  currently
99       implemented, indicating changes to the enforcing mode and to the loaded
100       policy in the kernel, respectively.   The  userspace  AVC  listens  for
101       these messages and takes the appropriate action, modifying the behavior
102       of avc_has_perm(3) to reflect the current enforcing mode  and  flushing
103       the cache on receipt of a policy load notification.  Audit messages are
104       produced when netlink notifications are processed.
105
106       In the default single-threaded mode, the userspace AVC checks  for  new
107       netlink  messages  at the start of each permission query.  If threading
108       and locking callbacks are passed to  avc_init()  however,  a  dedicated
109       thread  will  be  started  to  listen  on the netlink socket.  This may
110       increase performance and will ensure that log  messages  are  generated
111       immediately rather than at the time of the next permission query.
112

RETURN VALUE

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

NOTES

118       The msgprefix argument to avc_init() currently has a length limit of 15
119       characters and will be truncated if necessary.
120
121       If  a provided func_malloc callback does not set errno appropriately on
122       error, userspace AVC calls may exhibit the same behavior.
123
124       If a netlink thread has been created and an error occurs on the  socket
125       (such  as  an  access  error),  the  thread may terminate and cause the
126       userspace AVC to return EINVAL on all further permission  checks  until
127       avc_destroy is called.
128

AUTHOR

130       Eamon Walsh <ewalsh@tycho.nsa.gov>
131

SEE ALSO

133       avc_open(3), selinux_set_callback(3), selinux(8)
134
135
136
137                                  27 May 2004                      avc_init(3)
Impressum