Copy from existing domains

The main location you will work with is -dev/local/strict/policy/modules. This location is subdivide= d in +dev/hardened/strict.local/policy/modules. This location is = subdivided in categories:

The next step is to see if we are dealing with the right security contex= ts. This does require a bit of insight in how both the application (that is faili= ng) and -the policy relate to each other. +the policy relate to each other. In essence, you want to make sure that = the +process is running in the right domain and is trying to work on the righ= t target +type.

-TODO extend this explanation, use a common example, like mysql_stream_co= nnect in -postfix. +Interface functions are the APIs that a module provides towards other SE= Linux +modules when they need to interact with the domains. For instance, the +mysql module provides, amongst other functions, the +mysql_stream_connect interface:

-TODO explain that changes in the interface require rebuilds and reinstal= lations -of the base (package, not only .pp file, due to includes). tell that thi= s is the -reason why selinux-base-policy has that many revisions. +The interface declares that the domain passed on as its first (and only) +argument gets the rights offered by stream_connect_pattern, which= is a +macro (defined in policy/support/ipc_patterns.spt that look= s like +so: +

+Modules that need to interact with MySQL through a Unix domain stream so= cket +(/var/run/mysqld/mysqld.sock) will need the proper permissi= ons to +work with the target type (mysqld_var_run_t). Modules canno= t just +set allow statements towards mysqld_var_run_t as the= y do not +know this type. Instead, they call the mysql_stream_connect inter= face, +like the postfix.te file does: +

+If the change you need is adding existing interface calls to the module = (in=20 +the .te file) then you should be able to test it easily by = building +the changed module and loading it. However, if you need to change the in= terface +of your module itself (in the .if file) you will eventually= need +to rebuild the base policy and even provide and install a new +sec-policy/selinux-base-policy package as the interfaces ar= e placed +in /usr/share/selinux/strict/include. This is one of the re= asons +why the sec-policy/selinux-base-policy package in Gentoo Ha= rdened +has a high revision number (and many updates).

-TODO talk about potentially reusing domains (like apache module providin= g the -various httpd_* domains which can be reused by lighttpd). Talk about ass= igning -the proper labels to the files to see if that is sufficient. +If you are facing problems because you run an application which has no d= omain +itself (and hence is probably running in the user_t, +staff_t or sysadm_t domains - or even tries to= run in +the initrc_t domain), you will need to create one. But befo= re we do +that, it might be possible that the application can work within the doma= in +definition of a different application. +

+One example here is lighttpd. This lightweight HTTPd service "uses" the +definitions offered by the apache module. By marking its ex= ecutable +file httpd_exec_t it runs in the httpd_t domai= n and +uses the same policy like Apache. By labeling the files according to the +apache.fc definitions (but now for lighttpd) it might Just = Work +™ +

+Reusing existing domains requires that you at least consider the followi= ng +aspects:

-Copy from existing domains +(Do Not) Copy from existing domains =20

-TODO talk about finding a similar module (apps or service) and start fro= m a -(slimmed-down) domain. Not recommended as it might already open too much= , but it -is a good start, if not to just look at with every denial you get later.= Keep it -short, most information is in next section. +If reusing existing domains introduces too many risks, you'll need to cr= eate a +new domain for the application. Many people would be inclined to copy th= e domain +definition of a similar application and work from there. Although this i= s a +viable approach, it is considered a bad practice because you start by pr= oviding +privileges to the domain that are never needed, and removing privileges = from a +domain later is very difficult. Even more, if you are not the author of = the +modules, most developers will not even try to remove them as they assume= that +the author of the domain had a good reason to add it in the first place.= This is +one of the reasons why upstream takes great care in accepting patches - = they +must be properly documented before they are accepted. +

+ +

+Instead, create a domain from scratch but take a close eye on the domain= you +belief is very similar. Issues that arise during the module development = might be +quickly resolved by looking at how the original domain is defined.

=20 @@ -712,8 +825,238 @@ short, most information is in next section. =20

-TODO talk about defining the proper domains, set proper types (like file= _type or -application_type), refer to refpolicy guidelines +To start the development of a new module from scratch, first identify th= e +domain(s) you want to have. An application that, in its entire lifespan = only +constitutes of a single process, will most likely only have one domain. = For +instance, the Skype client will have just skype_t. However, +applications that have multiple processes running might need multiple do= mains +too. For instance, the Postfix application runs a master +(postfix_master_t), queue manager (postfix_qmgr_t) and +pickup service (postfix_pickup_t), but depending on the com= mands +you execute, it will also have (short-lived) processes running as +postfix_cleanup_t, postfix_bounce_t, etc.) It = is +considered a best practice to start with a fine-grained model for domain= s +and only later decide if merging multiple domains into one is beneficial= . +Splitting domains later is more difficult. Don't forget to look at the +client-side aspect too! +

+ +

+Next, define the types that each domain interacts with. This of course i= ncludes +the binary (like skype_exec_t) but do not forget resources = like +

+ +

+ The configuration file(s) in /etc (f.i. + postfix_etc_t) +
+ PID files (f.i. sshd_var_run_t) +
+ Spool files (f.i. postfix_spool_t) +
+ Variable data files (f.i. snmpd_var_lib_t) +
+ Log files (f.i. zebra_log_t) +
+ Cache files (f.i. squid_cache_t) +
+ (User) content files (f.i. httpd_sys_content_t and + httpd_user_content_t) +

+ +

+Also, try to separate types that are used by other domains as well. This= way, +the other domains can only interact with those files or resources that a= re +labeled accordingly, rather than interact with a broad spectrum of files= . The +distinction that the apache module makes between system-pro= vided +content (like phpmyadmin files) and user-provided content (in the +public_html directory in the users' home directories) seems= (and +is) very logical, but one could wrongly say that for Apache itself, the = access +controls are the same. Although that might be true, both types are clear= ly used +in different ways so this mandates the use of different domains. +

+ +

+Once you have defined those types too, start writing down the intra-doma= in +permissions. Right now is a good time to look at other modules to see ho= w they +do things. Start with defining the accesses towards the domains. +

+ +

+type spamassassin_t;
+type spamassassin_exec_t;
+application_domain(spamassassin_t, spamassassin_exec_t)
+ubac_constrained(spamassassin_t)
+

+ +

+This small snippet defines many things. The first two lines just mention= the new +types (the spamassassin_t domain and +spamassassin_exec_t type). The application_domain in= terface +marks spamassassin_t as an application domain type (it gets= the +application_domain_type and domain attributes = and a +few default permissions (like allowing that it sends SIGCHLD and SIGNULL= to +init). It also marks spamassassin_exec_t as an applications= ' +executable type (application_exec_type and exec_type<= /path> +attributes) so that it can be executed by regular users (these domains h= ave +execute rights against all resources that have the +application_exec_type attribute set. Finally, it marks the +spamassassin_t domain as a constrained domain for user-base= d access +controls. In other words, if SELinux users user_u and +staff_u launch the application in spamassassin_t +domains, then the domains are segregated from each other (the intra-doma= in rules +inside spamassassin_t are only valid for communication with= in the +same SELinux user, not between SELinux users). +

+ +

+Attributes are an important aspect in SELinux policy development. They m= ake +managing the domains easier, but you should always consider the implicat= ions +when you add an attribute to one of your types. It usually means that a = whole +lot of permissions are suddenly granted between other domains and yours. +

+ +

+Next, set the proper intra-domain permissions. For instance, allow your = domain +to read its configuration files as well as more access inside its own +/var/lib location: +

+ +

+allow openca_ca_t openca_etc_t:file read_file_perms;
+allow openca_ca_t openca_etc_t:dir list_dir_perms;
+
+manage_dirs_pattern(openca_ca_t, openca_var_lib_t, openca_var_lib_t)
+manage_files_pattern(openca_ca_t, openca_var_lib_t, openca_var_lib_t)
+

+ +

+The majority of work in developing SELinux policy modules is using and c= hoosing +the right interfaces. Having a few functions available to browse through= all the +available information is always interesting, so you might want to use th= e +following function definitions (definitely not mandatory - this is only = to help +people skim through the policy definitions): +

+ +

+POLICY_LOCATION=3D"/path/to/your/refpolicy";
+
+# sefindif - Find interface definitions that have a string that matches =
the
+# given regular expression
+sefindif() {
+  REGEXP=3D"$1";
+  cd ${POLICY_LOCATION}/policy/modules;
+  for FILE in */*.if;
+  do
+    awk "/(interface\(|template\()/ { NAME=3D\$NF; P=3D0 }; /${REGEXP}/ =
{ if (P=3D=3D0) {P=3D1; print NAME}; print };" ${FILE} | sed -e "s:^:${FI=
LE}\: :g";
+  done
+}
+
+# seshowif - Show the interface definition
+seshowif() {
+  INTERFACE=3D"$1";
+  cd ${POLICY_LOCATION}/policy/modules;
+  for FILE in */*.if;
+  do
+    grep -A 9999 "\(interface(\`${INTERFACE}'\|template(\`${INTERFACE}'\=
)" ${FILE} | grep -B 9999 -m 1 "^')";
+  done
+}
+
+# sefinddef - Find macro definitions that have a string that matches the=
 given
+# regular expression
+sefinddef() {
+  REGEXP=3D"$1";
+  grep -H "define(\`.*${REGEXP}.*" ${POLICY_LOCATION}/policy/support/* |=
 sed -e 's:.*\/\([^(]*\):\1:g'
+}
+
+# seshowdef - Show the macro definition
+seshowdef() {
+  MACRONAME=3D"$1";
+  cd ${POLICY_LOCATION}/policy/support;
+  for FILE in *.spt;
+  do
+    grep -A 9999 "define(\`${MACRONAME}'" ${FILE} | grep -B 999 -m 1 "')=
";
+  done
+}
+

+ +

+These functions can then be used to find the information / interfaces yo= u are +looking for. For instance, you need the application to read the postfix +configuration files: +

+ +

+~$ sefindif postfix_etc_t
+services/postfix.if: template(`postfix_domain_template',`
+services/postfix.if:    allow postfix_$1_t postfix_etc_t:dir list_dir_pe=
rms;
+services/postfix.if:    read_files_pattern(postfix_$1_t, postfix_etc_t, =
postfix_etc_t)
+services/postfix.if:    read_lnk_files_pattern(postfix_$1_t, postfix_etc=
_t, postfix_etc_t)
+services/postfix.if: interface(`postfix_read_config',`
+services/postfix.if:            type postfix_etc_t;
+services/postfix.if:    read_files_pattern($1, postfix_etc_t, postfix_et=
c_t)
+services/postfix.if:    read_lnk_files_pattern($1, postfix_etc_t, postfi=
x_etc_t)
+services/postfix.if: interface(`postfix_config_filetrans',`
+services/postfix.if:            type postfix_etc_t;
+services/postfix.if:    filetrans_pattern($1, postfix_etc_t, $2, $3)
+
+~$ seshowif postfix_read_config
+interface(`postfix_read_config',`
+        gen_require(`
+                type postfix_etc_t;
+        ')
+
+        read_files_pattern($1, postfix_etc_t, postfix_etc_t)
+        read_lnk_files_pattern($1, postfix_etc_t, postfix_etc_t)
+        files_search_etc($1)
+')
+

+ +

+Same thing if you want to look for the correct macro definition (usually= , if you +notice something but you cannot find it as an interface, then it is most= likely +a macro): +

+ +

+# Suppose you need to read, write, connect, ... to a socket
+~$ sefinddef connect
+ipc_patterns.spt:define(`stream_connect_pattern',`
+obj_perm_sets.spt:define(`rw_socket_perms', `{ ioctl read getat=
tr write setattr append bind connect getopt setopt shutdown }')
+obj_perm_sets.spt:define(`connected_socket_perms', `{ create ioctl read =
getattr write setattr append bind getopt setopt shutdown }')
+obj_perm_sets.spt:define(`connected_stream_socket_perms', `{ connected_s=
ocket_perms listen accept }')
+
+# To see what the ps_process_pattern is about
+~$ seshowdef ps_process_pattern
+define(`ps_process_pattern',`
+        allow $1 $2:dir list_dir_perms;
+        allow $1 $2:file read_file_perms;
+        allow $1 $2:lnk_file read_lnk_file_perms;
+        allow $1 $2:process getattr;
+')
+

+ +

+As we strive to bring most of our patches upstream, please do consider t= he c= ontribution +guidelines of the reference policy project. The project has a docu= mented +style guide, naming convention and an online API reference (for the vari= ous +interfaces). +

+ +

+Note that, the moment you create a new module, you'll need to create the= proper +role interfaces (if it is an application that is directly called from a = user +domain). Take a look at tvtime_role and how it is used in the +staff.te and sysadm.te role definitions.

=20 @@ -723,10 +1066,49 @@ application_type), refer to refpolicy guidelines =20

-TODO talk about users trying to do maximum testing (all the way). Also, = if they -want to support unconfined domains too, how they can do this (and should= test). +When you test your application, test it in as many ways as possible. If = your +application is a command-line application, run it both from a regular te= rminal +(tty) as well as a virtual one (in an xterm). See if it still works if y= ou run +it in a screen session. Try out all functions and features that the appl= ication +supports. +

+ +

+This rigorous testing is necessary because SELinux denies everything tha= t isn't +explicitly allowed. If you do not test certain features, chances are tha= t the +module does not provide the necessary permissions and as such, users wil= l be +impacted. +

+ +

+To test out a new module, load it (semodule -i modulename.pp) and= relabel +the files affiliated with the application (either through rlpkg o= r using +restorecon). Consider the following testing activities if applica= ble (not +all domains are interactive domains, so please read the activities with = your +domain definition in mind):

=20 +

+ Sending signals to the application (if you need to be able to kill i= t, try + killing it) +
+ Run it both as a regular user (user_u) as well as + administrative users (if applicable). If your domain needs to suppor= t + unconfined domains/users, run it from an unconfined user domain too. +
+ Run it from a terminal, console, screen, sudo, ... +
+ Change the applications' configuration file (including rendering it = useless + with syntax errors) and look at the applications' behavior. Especial= ly + syntax failures as that might trigger the application to log things = at + places that you haven't discovered earlier. +