Creating our own interface

Being able to call interfaces is nice, but when we develop SELinux policies, we will run into situations where we need to create our own interface for the SELinux module we are developing. This is done through a file with an .if extension.

In this recipe, we are going to extend the mylogging policy with an interface that allows other domains to execute the system log daemon binary (but without running this binary with the privileges of the system logger itself; this would be called a domain transition in SELinux).

How to do it…

1. If our current context is an unprivileged user domain (as unconfined domains are highly privileged and can do almost everything), we can try executing the system logger daemon (syslog-ng or rsyslog) directly and have it fail as follows:

   ~$ /usr/sbin/syslog-ng --help
   bash: /usr/sbin/syslog-ng: Permission denied
   

2. Now, create the mylogging.if file (in the same location where mylogging.te is) with the following content, granting all permissions needed to execute the binary:

   ## <summary>Local adaptation to the system logging SELinux policy</summary>
    
   ##########################################
   ## <summary>
   ##    Execute the system logging daemon in the caller domain
   ## </summary>
   ## <desc>
   ##   <p>
   ##     This does not include a transition.
   ##   </p>
   ## </desc>
   ## <param name="domain">
   ##    <summary>
   ##      Domain allowed access.
   ##    </summary>
   ## </param>
   #
   interface(`logging_exec_syslog',`
     gen_require(`
       type syslogd_exec_t;
     ')
     can_exec($1, syslogd_exec_t)
   ')

3. Create a new SELinux policy module for the user domain; this policy should be able to execute the system logger directly. For instance, for the sysadm_t domain, we would create a mysysadm.te file with the following content:

   policy_module(mysysadm, 0.1)
   gen_require(`
     type sysadm_t;
   ')
   logging_exec_syslog(sysadm_t)

4. Build the mysysadm policy module and load it. Then, test to see if the daemon binary can now be executed directly:

   ~$ /usr/sbin/syslog-ng --help
   

How it works…

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.

The location of the interface definitions

Whenever an SELinux policy module is built, the build system sources all interface files it finds at the following locations:

• /usr/share/selinux/mcs/include/* or /usr/share/selinux/devel/include/* (depending on the Linux distribution)
• The current working directory

The first location is where the interface files of all the SELinux modules provided by the Linux distribution are stored. The files are inside subdirectories named after particular categories (the reference policy calls these layers, but this is only used to make some structure amongst the definitions, nothing else) such as contrib/, system/, and roles/.

For local development of SELinux policies, this location is usually not writable. If we develop our own policy modules, then this would mean that none of the locally managed SELinux policy files can use interfaces of the other local interface files. The Makefile file, therefore, also sources all interface files it finds in the current working directory.

The in-line documentation

Inside the interface file created, we notice a few XML-like structures as comments. These comments are prefixed by a double hash sign (##) and are used by the reference policy build system to generate the API documentation (which can be found at /usr/share/doc/selinux-*).

For local policies, this in-line documentation is not used and, thus, not mandatory. However, writing the documentation even for local policies helps us in documenting the rules better. Also, if we ever want to push our changes upstream, this in-line documentation will be requested anyway.

The comment system uses the following constructs:

• Right before an interface definition, we encounter a <summary> element, which provides a one-sentence description of the interface
• Additional information can then be provided through a <desc> element under which the HTML code can be placed for documenting the interface further
• Every parameter to an interface is documented through a <param> entity, which again contains a <summary> line

See also

• The reference policy API documentation can be found online at http://oss.tresys.com/docs/refpolicy/api/