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 #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 */ 83 extern 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 */ 98 extern int avc_get_initial_sid(const char *name, security_id_t * sid); 99 100 /* 101 * AVC entry 102 */ 103 struct avc_entry; 104 struct 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 */ 130 struct 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 139 struct 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 152 struct 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 160 struct 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 */ 199 extern 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 */ 218 extern 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 */ 228 extern 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 */ 238 extern 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 */ 249 extern 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 */ 272 extern 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 */ 296 extern 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 */ 319 extern 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 */ 337 extern 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 */ 355 extern 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 */ 388 extern 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 406 struct 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 */ 426 extern 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 */ 435 extern 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 */ 444 extern void avc_sid_stats(void); 445 446 /** 447 * avc_netlink_open - Create a netlink socket and connect to the kernel. 448 */ 449 extern int avc_netlink_open(int blocking); 450 451 /** 452 * avc_netlink_loop - Wait for netlink messages from the kernel 453 */ 454 extern void avc_netlink_loop(void); 455 456 /** 457 * avc_netlink_close - Close the netlink socket 458 */ 459 extern 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 */ 467 extern 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 */ 474 extern 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 */ 482 extern int avc_netlink_check_nb(void); 483 484 /** 485 * selinux_status_open - Open and map SELinux kernel status page 486 * 487 */ 488 extern int selinux_status_open(int fallback); 489 490 /** 491 * selinux_status_close - Unmap and close SELinux kernel status page 492 * 493 */ 494 extern void selinux_status_close(void); 495 496 /** 497 * selinux_status_updated - Inform us whether the kernel status has been updated 498 * 499 */ 500 extern int selinux_status_updated(void); 501 502 /** 503 * selinux_status_getenforce - Get the enforce flag value 504 * 505 */ 506 extern int selinux_status_getenforce(void); 507 508 /** 509 * selinux_status_policyload - Get the number of policy reloaded 510 * 511 */ 512 extern int selinux_status_policyload(void); 513 514 /** 515 * selinux_status_deny_unknown - Get the behavior for undefined classes/permissions 516 * 517 */ 518 extern int selinux_status_deny_unknown(void); 519 520 #ifdef __cplusplus 521 } 522 #endif 523 #endif /* _SELINUX_AVC_H_ */ 524