/* * Access vector cache interface for object managers. * * Author : Eamon Walsh */ #ifndef _SELINUX_AVC_H_ #define _SELINUX_AVC_H_ #include #include #include #include #ifdef __cplusplus extern "C" { #endif /* * SID format and operations */ struct security_id { security_context_t ctx; unsigned int refcnt; }; typedef struct security_id *security_id_t; #define SECSID_WILD (security_id_t)NULL /* unspecified SID */ /** * avc_sid_to_context - get copy of context corresponding to SID. * @sid: input SID * @ctx: pointer to context reference * * Return a copy of the security context corresponding to the input * @sid in the memory referenced by @ctx. The caller is expected to * free the context with freecon(). Return %0 on success, -%1 on * failure, with @errno set to %ENOMEM if insufficient memory was * available to make the copy, or %EINVAL if the input SID is invalid. */ int avc_sid_to_context(security_id_t sid, security_context_t *ctx); /** * avc_context_to_sid - get SID for context. * @ctx: input security context * @sid: pointer to SID reference * * Look up security context @ctx in SID table, making * a new entry if @ctx is not found. Increment the * reference counter for the SID. Store a pointer * to the SID structure into the memory referenced by @sid, * returning %0 on success or -%1 on error with @errno set. */ int avc_context_to_sid(security_context_t ctx, security_id_t *sid); /** * sidget - increment SID reference counter. * @sid: SID reference * * Increment the reference counter for @sid, indicating that * @sid is in use by an (additional) object. Return the * new reference count, or zero if @sid is invalid (has zero * reference count). Note that avc_context_to_sid() also * increments reference counts. */ int sidget(security_id_t sid); /** * sidput - decrement SID reference counter. * @sid: SID reference * * Decrement the reference counter for @sid, indicating that * a reference to @sid is no longer in use. Return the * new reference count. When the reference count reaches * zero, the SID is invalid, and avc_context_to_sid() must * be called to obtain a new SID for the security context. */ int sidput(security_id_t sid); /* * AVC entry */ struct avc_entry; struct avc_entry_ref { struct avc_entry *ae; }; /** * avc_entry_ref_init - initialize an AVC entry reference. * @aeref: pointer to avc entry reference structure * * Use this macro to initialize an avc entry reference structure * before first use. These structures are passed to avc_has_perm(), * which stores cache entry references in them. They can increase * performance on repeated queries. */ #define avc_entry_ref_init(aeref) ((aeref)->ae = NULL) /* * User-provided callbacks for memory, auditing, and locking */ /* These structures are passed by reference to avc_init(). Passing * a NULL reference will cause the AVC to use a default. The default * memory callbacks are malloc() and free(). The default logging method * is to print on stderr. If no thread callbacks are passed, a separate * listening thread won't be started for kernel policy change messages. * If no locking callbacks are passed, no locking will take place. */ struct avc_memory_callback { /* malloc() equivalent. */ void *(*func_malloc)(size_t size); /* free() equivalent. */ void (*func_free) (void *ptr); /* Note that these functions should set errno on failure. If not, some avc routines may return -1 without errno set. */ }; struct avc_log_callback { /* log the printf-style format and arguments. */ void (*func_log)(const char *fmt, ...); /* store a string representation of auditdata (corresponding to the given security class) into msgbuf. */ void (*func_audit)(void *auditdata, security_class_t class, char *msgbuf, size_t msgbufsize); }; struct avc_thread_callback { /* create and start a thread, returning an opaque pointer to it; the thread should run the given function. */ void *(*func_create_thread)(void (*run)(void)); /* cancel a given thread and free its resources. */ void (*func_stop_thread)(void *thread); }; struct avc_lock_callback { /* create a lock and return an opaque pointer to it. */ void *(*func_alloc_lock)(void); /* obtain a given lock, blocking if necessary. */ void (*func_get_lock)(void *lock); /* release a given lock. */ void (*func_release_lock)(void *lock); /* destroy a given lock (free memory, etc.) */ void (*func_free_lock)(void *lock); }; /* * AVC operations */ /** * avc_init - Initialize the AVC. * @msgprefix: prefix for log messages * @mem_callbacks: user-supplied memory callbacks * @log_callbacks: user-supplied logging callbacks * @thread_callbacks: user-supplied threading callbacks * @lock_callbacks: user-supplied locking callbacks * * Initialize the access vector cache. Return %0 on * success or -%1 with @errno set on failure. * If @msgprefix is NULL, use "uavc". If any callback * structure references are NULL, use default methods * for those callbacks (see the definition of the callback * structures above). */ int avc_init(const char *msgprefix, const struct avc_memory_callback *mem_callbacks, const struct avc_log_callback *log_callbacks, const struct avc_thread_callback *thread_callbacks, const struct avc_lock_callback *lock_callbacks); /** * avc_cleanup - Remove unused SIDs and AVC entries. * * Search the SID table for SID structures with zero * reference counts, and remove them along with all * AVC entries that reference them. This can be used * to return memory to the system. */ void avc_cleanup(void); /** * avc_reset - Flush the cache and reset statistics. * * Remove all entries from the cache and reset all access * statistics (as returned by avc_cache_stats()) to zero. * The SID mapping is not affected. Return %0 on success, * -%1 with @errno set on error. */ int avc_reset(void); /** * avc_destroy - Free all AVC structures. * * Destroy all AVC structures and free all allocated * memory. User-supplied locking, memory, and audit * callbacks will be retained, but security-event * callbacks will not. All SID's will be invalidated. * User must call avc_init() if further use of AVC is desired. */ void avc_destroy(void); /** * avc_has_perm_noaudit - Check permissions but perform no auditing. * @ssid: source security identifier * @tsid: target security identifier * @tclass: target security class * @requested: requested permissions, interpreted based on @tclass * @aeref: AVC entry reference * @avd: access vector decisions * * Check the AVC to determine whether the @requested permissions are granted * for the SID pair (@ssid, @tsid), interpreting the permissions * based on @tclass, and call the security server on a cache miss to obtain * a new decision and add it to the cache. Update @aeref to refer to an AVC * entry with the resulting decisions, and return a copy of the decisions * in @avd. Return %0 if all @requested permissions are granted, -%1 with * @errno set to %EACCES if any permissions are denied, or to another value * upon other errors. This function is typically called by avc_has_perm(), * but may also be called directly to separate permission checking from * auditing, e.g. in cases where a lock must be held for the check but * should be released for the auditing. */ int avc_has_perm_noaudit(security_id_t ssid, security_id_t tsid, security_class_t tclass, access_vector_t requested, struct avc_entry_ref *aeref, struct av_decision *avd); /** * avc_has_perm - Check permissions and perform any appropriate auditing. * @ssid: source security identifier * @tsid: target security identifier * @tclass: target security class * @requested: requested permissions, interpreted based on @tclass * @aeref: AVC entry reference * @auditdata: auxiliary audit data * * Check the AVC to determine whether the @requested permissions are granted * for the SID pair (@ssid, @tsid), interpreting the permissions * based on @tclass, and call the security server on a cache miss to obtain * a new decision and add it to the cache. Update @aeref to refer to an AVC * entry with the resulting decisions. Audit the granting or denial of * permissions in accordance with the policy. Return %0 if all @requested * permissions are granted, -%1 with @errno set to %EACCES if any permissions * are denied or to another value upon other errors. */ int avc_has_perm(security_id_t ssid, security_id_t tsid, security_class_t tclass, access_vector_t requested, struct avc_entry_ref *aeref, void *auditdata); /** * avc_audit - Audit the granting or denial of permissions. * @ssid: source security identifier * @tsid: target security identifier * @tclass: target security class * @requested: requested permissions * @avd: access vector decisions * @result: result from avc_has_perm_noaudit * @auditdata: auxiliary audit data * * Audit the granting or denial of permissions in accordance * with the policy. This function is typically called by * avc_has_perm() after a permission check, but can also be * called directly by callers who use avc_has_perm_noaudit() * in order to separate the permission check from the auditing. * For example, this separation is useful when the permission check must * be performed under a lock, to allow the lock to be released * before calling the auditing code. */ void avc_audit(security_id_t ssid, security_id_t tsid, security_class_t tclass, access_vector_t requested, struct av_decision *avd, int result, void *auditdata); /* * security event callback facility */ /* security events */ #define AVC_CALLBACK_GRANT 1 #define AVC_CALLBACK_TRY_REVOKE 2 #define AVC_CALLBACK_REVOKE 4 #define AVC_CALLBACK_RESET 8 #define AVC_CALLBACK_AUDITALLOW_ENABLE 16 #define AVC_CALLBACK_AUDITALLOW_DISABLE 32 #define AVC_CALLBACK_AUDITDENY_ENABLE 64 #define AVC_CALLBACK_AUDITDENY_DISABLE 128 /** * avc_add_callback - Register a callback for security events. * @callback: callback function * @events: bitwise OR of desired security events * @ssid: source security identifier or %SECSID_WILD * @tsid: target security identifier or %SECSID_WILD * @tclass: target security class * @perms: permissions * * Register a callback function for events in the set @events * related to the SID pair (@ssid, @tsid) and * and the permissions @perms, interpreting * @perms based on @tclass. Returns %0 on success or * -%1 if insufficient memory exists to add the callback. */ int avc_add_callback(int (*callback)(u_int32_t event, security_id_t ssid, security_id_t tsid, security_class_t tclass, access_vector_t perms, access_vector_t *out_retained), u_int32_t events, security_id_t ssid, security_id_t tsid, security_class_t tclass, access_vector_t perms); /* * AVC statistics */ /* If set, cache statistics are tracked. This may * become a compile-time option in the future. */ #define AVC_CACHE_STATS 1 struct avc_cache_stats { unsigned entry_lookups; unsigned entry_hits; unsigned entry_misses; unsigned entry_discards; unsigned cav_lookups; unsigned cav_hits; unsigned cav_probes; unsigned cav_misses; }; /** * avc_cache_stats - get cache access statistics. * @stats: reference to statistics structure * * Fill the supplied structure with information about AVC * activity since the last call to avc_init() or * avc_reset(). See the structure definition for * details. */ void avc_cache_stats(struct avc_cache_stats *stats); /** * avc_av_stats - log av table statistics. * * Log a message with information about the size and * distribution of the access vector table. The audit * callback is used to print the message. */ void avc_av_stats(void); /** * avc_sid_stats - log SID table statistics. * * Log a message with information about the size and * distribution of the SID table. The audit callback * is used to print the message. */ void avc_sid_stats(void); #ifdef __cplusplus } #endif #endif /* _SELINUX_AVC_H_ */