Section 10.2. File-Related Object Labeling

10.2. File-Related Object Labeling

In SELinux, labeling most often refers to the labeling of file-related objects because this is the only form of label management that a normal user or administrator is likely to encounter. Much of the challenge with file labeling comes from the sheer number of files present on a normal system combined with the customization of how those files will be stored in the directory structure. The variety of filesystems available for Linux also contributes to the complexity. Common filesystems include traditional, native filesystems intended to store data on hard disks and removable media (for example, ext3 and XFS); non-native filesystems present for compatibility with other systems (for example, iso9660 and vfat); and in-memory, pseudo filesystems used for communication between the kernel and userspace (for example, proc and sysfs).

How file-related objects are labeled varies according to the intended purpose of the filesystem and the specific semantics of how the objects are created, stored, and used. For example, files stored persistently to hard disk using the ext3 filesystem are labeled when created and the security context stored with the file. In contrast, files in the proc filesystem exist only at runtime and must have their labels generated at runtime instead of stored persistently.

SELinux Mount Options

The context mount option (filesystems mounted with this option are often referred to in documentation as "mountpoint labeled") overrides the labeling behavior of any filesystem and applies a single security context to all of the file-related objects it contains. For example, consider the following mount command:

mount -t nfs -o context=user_u:object_r:user_home_t           gotham:/shares/homes/ /home/

In this example, the mount option context= user_u:object_r:user_home_t instructs SELinux to apply the specified security context to all file-related objects in the nfs filesystem mounted on the /home/ directory. The security context specified in the option, user_u:object_r:user_home_t in this example, will be applied to both existing and new files.

The context mount option works for all filesystems regardless of what labeling behavior they support or is specified in the policy. For example, filesystems that would normally use extended attribute labeling, such as ext3, can be mounted using the context option. (Although when mounted with the context option, new inodes do not receive any SELinux attributes on disk and existing on-disk inodes are not changed.) This is useful for removable media transferred from non-SELinux systems.

There are two related filesystem mount options, fscontext and defcontext, that may be used together or separately instead of the context option. The fscontext option is used to set or override the filesystem object instance security context (for example, to set the filesystem security context for an ext3 filesystem to something other than the default set for ext3 filesystems in the policy). The defcontext option is used to override the default file security context for a given filesystem. (The default file security context for filesystems is normally the file initial SID, which is explained later in this chapter.)

The standard nosuid mount option, besides negating standard Linux setuid/setgid behavior, also changes the behavior of SELinux for files on a filesystem. The nosuid option disables SELinux security context transitions for files labeled with enTRypoint types on the filesystem. It is possible to use the context mount option to achieve the same effect (that is, force all files to be labeled with an untrusted type), but the nosuid option is another good choice.

SELinux supports four kinds of labeling for file-related objects to address the various types of filesystems: extended attribute, task-based, transition-based, and generalized security contexts. The primary difference between these mechanisms is how SELinux determines the initial label of inodes for the filesystem. Security-extended attribute labeling also stores security contexts persistently to disk. Table 10-1 lists the filesystem labeling mechanisms and the filesystems that use each labeling mechanism on a Fedora Core 4 (FC4) system.

Table 10-1. Kinds of Filesystem Labeling Mechanisms and Associated Filesystems

Labeling Mechanism	Filesystems
Extended attributes	ext2, ext3, xfs, jfs, reiserfs
Task-based	pipefs, sockfs
Transition-based	devpts, tmpfs, shm, mqueue
Generalized	proc, rootfs, sysfs, selinuxfs, autofs, automount, usbdevfs, iso9660, udf, romfs, cramfs, ramfs, vfat, msdos, fat, ntfs, cifs, smbfs, nfs, nfs4, afs, debugfs, inotifyfs, hugetlbfs, capifs, eventpollfs, futexfs, bdev, usbfs, nfsd, rpc_pipefs, binfmt_misc

The kind of labeling is specified per filesystem in the policy using either the filesystem use statements or the generalized filesystem labeling support statement, normally called the genfscon statement. The SELinux policy language supports three filesystem use statements: fs_use_xattr, fs_use_task, and fs_use_trans, which specify extended attribute, task-based, and transition-based labeling behaviors, respectively.

The syntax for the all three filesystem use statements is identical (see the sidebar on page 211). As an example, consider the following fs_use_xattr statement:

fs_use_xattr ext3 system_u:object_r:fs_t;

This statement indicates that the ext3 filesystem (that is, all instances of ext3 on the system) will be labeled using security-extended attributes, and the filesystem object instance associated with all ext3 filesystems will be labeled with the security context system_u:object_r:fs_t. The filesystem name, ext3 in this example, is the same as that understood by the kernel and the mount(8) command. These names are listed in the file /proc/filesystems.

The generalized filesystem labeling support statement (genfscon) specifies both that the filesystem will use generalized filesystem security context labeling and how the individual file-related objects in that filesystem are labeled. The genfscon syntax is more complicated; we describe it later in this section.

Filesystem Use Statements Syntax

The filesystem use statements specify the labeling mechanism to be used for a kind of filesystem. The filesystem use statements begin with one of three keywords, which are marked in brackets. There can be only one filesystem use statement for each filesystem. The full syntax of the statements are as follows:

[fs_use_xattr | fs_use_task | fs_use_trans] fs_name fs_context

fs_name	The name of the filesystem that will use the specified labeling mechanism (for example, ext3). The filesystem names are the same as those understood by the kernel and mount(8) command and are listed in /proc/filesystems.
fs_context	The security context for the filesystem object instance associated with this filesystem.

The fs_use_xattr statement indicates that the filesystem will provide security context information (through its getxattr(2) method) using extended attributes. The fs_use_task statement indicates that the filesystem will use task-based labeling behavior, and the fs_use_trans statement indicates that the filesystem will use transition-based labeling behavior. The filesystem implementation must support the labeling behavior when using fs_use_xattr. (In the other cases, SELinux handles the labeling.)

The filesystem use statements are valid only in monolithic policies and base loadable modules. They are not valid in conditional statements or non-base loadable modules.

10.2.1. Extended Attribute Filesystems (fs_use_xattr)

Most native, disk-based Linux filesystems use extended attribute labeling. This labeling mechanism extends the standard extended attribute mechanisms to support setting, retrieving, and storing the security contexts associated with all file-related objects. (See the sidebar on page 212 for more details.) Filesystems that use this labeling mechanism support program-requested labeling and, when stored to persistent media, preserve the security contexts across reboots.

More on Security Contexts Using Extended Attributes

File-related resources stored in native Linux filesystems typically have important information about the resource, such as ownership and access mode, stored in a special data structure called an inode. In recent versions of Linux, additional information is associated with inodes in the form of extended attributes. Extended attributes, which store the additional information as name/value pairs, are used for storing system information, such as access control lists (ACLs), or other data required by some application or service. SELinux uses extended attributes to store the security context of all file-related objects.

The name portion of extended attributes is divided into multiple namespaces to allow different kinds of data to easily coexist. SELinux uses the security namespace, denoted by the prefix security., to store security contexts. This namespace is intended to be shared by all Linux Security Module (LSM) modules, so SELinux uses the name selinux to store the security contexts in the security namespace. To illustrate, let's directly examine the extended attributes of a file on SELinux:

# getfattr -n security.selinux /etc/shadow # file: etc/shadow security.selinux="system_u:object_r:shadow_t\000"

As you can see, the security context is stored directly as a string. Indeed, examining the extended attribute is how the ls -Z command displays security contexts for file-related objects. We recommend always using the libselinux API (for example, getfilecon(3)) instead of using the extended attribute API directly because the storage of the security context may change over time.

10.2.1.1. Labeling Behavior for Extended Attribute Filesystems

Labeling decisions for extended attribute filesystems use a combination of policy rules and security context inheritance. By default, all new file-related objects inherit the type of the containing directory and the user of the creating process. The role is always set to the special object role object_r. If a type_transition rule matches the type of the creating process and the type of the directory that will contain the new object, the default type specified in that rule will be used for the type of the new file-related object. The rest of the security context is set in the same way as if there were no type_transition rule.

Program-requested labeling allows processes to request a specific security context for a new file using the setfscreatecon(3) library call. In this situation, the object will be created with the requested security context unless the process lacks the required access. Normally, only applications that extend SELinux or are an SELinux utility (that is, so-called SELinux-aware applications) use this feature; files created by standard applications receive the correct security context through the automatic labeling decision described previously.

In addition to setting security contexts on creation, file-related objects can be relabeled for extended attribute labeled filesystems. This is done with the setfilecon(3), lsetfilecon(3), and fsetfilecon(3) library calls. Explicitly changing the label of an object requires appropriate relabelfrom and relabelto permissions, which should be tightly controlled by the policy. (See the sidebar on page 213 for more information.)

Policy Control of Object Labeling

The ability to change the security context of an object is a powerful privilege. Recall from Chapter 4, "Object Classes and Permissions," that the policy controls changing of types on file-related objects with relabelfrom and relabelto permissions for most object classes. The relabelfrom permission controls the starting type for the object, and the relabelto permission controls the resulting type; a domain must have both permissions to successfully relabel an object. For example, consider the following allow rules:

allow user_t user_home_t : file { relabelfrom }; allow user_t httpd_user_content_t : file { relabelto }; 

These allow rules state that a process with the type user_t is allowed to relabel files from the type user_home_t to the type httpd_user_content_t.

The relabelto and relabelfrom permissions control only changes to the type of the object. We saw in Chapter 7, "Constraints," that changing the user and role portions of security contexts can be controlled by constraints. For example, consider the following constraint:

constrain file { create relabelto relabelfrom } ( u1 == u2 or t1 == privowner ); 

This constraint states that when a process requests create relabelto, or relabelfrom permission on a file, the user portion of the security context must match that of the process or the process type must have the privowner attribute.

10.2.1.2. Managing Security Contexts in Extended Attribute Filesystems (File Contexts)

The labeling of file-related objects using extended attributes differs from the other filesystem and most other nonfile object classes. The security contexts using extended attributes are initialized, normally during installation with a package manager such as rpm, using runtime labeling requests. The runtime labeling requests are directed by one or more configuration files, called file context files, which list paths, or partial paths, and security contexts. The file context files are not included directly within the policy but are stored with it on the filesystem in a standard location (see Chapter 13, "Managing an SELinux System"). By using the appropriate file context files for a policy, the file-related object security contexts can be correctly initialized based on path name. Initialization puts the system in a known, secure state. After initialization, the automatic labeling decisions take over and ensure that any files created subsequently are correctly labeled and a secure state is always maintained.

This label management strategy is used to separate the policy, which deals primarily with types and security contexts, from path names and filenames. This strategy has several advantages. First, the layout of filesystems can vary greatly because of differences between distributions or user customization. By removing this aspect of variability from the policy, a single policy can be more easily adapted to multiple systems.

More important, in native Linux filesystems, file-related objects are not uniquely identified by a single path name. Hard links, chroot environments, and per-process filesystem namespaces all mean that a single file-related object could be identified by several path names. If the policy were enforced within the kernel using path names directly, there would be no way to determine which of these names was the correct one to use, possibly leading to a process having different access to the same object depending on how the access was attempted. For this reason, SELinux associates the security context directly with the object and uses only paths to initialize the security context. Only if initialization occurs when the system is in a protected, known-secure state (for example, during installation) is it safe from this ambiguity.

The format of a line in the file context files is a regular expression representing one or more file-related object paths, an optional object class specification, and a security context. For example, consider the following portion of a file context file:

 1  /bin(/.*)?                  system_u:object_r:bin_t 2  /bin/tcsh            --     system_u:object_r:shell_exec_t 3  /bin/bash            --     system_u:object_r:shell_exec_t 4  /bin/bash2           --     system_u:object_r:shell_exec_t 5  /bin/sash            --     system_u:object_r:shell_exec_t 6  /bin/d?ash           --     system_u:object_r:shell_exec_t 7  /bin/zsh.*           --     system_u:object_r:shell_exec_t 8  /usr/sbin/sesh       --     system_u:object_r:shell_exec_t 9  /bin/ls              --     system_u:object_r:ls_exec_t 10 /boot(/.*)?                 system_u:object_r:boot_t 11 /boot/System\.map(-.*)?     system_u:object_r:system_map_t 12 /dev(/.*)?                  system_u:object_r:device_t 13 /dev/pts(/.*)?              <<none>> 14 /dev/cpu/.*          -c     system_u:object_r:cpu_device_t 15 /dev/microcode       -c     system_u:object_r:cpu_device_t 16 /dev/MAKEDEV         --     system_u:object_r:sbin_t 17 /dev/null            -c     system_u:object_r:null_device_t 18 /dev/full            -c     system_u:object_r:null_device_t 19 /dev/zero            -c     system_u:object_r:zero_device_t

This example specifies how the files in the /bin/, /boot/, and part of /dev/ directories should be labeled. For example, line 3 is a simple entry that matches the filename /bin/bash and specifies that it should be labeled with the security context system_u:object_r:shell_exec_t. The object class specification is in this case, which means a regular file. The object class specifications are the same as those understood by the command find(1).

When processes query the file contexts, files using the matchpathcon(3) library call to match the name of a file-related object, the most specific entry is always used. For example, line 1 has a regular expression that will match all files in the /bin/ directory. If there is no object class specifier, as is the case in line 1, it will match all file-related objects. Lines 2 through 9, however, have regular expressions that are more specific and will match some files in the /bin/ directory. When the match for /bin/bash is requested, line 3 will match because it is an exact match. The file /bin/dd, however, has no more specific match than line 1.

Line 13 uses the special <<none>> syntax to specify that file-related objects that match this entry should not be labeled. This is used for files that must be labeled at runtime. Entries with <<none>> are used to prevent other, more general regular expressions from matching and causing the file-related objects to be labeled.

Many different utilities and applications use file contexts files, often during policy development and system administration. Chapter 13 describes these tools and their intended use.

10.2.2. Task-Based Filesystems (fs_use_task)

With task-based labeling, new file-related objects inherit their security context from the creating process. Filesystems that use task-based labeling do not support program-requested labeling. This type of labeling behavior is useful for simple pseudo filesystems that are not truly intended to store user data but rather are designed to support certain kinds of kernel resources such as unnamed pipes. For example, consider the following fs_use_task statement:

fs_use_task pipefs system_u:object_r:fs_t;

This statement specifies that the pipefs filesystem uses task-based labeling and that the security context for the filesystem object for pipfs is system_u:object_r:fs_t.

The pipefs filesystem is a good example of a filesystem that uses task-based labeling. This filesystem is a pseudo filesystem used to implement unnamed pipes. Unnamed pipes, created with the pipe(2) system call, are by their very nature not associated with a file in a user-space visible filesystem. Despite this, communications over pipes is done using standard read and write system calls on file descriptors. The Linux implementation, therefore, uses a special-purpose filesystem called pipefs that is not visible to userspace. The filesystem is mounted and used by the kernel internally and labeled using task labeling.

10.2.3. Transition-Based Filesystems (fs_use_trans)

Transition-based filesystem labeling is similar to task-based labeling. Both are normally used for simple pseudo filesystems. However, instead of using the security context from the creating process, transition-based labeling sets the security context of file-related objects based on type transition (type_transition) rules.

Type transition rules for transition-based labeling are subtly different from those for the more common extended attribute mechanism. On extended attribute labeled filesystems, labeling decisions use the security context of the creating process and the containing directory. For transition-based labeled filesystems, the type_transition rules use the security context of the creating process and the security context of the associated filesystem object instance for the filesystem. No provision exists for basing the security context of a new object on the context of the containing directory; the security context is always based on the type of the associated filesystem object. If there is not a relevant type_transition rule, the security context defaults to that of the filesystem object.

Consider the following filesystem use statement:

fs_use_trans devpts system_u:object_r:devpts_t;

This statement specifies that the devpts filesystem uses transition-based labeling. The security context for the devpts filesystem object is specified as system_u:object_r:devpts_t.

As mentioned previously, transition-based labeled filesystems use type_transition rules to derive the type for file-related objects. For example, consider the following type transition rule:

type_transition sysadm_t devpts_t : chr_file sysadm_devpts_t;

This rule states that when processes with the type sysadm_t create objects of chr_file class in filesystems labeled devpts_t, the resulting object should be labeled sysadm_devpts_t. The implied object class for the target of this type transition is filesystem rather than dir because this type transition will apply to the creation of objects in a transition-based filesystem regardless of the directory type. If there is no appropriate type_transition rule, any objects created on this filesystem will have the filesystem security context.

10.2.4. Generalized Security Context Labeling (genfscon)

The generalized security context statement (genfscon) is used for runtime labeling of pseudo filesystems, such as proc or sysfs, and legacy filesystems that do not support extended attributes. Unlike the other filesystem labeling mechanisms discussed so far, which require modification of the kernel filesystem code, genfscon labeling, at least in a limited form, can be used with unmodified filesystems.

The genfscon statement specifies both the labeling mechanism for the filesystem and the labeling for the file-related objects stored in the filesystem. There are two forms of genfscon statements: a full form that specifies fine-grained labeling for file-related objects and a limited form useful for legacy filesystems.

10.2.4.1. Fine-Grained Labeling with genfscon Statement

Consider the following example of the full-feature genfscon statements for the proc filesystem:

1  genfscon proc /                  system_u:object_r:proc_t 2  genfscon proc /kmsg              system_u:object_r:proc_kmsg_t 3  genfscon proc /kcore             system_u:object_r:proc_kcore_t 4  genfscon proc /mdstat            system_u:object_r:proc_mdstat_t 5  genfscon proc /mtrr              system_u:object_r:mtrr_device_t 6  genfscon proc /net               system_u:object_r:proc_net_t 7  genfscon proc /sysvipc           system_u:object_r:proc_t 8  genfscon proc /sys               system_u:object_r:sysctl_t 9  genfscon proc /sys/kernel        system_u:object_r:sysctl_kernel_t 10 genfscon proc /sys/net           system_u:object_r:sysctl_net_t 11 genfscon proc /sys/vm            system_u:object_r:sysctl_vm_t 12 genfscon proc /sys/dev           system_u:object_r:sysctl_dev_t 13 genfscon proc /net/rpc           system_u:object_r:sysctl_rpc_t 14 genfscon proc /irq               system_u:object_r:sysctl_irq_t

As these example statements show, the genfscon statement syntax requires the name of the filesystem, a full or partial path name (relative to the root of the filesystem), and a security context. The full syntax for the genfscon statement can be found on page 220.

These example genfscon statements show that there can be multiple genfscon statements for the same filesystem. For filesystems that support this full form of the genfscon statement, the multiple statements are used to specify fine-grained labels for file-related objects. When multiple genfscon statements are present, the security context for file-related objects is determined by matching the genfscon statement with the most specific partial path name and using the security context from that statement.

For example, assume that the proc filesystem is mounted at /proc (the standard location). Using these example genfscon statements, the file /proc/filesystems would match the statement on line 1 and receive the security context system_u:object_r:proc_t. Similarly, the directory /proc/sys/kernel/ would match the genfscon statement on line 9 (with the partial path /sys/kernel) and be labeled system_u:object_r:sysctl_kernel_t.

All filesystems that use genfscon labeling include at least one genfscon statement with / as the partial path. The security context in this genfscon statement is used to label the filesystem object associated with the filesystem in addition to being the default security context for all file-related objects stored in the filesystem. In the preceding example, the filesystem object for proc would receive the security context system_u:object_r:proc_t.

Labeling PID Files in Proc

The proc filesystem contains files and directories representing every active process on the system. These files and directories, which are contained in a directory named with the process ID (PID) of the process, can be used to get or set properties of the process preferably through libselinux calls (for example, getcon(3), setcon(3)). The PID directory and all the files and directories that it contains receive the same security context as the process that they represent.

For this reason, it is not uncommon to see rules such as the following:

allow apache_t self : dir { read getattr search }; allow apache_t self : file { read getattr write };

Rules such as these allow a domain, apache_t in this example, access to the files and directories representing it.

10.2.4.2. Legacy Filesystem Labeling with the genfscon Statement

As mentioned previously, genfscon can be used in two ways. Before examining the more limited form of this statement intended for legacy filesystems, let's examine some properties of the proc filesystem that make it work well with the full genfscon statement. This will help you understand why other filesystems cannot use the features. These properties concern how file-related object naming is handled on a Linux system.

First, the names of all the files and directories that can appear in the proc filesystem are well known and consistent across systems, with the exception of the files and directories representing active processes. For example, /proc/sys/kernel/hostname is always a file that is used to get or set the host name. Although the location of important files is often known for other filesystems (for example, /etc/shadow), the location is seldom known relative to the filesystem mount point and, more important, it is seldom the case that the security properties of all of the file-related objects can be determined by the path.

Second, file-related objects are uniquely identified by path name in the proc filesystem, and the kernel can easily determine this absolute path in all circumstances. The proc filesystem does not support the concept of hard links. This means, for example, the object identified by the path /proc/sys/kernel/hostname is never identified by any other path.

Together these properties make the proc filesystem suitable for labeling based on path name, as is done by genfscon labeling. Very few filesystems exhibit these properties, making labeling by path name not only difficult but potentially dangerous, as discussed previously.

We use the limited form of genfscon for labeling many legacy filesystems, including many that do not exhibit the same properties as proc. To handle filesystems that cannot be safely labeled by path name, we set a default label using the genfscon statement for the filesystem and all the file-related objects in that filesystem. We do this with a single genfscon statement for the entire filesystem. For example, consider the following genfscon statements:

genfscon vfat /               system_u:object_r:dosfs_t genfscon msdos /              system_u:object_r:dosfs_t genfscon fat /                system_u:object_r:dosfs_t genfscon ntfs /               system_u:object_r:dosfs_t

These genfscon statements for the vfat, msdos, fat, and ntfs filesystems set the security context for the associated filesystem objects and all the file-related objects stored in the filesystems to system_u:object_r:dosfs_t.

Generalized Security Context Statement (genfscon)

The generalized security context statement (genfscon) specifies the labeling mechanism to be used for a filesystem and the labeling for file-related objects stored in the filesystem. There can be multiple genfscon statements for each filesystem. The full syntax of the statement is as follows:

genfscon fs_name partial_path context; 

fs_name	The name of the filesystem that will use genfscon labeling (for example, proc). The filesystem names are the same as those understood by the kernel and mount(8) command and are listed in /proc/filesystems.
partial_path	A partial path relative to the mount point of the filesystem. (For example, for a filesystem mounted at /proc, the partial path / TRanslates to /proc at runtime.) If multiple genfscon statements are specified for a filesystem, file-related objects are labeled using the security context from the statement that includes the partial path that most closely matches the path to the file-related object.
context	A security context used to label file-related objects that most closely match this genfscon statement. For genfscon statements with the partial path of /, this security context is also used to label the filesystem object associated with the filesystem.

The genfscon statement is valid only in monolithic policies and base loadable modules. They are not valid in conditional statements and non-base loadable modules.