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 int avc_sid_to_context(security_id_t sid, char ** ctx); 41 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 int avc_context_to_sid(const char * ctx, security_id_t * sid); 55 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 void avc_sid_stats(void); 433 434 /** 435 * avc_netlink_open - Create a netlink socket and connect to the kernel. 436 */ 437 int avc_netlink_open(int blocking); 438 439 /** 440 * avc_netlink_loop - Wait for netlink messages from the kernel 441 */ 442 void avc_netlink_loop(void); 443 444 /** 445 * avc_netlink_close - Close the netlink socket 446 */ 447 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 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 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 int avc_netlink_check_nb(void); 471 472 /** 473 * selinux_status_open - Open and map SELinux kernel status page 474 * 475 */ 476 int selinux_status_open(int fallback); 477 478 /** 479 * selinux_status_close - Unmap and close SELinux kernel status page 480 * 481 */ 482 void selinux_status_close(void); 483 484 /** 485 * selinux_status_updated - Inform us whether the kernel status has been updated 486 * 487 */ 488 int selinux_status_updated(void); 489 490 /** 491 * selinux_status_getenforce - Get the enforce flag value 492 * 493 */ 494 int selinux_status_getenforce(void); 495 496 /** 497 * selinux_status_policyload - Get the number of policy reloaded 498 * 499 */ 500 int selinux_status_policyload(void); 501 502 /** 503 * selinux_status_deny_unknown - Get the behavior for undefined classes/permissions 504 * 505 */ 506 int selinux_status_deny_unknown(void); 507 508 #ifdef __cplusplus 509 } 510 #endif 511 #endif /* _SELINUX_AVC_H_ */ 512