1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Author: Eamon Walsh (ewalsh@tycho.nsa.gov) 2004
.TH "avc_init" "3" "27 May 2004" "" "SELinux API documentation"
.SH "NAME"
avc_init - legacy userspace SELinux AVC setup.
.SH "SYNOPSIS"
.B #include <selinux/selinux.h>
.B #include <selinux/avc.h>
.sp
.BI "int avc_init(const char *" msgprefix ,
.in +\w'int avc_init('u
.BI "const struct avc_memory_callback *" mem_callbacks ,
.BI "const struct avc_log_callback *" log_callbacks ,
.BI "const struct avc_thread_callback *" thread_callbacks ,
.BI "const struct avc_lock_callback *" lock_callbacks ");"
.SH "DESCRIPTION"
.B avc_init
is deprecated; please use
.BR avc_open (3)
in conjunction with
.BR selinux_set_callback (3)
in all new code.
.B avc_init
initializes the userspace AVC and must be called before any other AVC operation can be performed. A non-NULL
.I msgprefix
will be prepended to all audit messages produced by the userspace AVC. The default is `uavc'. The remaining arguments, if non-NULL, specify callbacks to be used by the userspace AVC.
.SH "CALLBACKS"
The userspace AVC can be directed how to perform memory allocation, logging, thread creation, and locking via callback functions passed to
.BR avc_init .
The purpose of this functionality is to allow the userspace AVC to be smoothly integrated into existing userspace object managers.
Use an
.B avc_memory_callback
structure to specify alternate functions for dynamic memory allocation.
.RS
.ta 4n 10n 24n
.nf
struct avc_memory_callback {
void *(*func_malloc)(size_t size);
void (*func_free)(void *ptr);
};
.fi
.ta
.RE
The two fields of the structure should be pointers to functions which behave as
.BR malloc (3)
and
.BR free (3),
which are used by default.
Use an
.B avc_log_callback
structure to specify alternate functions for logging.
.RS
.ta 4n 10n 24n
.nf
struct avc_log_callback {
void (*func_log)(const char *fmt, ...);
void (*func_audit)(void *auditdata,
security_class_t class,
char *msgbuf, size_t msgbufsize);
};
.fi
.ta
.RE
The
.B func_log
callback should accept a
.BR printf (3)
style format and arguments and log them as desired. The default behavior prints the message on the standard error. The
.B func_audit
callback should interpret the
.I auditdata
parameter for the given
.IR class ,
printing a human-readable interpretation to
.I msgbuf
using no more than
.I msgbufsize
characters. The default behavior is to ignore
.IR auditdata .
Use an
.B avc_thread_callback
structure to specify functions for starting and manipulating threads.
.RS
.ta 4n 10n 24n
.nf
struct avc_thread_callback {
void *(*func_create_thread)(void (*run)(void));
void (*func_stop_thread)(void *thread);
};
.fi
.ta
.RE
The
.B func_create_thread
callback should create a new thread and return a pointer which references it. The thread should execute the
.I run
argument, which does not return under normal conditions. The
.B func_stop_thread
callback should cancel the running thread referenced by
.IR thread .
By default, threading is not used; see
.B NETLINK NOTIFICATION
below.
Use an
.B avc_lock_callback
structure to specify functions to create, obtain, and release locks for use by threads.
.RS
.ta 4n 10n 24n
.nf
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);
};
.fi
.ta
.RE
The
.B func_alloc_lock
callback should create a new lock, returning a pointer which references it. The
.B func_get_lock
callback should obtain
.IR lock ,
blocking if necessary. The
.B func_release_lock
callback should release
.IR lock .
The
.B func_free_lock
callback should destroy
.IR lock ,
freeing any resources associated with it. The default behavior is not to perform any locking. Note that undefined behavior may result if threading is used without appropriate locking.
.SH "NETLINK NOTIFICATION"
Beginning with version 2.6.4, the Linux kernel supports SELinux status change notification via netlink. Two message types are currently implemented, indicating changes to the enforcing mode and to the loaded policy in the kernel, respectively. The userspace AVC listens for these messages and takes the appropriate action, modifying the behavior of
.BR avc_has_perm (3)
to reflect the current enforcing mode and flushing the cache on receipt of a policy load notification. Audit messages are produced when netlink notifications are processed.
In the default single-threaded mode, the userspace AVC checks for new netlink messages at the start of each permission query. If threading and locking callbacks are passed to
.B avc_init
however, a dedicated thread will be started to listen on the netlink socket. This may increase performance and will ensure that log messages are generated immediately rather than at the time of the next permission query.
.SH "RETURN VALUE"
Functions with a return value return zero on success. On error, \-1 is returned and
.I errno
is set appropriately.
.SH "NOTES"
The
.I msgprefix
argument to
.B avc_init
currently has a length limit of 15 characters and will be truncated if necessary.
If a provided
.B func_malloc
callback does not set
.I 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
.B EINVAL
on all further permission checks until
.B avc_destroy
is called.
.SH "AUTHOR"
Eamon Walsh <ewalsh@tycho.nsa.gov>
.SH "SEE ALSO"
.BR avc_open (3),
.BR selinux_set_callback (3),
.BR selinux (8)
|
