5.4 SELinux Policy Structure | Selinux: NSAs Open Source Security Enhanced Linux

Now that we've completed our close-up view of an SELinux policy component, let's return to a wide-angle view. This section explains the conventions observed by SELinux policy developers in choosing where to place policy statements of various types. The explanation is organized around the structure of the SELinux source directory tree, which is typically /etc/security/selinux/src/policy . In good computer science fashion, we'll first visit the leaf nodes (that is, the subdirectories of the tree) and ultimately visit the root node (that is, the policy directory itself). However, we'll depart from computer science conventions in one key respect: rather than visit the nodes in lexicographic (alphabetical) order, we'll visit them in an order in which several nodes having fundamental content are visited first, to facilitate the exposition.

5.4.1 The flask Subdirectory

The flask directory, as implied by being the first subdirectory visited in our traversal of the policy source directory tree, is the most fundamental of the subdirectories. It contains three important files:

initial_sids
security_classes
access_vectors

Like other policy source files, these files are read and processed during policy compilation. In addition, these files are used to generate C header files that are used during compilation of an SELinux-capable Linux kernel. In that context, the files specify symbol definitions for access vectors (that is, permissions), initial SIDs, and security classes. Because of their relationship to the kernel, changes to the contents of these files may require recompilation of the kernel. Therefore, in comparison to other policy source files, these files are relatively static.

Although several policy source files are used in the compilation of the kernel, you don't need to have SELinux policy sources available during kernel compilation. The kernel sources include copies of the necessary SELinux policy source files.

The following subsections explain the purpose and contents of these files. The most interesting of the files is the access_vectors file, which is explained in the last of the three subsections.

5.4.1.1 The flask/initial_sids file

The flask/initial_sids file specifies about two dozen initial SID values. The values are used to label transient objects and objects used during system bootup . The file is also used to generate a C header file, flask.h , used during kernel compilation. System administrators do not generally need to modify the initial_sids file, nor should they do so.

5.4.1.2 The flask/security_classes file

The flask/security_classes file defines thirty security object classes, which are shown in Appendix A. The classes file and dir are among the most commonly used security classes. Like the initial_sids file, the file is used to create the C header file flask.h , which is used during kernel compilation. System administrators do not generally need to modify the security_classes file, nor should they do so.

5.4.1.3 The flask/access_vectors file

As explained in Chapter 2, access vectors specify the operations that can be performed by subjects upon objects. In other words, they specify permissions. The flask/access_vectors file defines the range of operations associated with each object class. In all, about 150 different operations are specified on the thirty defined classes of SELinux security objects. Among the most commonly used operations are read , which denotes reading a file or file-like object, and write , which denotes writing a file or file-like object. Appendix B summarizes the operations defined in the file. The access_vectors file generates a C header file, av_permissions.h , used during kernel compilation. System administrators do not generally need to modify the access_vectors file, nor should they do so.

You may find the large amount of detail appearing in Appendix B somewhat overwhelming. You certainly don't need to memorize the table in order to effectively use SELinux. But you will likely have to refer to it from time to time. You may do so, for example:

To understand the log message generated when SELinux denies a requested operation. In this case, Appendix B will help you understand what the requesting program was attempting to do.
To find the SELinux name of an operation so that you can create a policy rule that allows or denies it under particular circumstances.

The policy configuration provides the ability to specify some operations that are nonsensical , such as associating swap space with a socket file. Valid, real-world policies don't actually authorize such operations, even though it's possible to do so.

The descriptions of SELinux operations provided in Appendix B are approximate. The actual meaning of an operation is determined by the system calls that are enabled or disabled by the permissions corresponding to the operation. Precisely understanding or defining an operation therefore requires a detailed understanding of the related system calls and is beyond the scope of this book.

5.4.2 The macros Subdirectory

The macros directory contains several files that define M4 macros used primarily in the TE files that define domains. The files are:

admin_macros.te: Defines the admin_domain macro.
base_user_macros.te: Defines the base_user_domain macro.
core_macros.te: Defines about five dozen fundamental macros, primarily defining sets of permissions and simple access vector rules.
global_macros.te: Defines about three dozen fundamental macros, primarily defining domain properties.
mini_user_macros.te: Defines the mini_user_domain macro.
user_macros.te: Defines the user_domain , full_user_role , and in_user_role macros.

Appendix C summarizes the macros defined in the macros subdirectory. A typical example of a macro is r_file_perms , which expands to the permissions needed to read files and file attributes, namely:

 { read getattr lock ioctl }

I suggest that you browse Appendix C at this point. However, unless you have photographic recall, don't attempt to commit it to memory. You'll primarily use the table just as you use the tables presented earlier in this chapter: to understand log messages and to find SELinux names when coding your own policy rules. Please note that the descriptions given in are approximate. In drafting them, I emphasized conciseness over completeness. Once you more fully understand the SELinux policy language, you'll be able to develop your own, more sophisticated understanding of these macros.

In addition to the files defining macros, the macros directory also contains a subdirectory named program . This subdirectory contains about three dozen files that define M4 macros used in defining user domains. Their function is closely related to that of the TE files that define user domains, so they are not explained separately in this chapter.

5.4.3 The file_contexts Subdirectory

The file_contexts directory tree contains files, known as file context files , that specify the security context of persistent files. The setfiles program consults the file context files when labeling a filesystem.

The file_contexts directory contains two subdirectories:

program: Contains specifications of the security contexts of files that are part of installed packages or programs.
misc: Contains miscellaneous specifications.

Some implementations of SELinux are distributed with an empty misc directory. The absence of files is not a cause for concern.

In addition, the file_contexts directory contains two files:

file_contexts: This file is automatically created when a policy is compiled. It aggregates the contents of all the file context files residing in the misc and program subdirectories.
types.fc: This file contains security contexts for general system files and user home directories.

Security contexts are specified in .fc (file context) files, which have a simple syntax:

   regex   [ -   type   ] (   context   <<none>> )

That is, each line begins with a regular expression ( regex ), which is optionally followed by a token representing a type ( type ). Each line ends with a token representing a context ( context ) or the special token <<none>> .

A file-context file may also contain comments. Any line beginning with a hash mark (#) is considered a comment and ignored by the setfiles program.

When files are being labeled, the path of each file is compared with the regular expressions of each successive file-context line. If a regular expression matches the path , the file is relabeled according to the specified security context; otherwise no action is performed. If multiple regular expressions match the path, the last matching regular expression determines the security context with which the file is labeled. The special token <<none>> specifies that files matching the associated regular expression should not be relabeled.

The file context specifications generally have the form / path /.* (or its equivalent), which matches any path beginning with / path . The associated security context, which is generally system_u:object_r:default_t , is used to label files not matching other regular expressions. Thus in practice, all files are labeled (unless the <<none>> token is used to direct otherwise).

For example, here's a typical file context specification:

 /home/[^/]+/.+            system_u:object_r:user_home_t

This specification matches files in users' home directories and indicates they should be labeled with the security context system_u:object_r:user_home_t .

The optional token representing a type takes one of the following values:

”: Matches only regular files.
-b: Matches only block device files.
-c: Matches only character device files.
-d: Matches only directories.
-s: Matches only socket files.

If the type token does not appear in a line, the line matches directories and files of all types, including device files and other nonregular files.

The regular expressions appearing in file context specifications are implicitly anchored. That is, they behave as though ^ (the regular expression metacharacter matching the beginning of a string) appears as their first character and $ (the regular expression metacharacter matching the end of a string) appears as their last character. Thus, the regular expression given earlier for users' home directories does not match the path /root/home/homedir/roots-file.txt , because the path does not begin with /home . Because of the implicit anchoring, it's important to use absolute, rather than relative, paths in file context specifications.

If you're unfamiliar with regular expressions ”or rusty in working with them ”I suggest that you consult Mastering Regular Expressions (O'Reilly).

5.4.4 The types Subdirectory

The types directory contains files that define general types and a few rules that govern their use. General types are types that are not associated with a particular domain. In all, over 150 general types are defined in 7 files:

device.te: Defines over two dozen types related to devices and device files. See Table D-1.
devpts.te: Defines two types related to the /dev/pts filesystem: ptmx_t , the type of the pty master multiplexor, and devpts_t , the type of the devpts filesystem and its root directory.
file.te: Defines almost six dozen types related to files. See Table D-2.
network.te: Defines about three dozen types related to networks. See Table D-3.
nfs.te: Defines the type nfs_t , the type used for NFS filesystems and the files they contain.
procfs.te: Defines over one dozen types related to the /proc filesystem, especially the sysctl parameters in /proc/sys . See Table D-4.
security.te: Defines six types related to SELinux itself. See Table D-5.

5.4.5 The domains Subdirectory

The domains subdirectory contains two files and two subdirectories. The files are:

admin.te: Defines the sysadm_t general type, which is used by system administrators, and specifies several rules defining related permissions. Also defines several types related to the sysadm_t type.
user.te: Defines several general types used by ordinary users and specifies several rules defining related permissions.

The system administrator does not generally need to modify the admin.te or user.te file.

Recall that a general type is one not related to a specific domain.

Like the domains directory, its subdirectories contain TE files defining domains. The subdirectories are:

misc

Defines several miscellaneous domains ”that is, domains not related to specific programs. The particular domains vary across different SELinux policies and policy versions. However, the directory is likely to define the following domains:

auth-net

Policy for PAM LDAP authentication

fcron

Policy for the crond_t domain, associated with cron

kernel

Policy for the kernel_t domain, associated with the Linux kernel

startx

Policy for running X

The system administrator does not generally need to modify the files defining these domains.

program

Defines ordinary domains related to specific programs. A typical installation may contain over 100 TE files defining domains. The TE files are generally given names resembling those of the related package or program. For example, the TE file defining domains related to the Apache web server is commonly named apache.te .

Along with the file_contexts/program subdirectory and the policy sources directory itself, the domains/program subdirectory is one of the SELinux directories most important to the system administrator. Most SELinux directories contain static files that the system administrator need not ”or must not ”change. However, the system administrator often finds it necessary to modify or supplement the files contained in the domains/program subdirectory.

Most Linux distributions feature package managers that assist in the installation of software products. Generally, when SELinux is implemented for a particular distribution, the distribution's package manager is modified to interoperate with SELinux by automatically installing the TE and FC files related to a package when the package is installed.

However, system administrators often install programs for which their Linux distribution offers no officially supported package. In such a case ”and in any case in which the package manager is unable to automatically install the FC and TE files related to a package ”the system administrator must manually install the FC and TE files. In some cases, prebuilt FC and TE files may not exist; then the system administrator must create and install appropriate FC and TE files before the installed program will operate properly under SELinux. Chapter 9 explains how to do so.

A one-to-one relationship exists between files in the file_contexts/program and domains/program directories. The SELinux Makefile enforces this correspondence and refuses to build a binary policy if the correspondence is violated. So if you create a TE file in domains/program , you must create a corresponding FC file in file_contexts/program , and vice versa.

5.4.6 The appconfig Subdirectory

The appconfig subdirectory stores configuration information used by security-aware programs modified to work with SELinux. The configuration information consists of default contexts and types assigned to objects by security-aware programs. Typically, the subdirectory contains five files:

default_contexts: Used by login , sshd , and crond to determine the legal security contexts for a given user that are reachable from the security context of the current process
default_type: Used by login to determine the default type (domain) for each role
failsafe_context: Used in X failsafe operation
initrc_context: Used by the run_init program to determine the security context for running /etc/rc.d scripts
root_default_contexts: Used by login to determine the security contexts available to the root user

The system administrator does not generally need to modify these files, with one exception: the root_default_contexts file contains a commented line that can be uncommented to cause the root user to automatically log into the sysadm_r role. However, doing so may make you system somewhat less secure and is not a generally recommended practice.

5.4.7 The Policy Source Directory

In addition to its various subdirectories, the policy source directory contains several files, a few of which are important to the system administrator. Here are the most important files, i.e. those which often must be modified:

tunable.te: Contains various definitions that the system administrator can enable or disable to customize the SELinux security policy. This file is distribution-specific and may not exist on your SELinux system.
users: Defines the SELinux users. Described further in Chapter 6, this file generally must be modified to include the Linux user names of users who can act as system administrators. Optionally, the file can be modified to include the Linux user names of other users.

The other files within the policy source directory include:

assert.te: Defines assertions that safeguard the integrity of the SELinux security policy. Assertions are more fully explained in Chapter 7. Essentially, an assertion states a condition that must not be violated by the SELinux security policy. When a policy is compiled, assertions are checked; violation of an assertion terminates the compilation and suppresses binary policy generation. Assertions protect against unwise or incorrect policy revisions that might compromise the integrity of SELinux or the security policy.
attrib.te: Defines about six dozen type attributes. As more fully explained in Chapter 7, type attributes define sets of types and domains having common permissions.
constraints: Defines several constraints on M4 macro invocations. Like SELinux policy assertions, the constraints safeguard the integrity of the SELinux policy.
fs_use: Specifies how various filesystem types are labeled by SELinux.
genfs_contexts: Specifies how SELinux handles filesystem types that do not support extended attributes or an SELinux-supported fixed-labeling scheme.
initial_sid_contexts: Specifes the security context of several initial security context IDs (SIDs).
Makefile: Controls the labeling of filesystems and the compilation and installation of the SELinux security policy. Chapter 4 explains how to invoke the operations supported by the Makefile .
mls: Specifies configuration options related to multilevel security (MLS). MLS is not supported by the current release of SELinux.
net_contexts: Specifies the security contexts of ports, interfaces, and other network objects.
policy.??: The binary security policy file; for instance, policy.17 .
policy.conf: A temporary file used during policy compilation, used to aggregate the source files involved in the compilation.
rbac: Defines legal role transitions. Currently, the only legal transition is from sysadm_r to system_r , a transition needed by the run_init program.
serviceusers: Specifies roles accessible by users that exist only if related optional packages are installed. For instance, the user cyrus is permitted to enter the role cyrus_r , but only if the cyrus.te domain is defined.

In addition, the policy sources directory includes several files that have no functional role but contain useful information for system administrators, including:

COPYING: Contains the license, currently the GNU General Public License, under which SELinux can be used.
ChangeLog: Summarizes changes made to SELinux versions.
policy.spec: The SPEC file associated with the source RPM containing the security policy. SPEC files specify how the RPM program builds source and binary RPM packages.
README: Provides a brief overview of the contents of the policy source directory tree.
VERSION: States the SELinux version.