next up previous contents
Next: Interfaces for the Security Up: Access Vector Cache Previous: Access Vector Cache   Contents

Interfaces for the Kernel

The data types and function prototypes for the AVC interfaces provided for the kernel object managers are in the include/linux/flask/avc.h header file. These interfaces are used by the kernel object managers to perform permission checks and to notify the AVC of completed operations. This subsection describes each of the data types and interfaces used by the kernel object managers. For each data type and function prototype, the type or prototype definition is listed followed by a description of the type or function.

void avc_init(void);

The avc_init function initializes the AVC. The kernel calls this function after the support for dynamic memory allocation has been initialized (init/main.c:start_kernel) so that the AVC may allocate memory using kmalloc. Alternatively, the AVC could be changed to reserve low memory for its use during the kernel initialization.

typedef struct avc_entry_ref {  
        avc_entry_t *ae;	
} avc_entry_ref_t;

#define AVC_ENTRY_REF_INIT(h) \
{ (h)->ae = NULL; }

#define AVC_ENTRY_REF_CPY(dst,src) \
(dst)->ae = (src)->ae

The AVC entry reference type (avc_entry_ref_t) consists of a pointer to an entry in the AVC. The AVC returns a reference to the entry used for a permission check. An object manager may save this reference with the corresponding object for subsequent use in other permission checks on the object. An object manager must initialize a reference before its first use with the AVC_ENTRY_REF_INIT macro. An object manager may copy a reference with the AVC_ENTRY_REF_CPY macro. AVC entry references should only be dereferenced by the AVC functions.

typedef struct avc_audit_data {
    char    type;
#define AVC_AUDIT_DATA_FS   1	
#define AVC_AUDIT_DATA_NET  2
    union     {
        struct {
            struct dentry *dentry;
            struct inode *inode;
        } fs;
        struct {
            char *netif;
            struct sk_buff *skb;
            struct sock *sk;
            __u16 port;
            __u32 daddr;
        } net;
    } u;
} avc_audit_data_t;

#define AVC_AUDIT_DATA_INIT(_d,_t) \
{ memset((_d), 0, \
  sizeof(struct avc_audit_data)); \
  (_d)->type = AVC_AUDIT_DATA_##_t; }

The AVC audit data type (avc_audit_data_t) consists of object or parameter information provided by the object manager for the AVC to use when a permission check is audited. This data supplements the audit information directly available to the AVC (i.e. the SID pair, the class, the requested permissions, and information about the current process). The type field indicates what type of data is being provided by the object manager to the AVC. Currently, two types are supported: file system (AVC_AUDIT_DATA_FS) and networking (AVC_AUDIT_DATA_NET). The AVC_AUDIT_DATA_INIT macro may be used to initialize the data with a specified type.

If the file system type is used, then the object manager may set either of the fields in the fs structure to identify the file involved in a permission check. If a dentry for the file is available, then the dentry field should be set. Otherwise, the inode for the file may be set.

If the networking type is used, then the object manager may set any of the fields in the net structure. The netif field may be set to identify a network interface. The skb field may be set to identify a packet. The sk field may be set to identify a socket. The port field may be set to identify a port number. The daddr field may be set to identify an IPv4 address.

inline int avc_has_perm_ref_audit(
        security_id_t ssid,
        security_id_t tsid,
        security_class_t tclass,
        access_vector_t requested,
        avc_entry_ref_t *aeref,
        avc_audit_data_t *auditdata);

The avc_has_perm_ref_audit inline function determines whether the requested permissions are granted for the specified SID pair and class. If aeref refers to a valid AVC entry for this permission check, then the referenced entry is used. Otherwise, this function obtains a valid entry and sets aeref to refer to this entry. To obtain a valid entry, this function first searches the cache. If this fails, then this function calls the security_compute_av interface of the security server to compute the access vectors and adds a new entry to the cache. If the appropriate audit access vector (auditallow or auditdeny) in the entry indicates that the permission check should be audited, then this function audits the permission check, using the auditdata parameter to supplement the audit information.

This function returns 0 if permission is granted. If the security server returns an error upon a security_compute_av call, then this function returns that error. If the security server returns a sequence number that is less than the latest policy change sequence number, then this function discards the security server response and returns -EAGAIN. If permission is denied, then this function returns -EACCES.

The kernel object managers call this function to perform permission checks. Kernel object managers may also use variants of this function, such as avc_has_perm, avc_has_perm_audit, and avc_has_perm_ref, in order to omit the reference or audit data parameters. Kernel object managers may also use macro versions of this function, such as AVC_HAS_PERM_REF, AVC_HAS_PERM, and AVC_HAS_PERM_AUDIT, in order to automatically include the class name in the permission symbol.

inline int avc_notify_perm_ref(
        security_id_t ssid,
        security_id_t tsid,
        security_class_t tclass,
        access_vector_t requested,
        avc_entry_ref_t *aeref)

The avc_notify_perm_ref inline function notifies the AVC component that an operation associated with the requested permissions has completed successfully. If any of the requested permissions are in the notify access vector of the corresponding AVC entry, then this function calls the security_notify_perm interface of the security server to notify the security server that the operation has completed successfully. If aeref refers to a valid AVC entry for the requested permissions, then the referenced entry is used to obtain the notify vector. Otherwise, this function obtains a valid entry and sets aeref to refer to this entry in the same manner as avc_has_perm_ref_audit.

This function returns 0 if the notification is successful. If the security server returns an error upon a security_compute_av call or a security_notify_perm call, then this function returns that error. If the security server returns a sequence number that is less than the latest policy change sequence number, then this function discards the security server response and returns -EAGAIN.

The kernel object managers have not yet been changed to call this function. Kernel object managers may also use a variant of this function, avc_notify_perm, in order to omit the reference parameter. Kernel object managers may also use macro versions of this function, such as AVC_NOTIFY_PERM_REF and AVC_NOTIFY_PERM, in order to automatically include the class name in the permission symbol.

#define AVC_CALLBACK_GRANT 	1
#define AVC_CALLBACK_TRY_REVOKE 2
#define AVC_CALLBACK_REVOKE     4
#define AVC_CALLBACK_RESET      8
#ifdef CONFIG_FLASK_AUDIT
#define AVC_CALLBACK_AUDITALLOW_ENABLE  16
#define AVC_CALLBACK_AUDITALLOW_DISABLE 32
#define AVC_CALLBACK_AUDITDENY_ENABLE   64
#define AVC_CALLBACK_AUDITDENY_DISABLE 128
#endif
#ifdef CONFIG_FLASK_NOTIFY
#define AVC_CALLBACK_NOTIFY_ENABLE     256
#define AVC_CALLBACK_NOTIFY_DISABLE    512
#endif

int avc_add_callback(
    int (*callback)(
            __u32 event, 
            security_id_t ssid,
            security_id_t tsid,
            security_class_t tclass,
            access_vector_t perms,
            access_vector_t *out_retained),
    __u32 events,
    security_id_t ssid,
    security_id_t tsid,
    security_class_t tclass,
    access_vector_t perms);

The avc_add_callback function registers an object manager callback function callback with the AVC component for policy change notifications. When the security server calls an AVC interface that corresponds to an event in the set events with a SID pair, class and permissions that match ssid, tsid, tclass and perms, the AVC component calls the registered callback function with the parameters provided by the security server. The callback function may then update any affected permissions that are retained in the state of the object manager. The wildcard SID, SECSID_WILD, may be used for the ssid and tsid parameters to match all SID values. Permission vectors match if they have a non-null intersection. The meaning of each event value is explained in the description of the corresponding interface in the next subsection. Callback functions have not yet been implemented for the kernel object managers, so this function is not currently called.


next up previous contents
Next: Interfaces for the Security Up: Access Vector Cache Previous: Access Vector Cache   Contents