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 */ 40int avc_sid_to_context(security_id_t sid, char ** ctx); 41int 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 */ 54int avc_context_to_sid(const char * ctx, security_id_t * sid); 55int 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 */ 67int 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 */ 79int 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 */ 90int avc_get_initial_sid(const char *name, security_id_t * sid); 91 92/* 93 * AVC entry 94 */ 95struct avc_entry; 96struct 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 */ 122struct 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 131struct 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 144struct 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 152struct 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 */ 191int 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 */ 206int 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 */ 216void 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 */ 226int 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 */ 237void 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 */ 260int 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 */ 284int 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 */ 307void 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 */ 325int 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 */ 343int 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 */ 376int 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 394struct 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 */ 414void 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 */ 423void 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 */ 432void avc_sid_stats(void); 433 434/** 435 * avc_netlink_open - Create a netlink socket and connect to the kernel. 436 */ 437int avc_netlink_open(int blocking); 438 439/** 440 * avc_netlink_loop - Wait for netlink messages from the kernel 441 */ 442void avc_netlink_loop(void); 443 444/** 445 * avc_netlink_close - Close the netlink socket 446 */ 447void 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 */ 455int 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 */ 462void 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 */ 470int avc_netlink_check_nb(void); 471 472/** 473 * selinux_status_open - Open and map SELinux kernel status page 474 * 475 */ 476int selinux_status_open(int fallback); 477 478/** 479 * selinux_status_close - Unmap and close SELinux kernel status page 480 * 481 */ 482void selinux_status_close(void); 483 484/** 485 * selinux_status_updated - Inform us whether the kernel status has been updated 486 * 487 */ 488int selinux_status_updated(void); 489 490/** 491 * selinux_status_getenforce - Get the enforce flag value 492 * 493 */ 494int selinux_status_getenforce(void); 495 496/** 497 * selinux_status_policyload - Get the number of policy reloaded 498 * 499 */ 500int selinux_status_policyload(void); 501 502/** 503 * selinux_status_deny_unknown - Get the behavior for undefined classes/permissions 504 * 505 */ 506int selinux_status_deny_unknown(void); 507 508#ifdef __cplusplus 509} 510#endif 511#endif /* _SELINUX_AVC_H_ */ 512