next up previous contents
Next: System Calls for Applications Up: Security Server Previous: Architecture Types and Constants   Contents

Interfaces for the Kernel

The function prototypes for the security server interfaces provided for the kernel object managers are in the include/linux/flask/security.h header file. This subsection describes each of these interfaces. For each interface, the function prototype is listed followed by a description of the interface and a discussion of how the interface is currently used by the kernel object managers.

int security_init(void);

The security_init function initializes the security server. The kernel calls this function after the root file system is mounted (fs/super.c:mount_root) so that the security server may read configuration data from the root file system.

int security_compute_av(
        security_id_t ssid,
        security_id_t tsid,
        security_class_t tclass,
        access_vector_t requested,
        access_vector_t *allowed,
        access_vector_t *decided,
#ifdef CONFIG_FLASK_AUDIT
        access_vector_t *auditallow,
        access_vector_t *auditdeny,
#endif
#ifdef CONFIG_FLASK_NOTIFY
        access_vector_t *notify,
#endif
        __u32 *seqno);

The security_compute_av function computes access vectors based on a SID pair for the permissions in a particular class. The access vector cache (AVC) component calls this function when no valid entry exists for the requested permissions in the cache (include/linux/flask/avc.h:avc_has_perm_ref_audit). The first SID parameter, ssid, is referred to as the source SID and the second SID parameter, tsid, is referred to as the target SID. The returned access vectors must contain decisions for every permission specified in the requested access vector.

The security server may optionally return decisions for other permissions in the same class. The decided access vector contains the set of permissions for which a decision was returned. The other returned access vectors may only be used for permissions in this set. The security server may choose to defer computation of permissions until they are explicitly requested.

The allowed access vector contains the set of granted permissions. The seqno parameter contains a sequence number associated with the access granting. If the sequence number provided by the latest policy change is greater than this value, then the access granting may be invalid and must be discarded. The sequence number addresses the issue of an interleaving of an access granting and a policy change.

Two additional access vectors are returned if auditing support is enabled in the kernel configuration. The auditallow and auditdeny access vectors contain the set of permissions that should be audited when granted or when denied, respectively. These vectors enable the security server to precisely control the auditing of permission checks. The AVC component ensures that auditing is performed in accordance with these vectors (avc_has_perm_ref_audit).

One additional access vector is returned if notification support is enabled in the kernel configuration. The notify access vector contains the set of permissions for which the security_notify_perm function should be called when the operation associated with the permission has successfully completed. This vector permits the security server to request that the AVC component notify the security server of the successful completion of operations so that the security server may base its decisions on the history of operations in the system. This differs from merely basing decisions on the history of granted permissions, since an operation may still fail due to other conditions even if permission is granted for that operation. To support this functionality, the kernel object managers must be changed to notify the AVC component of the successful completion of operations by calling the include/linux/flask/avc.h:avc_notify_perm_ref inline function. The AVC component may then notify the security server if any of the requested permissions are in the corresponding notify vector. The necessary changes to the kernel object managers to notify the AVC component have not yet been implemented.

int security_notify_perm(
        security_id_t ssid,
        security_id_t tsid,
        security_class_t tclass,
        access_vector_t requested);

The security_notify_perm function notifies the security server that an operation associated with the permissions in the requested access vector has completed successfully. The AVC component calls this function when it is called by an object manager to indicate that the operation has completed successfully if any of the requested permissions are in the corresponding notify vector (include/linux/flask/avc.h:avc_notify_perm_ref). Since the kernel object managers have not yet been changed to notify the AVC of operation completion, this function is currently never called.

int security_transition_sid(
        security_id_t ssid,
        security_id_t tsid,
        security_class_t tclass,
        security_id_t *out_sid);

The security_transition_sid function computes a SID for a new object based on a SID pair and a class. The kernel object managers call this function when objects are created if a SID was not specified for the object and there is more than one relevant SID that might be used as input in determining the SID of the new object. In particular, the file system code calls this function to obtain the SID of a new file based on the SID of the creating process and the SID of the parent directory, and the process management code calls this function to obtain the SID of a process transformed by an execve based on the current SID of the process and the SID of the executable program.

int security_member_sid(
        security_id_t ssid,
        security_id_t tsid,
        security_class_t tclass,
        security_id_t *out_sid);

The security_member_sid function computes a SID to use when selecting a member of a polyinstantiated object based on a SID pair and a class. Certain fixed resources, such as the /tmp directory or the TCP/UDP port number spaces, need be polyinstantiated to restrict sharing among processes. Each instantiation is referred to as a member. The kernel object managers call this function when a polyinstantiated object is accessed and then transparently redirect the process to the appropriate member. The necessary changes to the file system code and the networking code to support polyinstantiated directories and port number spaces are not yet implemented, so this function is currently never called.

int security_change_sid(
        security_id_t ssid,
        security_id_t tsid,
        security_class_t tclass,
        security_id_t *out_sid);

The security_change_sid function computes a SID to use when relabeling an object based on a SID pair and a class. The login program will be modified to call this interface to obtain the SID to use when relabeling devices for a user session, based on the SID for the user session and the current SID of the device. This modification to login has not yet been implemented.

int security_sid_to_context(
        security_id_t  sid,
        security_context_t *scontext,
        __u32   *scontext_len);

The security_sid_to_context function returns the security context associated with a particular SID. The AVC component calls this function to obtain both security contexts for a SID pair when writing an audit record. The file system code calls this function to obtain a security context to use when adding an entry to the persistent label mapping. The procfs code calls this function to obtain the security context of a process to include in its status file. The scontext parameter is set to point to a dynamically-allocated string of the correct size. The scontext_len parameter is set to the length of the security context string, including the terminating NULL character. The string is allocated using kmalloc and must be freed with kfree by the caller.

int security_context_to_sid(
        security_context_t scontext,
        __u32   scontext_len,
        security_id_t *out_sid);

The security_context_to_sid function returns a SID associated with a particular security context. The file system code calls this function to obtain the SID that corresponds to a security context stored in the persistent label mapping. The scontext_len parameter specifies the length of the security context string, including the terminating NULL character.

int security_fs_sid(
        char *dev,
        security_id_t *fs_sid,
        security_id_t *file_sid);

The security_fs_sid function returns SIDs to use for an unlabeled file system mounted from the device specified by dev. The file system code calls this function when a process attempts to mount an unlabeled file system. The value for the dev parameter is a string of the form ``major:minor'' where both the major and minor number are in hexadecimal and are right justified in a two character field, as returned by the kdevname function on the device number. The fs_sid parameter is set to the SID to use for the file system, and the file_sid parameter is set to the SID to use for any existing files in the file system.

int security_port_sid(
        __u16 domain,
        __u16 type,
        __u8 protocol,
        __u16 port,
        security_id_t *out_sid);

The security_port_sid function returns the SID to use for the port number port in the protocol specified by the triple (domain, type, protocol). The networking code calls this function when a process attempts to bind a port outside of the range used to automatically bind sockets.

int security_netif_sid(
        char *name,
        security_id_t *if_sid,
        security_id_t *msg_sid);

The security_netif_sid function returns SIDs to use for a network interface. The networking code calls this function when a process first attempts to configure a network interface. The value for the name parameter is typically the driver name followed by the unit number, e.g. the name eth0 would be used for the first Ethernet interface. The if_sid parameter is set to the SID to use for the interface, and the msg_sid parameter is set to the SID to use for any unlabeled messages received on the interface.

int security_node_sid(
        __u16 domain,
        void *addr,
        __u32 addrlen,
        security_id_t *out_sid);

The security_node_sid function returns the SID to use for the node whose address is specified by addr. The addrlen parameter specifies the length of the address in bytes, and the domain parameter specifies the communications domain or address family in which the address should be interpreted. The networking code calls this function when packets are sent to a node or received from a node.

int security_nfs_sid(
        __u16 domain,
        void *addr,
        __u32 addrlen,
        security_id_t *fs_sid,
        security_id_t *file_sid);

The security_nfs_sid function returns the SIDs to use for the file systems and files provided by the NFS server whose address is specified by addr. The addrlen parameter specifies the length of the address in bytes, and the domain parameter specifies the communications domain or address family in which the address should be interpreted. The NFS client code calls this function when a NFS file system is mounted.


next up previous contents
Next: System Calls for Applications Up: Security Server Previous: Architecture Types and Constants   Contents