Using the refpolicy naming convention

The interface names used to simplify policy development can be freely chosen. However, the reference policy itself uses a naming convention to try and structure the names used so that the SELinux policy developers can easily find the interfaces they need—if they exist—and give an unambiguous name to an interface they want to create.

The naming convention for the reference policy is available online at http://oss.tresys.com/projects/refpolicy/wiki/InterfaceNaming.

Getting ready

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:

• To read all logfiles
• To connect to the HTTP port over TCP
• To not audit getting the attributes of user home directories

How to do it…

1. First we need to figure out the file types that are involved in the situations:
   • Generic logfiles are var_log_t (as can be seen by querying the label of /var/log/itself):

     ~$ ls -dZ /var/log
     drwxr-xr-x. root root system_u:object_r:var_log_t:s0 /var/log
     

   • When we deal with all logfiles, we can safely assume this is handled by an SELinux attribute. Let's look at the attributes for the generic var_log_t type:

     ~$ seinfo –tvar_log_t –x
       var_log_t
         file_type
         non_security_file_type
         mountpoint
         non_auth_file_type
         logfile
     

   • The logfile attribute looks like an interesting hit. We can now grep through the policy sources to figure out which SELinux policy modules handle the logfile attribute, or use sefindif (assuming that there are interfaces defined that handle this attribute):

     ~$ sefindif 'attribute logfile'
     system/logging.if: interface(`logging_log_file',`
     …
     

   • For the logfiles example, the module we need is called logging as can be seen from the sefindif output. Similarly, we will find that for the HTTP port, the module is corenet, and home directories are userdom.
2. Next, we check whether there is a modifier. The first two situations have no specific modifier (all the actions are regular verbs). The last example has one: do not audit. In the SELinux policy language, this is known as a dontaudit statement.
3. Now, let's look at the verbs involved. This is mostly based on experience, but the situations show that there is a huge correlation between the verbs and the eventually chosen refpolicy name (which usually uses SELinux permission names):
   • In the first situation, this is read
   • The second one has connect over TCP, which is translated into tcp_connect
   • The last situation has getting the attributes, so it is translated as getattr
4. Finally, let's look at the object that is being referenced:
   • In the first situation, this is all logfiles, which we will name all_logs
   • In the second situation, this is HTTP port, so we will name http_port
   • The third situation has user home directories, so we will name user_home_dirs
5. Combining this gives us the following interface names:
   • Read all logfiles: logging_read_all_logs
   • Connect to the HTTP port over TCP: corenet_tcp_connect_http_port
   • Do not audit getting the attributes of user home directories: userdom_dontaudit_getattr_user_home_dirs

How it works…

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.

There's more...

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.