Look for a good location where the development environment should be stored. This usually is a location in the user's home directory, such as /home/staff/dev/selinux/. Whenever this book references a location with respect to the development environment, it will use the ${DEVROOT} variable to refer to this location.

Another piece of information that we need is the location of the repository that hosts the SELinux policies of the current system. This location is distribution specific, so consult the distribution site for more information. At the time of writing this book, the policies for Gentoo Linux and Fedora can be found at the following locations:

Whenever version control is used, we will use git in this book. Other version control systems exist as well, but this too is outside the scope of this book.

To create the development environment used in this book, perform the following steps:

The setup of the development environment helps us deal with policy development for further recipes. The checkout of the distributions' SELinux policy tree is to query the existing policy rules while developing new policies. SELinux does not require to have the policy sources available on a system (only the compiled binary SELinux policy modules and parts of the SELinux policy rules, which can be used by other policy modules). As a result, default installations usually do not have the policy rules available on the system.

By having the checkout at our disposal, we can review the existing SELinux policy files and happily use examples from it for our own use. A major user of this checkout is the functions.sh script, which uses the ${POLICY_LOCATION} variable to know where the checkout is hosted. This script provides several functions that we'll use throughout this book; they will also help in querying the sources.

By sourcing this functions.sh script during log on, these functions are readily available in the user's shell. One of these functions is the seshowif function, which displays the rules of a particular interface. The example given shows the definition of the files_read_etc_files interface, which we used to validate that our setup is working correctly.

The functions.sh script can also work with the interface files that are available through /usr/share/selinux/devel/ (on Fedora/Red Hat systems), making the checkout of the policy repository optional if the user does not need access to the complete policy rules. The policy location defined then is as follows:

export POLICY_LOCATION=/usr/share/selinux/devel/

Next to the distributions' SELinux policy tree, one can also use the reference policy SELinux tree. This is the upstream project that most, if not all, Linux distributions use as the source of their policies. It has to be said though that the reference policy often lags behind on the policy repositories of the individual distributions, as it has stricter acceptance criteria for policy enhancements.

It also doesn't hurt to check out the SELinux policy repositories of other distributions. Often, Linux distributions first do SELinux policy updates on their own repository before pushing their changes to the reference policy (which is called upstreaming in the free software development community). By looking at other distributions' repositories, developers can easily see if the necessary changes have been made in the past already (and are thus more likely to be correct).

For more information about the topics covered in this recipe, refer to the following resources:

Before we get started, we first need to make sure that we can test the outcome of the change. A simple method would be to change the context of the /var/log/messages file (or another general logfile that the system logger is configured to use) and send messages through the system logger using the logger command:

~$ logger "Just a simple log event"
~$ tail /var/log/messages

Verify that the message has indeed been delivered by looking at the last lines shown through the tail command. Then, change the context and try again. The event should not be shown, and a denial should be logged by the audit daemon:

~# chcon -t named_conf_t /var/log/messages
~$ logger "Another simple log event"
~$ tail /var/log/messages
~# ausearch -m avc -ts recent

With this in place, we can now create our first simple SELinux module.

Building a new SELinux policy is a matter of going through the following steps:

There are three important, new aspects of SELinux policy development that we got in touch with in this recipe:

At the end, we committed the file to our local repository. Using version control on policy files is recommended in order to track changes across time. A good hint would be to tag new releases of the policies—if users ever report issues with the policy, you can then ask them for the SELinux policy module version (through semodule –l) and use the tags in the repository to easily find rules for that particular policy module.

In the remainder of this book, we will no longer use git add/commit so that we can focus on the SELinux recipes.

~# semodule –l
aide  1.8.0
alsa  1.13.0
…
mylogging  0.1
…

Throughout this book, the build system used is based on the reference policy build system. This is a collection of M4 macros and affiliated scripts that make the development of SELinux policies easier. This is, however, not the only way of creating SELinux policies.

When visiting online resources, you might come across SELinux policy modules whose structure looks like the following:

module somename 1.0;
require {
  type some_type_t;
  type another_type_t;
}
allow some_type_t another_type_t:dir { read search };

These are policy files that do not use the reference policy build system. To build such files, we first create an intermediate module file with checkmodule, after which we package the module file towards a loadable binary SELinux policy with semodule_package:

~$ checkmodule -M –m –o somename.mod somename.te
~$ semodule_package –m somename.mod –o somename.pp

To keep things simple, we will stick to the reference policy build system.

Many topics and areas have been touched upon in this recipe. More information can be found at the following resources:

To use reference policy interfaces in an SELinux policy module, the following approach can be taken:

One of the principles behind the build system of the reference policy is that an SELinux policy module should not directly mention SELinux types that are not related to that module. Whenever a policy module needs to define rules against a type that is defined by a different module, interfaces defined by that different module should be used instead.

In our example, we need the interface used by the BIND SELinux policy (which handles the BIND-named daemon policy rules); this interface allows us to write to the BIND DNS server configuration file type (named_conf_t). We can check the online API, the API documentation in /usr/share/doc/selinux-*, or just guess the interface name. However, in order to be certain that the interface does what we need, we need to query the interface definitions themselves.

That is where the sefinddef, seshowdef, sefindif, and seshowif functions come into play. These functions are not part of any SELinux user space—they are provided through the functions.sh file we installed earlier and are simple awk/grep/sed combinations against the SELinux policy files.

With sefinddef (the SELinux find definition), we can search through the support macros (not related to a particular SELinux policy module) for any definition that matches the expression given to it. In this recipe, we gave file.*write as the expression to look for. The seshowdef (SELinux show definition) function shows us the entire definition of the given pattern.

The sefindif (SELinux find interface) function then allows us to find an interface that the SELinux policy provides. In this recipe, we used it to search for the interface that allows a domain to write to the BIND DNS server configuration files. There is also a seshowif (SELinux show interface) function that shows us the entire interface definition like the following:

~$ seshowif bind_write_config
interface(`bind_write_config',`
  gen_require(`
    type named_conf_t;
  ')
  write_files_pattern($1, named_conf_t, named_conf_t)
  allow $1 named_conf_t:file setattr_file_perms;
')

This example interface nicely shows how interfaces are handled by the SELinux reference policy build system. Whenever such an interface is called, one or more arguments are given to the interface. In our case, we passed on syslogd_t as the first (and only) argument.

The build system then substitutes every $1 occurrence in the interface with the first argument, effectively expanding the call to the following code:

write_files_pattern(syslogd_t, named_conf_t, named_conf_t)
allow syslogd_t named_conf_t:file setattr_file_perms;

The call to write_files_pattern is then expanded with the definition we saw earlier.

For the policy developer, this is all handled transparently. The sources of the SELinux policy file stay well-formatted and only call the interfaces. It is at build time that the expansion of the various interfaces is done. This allows developers to have nicely segregated, compartmentalized policy definitions.

Let's first look at how the build system knows where the interface definitions are. Then, we'll cover the in-line comment system used in the example.

In this recipe, we'll do a pen-and-paper exercise to see how the naming convention works. In the example, we will create interface names for three situations:

The naming convention that the reference policy uses is not mandated in a technical manner. Just like with coding styles, naming conventions are made so that collaboration is easier (everyone uses the same naming convention) and searching through the large set of interfaces can be directed more efficiently.

Using the proper naming convention is a matter of exercise. If uncertain, ask around in #selinux on irc://irc.freenode.net or on the reference policy mailing list.

Take some time to look through the interface files available at /usr/share/selinux/devel/include/. Next, for the more standard permission-based interface names, there are also interface names used for templates and type assignation.

For instance, there is a template called apache_content_template. Through it, additional SELinux types and permissions (used for web applications) are created in one go. Similarly, there is an interface called apache_cgi_domain that marks a particular type as being a domain that can be invoked through a web servers' CGI support.

Besides the naming convention, the reference policy also has a style guide available at http://oss.tresys.com/projects/refpolicy/wiki/StyleGuide. Like the naming convention, this is purely a human aspect for improved collaboration—there is no consequence of violating the coding style beyond the changes that might not be accepted in the upstream repositories.

To distribute SELinux policies, complete the following steps:

SELinux policy modules (the files ending with .pp) contain everything SELinux needs to activate the policy. By distributing these files across many systems (and loading it through the semodule command), these systems receive the wanted updates against their current SELinux policy.

Once loaded (and this only needs to happen once, as a loaded module is retained even after the system reboots), one does not really need the .pp files anymore (loaded modules are copied inside /etc/selinux). However, it is recommended that you keep the policies there so that administrators can reload policies as needed; this might help in troubleshooting the SELinux policy and system permission issues.

There are a few caveats to take into account though:

~# sestatus
SELinux status:      enabled
SELinuxfs mount:      /sys/fs/selinux
SELinux root directory:    /etc/selinux
Loaded policy name:    mcs
Current mode:      enforcing
Mode from config file:    enforcing
Policy MLS status:      enabled
Policy deny_unknown status:  denied
Max kernel policy version:  28