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