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