1/*
2 * Access vector cache interface for object managers.
3 *
4 * Author : Eamon Walsh <ewalsh@epoch.ncsc.mil>
5 */
6#ifndef _SELINUX_AVC_H_
7#define _SELINUX_AVC_H_
8
9#include <stdint.h>
10#include <errno.h>
11#include <stdlib.h>
12#include <selinux/selinux.h>
13
14#ifdef __cplusplus
15extern "C" {
16#endif
17
18/*
19 * SID format and operations
20 */
21struct security_id {
22 char * ctx;
23 unsigned int refcnt;
24};
25typedef struct security_id *security_id_t;
26
27#define SECSID_WILD (security_id_t)NULL /* unspecified SID */
28
29/**
30 * avc_sid_to_context - get copy of context corresponding to SID.
31 * @sid: input SID
32 * @ctx: pointer to context reference
33 *
34 * Return a copy of the security context corresponding to the input
35 * @sid in the memory referenced by @ctx. The caller is expected to
36 * free the context with freecon(). Return %0 on success, -%1 on
37 * failure, with @errno set to %ENOMEM if insufficient memory was
38 * available to make the copy, or %EINVAL if the input SID is invalid.
39 */
40extern int avc_sid_to_context(security_id_t sid, char ** ctx);
41extern int avc_sid_to_context_raw(security_id_t sid, char ** ctx);
42
43/**
44 * avc_context_to_sid - get SID for context.
45 * @ctx: input security context
46 * @sid: pointer to SID reference
47 *
48 * Look up security context @ctx in SID table, making
49 * a new entry if @ctx is not found. Increment the
50 * reference counter for the SID. Store a pointer
51 * to the SID structure into the memory referenced by @sid,
52 * returning %0 on success or -%1 on error with @errno set.
53 */
54extern int avc_context_to_sid(const char * ctx, security_id_t * sid);
55extern int avc_context_to_sid_raw(const char * ctx, security_id_t * sid);
56
57/**
58 * sidget - increment SID reference counter.
59 * @sid: SID reference
60 *
61 * Increment the reference counter for @sid, indicating that
62 * @sid is in use by an (additional) object. Return the
63 * new reference count, or zero if @sid is invalid (has zero
64 * reference count). Note that avc_context_to_sid() also
65 * increments reference counts.
66 */
67extern int sidget(security_id_t sid)
68#ifdef __GNUC__
69__attribute__ ((deprecated))
70#endif
71;
72
73/**
74 * sidput - decrement SID reference counter.
75 * @sid: SID reference
76 *
77 * Decrement the reference counter for @sid, indicating that
78 * a reference to @sid is no longer in use. Return the
79 * new reference count. When the reference count reaches
80 * zero, the SID is invalid, and avc_context_to_sid() must
81 * be called to obtain a new SID for the security context.
82 */
83extern int sidput(security_id_t sid)
84#ifdef __GNUC__
85__attribute__ ((deprecated))
86#endif
87;
88
89/**
90 * avc_get_initial_sid - get SID for an initial kernel security identifier
91 * @name: input name of initial kernel security identifier
92 * @sid: pointer to a SID reference
93 *
94 * Get the context for an initial kernel security identifier specified by
95 * @name using security_get_initial_context() and then call
96 * avc_context_to_sid() to get the corresponding SID.
97 */
98extern int avc_get_initial_sid(const char *name, security_id_t * sid);
99
100/*
101 * AVC entry
102 */
103struct avc_entry;
104struct avc_entry_ref {
105 struct avc_entry *ae;
106};
107
108/**
109 * avc_entry_ref_init - initialize an AVC entry reference.
110 * @aeref: pointer to avc entry reference structure
111 *
112 * Use this macro to initialize an avc entry reference structure
113 * before first use. These structures are passed to avc_has_perm(),
114 * which stores cache entry references in them. They can increase
115 * performance on repeated queries.
116 */
117#define avc_entry_ref_init(aeref) ((aeref)->ae = NULL)
118
119/*
120 * User-provided callbacks for memory, auditing, and locking
121 */
122
123/* These structures are passed by reference to avc_init(). Passing
124 * a NULL reference will cause the AVC to use a default. The default
125 * memory callbacks are malloc() and free(). The default logging method
126 * is to print on stderr. If no thread callbacks are passed, a separate
127 * listening thread won't be started for kernel policy change messages.
128 * If no locking callbacks are passed, no locking will take place.
129 */
130struct avc_memory_callback {
131 /* malloc() equivalent. */
132 void *(*func_malloc) (size_t size);
133 /* free() equivalent. */
134 void (*func_free) (void *ptr);
135 /* Note that these functions should set errno on failure.
136 If not, some avc routines may return -1 without errno set. */
137};
138
139struct avc_log_callback {
140 /* log the printf-style format and arguments. */
141 void
142#ifdef __GNUC__
143__attribute__ ((format(printf, 1, 2)))
144#endif
145 (*func_log) (const char *fmt, ...);
146 /* store a string representation of auditdata (corresponding
147 to the given security class) into msgbuf. */
148 void (*func_audit) (void *auditdata, security_class_t cls,
149 char *msgbuf, size_t msgbufsize);
150};
151
152struct avc_thread_callback {
153 /* create and start a thread, returning an opaque pointer to it;
154 the thread should run the given function. */
155 void *(*func_create_thread) (void (*run) (void));
156 /* cancel a given thread and free its resources. */
157 void (*func_stop_thread) (void *thread);
158};
159
160struct avc_lock_callback {
161 /* create a lock and return an opaque pointer to it. */
162 void *(*func_alloc_lock) (void);
163 /* obtain a given lock, blocking if necessary. */
164 void (*func_get_lock) (void *lock);
165 /* release a given lock. */
166 void (*func_release_lock) (void *lock);
167 /* destroy a given lock (free memory, etc.) */
168 void (*func_free_lock) (void *lock);
169};
170
171/*
172 * Available options
173 */
174
175/* no-op option, useful for unused slots in an array of options */
176#define AVC_OPT_UNUSED 0
177/* override kernel enforcing mode (boolean value) */
178#define AVC_OPT_SETENFORCE 1
179
180/*
181 * AVC operations
182 */
183
184/**
185 * avc_init - Initialize the AVC.
186 * @msgprefix: prefix for log messages
187 * @mem_callbacks: user-supplied memory callbacks
188 * @log_callbacks: user-supplied logging callbacks
189 * @thread_callbacks: user-supplied threading callbacks
190 * @lock_callbacks: user-supplied locking callbacks
191 *
192 * Initialize the access vector cache. Return %0 on
193 * success or -%1 with @errno set on failure.
194 * If @msgprefix is NULL, use "uavc". If any callback
195 * structure references are NULL, use default methods
196 * for those callbacks (see the definition of the callback
197 * structures above).
198 */
199extern int avc_init(const char *msgprefix,
200 const struct avc_memory_callback *mem_callbacks,
201 const struct avc_log_callback *log_callbacks,
202 const struct avc_thread_callback *thread_callbacks,
203 const struct avc_lock_callback *lock_callbacks)
204#ifdef __GNUC__
205 __attribute__ ((deprecated("Use avc_open and selinux_set_callback")))
206#endif
207;
208
209/**
210 * avc_open - Initialize the AVC.
211 * @opts: array of selabel_opt structures specifying AVC options or NULL.
212 * @nopts: number of elements in opts array or zero for no options.
213 *
214 * This function is identical to avc_init(), except the message prefix
215 * is set to "avc" and any callbacks desired should be specified via
216 * selinux_set_callback(). Available options are listed above.
217 */
218extern int avc_open(struct selinux_opt *opts, unsigned nopts);
219
220/**
221 * avc_cleanup - Remove unused SIDs and AVC entries.
222 *
223 * Search the SID table for SID structures with zero
224 * reference counts, and remove them along with all
225 * AVC entries that reference them. This can be used
226 * to return memory to the system.
227 */
228extern void avc_cleanup(void);
229
230/**
231 * avc_reset - Flush the cache and reset statistics.
232 *
233 * Remove all entries from the cache and reset all access
234 * statistics (as returned by avc_cache_stats()) to zero.
235 * The SID mapping is not affected. Return %0 on success,
236 * -%1 with @errno set on error.
237 */
238extern int avc_reset(void);
239
240/**
241 * avc_destroy - Free all AVC structures.
242 *
243 * Destroy all AVC structures and free all allocated
244 * memory. User-supplied locking, memory, and audit
245 * callbacks will be retained, but security-event
246 * callbacks will not. All SID's will be invalidated.
247 * User must call avc_init() if further use of AVC is desired.
248 */
249extern void avc_destroy(void);
250
251/**
252 * avc_has_perm_noaudit - Check permissions but perform no auditing.
253 * @ssid: source security identifier
254 * @tsid: target security identifier
255 * @tclass: target security class
256 * @requested: requested permissions, interpreted based on @tclass
257 * @aeref: AVC entry reference
258 * @avd: access vector decisions
259 *
260 * Check the AVC to determine whether the @requested permissions are granted
261 * for the SID pair (@ssid, @tsid), interpreting the permissions
262 * based on @tclass, and call the security server on a cache miss to obtain
263 * a new decision and add it to the cache. Update @aeref to refer to an AVC
264 * entry with the resulting decisions, and return a copy of the decisions
265 * in @avd. Return %0 if all @requested permissions are granted, -%1 with
266 * @errno set to %EACCES if any permissions are denied, or to another value
267 * upon other errors. This function is typically called by avc_has_perm(),
268 * but may also be called directly to separate permission checking from
269 * auditing, e.g. in cases where a lock must be held for the check but
270 * should be released for the auditing.
271 */
272extern int avc_has_perm_noaudit(security_id_t ssid,
273 security_id_t tsid,
274 security_class_t tclass,
275 access_vector_t requested,
276 struct avc_entry_ref *aeref, struct av_decision *avd);
277
278/**
279 * avc_has_perm - Check permissions and perform any appropriate auditing.
280 * @ssid: source security identifier
281 * @tsid: target security identifier
282 * @tclass: target security class
283 * @requested: requested permissions, interpreted based on @tclass
284 * @aeref: AVC entry reference
285 * @auditdata: auxiliary audit data
286 *
287 * Check the AVC to determine whether the @requested permissions are granted
288 * for the SID pair (@ssid, @tsid), interpreting the permissions
289 * based on @tclass, and call the security server on a cache miss to obtain
290 * a new decision and add it to the cache. Update @aeref to refer to an AVC
291 * entry with the resulting decisions. Audit the granting or denial of
292 * permissions in accordance with the policy. Return %0 if all @requested
293 * permissions are granted, -%1 with @errno set to %EACCES if any permissions
294 * are denied or to another value upon other errors.
295 */
296extern int avc_has_perm(security_id_t ssid, security_id_t tsid,
297 security_class_t tclass, access_vector_t requested,
298 struct avc_entry_ref *aeref, void *auditdata);
299
300/**
301 * avc_audit - Audit the granting or denial of permissions.
302 * @ssid: source security identifier
303 * @tsid: target security identifier
304 * @tclass: target security class
305 * @requested: requested permissions
306 * @avd: access vector decisions
307 * @result: result from avc_has_perm_noaudit
308 * @auditdata: auxiliary audit data
309 *
310 * Audit the granting or denial of permissions in accordance
311 * with the policy. This function is typically called by
312 * avc_has_perm() after a permission check, but can also be
313 * called directly by callers who use avc_has_perm_noaudit()
314 * in order to separate the permission check from the auditing.
315 * For example, this separation is useful when the permission check must
316 * be performed under a lock, to allow the lock to be released
317 * before calling the auditing code.
318 */
319extern void avc_audit(security_id_t ssid, security_id_t tsid,
320 security_class_t tclass, access_vector_t requested,
321 struct av_decision *avd, int result, void *auditdata);
322
323/**
324 * avc_compute_create - Compute SID for labeling a new object.
325 * @ssid: source security identifier
326 * @tsid: target security identifier
327 * @tclass: target security class
328 * @newsid: pointer to SID reference
329 *
330 * Call the security server to obtain a context for labeling a
331 * new object. Look up the context in the SID table, making
332 * a new entry if not found. Increment the reference counter
333 * for the SID. Store a pointer to the SID structure into the
334 * memory referenced by @newsid, returning %0 on success or -%1 on
335 * error with @errno set.
336 */
337extern int avc_compute_create(security_id_t ssid,
338 security_id_t tsid,
339 security_class_t tclass, security_id_t * newsid);
340
341/**
342 * avc_compute_member - Compute SID for polyinstantation.
343 * @ssid: source security identifier
344 * @tsid: target security identifier
345 * @tclass: target security class
346 * @newsid: pointer to SID reference
347 *
348 * Call the security server to obtain a context for labeling an
349 * object instance. Look up the context in the SID table, making
350 * a new entry if not found. Increment the reference counter
351 * for the SID. Store a pointer to the SID structure into the
352 * memory referenced by @newsid, returning %0 on success or -%1 on
353 * error with @errno set.
354 */
355extern int avc_compute_member(security_id_t ssid,
356 security_id_t tsid,
357 security_class_t tclass, security_id_t * newsid);
358
359/*
360 * security event callback facility
361 */
362
363/* security events */
364#define AVC_CALLBACK_GRANT 1
365#define AVC_CALLBACK_TRY_REVOKE 2
366#define AVC_CALLBACK_REVOKE 4
367#define AVC_CALLBACK_RESET 8
368#define AVC_CALLBACK_AUDITALLOW_ENABLE 16
369#define AVC_CALLBACK_AUDITALLOW_DISABLE 32
370#define AVC_CALLBACK_AUDITDENY_ENABLE 64
371#define AVC_CALLBACK_AUDITDENY_DISABLE 128
372
373/**
374 * avc_add_callback - Register a callback for security events.
375 * @callback: callback function
376 * @events: bitwise OR of desired security events
377 * @ssid: source security identifier or %SECSID_WILD
378 * @tsid: target security identifier or %SECSID_WILD
379 * @tclass: target security class
380 * @perms: permissions
381 *
382 * Register a callback function for events in the set @events
383 * related to the SID pair (@ssid, @tsid) and
384 * and the permissions @perms, interpreting
385 * @perms based on @tclass. Returns %0 on success or
386 * -%1 if insufficient memory exists to add the callback.
387 */
388extern int avc_add_callback(int (*callback)
389 (uint32_t event, security_id_t ssid,
390 security_id_t tsid, security_class_t tclass,
391 access_vector_t perms,
392 access_vector_t * out_retained),
393 uint32_t events, security_id_t ssid,
394 security_id_t tsid, security_class_t tclass,
395 access_vector_t perms);
396
397/*
398 * AVC statistics
399 */
400
401/* If set, cache statistics are tracked. This may
402 * become a compile-time option in the future.
403 */
404#define AVC_CACHE_STATS 1
405
406struct avc_cache_stats {
407 unsigned entry_lookups;
408 unsigned entry_hits;
409 unsigned entry_misses;
410 unsigned entry_discards;
411 unsigned cav_lookups;
412 unsigned cav_hits;
413 unsigned cav_probes;
414 unsigned cav_misses;
415};
416
417/**
418 * avc_cache_stats - get cache access statistics.
419 * @stats: reference to statistics structure
420 *
421 * Fill the supplied structure with information about AVC
422 * activity since the last call to avc_init() or
423 * avc_reset(). See the structure definition for
424 * details.
425 */
426extern void avc_cache_stats(struct avc_cache_stats *stats);
427
428/**
429 * avc_av_stats - log av table statistics.
430 *
431 * Log a message with information about the size and
432 * distribution of the access vector table. The audit
433 * callback is used to print the message.
434 */
435extern void avc_av_stats(void);
436
437/**
438 * avc_sid_stats - log SID table statistics.
439 *
440 * Log a message with information about the size and
441 * distribution of the SID table. The audit callback
442 * is used to print the message.
443 */
444extern void avc_sid_stats(void);
445
446/**
447 * avc_netlink_open - Create a netlink socket and connect to the kernel.
448 */
449extern int avc_netlink_open(int blocking);
450
451/**
452 * avc_netlink_loop - Wait for netlink messages from the kernel
453 */
454extern void avc_netlink_loop(void);
455
456/**
457 * avc_netlink_close - Close the netlink socket
458 */
459extern void avc_netlink_close(void);
460
461/**
462 * avc_netlink_acquire_fd - Acquire netlink socket fd.
463 *
464 * Allows the application to manage messages from the netlink socket in
465 * its own main loop.
466 */
467extern int avc_netlink_acquire_fd(void);
468
469/**
470 * avc_netlink_release_fd - Release netlink socket fd.
471 *
472 * Returns ownership of the netlink socket to the library.
473 */
474extern void avc_netlink_release_fd(void);
475
476/**
477 * avc_netlink_check_nb - Check netlink socket for new messages.
478 *
479 * Called by the application when using avc_netlink_acquire_fd() to
480 * process kernel netlink events.
481 */
482extern int avc_netlink_check_nb(void);
483
484/**
485 * selinux_status_open - Open and map SELinux kernel status page
486 *
487 */
488extern int selinux_status_open(int fallback);
489
490/**
491 * selinux_status_close - Unmap and close SELinux kernel status page
492 *
493 */
494extern void selinux_status_close(void);
495
496/**
497 * selinux_status_updated - Inform us whether the kernel status has been updated
498 *
499 */
500extern int selinux_status_updated(void);
501
502/**
503 * selinux_status_getenforce - Get the enforce flag value
504 *
505 */
506extern int selinux_status_getenforce(void);
507
508/**
509 * selinux_status_policyload - Get the number of policy reloaded
510 *
511 */
512extern int selinux_status_policyload(void);
513
514/**
515 * selinux_status_deny_unknown - Get the behavior for undefined classes/permissions
516 *
517 */
518extern int selinux_status_deny_unknown(void);
519
520#ifdef __cplusplus
521}
522#endif
523#endif /* _SELINUX_AVC_H_ */
524

source code of include/selinux/avc.h