Difference between revisions of "NB RefPolicy"

From SELinux Wiki
Jump to: navigation, search
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
= The Reference Policy =
 
= The Reference Policy =
 
== Introduction ==
 
== Introduction ==
The Reference Policy is now the standard policy source used to build SELinux policies. This provides a single source tree with supporting documentation that can be used to build policies for different purposes such as: confining important daemons, supporting MLS / MCS type policies and locking down systems so that all processes are under SELinux control.  
+
The Reference Policy is now the standard policy source used to build GNU/Linux SELinux policies. This provides a single source tree with supporting documentation that can be used to build policies for different purposes such as: confining important daemons, supporting MLS / MCS type policies and locking down systems so that all processes are under SELinux control.  
  
 
This section details how the Reference Policy is:
 
This section details how the Reference Policy is:
 
 
# Constructed and types of policy builds supported.
 
# Constructed and types of policy builds supported.
 +
# Adding new modules to the build.
 
# Installation as a full Reference Policy source or as Header files.
 
# Installation as a full Reference Policy source or as Header files.
 +
# Impact of the migration process being used to convert compiled module files (<tt><nowiki>*.pp</nowiki></tt>) to CIL.
 
# Modifying the configuration files to build new policies.
 
# Modifying the configuration files to build new policies.
# Adding new modules to the build.
+
# Explain the support macros.
  
=== Notebook Reference Policy Information ===
+
== Reference Policy Overview ==
This section makes use of the F-12 distribution that is built from the standard [http://oss.tresys.com/projects/refpolicy/wiki/DownloadRelease Reference Policy ][http://oss.tresys.com/projects/refpolicy/wiki/DownloadRelease VERSION=20090730]<ref name="ftn53">The full source code and details are at the following site: [http://oss.tresys.com/projects/refpolicy http://oss.tresys.com/projects/refpolicy].</ref>. This is modified and distributed by Red Hat as the following RPM:
+
Strictly speaking the 'Reference Policy' should refer to the policy taken from the master repository or the latest released version (see [https://github.com/TresysTechnology/refpolicy/wiki https://github.com/TresysTechnology/refpolicy/wiki]). This is because most Linux distributors take a released version and then tailor it to their specific requirements, for example the Fedora distribution is built from the standard Reference Policy but modified and distributed by Red Hat as a source RPM, for example:
 +
: '''selinux-policy-3.12.1-179.fc20.src.rpm'''<ref name="ftn48"><sup>These RPMs can be obtained from [http://koji.fedoraproject.org/ http://koji.fedoraproject.org].</sup></ref>
  
: '''selinux-policy-3.6.32-103.fc12.src.rpm'''<ref name="ftn54">This RPM can be obtained from the [http://koji.fedoraproject.org/ http://koji.fedoraproject.org] web site.</ref>
+
The master Reference Policy repository can be checked out using the following:
 +
<pre>
 +
# Check out the core policy:
 +
git clone https://github.com/TresysTechnology/refpolicy.git
 +
cd refpolicy
 +
# Add the contibuted modules (policy/modules/contrib)
 +
git submodule init
 +
git submodule update
 +
</pre>
  
This core source code is then used to build various policy RPMs that are distributed by Red Hat as:
+
The [http://selinuxproject.org/~rhaines/NB4-diagrams/26-ref-policy.png Reference Policy Source tree] diagram shows the layout that once installed would be located at:
 +
<pre>
 +
/etc/selinux/<NAME>/src/policy
 +
</pre>
  
: '''selinux-policy-3.6.32-103.fc12.noarch''' - Contains the SELinux /etc/selinux/config file, man pages and the "Policy Header" development environment that is located at /usr/share/selinux/devel
+
Where the <tt><nowiki><NAME></nowiki></tt> entry is taken from the <tt>build.conf</tt> file as discussed in the [[#Reference Policy Build Options - build.conf | Reference Policy Build Options - build.conf]] section. The [[#Installing and Building the Reference Policy Source | Installing and Building the Reference Policy Source]] section explains a simple build plus information on building the Fedora source.
: '''selinux-policy-doc-3.6.32-103.fc12.noarch''' - Contains the html policy documentation that is located at /usr/share/doc/selinux-policy-3.6.32/html
+
: '''selinux-policy-minimum-3.6.32-103.fc12.noarch'''
+
: '''selinux-policy-mls-3.6.32-103.fc12.noarch'''
+
: '''selinux-policy-targeted-3.6.32-103.fc12.noarch'''
+
  
These three rpms contain policy configuration files and the packaged policy modules (*.pp). These will be used to build the particular policy type in <nowiki>/usr/share/selinux/<policy_name>,</nowiki> the install process will then install the policy in the appropriate <nowiki>/etc/selinux/<policy_name></nowiki> directory.
+
The Reference Policy can be used to build two different formats of policy infrastructure:
 +
# Loadable Module Policy - A policy that has a base module for core services and has the ability to load / unload modules to support applications as required<ref name="ftn49">These can be installed by system administrators as required. The dynamic loading / unloading of policies as applications are loaded is not yet supported.</ref>. This is now the standard used by GNU / Linux distributions.
 +
# Monolithic Policy - A policy that has all the required policy information in a single base policy and does not require the services of the module infrastructure (<tt>'''semanage'''(8)</tt> or <tt>'''semodule'''(8)</tt>). These are more suitable for embedded or minimal systems.
  
 +
Each of the policy types are built using module files that define the specific rules required by the policy as detailed in the [[#Reference_Policy_Module_Files | Reference Policy Module Files]] section. Note that the monolithic policy is built using the the same module files by forming a single 'base' source file.
  
== Reference Policy Overview ==
+
The Reference Policy relies heavily on the <tt>'''m4'''(1)</tt> macro processor as the majority of supporting services are m4 macros.
The Reference Policy can be used to build two different formats of a policy:
+
 
+
# Loadable Module Policy - A policy that has a base module for core services and has the ability to load / unload modules to support applications as required<ref name="ftn55">These can be installed by system administrators as required. The dynamic loading / unloading of policies as applications are loaded is not yet supported.</ref>. This is now the standard used by GNU / Linux distributions.
+
# Monolithic Policy - A policy that has all the required policy information in a single base policy.
+
 
+
Each of the policy types are built using module files that define the specific modules required by the policy as detailed in the [[NB_RefPolicy#Reference_Policy_Module_Files | Reference Policy Module Files]] section. Note that the monolithic policy is built using the the same module files, however they are all assembled into a single "base" source file.
+
 
+
The Reference Policy is now used by all major distributions of SELinux, however each distribution makes its own specific changes to support their "version of the Reference Policy" (as this section should show as the Red Hat F-12 policy distribution has a slightly different build to the standard [http://oss.tresys.com/projects/refpolicy/wiki/DownloadRelease Reference Policy][http://oss.tresys.com/projects/refpolicy/wiki/DownloadRelease VERSION=2.20090730]).  
+
  
 
There are tools such as SLIDE (SELinux integrated development environment) that can be used to make the task of policy development and testing easier when using the Reference Policy source or headers. SLIDE is an [http://eclipse.org/ Eclipse] plugin and details can be found at:
 
There are tools such as SLIDE (SELinux integrated development environment) that can be used to make the task of policy development and testing easier when using the Reference Policy source or headers. SLIDE is an [http://eclipse.org/ Eclipse] plugin and details can be found at:
  
 
[http://oss.tresys.com/projects/slide http://oss.tresys.com/projects/slide]
 
[http://oss.tresys.com/projects/slide http://oss.tresys.com/projects/slide]
 +
  
 
=== Distributing Policies ===
 
=== Distributing Policies ===
 
It is possible to distribute the Reference Policy in two forms:
 
It is possible to distribute the Reference Policy in two forms:
 +
# As source code that is then used to build policies. This is not the general way policies are distributed as it contains the complete source that most administrators do not need. The [[#Reference Policy Source | Reference Policy Source]] section describes the source and the [[#Installing and Building the Reference Policy Source |Installing and Building the Reference Policy Source]] section describes how to install the source and build a policy.
 +
# As 'Policy Headers'. This is the most common way to distribute the Reference Policy. Basically, the modules that make up 'the distribution' are pre-built and then linked to form a base and optional modules. The 'headers' that make-up the policy are then distributed along with makefiles and documentation. A policy writer can then build policy using the core modules supported by the distribution, and using development tools they can add their own policy modules. The [[#Reference Policy Headers | Reference Policy Headers]] section describes how these are installed and used to build modules.
  
# As source code that is then used to build policies. This is not the general way policies are distributed as it contains the complete source that most administrators do not need. The [[NB_RefPolicy#Reference_Policy_Source | Reference Policy Source]] section describes the source and the [[NB_RefPolicy#Installing_and_Building_the_Reference_Policy_Source | Installing and Building the Reference Policy Source]] section describes how to install the source and build a policy.
+
The policy header files for F-20 are distributed in a number of rpms as follows:
# As "Policy Headers". This is the most common way to distribute the Reference Policy. Basically, the modules that make up "the distribution" are pre-built and then linked to form a base and optional modules. The "headers" that make-up the policy are then distributed along with makefiles and documentation. A policy writer can then build policy using the core modules supported by the distribution, and using development tools they can add their own policy modules. The [[NB_RefPolicy#Reference_Policy_Headers | Reference Policy Headers]] section describes how these are installed and used to build modules.
+
: '''selinux-policy-3.12.1-179.fc20.noarch.rpm''' - Contains the SELinux /etc/selinux/config file, man pages and the 'Policy Header' development environment that is located at /usr/share/selinux/devel
 
+
: '''selinux-policy-doc-3.12.1-179.fc20.noarch.rpm''' - Contains the html policy documentation that is located at /usr/share/doc/selinux-policy/html
The policy header files for F-12 are distributed in a number of rpms as follows:
+
: '''selinux-policy-minimum-3.12.1-179.fc20.noarch.rpm'''
 
+
: '''selinux-policy-mls-3.12.1-179.fc20.noarch.rpm'''
: '''selinux-policy-3.6.32-103.fc12.noarch''' - This package contains the SELinux /etc/selinux/config file, man pages and the "Policy Header" development environment that is located at /usr/share/selinux/devel
+
: '''selinux-policy-targeted-3.12.1-179.fc20.noarch.rpm'''
: '''selinux-policy-doc-3.6.32-103.fc12.noarch''' - This package contains the html policy documentation that is located at /usr/share/doc/selinux-policy-3.6.32/html
+
:: These three rpms contain policy configuration files and the packaged policy modules (<nowiki>*.pp</nowiki>). They will be used to form the particular policy type in <nowiki>/usr/share/selinux/<NAME></nowiki>, the install process will then install the policy in the appropriate <nowiki>/etc/selinux/<NAME></nowiki> directory. Normally only one policy would be installed and active, however for development purposes all can be installed.
: '''selinux-policy-minimum-3.6.32-103.fc12.noarch'''
+
: '''selinux-policy-sandbox-3.12.1-179.fc20.noarch.rpm'''
: '''selinux-policy-mls-3.6.32-103.fc12.noarch'''
+
:: Contains the sandbox module for use by the <tt>policycoreutils-sandbox</tt> package. This will be installed as a module for one of the three main policies described above.
: '''selinux-policy-targeted-3.6.32-103.fc12.noarch'''
+
: These three packages contain policy configuration files and policy modules (*.pp files) for the particular policy type to be installed. These files are used to build the policy type in /usr/share/selinux/<policy_name> and then install the policy in the /etc/selinux/<policy_name> directory.
+
: Normally only one policy would be installed and active, however for development purposes all three can be installed.
+
  
 
=== Policy Functionality ===
 
=== Policy Functionality ===
As can be seen from the policies distributed with F-12 above, they can be classified by the name of the functionality they support (taken from the <tt>NAME</tt> entry of the <tt>build.conf</tt> as shown in Table 2), for example the Red Hat policies support<ref name="ftn56">Note that Red Hat pre-configure MCS support within all their policies.</ref>:
+
As can be seen from the policies distributed with F-20 above, they can be classified by the name of the functionality they support (taken from the <tt>NAME</tt> entry of the <tt>build.conf</tt>), for example the Fedora policies support:
 
+
: minimum - MCS policy that supports a minimal set of confined daemons within their own domains. The remainder run in the unconfined_t space.
: mminimum - supports a minimal set of confined daemons within their own domains. The remainder run in the unconfined_t space.
+
: targeted - MCS policy that supports a greater number of confined daemons and can also confine other areas and users (this also supports the older 'strict' policy).  
 
+
: mls - MLS policy for server based systems.
: mls - supports server based MLS systems.
+
 
+
: targeted - supports a greater number of confined daemons and can also confine other areas and users (this targeted version also supports the older "strict" version).  
+
 
+
For information, the Reference Policy supports the following types (taken from the <tt>TYPE</tt> entry of the <tt>build.conf</tt> as shown in Table 2):
+
 
+
standard - supports confined daemons and can also confine other areas and users (this is an amalgamated version of the older "targeted" and "strict" versions).
+
 
+
: mcs - As standard but supports MCS labels.
+
 
+
: mls - supports MLS labels and confines server processes.
+
  
 
=== Reference Policy Module Files ===
 
=== Reference Policy Module Files ===
The reference policy modules are constructed using a mixture of [[PolicyLanguage | policy language statements]], [[NB_RefPolicy#Reference_Policy_Support_Macros | support macros]] and access interface calls using three principle types of source file:
+
The reference policy modules are constructed using a mixture of [[PolicyLanguage#Kernel_Policy_Language | Kernel Policy Language]], [[#Reference Policy Support Macros | support macros]] and Interface macros using three principle types of source file:
 +
* A private policy file that contains statements required to enforce policy on the specific GNU / Linux service being defined within the module. These files are named <nowiki><module_name>.te</nowiki>. For example the ada.te file shown below has two statements:
 +
** one to state that the ada_t process has permission to write to the stack and memory allocated to a file.
 +
** one that states that if the unconfined module is loaded, then allow the ada_t domain unconfined access. Note that if the flow of this statement is followed it will be seen that many more interfaces and macros are called to build the final raw SELinux language statements. An expanded module source is shown in the [[#Module Expansion Process | Module Expansion Process]] section.
 +
* An external interface file that defines the services available to other modules. These files are named <nowiki><module_name>.if</nowiki>.
 +
:: For example the ada.if file shown below has two interfaces defined for other modules to call (see also the [http://selinuxproject.org/~rhaines/NB4-diagrams/27-ref-doc.png Documentation Screenshot] that shows the documentation that can be automatically generated):
 +
** ada_domtrans - that allows another module (running in domain $1) to run the ada application in the ada_t domain.
 +
** ada_run - that allows another module to run the ada application in the ada_t domain (via the ada_domtrans interface), then associate the ada_t domain to the caller defined role ($2) and terminal ($3).
 +
: Provided of course the caller domain has permission.
 +
: It should be noted there are two types of interface specification:
 +
:: '''Access Interfaces''' - These are the most common and define interfaces that <tt>.te</tt> modules can call as described in the ada examples. They are generated by the <tt>interface</tt> macro as detailed in the the [[#interface Macro | interface Macro]] section.
 +
:: '''Template Interfaces''' - These are required whenever a module is required in different domains and allows the type(s) to be redefined by adding a prefix supplied by the calling module. The basic idea is to set up an application in a domain that is suitable for the defined SELinux user and role to access but not others. These are generated by the <tt>template</tt> macro as detailed in the [[#template Macro | template Macro]] section that also explains the <tt>openoffice.if</tt> template.
 +
* A file labeling file that defines the labels to be added to files for the specified module. These files are named <nowiki><module_name>.fc</nowiki>. The build process will amalgamate all the .fc files and finally form the file_contexts file that will be used to label the filesystem.
 +
: For example the ada.fc file shown below requires that the specified files are all labeled system_u:object_r:ada_exec_t:s0.
  
: 1. A private policy file that contains statements required to enforce policy on the specific GNU / Linux service being defined within the module. These files are named <nowiki><module_name>.te</nowiki>.
+
The <nowiki><module_name></nowiki> must be unique within the reference policy source tree and should reflect the specific GNU / Linux service being enforced by the policy.
 
+
For example the ada.te file shown below has two statements:
+
:: a) one to state that the ada_t process has permission to write to the stack and memory allocated to a file.
+
:: b) one that states that if the unconfined module is loaded, then allow the ada_t domain unconfined access. Note that if the flow of this statement is followed it will be seen that many more interfaces and macros are called to build the final raw SELinux language statements.
+
 
+
: 2. An external interface file that defines the services available to other modules. These files are named <module_name>.if.
+
 
+
: For example the ada.if file shown below has two interfaces defined for other modules to call (see also the [http://taiga.selinuxproject.org/~rhaines/diagrams/5-1-doc-screen.png Example Documentation Screen Shot] that shows a screen shot of the documentation that can be automatically generated):
+
:: a) ada_domtrans - that allows another module (running in domain $1) to run the ada application in the ada_t domain.
+
:: b) ada_run - that allows another module to run the ada application in the ada_t domain (via the ada_domtrans interface), then associate the ada_t domain to the caller defined role ($2) and terminal ($3).
+
: Provided of course that the caller domain has permission.
+
 
+
: It should be noted that there are two types of interface specification:
+
 
+
:: '''Access Interfaces''' - These are the most common and define interfaces that <tt>.te</tt> modules can call as described in the ada examples. They are generated by the <tt>interface</tt> macro as detailed in the the [[NB_RefPolicy#interfaceMacro | interface Macro]] section.
+
 
+
:: '''Template Interfaces''' - These are required whenever a module is required in different domains and allows the type(s) to be redefined by adding a prefix supplied by the calling module. The basic idea is to set up an application in a domain that is suitable for the defined SELinux user and role to access but not others. These are generated by the <tt>template</tt> macro as detailed in the [[NB_RefPolicy#templateMacro | template Macro]] section that also explains the <tt>openoffice.if</tt> template.
+
 
+
: 3. A file labeling file that defines the labels to be added to files for the specified module. These files are named <module_name>.fc. The build process will amalgamate all the .fc files and finally form the [[PolicyConfigurationFiles#contexts/file_contexts | file_contexts]] file that will be used to label the filesystem.
+
 
+
For example the ada.fc file shown below requires that the specified files are all labeled system_u:object_r:ada_exec_t:s0.
+
 
+
The <module_name> must be unique within the reference policy source tree and should reflect the specific GNU / Linux service being enforced by the policy.
+
  
 
The module files are constructed using a mixture of:
 
The module files are constructed using a mixture of:
 
+
# Policy language statements as defined in the [[PolicyLanguage#Kernel_Policy_Language | Kernel Policy Language]] section.
# Policy language statements as defined in the [[PolicyLanguage | SELinux Policy Language]] section.
+
# Reference Policy macros that are defined in the [[#Reference_Policy_Macros | Reference Policy Macros]] section.
# Reference Policy macros that are defined in the [[NB_RefPolicy#Reference_Policy_Macros | Reference Policy Macros]] section.
+
 
# External interface calls defined within other modules (.te and .if only).
 
# External interface calls defined within other modules (.te and .if only).
  
Line 111: Line 93:
 
'''ada.te file contents:'''
 
'''ada.te file contents:'''
 
<pre>
 
<pre>
policy_module(ada, 1.4.0)
+
policy_module(ada, 1.4.1)
  
 
########################################
 
########################################
Line 117: Line 99:
 
# Declarations
 
# Declarations
 
#
 
#
 +
 +
attribute_role ada_roles;
 +
roleattribute system_r ada_roles;
  
 
type ada_t;
 
type ada_t;
 
type ada_exec_t;
 
type ada_exec_t;
 
application_domain(ada_t, ada_exec_t)
 
application_domain(ada_t, ada_exec_t)
role system_r types ada_t;
+
role ada_roles types ada_t;
  
 
########################################
 
########################################
Line 130: Line 115:
 
allow ada_t self:process { execstack execmem };
 
allow ada_t self:process { execstack execmem };
  
userdom_use_user_terminals(ada_t)
+
userdom_use_inherited_user_terminals(ada_t)
 +
 
 
optional_policy(`
 
optional_policy(`
unconfined_domain(ada_t)
+
    unconfined_domain(ada_t)
 
')
 
')
 
</pre>
 
</pre>
Line 138: Line 124:
 
'''ada.if file contents:'''
 
'''ada.if file contents:'''
 
<pre>
 
<pre>
## <summary>GNAT Ada95 compiler</summary>
+
## <summary>GNAT Ada95 compiler.</summary>
 +
 
 
########################################
 
########################################
 
## <summary>
 
## <summary>
Line 145: Line 132:
 
## <param name="domain">
 
## <param name="domain">
 
##<summary>
 
##<summary>
##Domain allowed access.
+
##Domain allowed to transition.
 
##</summary>
 
##</summary>
 
## </param>
 
## </param>
 
#
 
#
 
interface(`ada_domtrans',`
 
interface(`ada_domtrans',`
gen_require(`
+
    gen_require(`
type ada_t, ada_exec_t;
+
        type ada_t, ada_exec_t;
')
+
    ')
  
corecmd_search_bin($1)
+
    corecmd_search_bin($1)
domtrans_pattern($1, ada_exec_t, ada_t)
+
    domtrans_pattern($1, ada_exec_t, ada_t)
 
')
 
')
  
Line 165: Line 152:
 
## <param name="domain">
 
## <param name="domain">
 
##<summary>
 
##<summary>
##Domain allowed access.
+
##Domain allowed to transition.
 
##</summary>
 
##</summary>
 
## </param>
 
## </param>
 
## <param name="role">
 
## <param name="role">
 
##<summary>
 
##<summary>
##The role to be allowed the ada domain.
+
##Role allowed access.
##</summary>
+
## </param>
+
## <param name="terminal">
+
##<summary>
+
##The type of the terminal allow the ada domain to use.
+
 
##</summary>
 
##</summary>
 
## </param>
 
## </param>
 
#
 
#
 
interface(`ada_run',`
 
interface(`ada_run',`
gen_require(`
+
    gen_require(`
type ada_t;
+
        attribute_role ada_roles;
')
+
    ')
  
 
ada_domtrans($1)
 
ada_domtrans($1)
role $2 types ada_t;
+
roleattribute $2 ada_roles;
 +
 
 
')
 
')
 
</pre>
 
</pre>
 +
 
'''ada.fc file contents:'''
 
'''ada.fc file contents:'''
 
<pre>
 
<pre>
#
 
# /usr
 
#
 
 
/usr/bin/gnatbind--gen_context(system_u:object_r:ada_exec_t,s0)
 
/usr/bin/gnatbind--gen_context(system_u:object_r:ada_exec_t,s0)
 
/usr/bin/gnatls--gen_context(system_u:object_r:ada_exec_t,s0)
 
/usr/bin/gnatls--gen_context(system_u:object_r:ada_exec_t,s0)
 
/usr/bin/gnatmake--gen_context(system_u:object_r:ada_exec_t,s0)
 
/usr/bin/gnatmake--gen_context(system_u:object_r:ada_exec_t,s0)
/usr/libexec/gcc(/.*)?/gnat1 -- gen_context(system_u:object_r:ada_exec_t,s0)
+
 
 +
/usr/libexec/gcc(/.*)?/gnat1--gen_context(system_u:object_r:ada_exec_t,s0)
 
</pre>
 
</pre>
  
Line 202: Line 184:
 
One of the advantages of the reference policy is that it is possible to automatically generate documentation as a part of the build process. This documentation is defined in XML and generated as HTML files suitable for viewing via a browser.  
 
One of the advantages of the reference policy is that it is possible to automatically generate documentation as a part of the build process. This documentation is defined in XML and generated as HTML files suitable for viewing via a browser.  
  
The documentation for F-12 can be found in the following locations:
+
The documentation for Fedora can be viewed in a browser by [file:///usr/share/doc/selinux-policy/html/index.html] once the <tt>selinux-policy-doc</tt> rpm has been installed.
  
: '''Distributed as Policy Headers''' - /usr/share/doc/selinux-policy-<version>/html. Where <version> is the version number of the Red Hat release, for the build used in this Notebook the location is:
+
The documentation for the Reference Policy source will be available at <nowiki><location>/src/policy/doc/html</nowiki> once <tt>make html</tt> has been executed (the <nowiki><location></nowiki> is the location of the installed source after make install-src has been executed as described in the [[#Installing and Building the Reference Policy Source | Installing and Building the Reference Policy Source]] section). The Reference Policy documentation may also be available at a default location of <tt>/usr/share/doc/refpolicy-VERSION/html</tt> if <tt>make install-doc</tt> has been executed (where <tt>VERSION</tt> is the entry from the source <tt>VERSION</tt> file.
  
:: /usr/share/doc/selinux-policy-3.6.32/html
+
The [http://selinuxproject.org/~rhaines/NB4-diagrams/27-ref-doc.png Documentation Screenshot] shows an example produced for the ada module interfaces.  
 
+
: '''Distributed as Policy Source''' - <location>/src/policy/doc/html. Where <location> is the location of the installed source after make install-src has been executed as described in the [[NB_RefPolicy#_Installing_The_Reference_Policy_Source | Installing The Reference Policy Source]] section. The documentation can then be generated using make html, where for the build used in this Notebook the location is:
+
<pre>
+
/etc/selinux/targeted-103/src/policy/doc/html
+
</pre>
+
 
+
The [http://taiga.selinuxproject.org/~rhaines/diagrams/5-1-doc-screen.png Example Documentation Screen Shot] shows an example screen of the documentation produced for the ada module interfaces.
+
  
 
== Reference Policy Source ==
 
== Reference Policy Source ==
This section will explain the source layout and configuration files, with the actual installation and building covered in the [[NB_RefPolicy#InstallingandBuilingtheReferencePolicySource | Building the Reference Policy Source]] section.  
+
This section explains the source layout and configuration files, with the actual installation and building covered in the [[#Installing and Building the Reference Policy Source | Installing and Building the Reference Policy Source]] section.  
  
 
The source has a README file containing information on the configuration and installation processes that has been used within this section (and updated with the authors comments as necessary). There is also a VERSION file that contains the Reference Policy release date which can be used to obtain the original source from the repository located at:
 
The source has a README file containing information on the configuration and installation processes that has been used within this section (and updated with the authors comments as necessary). There is also a VERSION file that contains the Reference Policy release date which can be used to obtain the original source from the repository located at:
 
+
: [https://github.com/TresysTechnology/refpolicy/wiki https://github.com/TresysTechnology/refpolicy/wiki]
: [http://oss.tresys.com/projects/refpolicy http://oss.tresys.com/projects/refpolicy]
+
  
 
=== Source Layout ===
 
=== Source Layout ===
The [http://taiga.selinuxproject.org/~rhaines/diagrams/5-2-ref-policy.png The Reference Policy Source Tree] diagram shows the layout of the reference policy source tree, that once installed would be located at:
+
The [http://selinuxproject.org/~rhaines/NB4-diagrams/26-ref-policy.png Reference Policy Source tree] diagram shows the layout of the reference policy source tree, that once installed would be located at:
 
+
<pre>
: <tt><nowiki>/etc/selinux/<policy_name>/src/policy</nowiki></tt>
+
/etc/selinux/<NAME>/src/policy
 +
</pre>
  
 
The following sections detail the source contents:
 
The following sections detail the source contents:
 +
* [[#Reference_Policy_Files_and Director | Reference Policy Files and Directories]] - Describes the files and their location.
 +
* [[#Source_Configuration_Files | Source Configuration Files]] - Details the contents of the build.conf and modules.conf configuration files.
 +
* [[#Source Installation and Build Make Options | Source Installation and Build Make Options]] - Describes the <tt>make</tt> targets.
 +
* [[#Modular_Policy_Build_Stucture | Modular Policy Build Structure]] - Describes how the various source files are linked together to form a base policy module (<tt>base.conf</tt>) during the build process.
  
* [[NB_RefPolicy#Reference_Policy_Files_and_Directories | Reference Policy Files and Directories]] - Describes the files and their location.
+
The [[#Installing and Building the Reference Policy Source | Installing and Building the Reference Policy Source]] section then describes how the initial source is installed and configured to allow a policy to be built.  
* [[NB_RefPolicy#Source_Configuration_Files | Source Configuration Files]] - Details the contents of the build.conf and modules.conf configuration files.
+
* [[NB_RefPolicy#Source_Installation_and_Build_Make_Options | Source Installation and Build Make Options]] - Describes the <tt>make</tt> targets.
+
* [[NB_RefPolicy#Modular_Policy_Build_Process | Modular Policy Build Process]] - Describes how the various source files are linked together to form a base policy module (<tt>base.conf</tt>) during the build process.
+
 
+
The [[NB_RefPolicy#Installing_and_Building_the_Reference_Policy_Source | Installing and Building the Reference Policy Source]] section then describes how the initial source is installed and configured to allow a version of the F-12 targeted policy to be built.
+
  
 
=== Reference Policy Files and Directories ===
 
=== Reference Policy Files and Directories ===
 
Table 1 shows the major files and their directories with a description of each taken from the README file. All directories are relative to the root of the Reference Policy source directory ./policy.
 
Table 1 shows the major files and their directories with a description of each taken from the README file. All directories are relative to the root of the Reference Policy source directory ./policy.
  
Two of these configuration files (build.conf and modules.conf) are further detailed in the [[NB_RefPolicy#Source_Configuration_Files | Source Configuration Files]] section as they define how the policy will be built.
+
Two of these configuration files (build.conf and modules.conf) are further detailed in the [[#Source_Configuration_Files | Source Configuration Files]] section as they define how the policy will be built.
  
During the build process, a file is generated in the ./policy directory called either policy.conf or base.conf depending whether a monolithic or modular policy is being built. This file is explained in the [[NB_RefPolicy#Modular_Policy_Build_Structure | Modular Policy Build Structure]] section.
+
During the build process, a file is generated in the ./policy directory called either policy.conf or base.conf depending whether a monolithic or modular policy is being built. This file is explained in the [[#Modular_Policy_Build_Stucture | Modular Policy Build Structure]] section.
 +
 
 +
<center>'''Table 1: The Reference Policy Files and Directories'''</center>
  
 
{| border="1"
 
{| border="1"
Line 261: Line 237:
 
|-
 
|-
 
| '''build.conf'''
 
| '''build.conf'''
| Options which influence the building of the policy, such as the policy type and distribution.
+
| Options which influence the building of the policy, such as the policy type and distribution. This file is described in the [[#Reference_Policy_Build_Options - build.conf | Reference Policy Build Options - build.conf]] section.
 +
 
 +
|-
 +
| '''<nowiki>config/appconfig-<type></nowiki>'''
 +
| <nowiki>Application configuration files for all configurations of the Reference Policy where <type> is taken from the </nowiki><tt>build.conf</tt> <tt>TYPE</tt> entry that are currently: standard, MLS and MCS). These files are used by SELinux-aware programs and described in the [[ConfigurationFiles | SELinux Configuration Files]] section.
  
 
|-
 
|-
| '''config/appconfig-<type>'''
+
| '''config/file_contexts.subs_dist'''
| Application configuration files for all configurations of the Reference Policy where <type> is taken from the build.conf TYPE entry that are currently: standard, MLS and MCS). These files are used by SELinux-aware programs.
+
| Used to configure file context aliases (see the [#4.4.26.contexts/files/file_contexts.subs and file_contexts.subs_dist File|outline contexts/files/file_contexts.subs and file_contexts.subs_dist File] section).
  
 
|-
 
|-
Line 271: Line 251:
 
| The file read by load policy for adding SELinux users to the policy on the fly.  
 
| The file read by load policy for adding SELinux users to the policy on the fly.  
  
Note that this file is not used in the F-12 modular policy build.
+
Note that this file is not used in the modular policy build.
  
 
|-
 
|-
 
| '''doc/html/*'''
 
| '''doc/html/*'''
| When <tt>make html</tt> has been executed, contains the in-policy XML documentation, presented in web page form  
+
| When <tt>make html</tt> has been executed, contains the in-policy XML documentation, presented in web page form .
  
 
|-
 
|-
Line 288: Line 268:
 
| '''doc/templates/*'''
 
| '''doc/templates/*'''
 
| Templates used for documentation web pages.
 
| Templates used for documentation web pages.
 +
 +
|-
 +
| '''man/*'''
 +
| Various man pages for modules (ftp, http etc.)
  
 
|-
 
|-
Line 297: Line 281:
 
| This file has declarations for each initial SID.
 
| This file has declarations for each initial SID.
  
The file usage in policy generation is described in the [[NB_RefPolicy#Modular_Policy_Build_Structure | Modular Policy Build Structure]] section.
+
The file usage in policy generation is described in the [[#Modular Policy Build Structure | Modular Policy Build Structure]] section.
  
 
|-
 
|-
Line 303: Line 287:
 
| This file has declarations for each security class.
 
| This file has declarations for each security class.
  
The file usage in policy generation is described in the [[NB_RefPolicy#Modular_Policy_Build_Structure | Modular Policy Build Structure]] section.
+
The file usage in policy generation is described in the [[#Modular Policy Build Structure | Modular Policy Build Structure]] section.
  
 
|-
 
|-
 
| '''policy/flask/access_vectors'''
 
| '''policy/flask/access_vectors'''
| This file defines the access vectors. Common prefixes for access vectors may be defined at the beginning of the file. After the common prefixes are defined, an access vector may be defined for each security class.
+
| This file defines the common permissions and class specific permissions. The file is described in the [[#Modular Policy Build Structure | Modular Policy Build Structure]] section.
 
+
The file usage in policy generation is described in the [[NB_RefPolicy#Modular_Policy_Build_Structure | Modular Policy Build Structure]] section.
+
  
 
|-
 
|-
 
| '''policy/modules/*'''
 
| '''policy/modules/*'''
| Each directory represents a layer in Reference Policy all of the modules are contained in one of these layers.
+
| Each directory represents a layer in Reference Policy. All of the modules are contained in one of these layers. The <tt>contrib</tt> modules are supplied externally to the Reference Policy, then linked into the build.
  
The files present are:
+
The files present in each directory are:
  
 
metadata.xml - describes the layer.
 
metadata.xml - describes the layer.
  
<module_name>.te, .if & .fc - contains policy source as described in the [[NB_RefPolicy#Reference_Policy_Module_Files | Reference Policy Module Files]] section.
+
<nowiki><module_name>.te</nowiki>, .if & .fc - contains policy source as described in the [[#Reference Policy Module Files | Reference Policy Module Files]] section.
  
The file usage in policy generation is described in the [[NB_RefPolicy#Modular_Policy_Build_Structure | Modular Policy Build Structure]] section.
+
The file usage in policy generation is described in the [[#Modular Policy Build Structure| Modular Policy Build Structure]] section.
 +
 
 +
|-
 +
| '''policy/support/*'''
 +
| Reference Policy support macros. These are described in the [[#Reference Policy Macros | Reference Policy Macros]] section.
  
 
|-
 
|-
 
| '''policy/booleans.conf'''
 
| '''policy/booleans.conf'''
| This file is generated/updated by the conf make target. It contains the booleans in the policy, and their default values. If tunables are implemented as booleans, tunables will also be included. This file will be installed as the /etc/selinux/NAME/booleans file (note that this is not true for F-12 or any system that implements the modular policy - see the [[NB_RefPolicy#Booleans,_Global_Booleans_and_Tunable_Booleans | Booleans, Global Booleans and Tunable Booleans]] section).
+
| This file is generated/updated by the conf make target. It contains the booleans in the policy, and their default values. If tunables are implemented as booleans, tunables will also be included. This file will be installed as the /etc/selinux/NAME/booleans file (note that this is not true for any system that implements the modular policy - see the [[#Booleans, Global Booleans and Tunable Booleans | Booleans, Global Booleans and Tunable Booleans]] section).
 
+
This file is also included in the F-12 source updates as described in the [[NB_RefPolicy#Installing_and_Building_the_Reference_Policy_Source | Installing and Building the Reference Policy Source]] section.
+
  
 
|-
 
|-
 
| '''policy/constraints'''
 
| '''policy/constraints'''
| This file defines additional constraints on permissions in the form of boolean expressions that must be satisfied in order for specified permissions to be granted. These constraints are used to further refine the type enforcement rules and the role allow rules. Typically, these constraints are used to restrict changes in user identity or role to certain domains.
+
| This file defines constraints on permissions in the form of boolean expressions that must be satisfied in order for specified permissions to be granted. These constraints are used to further refine the type enforcement rules and the role allow rules. Typically, these constraints are used to restrict changes in user identity or role to certain domains.
  
 
(Note that this file does not contain the MLS / MCS constraints as they are in the <tt>mls</tt> and <tt>mcs</tt> files described below).
 
(Note that this file does not contain the MLS / MCS constraints as they are in the <tt>mls</tt> and <tt>mcs</tt> files described below).
  
The file usage in policy generation is described in the [[NB_RefPolicy#Modular_Policy_Build_Structure | Modular Policy Build Structure]] section.
+
The file usage in policy generation is described in the [[#Modular Policy Build Structure | Modular Policy Build Structure]] section.
 +
 
 +
|-
 +
| '''policy/context_defaults'''
 +
| This would contain any specific <tt>default_user</tt>, <tt>default_role</tt>, <tt>default_type</tt> and/or <tt>default_range</tt> rules required by the policy.
  
 
|-
 
|-
 
| '''policy/global_booleans'''
 
| '''policy/global_booleans'''
| This file defines all booleans that have a global scope, their default value, and documentation. See the [[NB_RefPolicy#Booleans,_Global_Booleans_and_Tunable_Booleans | Booleans, Global Booleans and Tunable Booleans]] section.
+
| This file defines all booleans that have a global scope, their default value, and documentation. See the [[#Booleans, Global Booleans and Tunable Booleans |Booleans, Global Booleans and Tunable Booleans]] section.
  
 
|-
 
|-
 
| '''policy/global_tunables'''
 
| '''policy/global_tunables'''
| This file defines all tunables that have a global scope, their default value, and documentation. See the [[NB_RefPolicy#Booleans,_Global_Booleans_and_Tunable_Booleans | Booleans, Global Booleans and Tunable Booleans]] section.
+
| This file defines all tunables that have a global scope, their default value, and documentation. See the [[#Booleans, Global Booleans and Tunable Booleans | Booleans, Global Booleans and Tunable Booleans]] section.
  
 
|-
 
|-
Line 349: Line 337:
 
| This contains information used to generate the <tt>sensitivity</tt>, <tt>category</tt>, <tt>level</tt> and <tt>mlsconstraint</tt> statements used to define the MCS configuration.
 
| This contains information used to generate the <tt>sensitivity</tt>, <tt>category</tt>, <tt>level</tt> and <tt>mlsconstraint</tt> statements used to define the MCS configuration.
  
The file usage in policy generation is described in the [[NB_RefPolicy#Modular_Policy_Build_Structure |Modular Policy Build Structure]] section.
+
The file usage in policy generation is described in the [[#Modular Policy Build Structure | Modular Policy Build Structure]] section.
  
 
|-
 
|-
Line 355: Line 343:
 
| This contains information used to generate the <tt>sensitivity</tt>, <tt>category</tt>, <tt>level</tt> and <tt>mlsconstraint</tt> statements used to define the MLS configuration.
 
| This contains information used to generate the <tt>sensitivity</tt>, <tt>category</tt>, <tt>level</tt> and <tt>mlsconstraint</tt> statements used to define the MLS configuration.
  
The file usage in policy generation is described in the [[NB_RefPolicy#Modular_Policy_Build_Structure | Modular Policy Build Structure]] section.
+
The file usage in policy generation is described in the [[#Modular Policy Build Structure | Modular Policy Build Structure]] section.
  
 
|-
 
|-
Line 361: Line 349:
 
| This file contains a listing of available modules, and how they will be used when building Reference Policy.
 
| This file contains a listing of available modules, and how they will be used when building Reference Policy.
  
This file is described in the [[NB_RefPolicy#Reference_Policy_Build_Options | Reference Policy Build Options]] section, it is also updated by the F-12 source updates as described in the [[NB_RefPolicy#Installing_and_Building_the_Reference_Policy_Source | Installing and Building the Reference Policy Source]] section.
+
To prevent a module from being used, set the module to "off". For monolithic policies, modules set to "base" and "module" will be included in the policy. For modular policies, modules set to "base" will be included in the base module; those set to "module" will be compiled as individual loadable modules.
 +
 
 +
This file is described in the [[#Reference_Policy_Build_Options - modules.conf | Reference Policy Build Options - modules.conf]] section.
  
 
|-
 
|-
Line 367: Line 357:
 
| This file defines the policy capabilities that can be enabled in the policy.
 
| This file defines the policy capabilities that can be enabled in the policy.
  
The file usage in policy generation is described in the [[NB_RefPolicy#Modular_Policy_Build_Structure | Modular Policy Build Structure]] section.
+
The file usage in policy generation is described in the [[#Modular Policy Build Structure | Modular Policy Build Structure]] section.
 
+
|-
+
| '''policy/rolemap'''
+
| This file contains prefix and user domain type that corresponds to each user role. The contents of this file will be used to expand the per-user domain templates for each module.
+
 
+
''Note this is not used in the Reference Policy (commented out in makefiles).''
+
  
 
|-
 
|-
Line 379: Line 363:
 
| This file defines the users included in the policy.
 
| This file defines the users included in the policy.
  
The file usage in policy generation is described in the [[NB_RefPolicy#Modular_Policy_Build_Structure |Modular Policy Build Structure]] section.
+
The file usage in policy generation is described in the [[#Modular Policy Build Structure | Modular Policy Build Structure]] section.
 
+
|-
+
| '''policy/support/*'''
+
| Reference Policy support macros. These are described in the [[NB_RefPolicy#Reference_Policy_Macros | Reference Policy Macros]] section.
+
  
 
|-
 
|-
 
| '''securetty_types'''
 
| '''securetty_types'''
| These files are not part of the standard distribution but is added by the F-12 source updates as described in the [[NB_RefPolicy#Installing_and_Building_the_Reference_Policy_Source | Installing and Building the Reference Policy Source]] section.
+
| These files are not part of the standard Reference Policy distribution but are added by Fedora source updates.
  
 
|-
 
|-
Line 393: Line 373:
  
 
|}
 
|}
''Table 1: The Reference Policy Files and Directories''
+
 
  
 
=== Source Configuration Files ===
 
=== Source Configuration Files ===
 
There are two major configuration files (build.conf and modules.conf) that define the policy to be built and are detailed in this section.
 
There are two major configuration files (build.conf and modules.conf) that define the policy to be built and are detailed in this section.
 
  
 
==== Reference Policy Build Options - build.conf ====
 
==== Reference Policy Build Options - build.conf ====
This file defines the policy type to be built that will influence its name and where the source will be located once it is finally installed. It also configures the MCS / MLS sensitivity and category maximum values. An example file content is shown in the [[NB_RefPolicy#Installing_and_Building_the_Reference_Policy_Source | Installing and Building the Reference Policy Source]] section where it is used to install and then build the policy.
+
This file defines the policy type to be built that will influence its name and where the source will be located once it is finally installed. An example file content is shown in the [[#Installing_and_Building_the Reference Policy Source | Installing and Building the Reference Policy Source]] section where it is used to install and then build the policy.
 
+
Table 2 explains the fields that can be defined within this file, however there are a number of <tt>m4</tt> macro parameters that are set up when this file is read by the build process makefiles. These definitions are shown in Table 3 and are also used within the module source files to control how the policy is built with examples shown in the [[NB_RefPolicy#ifdef/ifndef Parameters | ifdef / ifndef Parameters]] section.
+
  
 +
Table 2 explains the fields that can be defined within this file, however there are a number of <tt>m4</tt> macro parameters that are set up when this file is read by the build process makefiles. These macro definitions are shown in Table 20 and are also used within the module source files to control how the policy is built with examples shown in the [[#ifdef / ifndef Parameters | ifdef / ifndef Parameters]] section.
  
 +
<center>'''Table 2: build.conf Entries'''</center>
 
{| border="1"
 
{| border="1"
 
! Option
 
! Option
Line 418: Line 397:
 
| '''TYPE'''
 
| '''TYPE'''
 
| String
 
| String
| Available options are standard, mls, and mcs. For a type enforcement only system, set standard. This optionally enables multi-level security (MLS) or multi-category security (MCS) features. This option controls enable_mls, and enable_mcs policy blocks.
+
| Available options are standard (uses RBAC/TE), mcs (uses RBAC/TE/MCS) and mls (uses RBAC/TE/MLS).
 +
 
 +
The <tt>mls</tt> and <tt>mcs</tt> options control the enable_mls, and enable_mcs policy blocks.
  
 
|-
 
|-
 
| '''NAME'''
 
| '''NAME'''
| String (optional)
+
| String
 
| Sets the name of the policy; the NAME is used when installing files to e.g., /etc/selinux/NAME and /usr/share/selinux/NAME. If not set, the policy type field (TYPE) is used.
 
| Sets the name of the policy; the NAME is used when installing files to e.g., /etc/selinux/NAME and /usr/share/selinux/NAME. If not set, the policy type field (TYPE) is used.
 
The policy built under this directory is also controlled by the modules.conf that is described in the [[NB_RefPolicy#Reference_Policy_Build_Options | Reference Policy Build Options]] section.
 
  
 
|-
 
|-
Line 435: Line 414:
 
| '''UNK_PERMS'''
 
| '''UNK_PERMS'''
 
| String
 
| String
| Set the kernel behaviour for handling of permissions defined in the kernel but missing from the policy. The permissions can either be allowed, denied, or the policy loading can be rejected. See the [[NB_LSM#SELinux_Filesystem | SELinux Filesystem]] for more details.
+
| Set the kernel behaviour for handling of permissions defined in the kernel but missing from the policy. The permissions can either be allowed, denied, or the policy loading can be rejected. See the [[NB_LSM#SELinux_Filesystem | SELinux Filesystem]] section for more details. If not set, then it will be taken from the <tt>semanage.conf</tt> file.
  
 
|-
 
|-
 
| '''DIRECT_INITRC'''
 
| '''DIRECT_INITRC'''
| Boolean (<tt><nowiki>y|n</nowiki></tt>)
+
| Boolean (<tt>y|n</tt>)
 
| If '<tt>y</tt>' sysadm will be allowed to directly run init scripts, instead of requiring the run_init tool. This is a build option instead of a tunable since role transitions do not work in conditional policy. This option controls direct_sysadm_daemon policy blocks.
 
| If '<tt>y</tt>' sysadm will be allowed to directly run init scripts, instead of requiring the run_init tool. This is a build option instead of a tunable since role transitions do not work in conditional policy. This option controls direct_sysadm_daemon policy blocks.
  
 
|-
 
|-
 
| '''MONOLITHIC'''
 
| '''MONOLITHIC'''
| Boolean (<tt><nowiki>y|n</nowiki></tt>)
+
| Boolean (<tt>y|n</tt>)
 
| If '<tt>y</tt>' a monolithic policy is built, otherwise a modular policy is built.
 
| If '<tt>y</tt>' a monolithic policy is built, otherwise a modular policy is built.
  
 
|-
 
|-
 
| '''UBAC'''
 
| '''UBAC'''
| Boolean (<tt><nowiki>y|n</nowiki></tt>)
+
| Boolean (<tt>y|n</tt>)
 
| If '<tt>y</tt>' User Based Access Control policy is built. The default for Red Hat is '<tt>n</tt>'. These are defined as constraints in the <tt>policy/constraints</tt> file. Note Version 1 of the Reference Policy did not have this entry and defaulted to Role Based Access Control.
 
| If '<tt>y</tt>' User Based Access Control policy is built. The default for Red Hat is '<tt>n</tt>'. These are defined as constraints in the <tt>policy/constraints</tt> file. Note Version 1 of the Reference Policy did not have this entry and defaulted to Role Based Access Control.
 +
 +
The UBAC option is described at [http://blog.siphos.be/2011/05/selinux-user-based-access-control/ http://blog.siphos.be/2011/05/selinux-user-based-access-control/].
 +
 +
|-
 +
| '''CUSTOM_BUILDOPT'''
 +
| String
 +
| Space separated list of custom build options.
  
 
|-
 
|-
Line 469: Line 455:
 
|-
 
|-
 
| '''QUIET'''
 
| '''QUIET'''
| Boolean (<tt><nowiki>y|n</nowiki></tt>)
+
| Boolean (<tt>y|n</tt>)
 
| If '<tt>y</tt>' the build system will only display status messages and error messages. This option has no effect on policy.
 
| If '<tt>y</tt>' the build system will only display status messages and error messages. This option has no effect on policy.
  
 
|}
 
|}
''Table 2: build.conf Entries''
 
  
  
 +
<center>'''Table 3: <tt>m4</tt> parameters set at build time - '''''These have been extracted from the Reference Policy <tt>Makefile</tt> file.''</center>
  
 
{| border="1"
 
{| border="1"
Line 528: Line 514:
  
 
|}
 
|}
''Table 3: <tt>m4</tt> parameters set at build time - These have been extracted from the Reference Policy <tt>Makefile</tt> file.''
+
 
  
 
==== Reference Policy Build Options - policy/modules.conf ====
 
==== Reference Policy Build Options - policy/modules.conf ====
Line 537: Line 523:
 
# Required in base
 
# Required in base
 
#
 
#
# Policy for kernel threads, proc filesystem, unlabeled processes and objects.
+
# Policy for kernel threads, proc filesystem,and unlabeled processes and
 +
# objects.
 
#  
 
#  
 
kernel = base
 
kernel = base
Line 555: Line 542:
 
</pre>
 
</pre>
  
As can be seen the only active line (those without comments<ref name="ftn57">The comments are also important as they form part of the documentation when it is generated by the <tt>make html</tt> target.</ref>) is:
+
As can be seen the only active line (those without comments<ref name="ftn50">The comments are also important as they form part of the documentation when it is generated by the <tt>make html</tt> target.</ref>) is:
 
<pre>
 
<pre>
 
<module_name> = base | module | off
 
<module_name> = base | module | off
Line 568: Line 555:
 
|-
 
|-
 
| base
 
| base
| The module will be in the base module for a modular policy build (build.conf entry MONOLITHIC = n).
+
| The module will be in the base module for a modular policy build (build.conf entry MONOLITHIC <nowiki>=</nowiki> n).
  
 
|-
 
|-
 
| module
 
| module
| The module will be built as a loadable module for a modular policy build. If a monolithic policy is being built (build.conf entry MONOLITHIC = y), then this module will be built into the base module.
+
| The module will be built as a loadable module for a modular policy build. If a monolithic policy is being built (build.conf entry MONOLITHIC <nowiki>=</nowiki> y), then this module will be built into the base module.
  
 
|-
 
|-
Line 580: Line 567:
 
|}
 
|}
  
Generally it is up to the policy writer to decide which modules are in the base and those that are loadable, however there are some modules that MUST be in the base module. To highlight this there is a special entry at the start of the modules interface file (.if) that has the entry <required val='true'> as shown below (taken from the kernel.if file):  
+
Generally it is up to the policy distributor to decide which modules are in the base and those that are loadable, however there are some modules that MUST be in the base module. To highlight this there is a special entry at the start of the modules interface file (.if) that has the entry <nowiki><required val="true"></nowiki> as shown below (taken from the kernel.if file):  
 
<pre>
 
<pre>
 
## <summary>
 
## <summary>
Line 591: Line 578:
 
</pre>
 
</pre>
  
The <tt>modules.conf</tt> file will also reflect that a module is required in the base by adding a comment "Required in base" when the make conf target is executed (as all the <tt>.if</tt> files are checked during this process and the <tt>modules.conf</tt> file updated).
+
The <tt>modules.conf</tt> file will also reflect that a module is required in the base by adding a comment 'Required in base' when the make conf target is executed (as all the <tt>.if</tt> files are checked during this process and the <tt>modules.conf</tt> file updated).
 
<pre>
 
<pre>
 
# Layer: kernel
 
# Layer: kernel
Line 602: Line 589:
 
</pre>
 
</pre>
  
There are 13 modules in the F-12 reference policy source marked as required and are shown in Table 4.
+
Those marked as required in base are shown in Table 4 (note that F-20 and the standard Reference Policy are different)
 +
 
 +
<center>'''Table 4: Mandatory modules.conf Entries'''</center>
  
 
{| border="1"
 
{| border="1"
Line 609: Line 598:
 
! Comments
 
! Comments
  
|-
 
| system
 
| application
 
| <nowiki>Policy for user executable applications.
 
 
All the interface calls start with 'application_'.</nowiki>
 
 
|-
 
| system
 
| setrans
 
| <nowiki>Policy for the SELinux MLS/MCS label translation service.
 
 
All the interface calls start with 'setrans_'.
 
</nowiki>
 
 
|-
 
|-
 
| kernel
 
| kernel
 
| corecommands
 
| corecommands
| <nowiki>Core policy for shells, and generic programs in:
+
| Core policy for shells, and generic programs in:
  
 
  /bin, /sbin, /usr/bin, and /usr/sbin.  
 
  /bin, /sbin, /usr/bin, and /usr/sbin.  
 +
 
  The .fc file sets up the labels for these items.  
 
  The .fc file sets up the labels for these items.  
  All the interface calls start with 'corecmd_'.</nowiki>
+
 +
  All the interface calls start with 'corecmd_'.
  
 
|-
 
|-
Line 712: Line 689:
  
 
All the interface calls start with '<tt>term_</tt>'.
 
All the interface calls start with '<tt>term_</tt>'.
 +
 +
|-
 +
| kernel
 +
| ubac
 +
| Disabled by Fedora but enabled on standard Ref Policy.
 +
 +
Support user-based access control.
 +
 +
|-
 +
| system
 +
| application
 +
| Enabled by Fedora but not standard Ref Policy.
 +
 +
Defines attributes and interfaces for all user apps.
 +
 +
|-
 +
| system
 +
| setrans
 +
| Enabled by Fedora but not standard Ref Policy.
 +
 +
Support for <tt>'''mcstransd'''(8)</tt>.
  
 
|}
 
|}
''Table 4: Mandatory modules.conf Entries''
 
  
  
Line 720: Line 717:
 
The file can be created by an editor, however it is generally built initially by make conf that will add any additional modules to the file. The file can then be edited to configure the required modules as base, module or off.
 
The file can be created by an editor, however it is generally built initially by make conf that will add any additional modules to the file. The file can then be edited to configure the required modules as base, module or off.
  
As will be seen in the [[NB_RefPolicy#InstallingandBuilingtheReferencePolicySource | Installing and Building the Reference Policy Source]] section, the reference policy source comes with a number of pre-configured files that are used to produce the required policy including multiple versions of the modules.conf file.
+
As will be seen in the [[#Installing_and_Builing_the Reference Policy Source | Installing and Building the Reference Policy Source]] section, the Red Hat reference policy source comes with a number of pre-configured files that are used to produce the required policy including multiple versions of the modules.conf file.
  
 
=== Source Installation and Build Make Options ===
 
=== Source Installation and Build Make Options ===
 
This section explains the various make options available that have been taken from the <tt>README</tt> file. Table 5 describes the general make targets, Table 6 describes the modular policy make targets and Table 7 describes the monolithic policy make targets.
 
This section explains the various make options available that have been taken from the <tt>README</tt> file. Table 5 describes the general make targets, Table 6 describes the modular policy make targets and Table 7 describes the monolithic policy make targets.
  
 
+
<center>'''Table 5: General Build Make Targets'''</center>
 
{| border="1"
 
{| border="1"
 
! Make Target
 
! Make Target
Line 737: Line 734:
 
| '''conf'''
 
| '''conf'''
 
| Regenerate policy.xml, and update/create modules.conf and booleans.conf. This should be done after adding or removing modules, or after running the bare target. If the configuration files exist, their settings will be preserved. This must be run on policy sources that are checked out from the CVS repository before they can be used.
 
| Regenerate policy.xml, and update/create modules.conf and booleans.conf. This should be done after adding or removing modules, or after running the bare target. If the configuration files exist, their settings will be preserved. This must be run on policy sources that are checked out from the CVS repository before they can be used.
 +
 +
Note that if <tt>make bare</tt> has been executed before this make target, or it is a first build, then the <tt>modules/kernel/corenetwork.??.in</tt> files will be used to generate the <tt>corenetwork.te</tt> and <tt>corenetwork.if</tt> module files. These <tt><nowiki>*.in</nowiki></tt> files may be edited to configure network ports etc. (see the <tt><nowiki># network_node examples</nowiki></tt> entries).
  
 
|-
 
|-
Line 755: Line 754:
  
 
|}
 
|}
''Table 5: General Build Make Targets''
 
  
  
 +
<center>'''Table 6: Modular Policy Build Make Targets'''</center>
 
{| border="1"
 
{| border="1"
 
! Make Target
 
! Make Target
Line 772: Line 771:
 
|-
 
|-
 
| '''MODULENAME.pp'''
 
| '''MODULENAME.pp'''
| Compile and package the MODULENAME Reference Policy module.
+
| Compile and package the <tt>MODULENAME</tt> Reference Policy module.
  
 
|-
 
|-
Line 793: Line 792:
 
| '''install-headers'''
 
| '''install-headers'''
 
| Install the policy headers into /usr/share/selinux/NAME. The headers are sufficient for building a policy module locally, without requiring the complete Reference Policy sources. The build.conf settings for this policy configuration should be set before using this target.
 
| Install the policy headers into /usr/share/selinux/NAME. The headers are sufficient for building a policy module locally, without requiring the complete Reference Policy sources. The build.conf settings for this policy configuration should be set before using this target.
 +
 +
|-
 +
| '''install-docs'''
 +
| Build and install the documentation and example module source with Makefile. The default location is <tt>/usr/share/doc/refpolicy-VERSION</tt>, where the version is the value in the <tt>VERSION</tt> file.
  
 
|}
 
|}
''Table 6: Modular Policy Build Make Targets''
 
  
  
 +
<center>'''Table 7: Monolithic Policy Build Make Targets'''</center>
 
{| border="1"
 
{| border="1"
 
! Make Target
 
! Make Target
Line 831: Line 834:
  
 
|}
 
|}
''Table 7: Monolithic Policy Build Make Targets''
 
  
  
Line 841: Line 843:
 
| This file is generated / updated by <tt>make conf</tt>, and contains all the booleans in the policy with their default values. If tunable and global booleans are implemented then these are also included.  
 
| This file is generated / updated by <tt>make conf</tt>, and contains all the booleans in the policy with their default values. If tunable and global booleans are implemented then these are also included.  
  
This file can also be delivered as a part of the reference policy source as shown in the [[NB_RefPolicy#Installing_and_Building_the_Reference_Policy_Source |outline Installing and Building the Reference Policy Source]] section. This is generally because other default values are used for booleans and not those defined within the modules themselves (i.e. distribution specific booleans). When the make install is executed, then this file will be used to set the default values.  
+
This file can also be delivered as a part of the Fedora reference policy source as shown in the [[#Installing and Building the Reference Policy Source | Installing and Building the Reference Policy Source]] section. This is generally because other default values are used for booleans and not those defined within the modules themselves (i.e. distribution specific booleans). When the make install is executed, this file will be used to set the default values.  
  
Note that if booleans are updated locally then the policy store will contain a booleans.local file.
+
Note that if booleans are updated locally the policy store will contain a [[PolicyStoreConfigurationFiles#modules_active_booleans.local_File | booleans.local]] file.
  
 
In SELinux enabled systems that support the policy store features (modular policies) this file is not installed as <tt>/etc/selinux/NAME/booleans</tt>.
 
In SELinux enabled systems that support the policy store features (modular policies) this file is not installed as <tt>/etc/selinux/NAME/booleans</tt>.
Line 849: Line 851:
 
|-
 
|-
 
|  global_booleans
 
|  global_booleans
| These are booleans that have been defined in the <tt>global_tunables</tt> file using the [[NB_RefPolicy#gen_bool_Macro | gen_bool]] macro. They are normally booleans for managing the overall policy and currently consist of the following (where the default values are <tt>false</tt>):
+
| These are booleans that have been defined in the <tt>global_tunables</tt> file using the [[#gen_bool Macro | gen_bool]] macro. They are normally booleans for managing the overall policy and currently consist of the following (where the default values are <tt>false</tt>):
  
 
  secure_mode
 
  secure_mode
secure_mode_insmod
 
secure_mode_policyload
 
  
 
|-
 
|-
 
|  global_tunables
 
|  global_tunables
| These are booleans that have been defined in module files using the [[NB_RefPolicy#gen_tunable_Macro | gen_tunable]] macro and added to the <tt>global_tunables</tt> file by <tt>make conf</tt>. The [[NB_RefPolicy#tunable_policy_Macro | tunable_policy]] macros are defined in each module where policy statements or interface calls are required. They are booleans for managing specific areas of policy that are global in scope. An example is <tt>allow_execstack</tt> that will allow all processes running in <tt>unconfined_t</tt> to make their stacks executable.
+
| These are booleans that have been defined in module files using the [[#gen_tunable Macro | gen_tunable]] macro and added to the <tt>global_tunables</tt> file by <tt>make conf</tt>. The [[#tunable_policy Macro | tunable_policy]] macros are defined in each module where policy statements or interface calls are required. They are booleans for managing specific areas of policy that are global in scope. An example is <tt>allow_execstack</tt> that will allow all processes running in <tt>unconfined_t</tt> to make their stacks executable.
  
 
|}
 
|}
Line 867: Line 867:
 
When make all or make load or make install are executed the build.conf and modules.conf files are used to define the policy name and what modules will be built in the base and those as individual loadable modules.
 
When make all or make load or make install are executed the build.conf and modules.conf files are used to define the policy name and what modules will be built in the base and those as individual loadable modules.
  
Basically the source modules (<tt>.te</tt>, <tt>.if</tt> and <tt>.fc</tt>) and core flask files are rebuilt in the tmp directory where the reference policy macros<ref name="ftn58">These are explained in the [[NB_RefPolicy#Reference_Policy_Macros | Reference Policy Macros]] section.</ref> in the source modules will be expanded to form actual policy language statements as described in the [[PolicyLanguage | Policy Language]] section. Figure 3 shows these temporary files that are used to form the base.conf<ref name="ftn59">The base.conf gets built for modular policies and a policy.conf file gets built for a monolithic policy.</ref> file during policy generation.  
+
Basically the source modules (<tt>.te</tt>, <tt>.if</tt> and <tt>.fc</tt>) and core flask files are rebuilt in the tmp directory where the reference policy macros<ref name="ftn51"><sup>These are explained in the [[#Reference Policy Support Macros | Reference Policy Macros]] section.</sup></ref> in the source modules will be expanded to form actual policy language statements as described in the [[PolicyLanguage#Kernel_Policy_Language | SELinux Policy Language Policy Language]] section. '''Layout 1''' shows these temporary files that are used to form the base.conf<ref name="ftn52"><sup>The base.conf gets built for modular policies and a policy.conf file gets built for a monolithic policy.</sup></ref> file during policy generation.  
  
 
The <tt>base.conf</tt> file will consist of language statements taken from the module defined as <tt>base</tt> in the <tt>modules.conf</tt> file along with the constraints, users etc. that are required to build a complete policy.
 
The <tt>base.conf</tt> file will consist of language statements taken from the module defined as <tt>base</tt> in the <tt>modules.conf</tt> file along with the constraints, users etc. that are required to build a complete policy.
  
The individual loadable modules are built in much the same way as shown in Figure 4.
+
The individual loadable modules are built in much the same way as shown in '''Layout 2'''.
  
 +
<center>'''Layout 1: Base Module Build - '''''This shows the temporary build files used to build the base module '<tt>base.conf</tt>' as a part of the 'make' process. Note that the modules marked as <tt>base</tt> in <tt>modules.conf</tt> are built here. ''</center>
 
{| border="1"
 
{| border="1"
 
! Base Policy Component Description
 
! Base Policy Component Description
Line 902: Line 903:
  
 
|-
 
|-
| This area contains all the attribute, bool, type and typealias statements extracted from the *.te and *.if files that form the base module.
+
| This area contains all the attribute, bool, type and typealias statements extracted from the <nowiki>*.te</nowiki> and <nowiki>*.if</nowiki> files that form the base module.
 
| modules/*/*.te
 
| modules/*/*.te
  
Line 919: Line 920:
  
 
|-
 
|-
| Contains the rules extracted from each of the modules .te and .if files defined in the modules.conf file as "base".
+
| Contains the rules extracted from each of the modules .te and .if files defined in the modules.conf file as 'base'.
 
| base modules
 
| base modules
 
| only_te_rules.conf
 
| only_te_rules.conf
Line 933: Line 934:
  
 
|-
 
|-
| Contains the default SID labeling extracted from the *.te files.
+
| Contains the default SID labeling extracted from the <nowiki>*.te</nowiki> files.
 
| modules/*/*.te
 
| modules/*/*.te
  
 
|-
 
|-
| Contains the fs_use_xattr, fs_use_task, fs_use_trans and genfscon statements extracted from each of the modules .te and .if files defined in the modules.conf file as "base".
+
| Contains the fs_use_xattr, fs_use_task, fs_use_trans and genfscon statements extracted from each of the modules .te and .if files defined in the modules.conf file as 'base'.
 
| modules/*/*.te
 
| modules/*/*.te
  
Line 946: Line 947:
  
 
|-
 
|-
| Contains the netifcon, nodecon and portcon statements extracted from each of the modules .te and .if files defined in the modules.conf file as "base".
+
| Contains the netifcon, nodecon and portcon statements extracted from each of the modules .te and .if files defined in the modules.conf file as 'base'.
 
| modules/*/*.te
 
| modules/*/*.te
  
Line 956: Line 957:
  
 
|-
 
|-
| Contains the expanded file context file entries extracted from the *.fc files defined in the modules.conf file as "base".
+
| Contains the expanded file context file entries extracted from the <nowiki>*.fc</nowiki> files defined in the modules.conf file as 'base'.
 
| modules/*/*.fc
 
| modules/*/*.fc
 
| base.fc.tmp
 
| base.fc.tmp
Line 967: Line 968:
 
|-
 
|-
 
| colspan="3" | These are the commands used to compile, link and load the base policy module:
 
| colspan="3" | These are the commands used to compile, link and load the base policy module:
 
+
<pre>
 
checkmodule base.conf -o tmp/base.mod
 
checkmodule base.conf -o tmp/base.mod
 
 
semodule_package -o base.conf -m base_mod -f base_fc -u users_extra -s tmp/seusers
 
semodule_package -o base.conf -m base_mod -f base_fc -u users_extra -s tmp/seusers
 
 
semodule -s $(NAME) -b base.pp) -i and each module .pp file
 
semodule -s $(NAME) -b base.pp) -i and each module .pp file
 
+
</pre>
The "NAME" is that defined in the build.conf file.
+
The 'NAME' is that defined in the build.conf file.
  
 
|}
 
|}
''Figure 3: Base Module Build - This shows the temporary build files used to build the base module "<tt>base.conf</tt>" as a part of the "make" process. Note that the modules marked as <tt>base</tt> in <tt>modules.conf</tt> are built here. ''
 
  
  
 +
<center>'''Layout 2: Module Build - '''''This shows the module files and the temporary build files used to build each module as a part of the 'make' process (i.e. those modules marked as <tt>module</tt> in <tt>modules.conf</tt>).''</center>
 
{| border="1"
 
{| border="1"
 
| '''Base Policy Component Description'''
 
| '''Base Policy Component Description'''
Line 988: Line 987:
  
 
|-
 
|-
| For each module defined as "module" in the modules.conf configuration file, a source module is produced that has been extracted from the *.te and *.if file for that module.
+
| For each module defined as 'module' in the modules.conf configuration file, a source module is produced that has been extracted from the <nowiki>*.te</nowiki> and <nowiki>*.if</nowiki> file for that module.
 
| <nowiki>modules/*/<module_name>.te</nowiki>
 
| <nowiki>modules/*/<module_name>.te</nowiki>
  
Line 1,001: Line 1,000:
  
 
|-
 
|-
| For each module defined as "module" in the modules.conf configuration file, an object module is produced from executing the checkmodule command shown below.
+
| For each module defined as 'module' in the modules.conf configuration file, an object module is produced from executing the checkmodule command shown below.
| tmp/<module_name>.tmp
+
| <nowiki>tmp/<module_name>.tmp</nowiki>
| <module_name>.mod
+
| <nowiki><module_name>.mod</nowiki>
  
 
|-
 
|-
| For each module defined as "module" in the modules.conf configuration file, an expanded file context file is built from the <module_name>.fc file.
+
| For each module defined as 'module' in the modules.conf<nowiki> configuration file, an expanded file context file is built from the <module_name></nowiki>.fc file.
 
| <nowiki>modules/*/<module_name>.fc</nowiki>
 
| <nowiki>modules/*/<module_name>.fc</nowiki>
 
| base.fc.tmp
 
| base.fc.tmp
Line 1,019: Line 1,018:
 
<pre>
 
<pre>
 
semodule_package -o base.conf -m base_mod -f base_fc -u users_extra -s tmp/seusers
 
semodule_package -o base.conf -m base_mod -f base_fc -u users_extra -s tmp/seusers
 
 
semodule -s $(NAME) -b base.pp) -i and each module .pp file
 
semodule -s $(NAME) -b base.pp) -i and each module .pp file
 
</pre>
 
</pre>
The "NAME" is that defined in the build.conf file.
+
The 'NAME' is that defined in the build.conf file.
  
 
|}
 
|}
''Figure 4: Module Build - This shows the module files and the temporary build files used to build each module as a part of the "make" process (i.e. those modules marked as <tt>module</tt> in <tt>modules.conf</tt>).''
 
 
  
 
=== Creating Additional Layers ===
 
=== Creating Additional Layers ===
One objective of the reference policy is to separate the modules into different layers reflecting their "service" (e.g. kernel, system, app etc.). While it can sometimes be difficult to determine where a particular module should reside, it does help separation, however because the way the build process works, each module must have a unique name.
+
One objective of the reference policy is to separate the modules into different layers reflecting their 'service' (e.g. kernel, system, app etc.). While it can sometimes be difficult to determine where a particular module should reside, it does help separation, however because the way the build process works, each module must have a unique name.
  
 
If a new layer is required, then the following will need to be completed:
 
If a new layer is required, then the following will need to be completed:
Line 1,040: Line 1,036:
  
 
== Installing and Building the Reference Policy Source ==
 
== Installing and Building the Reference Policy Source ==
This section explains how to install the F-12 reference policy source that is distributed by Red Hat (however the same principle is followed for the source taken directly from the [http://oss.tresys.com/projects/refpolicy Tresys repository], except that it will not build a compatible policy to that discussed in this section).
+
This section will give a brief overview of how to build the Reference Policy for an MCS modular build that is similar (but not the same) as the Fedora targeted policy. The Fedora F-20 version of the targeted policy build is discussed but building without using the rpm spec file is more complex.  
  
Any F-12 policy source rpm will suffice and can be obtained from the [http://koji.fedoraproject.org/ http://koji.fedoraproject.org] web site, however it is assumed that the source rpm is:
+
=== Building Standard Reference Policy ===
 +
This will run through a simple configuration process and build of a reference policy similar to the Fedora targeted policy. By convention the source is installed in a central location and then for each type of policy a copy of the source is installed at <tt><nowiki>/etc/selinux/<NAME>/src/policy</nowiki></tt>.
  
: '''selinux-policy-3.6.32-103.fc12.src.rpm'''
+
The basic steps are:
 +
* Install master Reference Policy Source and add the contributed modules:
 +
<pre>
 +
# Check out the core policy:
 +
git clone https://github.com/TresysTechnology/refpolicy.git
 +
cd refpolicy
  
The objective of this exercise is to show that the policy built from the above source rpm is an exact replica of the targeted policy distributed as header files in the F-12 targeted rpm:
+
# Add the contibuted modules (policy/modules/contrib)
 +
git submodule init
 +
git submodule update
 +
</pre>
  
: '''selinux-policy-targeted-3.6.32-103.fc12.noarch.rpm'''
+
* Edit the <tt>build.conf</tt> file to reflect the policy to be built, the minimum required is setting the <tt>NAME =</tt> entry. An example file with <tt>NAME = refpolicy-test</tt> is as follows:
 +
<pre>
 +
############################################
 +
# Policy build options
 +
#
  
Note that there is a good overview of rebuilding the source policy at Dan Walsh's site:
+
# Policy version
 +
# By default, checkpolicy will create the highest version policy it supports.
 +
# Setting this will override the version. This only has an effect for
 +
# monolithic policies.
 +
#OUTPUT_POLICY = 18
  
: [http://danwalsh.livejournal.com/2009/02/16/ http://danwalsh.livejournal.com/2009/02/16/]
+
# Policy Type
 +
# standard, mls, mcs. ** Note Red Hat always build the MCS Policy Type
 +
# for their 'targeted' version. **
 +
TYPE = mcs
  
=== Installation and Configuration ===
+
# Policy Name
Install the source by:
+
# If set, this will be used as the policy name. Otherwise the policy type
<pre>
+
# will be used for the name. ** This entry is also used by the
rpm -Uvh selinux-policy-3.6.32-103.fc12.src.rpm
+
#'make install-src' process to copy the source to the:
</pre>
+
#    /etc/selinux/<NAME>/src/policy directory. **
 +
NAME = refpolicy-test
  
The source will be installed in the users home directory under ./rpmbuild/SOURCES where the serefpolicy-3.6.32.tgz will need to be unpacked:
+
# Distribution
<pre>
+
# Some distributions have portions of policy for programs or configurations
cd $HOME/rpmbuild/SOURCES
+
# specific to the distribution. Setting this will enable options for the
tar -xzf serefpolicy.tgz
+
# distribution. redhat, gentoo, debian, suse, and rhel4 are current options.
 +
# ** Fedora users should enable redhat.**
 +
DISTRO = redhat
 +
 
 +
# Unknown Permissions Handling
 +
# The behaviour for handling permissions defined in the kernel but missing
 +
# from the policy. The permissions can either be allowed, denied, or
 +
# the policy loading can be rejected.
 +
# allow, deny, and reject are current options. ** Fedora use allow for all
 +
# policies except MLS that uses 'deny'.**
 +
UNK_PERMS = allow
 +
 
 +
# Direct admin init
 +
# Setting this will allow sysadm to directly run init scripts, instead of
 +
# requiring run_init. This is a build option, as role transitions do not
 +
# work in conditional policy.
 +
DIRECT_INITRC = n
 +
 
 +
# Build monolithic policy. Putting y here will build a monolithic policy.
 +
MONOLITHIC = n
 +
 
 +
# User-based access control (UBAC)
 +
# Enable UBAC for role separations. ** Note Fedora disables UBAC.**
 +
UBAC = n
 +
 
 +
# Custom build options. This field enables custom build options. Putting
 +
# foo here will enable build option blocks foo. Options should be separated
 +
# by spaces.
 +
CUSTOM_BUILDOPT =
 +
 
 +
# Number of MLS Sensitivities
 +
# The sensitivities will be s0 to s(MLS_SENS-1). Dominance will be in
 +
# increasing numerical order with s0 being lowest.
 +
MLS_SENS = 16
 +
 
 +
# Number of MLS Categories.
 +
# The categories will be c0 to c(MLS_CATS-1).
 +
MLS_CATS = 1024
 +
 
 +
# Number of MCS Categories
 +
# The categories will be c0 to c(MLC_CATS-1).
 +
MCS_CATS = 1024
 +
 
 +
# Set this to y to only display status messages during build.
 +
QUIET = n
 
</pre>
 
</pre>
  
The <tt>SOURCES</tt> directory contents will then look like this:
+
* Run <tt>make install-src</tt> to install source at policy build location.
 +
* Change to the <tt><nowiki>/etc/selinux/<NAME>/src/policy</nowiki></tt> directory where an unconfigured basic policy has been installed.
 +
* Run <tt>make conf</tt> to build an initial <tt>policy/booleans.conf</tt> and <tt>policy/modules.conf</tt> files. For this simple configuration these files will not be edited.
 +
: This process will also build the <tt>policy/modules/kernel/corenetwork.te</tt> / <tt>corenetwork.if</tt> files if not already present. These would be based on the contents of <tt>corenetwork.te.in</tt> and <tt>corenetwork.if.in</tt> configuration files (for this simple configuration these files will not be edited).
 +
: Run <tt>make load</tt> to build the policy, add the modules to the store and install the binary kernel policy plus its supporting configuration files.
 +
: Note that if policy stores have been migrated, the store will default to <tt>/var/lib/selinux/refpolicy-test</tt>, with the modules in <tt><nowiki>active/modules/400/<module_name></nowiki></tt>, there will also be a CIL version of the module (see [#4.1.1.Policy Store Migration|outline Policy Store Migration] for details).
 +
* The policy should now be built and can be checked using tools such as <tt>'''apol'''(8)</tt> or loaded by editing the <tt>/etc/selinux/config</tt> file, running '<tt>touch /.autorelabel</tt>' and rebooting the system.
 +
 
 +
=== Building the Fedora Policy ===
 +
Building Fedora policies by hand is complex as they use the <tt>rpmbuild/SPECS/selinux-policy.spec</tt> file, therefore this section will give an overview of how this can be achieved, the reader can then experiment (the spec file gives an insight). The build process assumes that an equivelent '<tt>targeted</tt>' policy will be built named '<tt>targeted-179</tt>'.
 +
 
 +
Install the source as follows:
 
<pre>
 
<pre>
booleans-minimum.conf    booleans-mls.conf      booleans-olpc.conf
+
rpm -Uvh selinux-policy-3.12.1-179.fc20.src.rpm
booleans-targeted.conf  config.tgz            customizable_types
+
Makefile.devel          modules-minimum.conf  modules-mls.conf
+
modules-olpc.conf        modules-targeted.conf  policy-20100106.patch
+
policy-F12.patch        policygentool          securetty_types-minimum
+
securetty_types-mls      securetty_types-olpc  securetty_types-targeted
+
serefpolicy-3.6.32      serefpolicy-3.6.32.tgz setrans-minimum.conf
+
setrans-mls.conf        setrans-olpc.conf      setrans-targeted.conf
+
users-minimum            users-mls              users-olpc
+
users-targeted
+
 
</pre>
 
</pre>
  
The files with minimum, targeted, mls and olpc within their names are the specific configuration files used within the Reference Policy for that particular Red Hat policy type.
+
The <tt>rpmbuild/SOURCES</tt> directory contents should be as follows with comments on how the files should be installed:
  
The latest patches now need to be applied to the source tree as follows:
+
{| border="1"
 +
| <center>'''File Name'''</center>
 +
| <center>'''Comments'''</center>
 +
 
 +
|-
 +
| serefpolicy-3.12.1.tgz
 +
| The Reference Policy version 2.20120725
 +
 
 +
This should be unpacked into:
 
<pre>
 
<pre>
patch -p0 <policy-F12.patch
+
rpmbuild/SOURCES/serefpolicy-3.12.1
 +
</pre>
 +
|-
 +
| policy-f20-base.patch
 +
| Fedora changes to Reference Policy version 2.20120725.
  
patch -p0 <policy-20100106.patch
+
These patches should be used to update the above
 +
<pre>
 +
patch -p1 < policy-f20-base.patch
 
</pre>
 
</pre>
 +
|-
 +
| serefpolicy-contrib-3.12.1.tgz
 +
| The Reference Policy contribution modules from version 2.20120725
  
The <tt>config.tgz</tt> is Red Hat's updated configuration files this will need to be unpacked and replace the original set of files:
+
Unpack the files, apply the <tt>policy-f20-contrib.patch</tt> and then installed into:
 
<pre>
 
<pre>
# Unpack the archive:
+
./serefpolicy-3.12.1/policy/modules/contrib
tar -xzf config.tgz
+
</pre>
 +
|-
 +
| policy-f20-contrib.patch
 +
| Fedora changes to Reference Policy contribution modules.
  
# move to source directory:
+
|-
cd serefpolicy-3.6.32
+
| colspan="2" | Once the above has been completed, run <tt>make conf</tt> from <tt>./serefpolicy-3.12.1 </tt>to initialise the build (it creates two important files in <tt>./serefpolicy-3.12.1/policy/modules/kernel</tt> called <tt>corenetwork.te</tt> and <tt>corenetwork.if</tt>).
  
# save the old files:
+
|-
mv config config.org
+
| config.tgz
 +
| Fedora changes to Reference Policy version 2.20120725 application config files.
  
# and copy over the new Red Hat files
+
These should be unpacked to update the <tt>./serefpolicy-3.12.1/config</tt> versions (some will be added and others updated).
cp -r ../config config
+
</pre>
+
  
As the "targeted" policy is being built, the files shown in Table 8 left hand column need to be copied to the location and named as shown in the right hand column.
+
|-
 +
| permissivedomains.pp
 +
| Contains Fedora domains currently sets to permissive. In <tt>selinux-policy-3.12.1-179.fc20</tt> there are 31 permissive domains. Copy this to <tt>./serefpolicy-3.12.1</tt> as it will then be built into the policy.
  
{| border="1"
+
|-
| <center>'''Configuration File:'''</center>
+
| selinux-policy.conf
| <center>'''Installed as Reference Policy Configuration File:'''</center>
+
| Allows the build process to determine network information.
 +
 
 +
Not required for this exercise as the <tt>corenetwork.te</tt> and <tt>corenetwork.if</tt> files have been built.
  
 
|-
 
|-
| booleans-targeted.conf
+
| Makefile.devel
| ./serefpolicy-3.6.32/policy/booleans.conf
+
| Fedora makefile when using headers. This can replace the <tt>./serefpolicy-3.12.1/support/Makefile.devel</tt>
 +
 
 +
|-
 +
| booleans.subs_dist
 +
| Common files installed for each policy type. Not required for this exercise.
  
 
|-
 
|-
 
| customizable_types
 
| customizable_types
| ./serefpolicy-3.6.32/config/appconfig-mcs/ customizable_types
 
  
 
|-
 
|-
| modules-targeted.conf
+
| file_contexts.subs_dist
| ./serefpolicy-3.6.32/policy/modules.conf
+
 
 +
|-
 +
| colspan="2" | <center>'''Used to build "targeted" policy'''</center>
 +
 
 +
|-
 +
| booleans-targeted.conf
 +
| Replace the <tt>./serefpolicy-3.12.1/policy/booleans.conf</tt> file with this version.
 +
 
 +
|-
 +
| modules-targeted-base.conf
 +
| Concatenate both files and copy this to become:
 +
 
 +
<tt>./serefpolicy-3.12.1/policy/modules.conf</tt>
 +
 
 +
|-
 +
| modules-targeted-contrib.conf
  
 
|-
 
|-
 
| securetty_types-targeted
 
| securetty_types-targeted
| ./serefpolicy-3.6.32/config/appconfig-mcs/ securetty_types
+
| Replace the <tt>./serefpolicy-3.12.1/config/appconfig-mcs/securetty_types</tt> file with this version.
  
 
|-
 
|-
 
| setrans-targeted.conf
 
| setrans-targeted.conf
| ./serefpolicy-3.6.32/config/appconfig-mcs/ setrans.conf
+
| Not required for this exercise.
  
 
|-
 
|-
| users-targeted.conf
+
| users-targeted
| ./serefpolicy-3.6.32/policy/users
+
| Replace the <tt>./serefpolicy-3.12.1/policy/users</tt> file with this version.
  
|}
+
|-
''Table 8: Red Hat specific policy configuration files - This example builds a "targeted" policy.''
+
| colspan="2" | <center>'''Used to build "<tt>minimum</tt>" policy'''</center>
  
 +
|-
 +
| booleans-minimum.conf
 +
|
  
The serefpolicy-3.6.32 directory will now contain the source code with the latest patches for this release (3.6.32-103) of the Red Hat Reference Policy and the correct configuration files for a targeted policy.
+
|-
 +
| modules-targeted-base.conf
 +
| Uses the targeted <tt>modules.conf</tt>.
  
The ./serefpolicy-3.6.32/build.conf must now be modified to allow the source to be installed in its final location and have the correct parameters set for the build. The entries that need to be updated in the build.conf file are highlighted below<ref name="ftn60">The README file in this directory contains helpful information on installation of the source, headers, documentation etc. The only point the <tt>README</tt> will not cover are the Red Hat specific configuration files that need to be copied over as shown in Table 8.</ref>:
+
|-
 +
| modules-targeted-contrib.conf
 +
 
 +
|-
 +
| securetty_types-minimum
 +
|
 +
 
 +
|-
 +
| setrans-minimum.conf
 +
|
 +
 
 +
|-
 +
| users-minimum
 +
|
 +
 
 +
|-
 +
| colspan="2" | <center>'''Used to build "<tt>mls</tt>" policy'''</center>
 +
 
 +
|-
 +
| booleans-mls.conf
 +
|
 +
 
 +
|-
 +
| modules-mls-base.conf
 +
|
 +
 
 +
|-
 +
| modules-mls-contrib.conf
 +
|
 +
 
 +
|-
 +
| securetty_types-mls
 +
|
 +
 
 +
|-
 +
| setrans-mls.conf
 +
|
 +
 
 +
|-
 +
| users-mls
 +
|
 +
 
 +
|}
 +
 
 +
 
 +
The basic steps are:
 +
* Edit the <tt>build.conf</tt> file to reflect the policy to be built:
 
<pre>
 
<pre>
#
+
############################################
 
# Policy build options
 
# Policy build options
 
#
 
#
Line 1,153: Line 1,308:
  
 
# Policy Type
 
# Policy Type
# standard, mls, mcs. Note Red Hat always build the MCS Policy Type as their “targeted” version.
+
# standard, mls, mcs. ** Note Red Hat always build the MCS Policy Type
 +
# for their 'targeted' version. **
 
TYPE = mcs
 
TYPE = mcs
  
 
# Policy Name
 
# Policy Name
 
# If set, this will be used as the policy name. Otherwise the policy type  
 
# If set, this will be used as the policy name. Otherwise the policy type  
# will be used for the name. This entry is also used by the "make install-src" process to copy the source to the:
+
# will be used for the name. ** This entry is also used by the
# /etc/selinux/targeted-103/src/policy directory.
+
# 'make install-src' process to copy the source to the:
NAME = targeted-103
+
#     /etc/selinux/<NAME>/src/policy directory.**
 +
NAME = targeted-179
  
 
# Distribution
 
# Distribution
Line 1,166: Line 1,323:
 
# specific to the distribution. Setting this will enable options for the
 
# specific to the distribution. Setting this will enable options for the
 
# distribution. redhat, gentoo, debian, suse, and rhel4 are current options.
 
# distribution. redhat, gentoo, debian, suse, and rhel4 are current options.
# Fedora users should enable redhat.
+
# Fedora users should enable ** redhat. **
 
DISTRO = redhat
 
DISTRO = redhat
  
 
# Unknown Permissions Handling
 
# Unknown Permissions Handling
# The behaviour for handling permissions defined in the kernel but missing from
+
# The behaviour for handling permissions defined in the kernel but missing
# the policy. The permissions can either be allowed, denied, or the policy
+
# from the policy. The permissions can either be allowed, denied, or
# loading can be rejected.
+
# the policy loading can be rejected.
# allow, deny, and reject are current options. Red Hat use allow for all
+
# allow, deny, and reject are current options. ** Fedora use allow for all
# policies except MLS that uses 'deny'.
+
# policies except MLS that uses 'deny'.**
 
UNK_PERMS = allow
 
UNK_PERMS = allow
  
 
# Direct admin init
 
# Direct admin init
 
# Setting this will allow sysadm to directly run init scripts, instead of  
 
# Setting this will allow sysadm to directly run init scripts, instead of  
# requiring run_init. This is a build option, as role transitions do not work in
+
# requiring run_init. This is a build option, as role transitions do not
# conditional policy.
+
# work in conditional policy.
 
DIRECT_INITRC = n
 
DIRECT_INITRC = n
  
# Build monolithic policy. Putting n here will build a loadable module policy.
+
# Build monolithic policy. Putting y here will build a monolithic policy.
 
MONOLITHIC = n
 
MONOLITHIC = n
  
 
# User-based access control (UBAC)
 
# User-based access control (UBAC)
# Enable UBAC for role separations. Note Red Hat disable UBAC.
+
# Enable UBAC for role separations. ** Note Fedora disables UBAC **
 
UBAC = n
 
UBAC = n
 +
 +
# Custom build options. This field enables custom build options. Putting
 +
# foo here will enable build option blocks foo. Options should be separated
 +
# by spaces.
 +
CUSTOM_BUILDOPT =
  
 
# Number of MLS Sensitivities
 
# Number of MLS Sensitivities
# The sensitivities will be s0 to s(MLS_SENS-1). Dominance will be in increasing
+
# The sensitivities will be s0 to s(MLS_SENS-1). Dominance will be in
# numerical order with s0 being lowest.
+
# increasing numerical order with s0 being lowest.
 
MLS_SENS = 16
 
MLS_SENS = 16
  
# Number of MLS Categories. Note Red Hat use 1024 categories for MLS and MCS.
+
# Number of MLS Categories.
 
# The categories will be c0 to c(MLS_CATS-1).
 
# The categories will be c0 to c(MLS_CATS-1).
 
MLS_CATS = 1024
 
MLS_CATS = 1024
  
 
# Number of MCS Categories
 
# Number of MCS Categories
# The categories will be c0 to c(MLS_CATS-1).
+
# The categories will be c0 to c(MLC_CATS-1).
 
MCS_CATS = 1024
 
MCS_CATS = 1024
  
Line 1,207: Line 1,369:
 
</pre>
 
</pre>
  
The policy source is now in a position to be installed at its default location that will be derived from the NAME = targeted-103 entry and will therefore be located at:
+
* From <tt>rpmbuild/SOURCES/serefpolicy-3.12.1</tt> run <tt>make install-src</tt> to install source at policy build location.
 
+
* Change to the <tt>/etc/selinux/targeted-179/src/policy</tt> directory where the policy has been installed.
: /etc/selinux/targeted-103/src/policy
+
* Run <tt>make load</tt> to build the policy, add the modules to the store and install the binary kernel policy plus its supporting configuration files.
 
+
: Note that if policy stores have been migrated, the store will default to <tt>/var/lib/selinux/targeted-179</tt>, with the modules in <tt><nowiki>active/modules/400/<module_name></nowiki></tt>, there will also be a CIL version of the module (see [#4.1.1.Policy Store Migration|outline Policy Store Migration] for details).
=== Building the targeted Policy Type ===
+
* Install the <tt>permissivedomains.pp</tt> module as follows (this will set 31 permissive domains that are in the F-20 version of the policy):
From the ./serefpolicy-3.6.32 directory run the following command:
+
 
<pre>
 
<pre>
make install-src
+
semodule -s targeted-179 -i permissivedomains.pp
 
</pre>
 
</pre>
  
This will copy the source code to its final location making any directories required.
+
* The policy should now be built and can be checked using tools such as <tt>'''apol'''(8)</tt> or loaded by editing the <tt>/etc/selinux/config</tt> file, running '<tt>touch /.autorelabel</tt>' and rebooting the system.
 
+
Once the copy process is complete the policy can be built and the modules loaded into the policy store<ref name="ftn61">Note that the term "load" is not loading the policy as the active policy, but just building the base policy + the modules and installing them ready to be activated if required</ref> by running the following commands:
+
<pre>
+
# Go to the source location:
+
cd /etc/selinux/targeted-103/src/policy
+
</pre>
+
<pre>
+
# To ensure a clean source build:
+
make clean
+
</pre>
+
<pre>
+
# Build the policy modules and load into the policy store:
+
make load
+
</pre>
+
<pre>
+
# Finally copy over two files that are not automatically
+
# managed by the build process. These are held in the
+
# config/appconfig-mcs directory.
+
#
+
cp config/appconfig-mcs/setrans.conf /etc/selinux/targeted-103
+
 
+
# Need to over-write the old version of this file with this one:
+
cp config/appconfig-mcs/customizable_types /etc/selinux/targeted-103/contexts
+
</pre>
+
 
+
The policy will now be built as a targeted policy that will be an exact copy of the policy distributed in the following rpm:
+
 
+
: '''selinux-policy-targeted-3.6.32-103.fc12.noarch.rpm'''
+
 
+
=== Checking the Build ===
+
Now that the targeted policy has been built, the policy binary file can be compared to the one that is distributed and built by the following rpm:
+
 
+
: '''selinux-policy-targeted-3.6.32-103.fc12.noarch'''
+
 
+
The binary files sizes of both policies should be 4,776,004 bytes.
+
<pre>
+
ls -l /etc/selinux/targeted/policy
+
-rw-r--r-- root root 4776004 <date+time> policy.24
+
 
+
ls -l /etc/selinux/targeted-103/policy
+
-rw-r--r-- root root 4776004 <date+time> policy.24
+
</pre>
+
 
+
Note that the binaries would not be an exact comparison due to time stamps etc., therefore the SETools sediffx utility should be run against the two binary policies<ref name="ftn62">Be aware that comparing these two policies on a low specification machine will take hours. It is best to select a few items for comparison first.</ref> which should show that they are the same and give the results shown in [http://taiga.selinuxproject.org/~rhaines/diagrams/5-5-Two-Policies.png "Comparing the two "targeted" policies using <tt>sediffx</tt>"] screen shots.
+
 
+
=== Running with the new Policy ===
+
To run the system using the new <tt>targeted-103</tt> build edit the <tt>/etc/selinux/config</tt> file entry to read <tt>SELINUXTYPE=targeted-103</tt>, and then run the following commands:
+
<pre>
+
touch /.autorelabel
+
reboot
+
</pre>
+
 
+
During reboot, the system will be relabeled and the policy loaded (hopefully with no errors).
+
  
 
== Reference Policy Headers ==
 
== Reference Policy Headers ==
 
This method of building policy and adding new modules is used for distributions that do not require access to the source code.  
 
This method of building policy and adding new modules is used for distributions that do not require access to the source code.  
  
Note that the Reference Policy header and the [[NB_RefPolicy#Using_F-12_Supplied_Headers | Red Hat F-12 policy header installations]] are slightly different as described below.
+
Note that the Reference Policy header and the Fedora policy header installations are slightly different as described below.
  
 
=== Building and Installing the Header Files ===
 
=== Building and Installing the Header Files ===
 
To be able to fully build the policy headers from the reference policy source two steps are required:
 
To be able to fully build the policy headers from the reference policy source two steps are required:
 
+
* Ensure the source is installed and configured as described in the [[#8.4.Installing and Building the Reference Policy Source | Installing and Building the Reference Policy Source]] section. This is because the <tt>make load</tt> (or <tt>make install</tt>) command will package all the modules as defined in the <tt>modules.conf</tt> file, producing a <tt>base.pp</tt> and the relevant <tt>.pp</tt> packages. The build process will then install these in the <tt><nowiki>/usr/share/selinux/<NAME></nowiki></tt> directory.
# Ensure the source is installed and configured as described in the [[NB_RefPolicy#Installing_and_Building_the_Reference_Policy_Source | Installing and Building the Reference Policy Source]] section. This is because the <tt>make load</tt> (or <tt>make install</tt>) command will package all the modules as defined in the <tt>modules.conf</tt> file, producing a <tt>base.pp</tt> and the relevant <tt>.pp</tt> packages. The build process will then install these files in the <tt>/usr/share/selinux/<policy_name></tt> directory.
+
* Execute the <tt>make install-headers</tt> that will:
# Execute the <tt>make install-headers</tt> command that will:
+
** Produce a <tt>build.conf</tt> file that represents the contents of the master <tt>build.conf</tt> file and place it in the <tt><nowiki>/usr/share/selinux/<NAME>/include</nowiki></tt> directory.
: a) Produce a <tt>build.conf</tt> file that represents the contents of the master <tt>build.conf</tt> file and place it in the <tt>/usr/share/selinux/<policy_name>/include</tt> directory.
+
** Produce the XML documentation set that reflects the source and place it in the <tt><nowiki>/usr/share/selinux/<NAME>/include</nowiki></tt> directory.
: b) Produce the XML documentation set that reflects the source and place it in the <tt>/usr/share/selinux/<policy_name>/include</tt> directory.
+
** Copy a development <tt>Makefile</tt> for building from policy headers to the <tt><nowiki>/usr/share/selinux/<NAME>/include</nowiki></tt> directory.
: c) Copy a development <tt>Makefile</tt> for building from policy headers to the <tt>/usr/share/selinux/<policy_name>/include</tt> directory.
+
** Copy the support macros <tt>.spt</tt> files to the <tt><nowiki>/usr/share/selinux/<NAME>/include/support</nowiki></tt> directory. This will also include an <tt>all_perms.spt</tt> file that will contain macros to allow all classes and permissions to be resolved.
: d) Copy the support macros <tt>.spt</tt> files to the <tt>/usr/share/selinux/<policy_name>/include/support</tt> directory.
+
** Copy the module interface files (<tt>.if</tt>) to the relevant module directories at:
: e) Copy the module interface files (<tt>.if</tt>) to the relevant module directories at:
+
:: <tt>/usr/share/selinux/<policy_name>/include/modules</tt>.
+
 
+
The directory structure for the <tt>targeted-103</tt> build generated above (edited for readability) would be:
+
 
<pre>
 
<pre>
# The policy packages:
+
/usr/share/selinux/<NAME>/include/modules
targeted-103/abrt.pp
+
....
+
targeted-103/base.pp
+
 
+
# Build / Configuration files:
+
targeted-103/include/build.conf
+
targeted-103/include/Makefile
+
targeted-103/include/rolemap # Note this file is not used by F-12
+
 
+
# XML Documentation:
+
targeted-103/include/global_tunables.xml
+
targeted-103/include/global_booleans.xml
+
targeted-103/include/apps.xml
+
targeted-103/include/roles.xml
+
targeted-103/include/system.xml
+
targeted-103/include/kernel.xml
+
targeted-103/include/services.xml
+
targeted-103/include/admin.xml
+
 
+
# Support Macros:
+
targeted-103/include/support/ipc_patterns.spt
+
...
+
...
+
 
+
# The module interface files in their relevant directories:
+
targeted-103/include/admin/acct.if
+
..
+
targeted-103/include/apps/ada.if
+
..
+
targeted-103/include/kernel/corecommands.if
+
..
+
targeted-103/include/roles/auditadm.if
+
..
+
targeted-103/include/services/abrt.if
+
...
+
targeted-103/include/system/application.if
+
...
+
 
</pre>
 
</pre>
  
=== Using the Header Files ===
+
=== Using the Reference Policy Headers ===
Note that this section describes the standard Reference Policy headers, the F-12 installation is slightly different and described in the [[NB_RefPolicy#Using_F-12_Supplied_Headers | Using F-12 Supplied Headers]] section.  
+
Note that this section describes the standard Reference Policy headers, the F-20 installation is slightly different and described in the [[#Using Fedora Supplied Headers | Using Fedora Supplied Headers]] section.  
  
Once the headers are installed as defined above, new modules can be built in any local directory. An example set of module files are located in the reference policy source at /etc/selinux/targeted-103/src/policy/<tt>doc</tt> and are called <tt>example.te</tt>, <tt>example.if</tt>, and <tt>example.fc</tt>.
+
Once the headers are installed as defined above, new modules can be built in any local directory. An example set of module files are located in the reference policy source at <nowiki>/etc/selinux/<NAME>/src/policy/</nowiki><tt>doc</tt> and are called <tt>example.te</tt>, <tt>example.if</tt>, and <tt>example.fc</tt>.
  
 
During the header build process a <tt>Makefile</tt> was included in the headers directory. This <tt>Makefile</tt> can be used to build the example modules by using makes <tt>-f</tt> option as follows (assuming that the example module files are in the local directory):
 
During the header build process a <tt>Makefile</tt> was included in the headers directory. This <tt>Makefile</tt> can be used to build the example modules by using makes <tt>-f</tt> option as follows (assuming that the example module files are in the local directory):
 
<pre>
 
<pre>
make -f <tt>/usr/share/selinux/<policy_name>/include/Makefile</tt>
+
make -f /usr/share/selinux/<NAME>/include/Makefile
 
</pre>
 
</pre>
  
However there is another <tt>Makefile</tt> that can be installed in the users home directory (<tt>$HOME</tt>) that will call the master <tt>Makefile</tt>. This is located at /etc/selinux/targeted-103/src/policy/<tt>doc</tt> in the reference policy source and is called <tt>Makefile.example</tt>. This is shown below (note that it extracts the <tt><policy_name></tt> from the SELinux <tt>config</tt> file):
+
However there is another <tt>Makefile</tt> that can be installed in the users home directory (<tt>$HOME</tt>) that will call the master <tt>Makefile</tt>. This is located at <nowiki>/etc/selinux/<NAME>/src/policy/</nowiki><tt>doc</tt> in the reference policy source and is called <tt>Makefile.example</tt>. This is shown below (note that it extracts the <tt><nowiki><policy_n</nowiki></tt>NAME <tt>/etc/selinux/config</tt> file):
 
<pre>
 
<pre>
 
AWK ?= gawk
 
AWK ?= gawk
Line 1,352: Line 1,419:
 
</pre>
 
</pre>
  
Table 9 shows the make targets for modules built from headers.
+
Table 8 shows the make targets for modules built from headers.
 +
 
 +
<center>'''Table 8: Header Policy Build Make Targets'''</center>
  
 
{| border="1"
 
{| border="1"
Line 1,379: Line 1,448:
  
 
|}
 
|}
''Table 9: Header Policy Build Make Targets''
 
  
  
=== Using F-12 Supplied Headers ===
+
=== Using Fedora Supplied Headers ===
The F-12 distribution installs the headers in a slightly different manner as Red Hat installs:
+
The F-20 distribution installs the headers in a slightly different manner as Fedora installs:
 +
 
 +
* A <tt>modules-base.lst</tt> and <tt>modules-contrib.lst</tt> containing a list of installed modules under <tt><nowiki>/usr/share/selinux/<</nowiki></tt>NAME<tt>></tt>.
 +
* The development header files are installed in the /usr/share/selinux/devel directory. The example modules are also in this directory and the <tt>Makefile</tt> is also slightly different to that used by the Reference Policy source.
 +
* The documentation is installed in the /usr/share/doc/selinux-policy/html directory.
  
* The packaged files under the <tt>/usr/share/selinux/<policy_name></tt>, these files may be <tt>.pp</tt> files or <tt>.pp.bz2</tt> depending on the version of rpm installed (later ones compressed the packages). They are installed by the <nowiki>selinux-policy-<policy_name>-3.6.32-103.fc12.noarch</nowiki> type rpms.
+
== Migrating Compiled Modules to CIL ==
* The development header files are installed in the /usr/share/selinux/devel directory by the selinux-policy-3.6.32-103.fc12.noarch rpm. Red Hat also include an additional application called <tt>policygentool</tt> that allows users to generate policy by answering various questions. This tool is described in the [http://docs.fedoraproject.org/selinux-user-guide/f12/en-US/index.html Fedora 12 SELinux User Guide]. The example modules are also in this directory and the <tt>Makefile</tt> is also slightly different to that used by the Reference Policy source.
+
As explained in the [[ConfigurationFiles#Policy_Store_Migration | Policy Store Migration]] section, when <tt>libsepol</tt> etc. are upgraded to version 2.4, the policy stores will be migrated to the new location that will contain also contain CIL versions of the policy modules.  
* The documentation is supplied in the selinux-policy-doc-3.6.32-103.fc12.noarch type rpms and would be installed (for this version), in the /usr/share/doc/selinux-policy-3.6.32/html directory.
+
  
 
== Reference Policy Support Macros ==
 
== Reference Policy Support Macros ==
This section explains some of the support macros used to build reference policy source modules (see Table 10 for the list). These macros are located at:
+
This section explains some of the support macros used to build reference policy source modules (see Table 9 for the list). These macros are located at:
  
* <tt>./policy/policy/support</tt> for the reference policy source.
+
* <tt>./policy/support</tt> for the reference policy source.
* <tt>/usr/share/selinux/<policy_name>/include/support</tt> for reference policy installed header files.
+
* <tt><nowiki>/usr/share/selinux/<</nowiki></tt>NAME<tt>>/include/support</tt> for Reference Policy installed header files.
* <tt>/usr/share/selinux/devel/support</tt> for Red Hat installed header files.
+
* /usr/share/selinux/devel/support for Fedora installed header files.
  
They consist of the following files:
+
The following support macro file contents are explained:
 
: <tt>loadable_module.spt</tt> - Loadable module support.
 
: <tt>loadable_module.spt</tt> - Loadable module support.
 
: <tt>misc_macros.spt</tt> - Generate users, bools and security contexts.
 
: <tt>misc_macros.spt</tt> - Generate users, bools and security contexts.
Line 1,405: Line 1,476:
 
: <tt>obj_perm_sets.spt</tt> - Object classes and permissions.
 
: <tt>obj_perm_sets.spt</tt> - Object classes and permissions.
  
 +
When the header files are installed the <tt>all_perms.spt</tt> support macro file is also installed that describes all classes and permissions configured in the original source policy.
  
 +
<center>'''Table 9: Support Macros described in this section'''</center>
 
{| border="1"
 
{| border="1"
 
| '''Macro Name'''
 
| '''Macro Name'''
Line 1,490: Line 1,563:
  
 
|}
 
|}
''Table 10: Support Macros described in this section''
+
 
  
 
Notes:
 
Notes:
# The macro calls can be in any configuration file read by the build process and are contained in (for example) the <tt>users</tt>, <tt>mls</tt>, <tt>mcs</tt> and <tt>constraints</tt> files.
+
* The macro calls can be in any configuration file read by the build process and can be found in (for example) the <tt>users</tt>, <tt>mls</tt>, <tt>mcs</tt> and <tt>constraints</tt> files.
# There are four main m4 <tt>ifdef</tt> parameters used within modules:
+
* There are four main m4 <tt>ifdef</tt> parameters used within modules:
## <tt>enable_mcs</tt> - this is used to test if the MCS policy is being built.
+
** <tt>enable_mcs</tt> - this is used to test if the MCS policy is being built.
## <tt>enable_mls</tt> - this is used to test if the MLS policy is being built.
+
** <tt>enable_mls</tt> - this is used to test if the MLS policy is being built.
## <tt>enable_ubac</tt> - this enables the user based access control within the <tt>constraints</tt> file.
+
** <tt>enable_ubac</tt> - this enables the user based access control within the <tt>constraints</tt> file.
## <tt>hide_broken_symptoms</tt> - this is used to hide errors in modules with <tt>dontaudit</tt> rules.  
+
** <tt>hide_broken_symptoms</tt> - this is used to hide errors in modules with <tt>dontaudit</tt> rules.  
 
+
:: These are also mentioned in Table 20 as they are set by the initial build process with examples shown in the [[#ifdef / ifndef Parameters | ifdef / ifndef Parameters]] section.
These are also mentioned in Table 3 as they are set by the initial build process with examples shown in the [[NB_RefPolicy#ifdef_/_ifndef_Parameters | ifdef / ifndef Parameters]] section.
+
* The macro examples in this section have been taken from the reference policy module files and shown in each relevant "'''Example Macro'''" section. The macros are then expanded by the build process to form modules containing the policy language statements and rules in the <tt>tmp</tt> directory. These files have been extracted and modified for readability, then shown in each relevant "'''Expanded Macro'''" section.  
 
+
* An example policy that has had macros expanded is shown in the [[#Module Expansion Process | Module Expansion Process]] section.
# The macro examples in this section have been taken from the reference policy module files and shown in each relevant ''''Example Macro'''' section. The macros are then expanded by the build process to form modules containing the policy language statements and rules in the <tt>tmp</tt> directory. These files have been extracted and modified for readability, then shown in each relevant ''''Expanded Macro'''' section.  
+
* Be aware that spaces between macro names and their parameters are not allowed:
# An example policy that has had macros expanded is shown in the [[NB_RefPolicy#Module_Expansion_Process | Module Expansion Process]] section.
+
** Correct:
# Be aware that spaces between macro names and their parameters are not allowed:
+
 
+
Allowed:
+
 
<pre>
 
<pre>
 
policy_module(ftp, 1.7.0)
 
policy_module(ftp, 1.7.0)
 
</pre>
 
</pre>
 
+
** Incorrect:
Not allowed:
+
 
<pre>
 
<pre>
 
policy_module (ftp, 1.7.0)
 
policy_module (ftp, 1.7.0)
Line 1,520: Line 1,589:
  
 
==== policy_module Macro ====
 
==== policy_module Macro ====
This macro will add the module Statement to a loadable module, and automatically add a require Statement with pre-defined information for all loadable modules such as the system_r role, kernel classes and permissions, and optionally MCS / MLS information (<tt>sensitivity</tt> and <tt>category</tt> statements).
+
This macro will add the [[PolicyStatements#module | module]] statement to a loadable module, and automatically add a [[PolicyStatements#require | require]] statement with pre-defined information for all loadable modules such as the system_r role, kernel classes and permissions, and optionally MCS / MLS information (<tt>sensitivity</tt> and <tt>category</tt> statements).
  
 
'''The macro definition is:'''
 
'''The macro definition is:'''
Line 1,526: Line 1,595:
 
policy_module(module_name,version)
 
policy_module(module_name,version)
 
</pre>
 
</pre>
 +
 
'''Where:'''
 
'''Where:'''
  
Line 1,541: Line 1,611:
  
 
|}
 
|}
 +
  
 
'''The macro is valid in:'''
 
'''The macro is valid in:'''
Line 1,555: Line 1,626:
  
 
|}
 
|}
 +
  
 
'''Example Macro:'''
 
'''Example Macro:'''
Line 1,562: Line 1,634:
 
policy_module(ftp, 1.7.0)
 
policy_module(ftp, 1.7.0)
 
</pre>
 
</pre>
 +
 
'''Expanded Macro:'''
 
'''Expanded Macro:'''
 
<pre>
 
<pre>
Line 1,567: Line 1,640:
 
#
 
#
 
module ftp 1.7.0;
 
module ftp 1.7.0;
   
 
 
require {
 
require {
 
     role system_r;
 
     role system_r;
Line 1,574: Line 1,646:
 
     class capability2 (mac_override mac_admin };
 
     class capability2 (mac_override mac_admin };
  
# If MLS or MCS configured then the:
+
    # If MLS or MCS configured then the:
 
     sensitivity s0;
 
     sensitivity s0;
 
     ....
 
     ....
Line 1,589: Line 1,661:
 
gen_require(`require_statements`)
 
gen_require(`require_statements`)
 
</pre>
 
</pre>
 +
 
'''Where:'''
 
'''Where:'''
  
Line 1,597: Line 1,670:
 
|-
 
|-
 
| require_statements
 
| require_statements
| These statements consist of those allowed in the policy language require Statement.
+
| These statements consist of those allowed in the policy language [[PolicyStatements#require | require]] statement.
  
 
|}
 
|}
 +
  
 
'''The macro is valid in:'''
 
'''The macro is valid in:'''
Line 1,614: Line 1,688:
  
 
|}
 
|}
 +
  
 
'''Example Macro:'''
 
'''Example Macro:'''
Line 1,621: Line 1,696:
 
gen_require(`type ftp_script_exec_t;')
 
gen_require(`type ftp_script_exec_t;')
 
</pre>
 
</pre>
 +
 
'''Expanded Macro:'''
 
'''Expanded Macro:'''
 
<pre>
 
<pre>
Line 1,637: Line 1,713:
 
optional_policy(`optional_statements`)
 
optional_policy(`optional_statements`)
 
</pre>
 
</pre>
 +
 
'''Where:'''
 
'''Where:'''
  
Line 1,645: Line 1,722:
 
|-
 
|-
 
| optional_statements
 
| optional_statements
| These statements consist of those allowed in the policy language optional Statement. However they can also be [[NB_RefPolicy#interface_Macro | interface]], [[NB_RefPolicy#template_Macro | template]] or support macro calls.
+
| These statements consist of those allowed in the policy language [[PolicyStatements#optional | optional]] statement. However they can also be [[#interface Macro | interface template]], or support macro calls.
  
 
|}
 
|}
'''The macro is valid in:'''
 
  
 +
 +
'''The macro is valid in:'''
  
 
{| border="1"
 
{| border="1"
Line 1,662: Line 1,740:
  
 
|}
 
|}
 +
  
 
'''Example Macro:'''
 
'''Example Macro:'''
Line 1,673: Line 1,752:
 
     cron_system_entry(ftpd_t, ftpd_exec_t)
 
     cron_system_entry(ftpd_t, ftpd_exec_t)
  
    optional_policy(`
+
        optional_policy(`
 
         logrotate_exec(ftpd_t)
 
         logrotate_exec(ftpd_t)
 
     ')
 
     ')
Line 1,682: Line 1,761:
 
<pre>
 
<pre>
 
# This is the expanded macro from the tmp/ftp.tmp file showing
 
# This is the expanded macro from the tmp/ftp.tmp file showing
# the policy language statements with both optional levels
+
# the policy language statements with both optional levels expanded.
# expanded.
+
 
#
 
#
 
##### Start optional_policy - Level 1 ###########
 
##### Start optional_policy - Level 1 ###########
Line 1,689: Line 1,767:
 
##### begin corecmd_exec_shell(ftpd_t)
 
##### begin corecmd_exec_shell(ftpd_t)
 
     require {
 
     require {
    type bin_t, shell_exec_t;
+
        type bin_t, shell_exec_t;
 
     } # end require
 
     } # end require
 
     allow ftpd_t bin_t:dir { getattr search };
 
     allow ftpd_t bin_t:dir { getattr search };
Line 1,717: Line 1,795:
 
     dontaudit system_crond_t ftpd_t:process { noatsecure siginh rlimitinh };
 
     dontaudit system_crond_t ftpd_t:process { noatsecure siginh rlimitinh };
 
     type_transition system_crond_t ftpd_exec_t:process ftpd_t;
 
     type_transition system_crond_t ftpd_exec_t:process ftpd_t;
# cjp: perhaps these four rules from the old
+
    # cjp: perhaps these four rules from the old
# domain_auto_trans are not needed?
+
    # domain_auto_trans are not needed?
 
     allow ftpd_t system_crond_t:fd use;
 
     allow ftpd_t system_crond_t:fd use;
 
     allow ftpd_t system_crond_t:fifo_file { getattr read write append ioctl lock };
 
     allow ftpd_t system_crond_t:fifo_file { getattr read write append ioctl lock };
Line 1,731: Line 1,809:
 
     optional {
 
     optional {
 
##### begin logrotate_exec(ftpd_t)
 
##### begin logrotate_exec(ftpd_t)
    require {
+
        require {
        type logrotate_exec_t;
+
            type logrotate_exec_t;
    } # end require
+
        } # end require
    allow ftpd_t logrotate_exec_t:file { { getattr read execute ioctl } ioctl lock execute_no_trans };
+
        allow ftpd_t logrotate_exec_t:file { { getattr read execute ioctl } ioctl lock execute_no_trans };
 
##### end logrotate_exec(ftpd_t)
 
##### end logrotate_exec(ftpd_t)
 
     } # end optional 2nd level
 
     } # end optional 2nd level
 +
 
} # end optional 1st level
 
} # end optional 1st level
 
</pre>
 
</pre>
  
 
==== gen_tunable Macro ====
 
==== gen_tunable Macro ====
This macro defines booleans that are global in scope. The corresponding [[NB_RefPolicy#tunable_policy_Macro | tunable_policy]] macro contains the supporting statements allowed or not depending on the value of the boolean. These entries are extracted as a part of the build process (by the <tt>make conf</tt> target) and added to the <tt>global_tunables</tt> file where they can then be used to alter the default values for the <tt>make load</tt> or <tt>make install</tt> targets.
+
This macro defines booleans that are global in scope. The corresponding [[#tunable_policy Macro | tunable_policy]] macro contains the supporting statements allowed or not depending on the value of the boolean. These entries are extracted as a part of the build process (by the <tt>make conf</tt> target) and added to the <tt>global_tunables</tt> file where they can then be used to alter the default values for the <tt>make load</tt> or <tt>make install</tt> targets.
  
Note that the comments shown in the example MUST be present as they are used to describe the function and are extracted for the [[NB_RefPolicy#Reference_Policy_Documentation | documentation]].
+
Note that the comments shown in the example MUST be present as they are used to describe the function and are extracted for the [[#Reference Policy Documentation | documentation]].
  
 
'''The macro definition is:'''
 
'''The macro definition is:'''
Line 1,765: Line 1,844:
  
 
|}
 
|}
 +
  
 
'''The macro is valid in:'''
 
'''The macro is valid in:'''
Line 1,779: Line 1,859:
  
 
|}
 
|}
 +
  
 
'''Example Macro:'''
 
'''Example Macro:'''
Line 1,793: Line 1,874:
 
gen_tunable(allow_ftpd_use_nfs, false)
 
gen_tunable(allow_ftpd_use_nfs, false)
 
</pre>
 
</pre>
 +
 
'''Expanded Macro:'''
 
'''Expanded Macro:'''
 
<pre>
 
<pre>
Line 1,801: Line 1,883:
  
 
==== tunable_policy Macro ====
 
==== tunable_policy Macro ====
This macro contains the statements allowed or not depending on the value of the boolean defined by the [[NB_RefPolicy#gen_tunable_Macro | gen_tunable]] macro.  
+
This macro contains the statements allowed or not depending on the value of the boolean defined by the [[#gen_tunable Macro | gen_tunable]] macro.  
  
 
'''The macro definition is:'''
 
'''The macro definition is:'''
 
<pre>
 
<pre>
tunable_policy(`gen_tunable_id`,`tunable_policy_rules`)
+
tunable_policy(`gen_tunable_id',`tunable_policy_rules`)
 
</pre>
 
</pre>
  
Line 1,820: Line 1,902:
 
|-
 
|-
 
| tunable_policy_rules
 
| tunable_policy_rules
| These are the policy rules and statements as defined in the if Statement policy language section.
+
| These are the policy rules and statements as defined in the [[ConditionalStatements | if]] statement policy language section.
  
 
|}
 
|}
 +
  
 
'''The macro is valid in:'''
 
'''The macro is valid in:'''
Line 1,837: Line 1,920:
  
 
|}
 
|}
 +
 +
 
'''Example Macro:'''
 
'''Example Macro:'''
 
<pre>
 
<pre>
Line 1,843: Line 1,928:
 
#
 
#
 
tunable_policy(`allow_ftpd_use_nfs && allow_ftpd_anon_write',`
 
tunable_policy(`allow_ftpd_use_nfs && allow_ftpd_anon_write',`
fs_manage_nfs_files(ftpd_t)
+
    fs_manage_nfs_files(ftpd_t)
 
')
 
')
 
</pre>
 
</pre>
 +
 
'''Expanded Macro:'''
 
'''Expanded Macro:'''
 
<pre>
 
<pre>
Line 1,853: Line 1,939:
  
 
##### begin fs_manage_nfs_files(ftpd_t)
 
##### begin fs_manage_nfs_files(ftpd_t)
require {
+
    require {
    type nfs_t;
+
        type nfs_t;
 
     } # end require
 
     } # end require
allow ftpd_t nfs_t:dir { read getattr lock search ioctl add_name remove_name write };
+
 
allow ftpd_t nfs_t:file { create open getattr setattr read write append rename link unlink ioctl lock };
+
    allow ftpd_t nfs_t:dir { read getattr lock search ioctl add_name remove_name write };
 +
    allow ftpd_t nfs_t:file { create open getattr setattr read write append rename link unlink ioctl lock };
 
##### end fs_manage_nfs_files(ftpd_t)
 
##### end fs_manage_nfs_files(ftpd_t)
 +
 
} # end if
 
} # end if
 
</pre>
 
</pre>
  
 
==== interface Macro ====
 
==== interface Macro ====
Access interface macros are defined in the interface module file (<tt>.if</tt>) and form the interface through which other modules can call on the modules services (as shown in [http://taiga.selinuxproject.org/~rhaines/diagrams/5-7-resulting-code.png The Resulting Code] diagram and described in the [[NB_RefPolicy#Module_Expansion | Module Expansion]] section.
+
Access interface macros are defined in the interface module file (<tt>.if</tt>) and form the interface through which other modules can call on the modules services (as described in the [[#Module Expansion | Module Expansion]] section.
 
+
Note that the comments shown in the example MUST be present as they are used to describe the function and are extracted for the [[NB_RefPolicy#Reference_Policy_Documentation | documentation]].
+
  
 
'''The macro definition is:'''
 
'''The macro definition is:'''
Line 1,871: Line 1,957:
 
interface(`name`,`interface_rules`)
 
interface(`name`,`interface_rules`)
 
</pre>
 
</pre>
 +
 
'''Where:'''
 
'''Where:'''
  
Line 1,886: Line 1,973:
  
 
|}
 
|}
 +
  
 
'''The macro is valid in:'''
 
'''The macro is valid in:'''
Line 1,900: Line 1,988:
  
 
|}
 
|}
 +
  
 
'''Example Interface Definition:'''
 
'''Example Interface Definition:'''
 +
 +
Note that the comments shown in the example MUST be present as they are used to describe the function and are extracted for the [[#Reference Policy Documentation | documentation]].
 +
 
<pre>
 
<pre>
 
# This example is from the modules/services/ftp.if module
 
# This example is from the modules/services/ftp.if module
# showing the "ftp_read_config" interface.
+
# showing the 'ftp_read_config' interface.
 
#
 
#
  
Line 1,918: Line 2,010:
 
#
 
#
 
interface(`ftp_read_config',`
 
interface(`ftp_read_config',`
gen_require(`
+
    gen_require(`
    type ftpd_etc_t;
+
        type ftpd_etc_t;
 
     ')
 
     ')
  
files_search_etc($1)
+
    files_search_etc($1)
allow $1 ftpd_etc_t:file { getattr read };
+
    allow $1 ftpd_etc_t:file { getattr read };
 
')
 
')
 
</pre>
 
</pre>
  
'''Expanded Macro:''' (taken from the <tt>base.conf</tt> file):
+
'''Expanded Macro: (taken from the <tt>base.conf</tt> file):'''
 
<pre>
 
<pre>
 
# Access Interfaces are only expanded at policy compile time  
 
# Access Interfaces are only expanded at policy compile time  
Line 1,939: Line 2,031:
 
#
 
#
 
# optional_policy(`
 
# optional_policy(`
# ftp_read_config(initrc_t)
+
#     ftp_read_config(initrc_t)
 
# ')
 
# ')
 
#
 
#
Line 1,948: Line 2,040:
 
#
 
#
 
optional { # Start optional_policy segment for ftp interface
 
optional { # Start optional_policy segment for ftp interface
#
+
    #
# This is the resulting output contained the base.conf file
+
    # This is the resulting output contained the base.conf file
# where init calls the ftp_read_config ($1) interface from
+
    # where init calls the ftp_read_config ($1) interface from
# init.te with the parameter initrc_t:
+
    # init.te with the parameter initrc_t:
#
+
    #
 
     require {
 
     require {
 
         type ftpd_etc_t;
 
         type ftpd_etc_t;
 
     }  
 
     }  
  
#
+
    #
# Call the files_search_etc ($1) interface contained in the  
+
    # Call the files_search_etc ($1) interface contained in the  
# ftp.if file with the parameter initrc_t:
+
    # ftp.if file with the parameter initrc_t:
#
+
    #
 
     require {
 
     require {
 
         type etc_t;
 
         type etc_t;
 
     }  
 
     }  
 
     allow initrc_t etc_t:dir { getattr search };
 
     allow initrc_t etc_t:dir { getattr search };
#
+
    #
# end files_search_etc(initrc_t)
+
    # end files_search_etc(initrc_t)
#
+
    #
# This is the '''allow $1 ftpd_etc_t:file { getattr read };
+
    # This is the allow $1 ftpd_etc_t:file { getattr read };
# statement with the '''initrc_t''' parameter resolved:  
+
    # statement with the initrc_t parameter resolved:  
#
+
    #
 
     allow initrc_t ftpd_etc_t:file { getattr read };
 
     allow initrc_t ftpd_etc_t:file { getattr read };
#
+
    #
# end ftp_read_config(initrc_t)
+
    # end ftp_read_config(initrc_t)
 
+
 
} # End optional_policy segment for this ftp interface
 
} # End optional_policy segment for this ftp interface
 
</pre>
 
</pre>
  
 
==== template Macro ====
 
==== template Macro ====
A template interface is used to help create a domain and set up the appropriate rules and statements to run an application / process. The basic idea is to set up an application in a domain that is suitable for the defined SELinux user and role to access but not others. Should a different user / role need to access the same application, another domain would be allocated (these are known as "derived domains" as the domain name is derived from caller information).  
+
A template interface is used to help create a domain and set up the appropriate rules and statements to run an application / process. The basic idea is to set up an application in a domain that is suitable for the defined SELinux user and role to access but not others. Should a different user / role need to access the same application, another domain would be allocated (these are known as 'derived domains' as the domain name is derived from caller information).  
  
 
The application template shown in the example below is for <tt>openoffice.org</tt> where the domain being set up to run the application is based on the SELinux user <tt>xguest</tt> (parameter <tt>$1</tt>) therefore a domain type is initialised called <tt>xguest_openoffice_t</tt>, this is then added to the user domain attribute xguest_usertype (parameter <tt>$2</tt>). Finally the role <tt>xguest_r</tt> (parameter <tt>$3</tt>) is allowed access to the domain type <tt>xguest_openoffice_t</tt>. If a different user / role required access to openoffice.org, then by passing different parameters (i.e. <tt>user_u</tt>), a different domain would be set up.
 
The application template shown in the example below is for <tt>openoffice.org</tt> where the domain being set up to run the application is based on the SELinux user <tt>xguest</tt> (parameter <tt>$1</tt>) therefore a domain type is initialised called <tt>xguest_openoffice_t</tt>, this is then added to the user domain attribute xguest_usertype (parameter <tt>$2</tt>). Finally the role <tt>xguest_r</tt> (parameter <tt>$3</tt>) is allowed access to the domain type <tt>xguest_openoffice_t</tt>. If a different user / role required access to openoffice.org, then by passing different parameters (i.e. <tt>user_u</tt>), a different domain would be set up.
  
 
The main differences between an application interface and a template interface are:
 
The main differences between an application interface and a template interface are:
 +
 
* An access interface is called by other modules to perform a service.
 
* An access interface is called by other modules to perform a service.
 
* A template interface allows an application to be run in a domain based on user / role information to isolate different instances.
 
* A template interface allows an application to be run in a domain based on user / role information to isolate different instances.
  
Note that the comments shown in the example MUST be present as they are used to describe the function and are extracted for the [[NB_RefPolicy#Reference_Policy_Documentation | documentation]].
+
Note that the comments shown in the example MUST be present as they are used to describe the function and are extracted for the [[#Reference Policy Documentation | documentation]].
  
 
'''The macro definition is:'''
 
'''The macro definition is:'''
Line 1,993: Line 2,085:
 
template(`name`,`template_rules`)
 
template(`name`,`template_rules`)
 
</pre>
 
</pre>
 +
 
'''Where:'''
 
'''Where:'''
  
Line 2,006: Line 2,099:
 
| <tt>template</tt>_rules
 
| <tt>template</tt>_rules
 
| This can consist of the support macros, policy language statements or <tt>interface</tt> calls as required to provide the service.
 
| This can consist of the support macros, policy language statements or <tt>interface</tt> calls as required to provide the service.
 +
  
 
|}
 
|}
 +
  
 
'''The macro is valid in:'''
 
'''The macro is valid in:'''
Line 2,022: Line 2,117:
  
 
|}
 
|}
 +
  
 
'''Example Macro:'''
 
'''Example Macro:'''
 
<pre>
 
<pre>
 
# This example is from the modules/apps/openoffice.if module
 
# This example is from the modules/apps/openoffice.if module
# showing the "openoffice_per_role_template" template interface.
+
# showing the 'openoffice_per_role_template' template interface.
 
#
 
#
 
#######################################
 
#######################################
Line 2,084: Line 2,180:
 
     allow $2 $1_openoffice_t:process { signal sigkill };
 
     allow $2 $1_openoffice_t:process { signal sigkill };
 
     allow $1_openoffice_t $2:unix_stream_socket connectto;
 
     allow $1_openoffice_t $2:unix_stream_socket connectto;
 +
 
')
 
')
 
</pre>
 
</pre>
Line 2,094: Line 2,191:
 
# module and extracted from tmp/xguest.tmp.
 
# module and extracted from tmp/xguest.tmp.
 
#
 
#
################# START Expanded code segment ###########
+
################# '''START Expanded code segment''' ###########
 
#
 
#
 
optional {
 
optional {
 
+
    ##### begin openoffice_per_role_template(xguest,xguest_usertype,xguest_r)
##### begin openoffice_per_role_template(xguest,xguest_usertype,xguest_r)
+
 
     require {
 
     require {
 
         type openoffice_exec_t;
 
         type openoffice_exec_t;
Line 2,105: Line 2,201:
  
 
     ......
 
     ......
# This is a long set of rules, therefore has been cut down.'''
+
    # This is a long set of rules, therefore has been cut down.
 
     ......
 
     ......
 
     ....
 
     ....
Line 2,116: Line 2,212:
 
     allow xguest_usertype xguest_openoffice_t:process { signal sigkill };
 
     allow xguest_usertype xguest_openoffice_t:process { signal sigkill };
 
     allow xguest_openoffice_t xguest_usertype:unix_stream_socket connectto;
 
     allow xguest_openoffice_t xguest_usertype:unix_stream_socket connectto;
##### end openoffice_per_role_template(xguest,xguest_usertype,xguest_r)
+
    ##### end openoffice_per_role_template(xguest,xguest_usertype,xguest_r)
 
+
 
} # end optional
 
} # end optional
 
</pre>
 
</pre>
Line 2,131: Line 2,226:
 
gen_context(context[,mls | mcs])  
 
gen_context(context[,mls | mcs])  
 
</pre>
 
</pre>
 +
 
'''Where:'''
 
'''Where:'''
  
Line 2,146: Line 2,242:
  
 
|}
 
|}
 +
  
 
'''The macro is valid in:'''
 
'''The macro is valid in:'''
Line 2,160: Line 2,257:
  
 
|}
 
|}
 +
  
 
'''Example Macro:'''
 
'''Example Macro:'''
Line 2,182: Line 2,280:
 
# This is from the modules/apps/gnome.fc file. Note that the
 
# This is from the modules/apps/gnome.fc file. Note that the
 
# HOME_DIR and USER parameters will be entered during
 
# HOME_DIR and USER parameters will be entered during
# the file_contexts.homedirs file build.
+
# the contexts/file_contexts.homedirs file.
 
#
 
#
  
Line 2,208: Line 2,306:
  
 
/tmp/gconfd-USER/.*--system_u:object_r:gconf_tmp_t:s0
 
/tmp/gconfd-USER/.*--system_u:object_r:gconf_tmp_t:s0
 +
 
HOME_DIR/.pulse(/.*)?system_u:object_r:gnome_home_t:s0
 
HOME_DIR/.pulse(/.*)?system_u:object_r:gnome_home_t:s0
 
</pre>
 
</pre>
  
 
==== gen_user Macro ====
 
==== gen_user Macro ====
This macro is used to generate a valid [[UserStatements | user statement]] and add an entry in the [[PolicyStoreConfigurationFiles#users_extra.2C_users_extra.local_and_users.local_Files | users_extra]] configuration file if it exists.
+
This macro is used to generate a valid [[User Statements | user]] statement and add an entry in the [[PolicyStoreConfigurationFiles#modules_active_users_extra._users_extra.local_and_users.local_Files | users_extra]] configuration file if it exists.
  
 
'''The macro definition is:'''
 
'''The macro definition is:'''
 
<pre>
 
<pre>
gen_user(username, prefix, role_set, mls_defaultlevel, mls_range, [mcs_categories])  
+
gen_user(username, prefix, role_set, mls_defaultlevel, mls_range, [mcs_categories])
 
</pre>
 
</pre>
  
Line 2,231: Line 2,330:
 
|-
 
|-
 
| prefix
 
| prefix
| SELinux users without the prefix will not be in the <tt>users_extra</tt> file. This is added to user directories by the <tt>genhomedircon</tt> as discussed in the [[PolicyStoreConfigurationFiles#file_contexts.template_File | modules/active/file_contexts.template]] File section.
+
| SELinux users without the prefix will not be in the <tt>users_extra</tt> file. This is added to user directories by the <tt>genhomedircon</tt> as discussed in the [[PolicyStoreConfigurationFiles#modules_active_file_contexts.template_File | modules/active/file_contexts.template]] file section.
  
 
|-
 
|-
Line 2,250: Line 2,349:
  
 
|}
 
|}
 +
  
 
'''The macro is valid in:'''
 
'''The macro is valid in:'''
Line 2,264: Line 2,364:
  
 
|}
 
|}
 +
  
 
'''Example Macro:'''
 
'''Example Macro:'''
 
<pre>
 
<pre>
# This example has been taken from the policy/policy/users file:
+
# This example has been taken from the policy/policy/users file:
#
+
#
gen_user(root, user, unconfined_r sysadm_r staff_r ifdef(`enable_mls',`secadm_r auditadm_r') system_r, s0, s0 - mls_systemhigh, mcs_allcats)  
+
 
 +
gen_user(root, user, unconfined_r sysadm_r staff_r ifdef(`enable_mls',`secadm_r auditadm_r') system_r, s0, s0 - mls_systemhigh, mcs_allcats)  
 
</pre>
 
</pre>
  
Line 2,279: Line 2,381:
 
#
 
#
 
user root roles { unconfined_r sysadm_r staff_r secadm_r auditadm_r system_r } level s0 range s0 - s15:c0.c1023;  
 
user root roles { unconfined_r sysadm_r staff_r secadm_r auditadm_r system_r } level s0 range s0 - s15:c0.c1023;  
</pre>
+
 
<pre>
+
 
# users_extra file entry:
 
# users_extra file entry:
 
#
 
#
Line 2,288: Line 2,389:
 
==== gen_bool Macro ====
 
==== gen_bool Macro ====
 
This macro defines a boolean and requires the following steps:
 
This macro defines a boolean and requires the following steps:
 +
# Declare the [[ConditionalStatements | boolean]] in the [[#Booleans, Global Booleans and Tunable Booleans | global_booleans]] file.
 +
# Use the boolean in the module files with an if / else statement as shown in the example.
  
# Declare the boolean in the global_booleans file.
+
Note that the comments shown in the example MUST be present as they are used to describe the function and are extracted for the [[#Reference Policy Documentation | documentation]].
# Use the boolean in the module files with an if Statement as shown in the example.
+
 
+
Note that the comments shown in the example MUST be present as they are used to describe the function and are extracted for the [[NB_RefPolicy#Reference Policy Documentation | documentation]].
+
  
 
'''The macro definition is:'''
 
'''The macro definition is:'''
Line 2,315: Line 2,415:
 
|}
 
|}
  
'''The macro is only valid in in the global_booleans file but the boolean declared can be used in the following module types:'''
+
 
 +
The macro is only valid in the'''global_booleans'''file but the boolean declared can be used in the following module types:
  
 
{| border="1"
 
{| border="1"
Line 2,328: Line 2,429:
  
 
|}
 
|}
 +
  
 
'''Example Macro (in global_booleans):'''
 
'''Example Macro (in global_booleans):'''
Line 2,340: Line 2,442:
 
## Disable transitions to insmod.
 
## Disable transitions to insmod.
 
## </p>
 
## </p>
## </desc>gen_bool(secure_mode_insmod,false)
+
## </desc>
 
+
gen_bool(secure_mode_insmod,false)
 +
</pre>
 +
<pre>
 
# Example usage from the system/modutils.te module:
 
# Example usage from the system/modutils.te module:
 
#
 
#
Line 2,356: Line 2,460:
  
 
if( ! secure_mode_insmod ) {
 
if( ! secure_mode_insmod ) {
##### begin kernel_domtrans_to(insmod_t,insmod_exec_t)
+
    ##### begin kernel_domtrans_to(insmod_t,insmod_exec_t)
 
     allow kernel_t insmod_exec_t:file { getattr read execute };
 
     allow kernel_t insmod_exec_t:file { getattr read execute };
 
     allow kernel_t insmod_t:process transition;
 
     allow kernel_t insmod_t:process transition;
Line 2,364: Line 2,468:
 
     allow insmod_t kernel_t:fifo_file { getattr read write append ioctl lock };
 
     allow insmod_t kernel_t:fifo_file { getattr read write append ioctl lock };
 
     allow insmod_t kernel_t:process sigchld;
 
     allow insmod_t kernel_t:process sigchld;
##### end kernel_domtrans_to(insmod_t,insmod_exec_t)
+
    ##### end kernel_domtrans_to(insmod_t,insmod_exec_t)
 
}
 
}
 
</pre>
 
</pre>
Line 2,372: Line 2,476:
  
 
==== gen_cats Macro ====
 
==== gen_cats Macro ====
This macro will generate a category Statement for each category defined. These are then used in the <tt>base.conf</tt> / <tt>policy.conf</tt> source file and also inserted into each module by the [[NB_RefPolicy#policy_module_Macro | policy_module Macro]]. The <tt>policy/policy/mcs</tt> and <tt>mls</tt> configuration files are the only files that contain this macro in the current reference policy.
+
This macro will generate a [[MLSStatements#category | category]] statement for each category defined. These are then used in the <tt>base.conf</tt> / <tt>policy.conf</tt> source file and also inserted into each module by the [[#policy_module Macro | policy_module]] Macro. The <tt>policy/policy/mcs</tt> and <tt>mls</tt> configuration files are the only files that contain this macro in the current reference policy.
  
 
'''The macro definition is:'''
 
'''The macro definition is:'''
Line 2,392: Line 2,496:
  
 
|}
 
|}
 +
  
 
'''The macro is valid in:'''
 
'''The macro is valid in:'''
Line 2,406: Line 2,511:
  
 
|}
 
|}
 +
  
 
'''Example Macro:'''
 
'''Example Macro:'''
Line 2,417: Line 2,523:
 
'''Expanded Macro:'''
 
'''Expanded Macro:'''
 
<pre>
 
<pre>
# This example has been extracted from the base.conf source
+
# This example has been extracted from the base.conf source file.
# file.
+
  
 
category c0;
 
category c0;
Line 2,427: Line 2,532:
  
 
==== gen_sens Macro ====
 
==== gen_sens Macro ====
This macro will generate a sensitivity Statement for each sensitivity defined. These are then used in the <tt>base.conf</tt> / <tt>policy.conf</tt> source file and also inserted into each module by the [[NB_RefPolicy#policy_module_Macro | policy_module Macro]]. The <tt>policy/policy/mcs</tt> and <tt>mls</tt> configuration files are the only files that contain this macro in the current reference policy (note that the <tt>mcs</tt> file has <tt>gen_sens(1)</tt> as only one sensitivity is required).
+
This macro will generate a [[MLSStatements#sensitivity | sensitivity]] statement for each sensitivity defined. These are then used in the <tt>base.conf</tt> / <tt>policy.conf</tt> source file and also inserted into each module by the [[#policy_module Macro | policy_module]] Macro. The <tt>policy/policy/mcs</tt> and <tt>mls</tt> configuration files are the only files that contain this macro in the current reference policy (note that the <tt>mcs</tt> file has <tt>gen_sens(1)</tt> as only one sensitivity is required).
  
 
'''The macro definition is:'''
 
'''The macro definition is:'''
Line 2,445: Line 2,550:
  
 
|}
 
|}
 +
  
 
'''The macro is valid in:'''
 
'''The macro is valid in:'''
Line 2,459: Line 2,565:
  
 
|}
 
|}
 +
  
 
'''Example Macro:'''
 
'''Example Macro:'''
Line 2,470: Line 2,577:
 
'''Expanded Macro:'''
 
'''Expanded Macro:'''
 
<pre>
 
<pre>
# This example has been extracted from the base.conf source
+
# This example has been extracted from the base.conf source file.
# file.
+
  
 
sensitivity s0;
 
sensitivity s0;
Line 2,480: Line 2,586:
  
 
==== gen_levels Macro ====
 
==== gen_levels Macro ====
This macro will generate a level Statement for each level defined. These are then used in the <tt>base.conf</tt> / <tt>policy.conf</tt> source file. The <tt>policy/policy/mcs</tt> and <tt>mls</tt> configuration files are the only files that contain this macro in the current reference policy.
+
This macro will generate a [[MLSStatements#level | level]] statement for each level defined. These are then used in the <tt>base.conf</tt> / <tt>policy.conf</tt> source file. The <tt>policy/policy/mcs</tt> and <tt>mls</tt> configuration files are the only files that contain this macro in the current reference policy.
  
 
'''The macro definition is:'''
 
'''The macro definition is:'''
Line 2,488: Line 2,594:
  
 
'''Where:'''
 
'''Where:'''
 +
 
{| border="1"
 
{| border="1"
 
| gen_levels
 
| gen_levels
Line 2,494: Line 2,601:
 
|-
 
|-
 
| mls_num_sens
 
| mls_num_sens
| This is the parameter that defines the number of sensitivities to generate. The MCS policy is set to "<tt>1</tt>".
+
| This is the parameter that defines the number of sensitivities to generate. The MCS policy is set to '<tt>1</tt>'.
  
 
|-
 
|-
Line 2,503: Line 2,610:
  
 
|}
 
|}
 +
  
 
'''The macro is valid in:'''
 
'''The macro is valid in:'''
Line 2,517: Line 2,625:
  
 
|}
 
|}
 +
  
 
'''Example Macro:'''
 
'''Example Macro:'''
Line 2,574: Line 2,683:
 
     cron_dontaudit_rw_tcp_sockets(domain)
 
     cron_dontaudit_rw_tcp_sockets(domain)
 
     allow domain domain:key { link search };
 
     allow domain domain:key { link search };
')
+
')
 
</pre>
 
</pre>
  
Line 2,603: Line 2,712:
  
 
==== enable_ubac  ====
 
==== enable_ubac  ====
This is used within the <tt>./policy/constraints</tt> configuration file to set up various attributes to support user based access control (UBAC). These attributes are then used within the various modules that want to support UBAC. This support was added in version 2 of the Referefence Policy.  
+
This is used within the <tt>./policy/constraints</tt> configuration file to set up various attributes to support user based access control (UBAC). These attributes are then used within the various modules that want to support UBAC. This support was added in version 2 of the Reference Policy.  
  
The orginal method (role based access control, or RBAC) is the default for F-12 (<tt>ubac = n</tt>). The parameter is set up by the <tt>Makefile</tt> with information taken from the <tt>build.conf</tt> file at the start of the build process (<tt>ubac = y | ubac = n</tt>).
+
The parameter is set up by the <tt>Makefile</tt> with information taken from the <tt>build.conf</tt> file at the start of the build process (<tt>ubac = y | ubac = n</tt>).
  
 
'''Example Macro:'''
 
'''Example Macro:'''
Line 2,633: Line 2,742:
 
ifndef(`direct_sysadm_daemon',`
 
ifndef(`direct_sysadm_daemon',`
 
     ifdef(`distro_gentoo',`
 
     ifdef(`distro_gentoo',`
# Gentoo integrated run_init:
+
    # Gentoo integrated run_init:
 
         init_script_file_entry_type(run_init_t)
 
         init_script_file_entry_type(run_init_t)
 
     ')
 
     ')
Line 2,645: Line 2,754:
 
')
 
')
 
</pre>
 
</pre>
 
  
 
== Module Expansion Process ==
 
== Module Expansion Process ==
 
The objective of this section is to show how the modules are expanded by the reference policy build process to form files that can then be compiled and then loaded into the policy store by using the <tt>make MODULENAME.pp</tt> target.
 
The objective of this section is to show how the modules are expanded by the reference policy build process to form files that can then be compiled and then loaded into the policy store by using the <tt>make MODULENAME.pp</tt> target.
  
The files shown are those produced by the build process using the ada policy modules from the Reference Policy source tree (<tt>ada.te</tt>, <tt>ada.if</tt> and <tt>ada.fc</tt>) that are shown in the [[NB_RefPolicy#Reference_Policy_Module_Files | Reference Policy Module Files]] section.
+
The files shown are those produced by the build process using the ada policy modules from the Reference Policy source tree (<tt>ada.te</tt>, <tt>ada.if</tt> and <tt>ada.fc</tt>) that are shown in the [[#Reference Policy Module Files | Reference Policy Module Files]] section.
  
The initial build process will build the source text files in the <tt>policy/tmp</tt> directory as <tt>ada.tmp</tt> and <tt>ada.mod.fc</tt> (that are basically build equivalent <tt>ada.conf</tt> and <tt>ada.fc</tt> formatted files). The basic steps are shown in [http://taiga.selinuxproject.org/~rhaines/diagrams/5-6-ada-process.png The <tt>make ada</tt> sequence of events] diagram, and the resulting expanded code shown in [http://taiga.selinuxproject.org/~rhaines/diagrams/5-7-resulting-code.png The Resulting Code] diagram. The actual module expansion is left to the reader to investigate.
+
The initial build process will build the source text files in the <tt>policy/tmp</tt> directory as <tt>ada.tmp</tt> and <tt>ada.mod.fc</tt> (that are basically build equivalent <tt>ada.conf</tt> and <tt>ada.fc</tt> formatted files). The basic steps are shown in the [http://selinuxproject.org/~rhaines/NB4-diagrams/28-mod-expand-1.png The <tt>make ada</tt> sequence of events] diagram, and the resulting expanded code shown in the [http://selinuxproject.org/~rhaines/NB4-diagrams/29-mod-expand-2.png The expansion process] diagram.
 +
 
 +
 
 +
{| style="width: 100%;" border="0"
 +
|-
 +
| [[XENStatements | '''Previous''']]
 +
| <center>[[NewUsers | '''Home''']]</center>
 +
| <center>[[NB_Imp_SELinux-aware_Apps | '''Next''']]</center>
 +
|}
  
  
 
----
 
----
 
<references/>
 
<references/>
 +
 +
[[Category:Notebook]]

Latest revision as of 14:37, 25 September 2015

Contents

The Reference Policy

Introduction

The Reference Policy is now the standard policy source used to build GNU/Linux SELinux policies. This provides a single source tree with supporting documentation that can be used to build policies for different purposes such as: confining important daemons, supporting MLS / MCS type policies and locking down systems so that all processes are under SELinux control.

This section details how the Reference Policy is:

  1. Constructed and types of policy builds supported.
  2. Adding new modules to the build.
  3. Installation as a full Reference Policy source or as Header files.
  4. Impact of the migration process being used to convert compiled module files (*.pp) to CIL.
  5. Modifying the configuration files to build new policies.
  6. Explain the support macros.

Reference Policy Overview

Strictly speaking the 'Reference Policy' should refer to the policy taken from the master repository or the latest released version (see https://github.com/TresysTechnology/refpolicy/wiki). This is because most Linux distributors take a released version and then tailor it to their specific requirements, for example the Fedora distribution is built from the standard Reference Policy but modified and distributed by Red Hat as a source RPM, for example:

selinux-policy-3.12.1-179.fc20.src.rpm[1]

The master Reference Policy repository can be checked out using the following:

# Check out the core policy:
git clone https://github.com/TresysTechnology/refpolicy.git
cd refpolicy
# Add the contibuted modules (policy/modules/contrib)
git submodule init
git submodule update

The Reference Policy Source tree diagram shows the layout that once installed would be located at:

/etc/selinux/<NAME>/src/policy

Where the <NAME> entry is taken from the build.conf file as discussed in the Reference Policy Build Options - build.conf section. The Installing and Building the Reference Policy Source section explains a simple build plus information on building the Fedora source.

The Reference Policy can be used to build two different formats of policy infrastructure:

  1. Loadable Module Policy - A policy that has a base module for core services and has the ability to load / unload modules to support applications as required[2]. This is now the standard used by GNU / Linux distributions.
  2. Monolithic Policy - A policy that has all the required policy information in a single base policy and does not require the services of the module infrastructure (semanage(8) or semodule(8)). These are more suitable for embedded or minimal systems.

Each of the policy types are built using module files that define the specific rules required by the policy as detailed in the Reference Policy Module Files section. Note that the monolithic policy is built using the the same module files by forming a single 'base' source file.

The Reference Policy relies heavily on the m4(1) macro processor as the majority of supporting services are m4 macros.

There are tools such as SLIDE (SELinux integrated development environment) that can be used to make the task of policy development and testing easier when using the Reference Policy source or headers. SLIDE is an Eclipse plugin and details can be found at:

http://oss.tresys.com/projects/slide


Distributing Policies

It is possible to distribute the Reference Policy in two forms:

  1. As source code that is then used to build policies. This is not the general way policies are distributed as it contains the complete source that most administrators do not need. The Reference Policy Source section describes the source and the Installing and Building the Reference Policy Source section describes how to install the source and build a policy.
  2. As 'Policy Headers'. This is the most common way to distribute the Reference Policy. Basically, the modules that make up 'the distribution' are pre-built and then linked to form a base and optional modules. The 'headers' that make-up the policy are then distributed along with makefiles and documentation. A policy writer can then build policy using the core modules supported by the distribution, and using development tools they can add their own policy modules. The Reference Policy Headers section describes how these are installed and used to build modules.

The policy header files for F-20 are distributed in a number of rpms as follows:

selinux-policy-3.12.1-179.fc20.noarch.rpm - Contains the SELinux /etc/selinux/config file, man pages and the 'Policy Header' development environment that is located at /usr/share/selinux/devel
selinux-policy-doc-3.12.1-179.fc20.noarch.rpm - Contains the html policy documentation that is located at /usr/share/doc/selinux-policy/html
selinux-policy-minimum-3.12.1-179.fc20.noarch.rpm
selinux-policy-mls-3.12.1-179.fc20.noarch.rpm
selinux-policy-targeted-3.12.1-179.fc20.noarch.rpm
These three rpms contain policy configuration files and the packaged policy modules (*.pp). They will be used to form the particular policy type in /usr/share/selinux/<NAME>, the install process will then install the policy in the appropriate /etc/selinux/<NAME> directory. Normally only one policy would be installed and active, however for development purposes all can be installed.
selinux-policy-sandbox-3.12.1-179.fc20.noarch.rpm
Contains the sandbox module for use by the policycoreutils-sandbox package. This will be installed as a module for one of the three main policies described above.

Policy Functionality

As can be seen from the policies distributed with F-20 above, they can be classified by the name of the functionality they support (taken from the NAME entry of the build.conf), for example the Fedora policies support:

minimum - MCS policy that supports a minimal set of confined daemons within their own domains. The remainder run in the unconfined_t space.
targeted - MCS policy that supports a greater number of confined daemons and can also confine other areas and users (this also supports the older 'strict' policy).
mls - MLS policy for server based systems.

Reference Policy Module Files

The reference policy modules are constructed using a mixture of Kernel Policy Language, support macros and Interface macros using three principle types of source file:

  • A private policy file that contains statements required to enforce policy on the specific GNU / Linux service being defined within the module. These files are named <module_name>.te. For example the ada.te file shown below has two statements:
    • one to state that the ada_t process has permission to write to the stack and memory allocated to a file.
    • one that states that if the unconfined module is loaded, then allow the ada_t domain unconfined access. Note that if the flow of this statement is followed it will be seen that many more interfaces and macros are called to build the final raw SELinux language statements. An expanded module source is shown in the Module Expansion Process section.
  • An external interface file that defines the services available to other modules. These files are named <module_name>.if.
For example the ada.if file shown below has two interfaces defined for other modules to call (see also the Documentation Screenshot that shows the documentation that can be automatically generated):
    • ada_domtrans - that allows another module (running in domain $1) to run the ada application in the ada_t domain.
    • ada_run - that allows another module to run the ada application in the ada_t domain (via the ada_domtrans interface), then associate the ada_t domain to the caller defined role ($2) and terminal ($3).
Provided of course the caller domain has permission.
It should be noted there are two types of interface specification:
Access Interfaces - These are the most common and define interfaces that .te modules can call as described in the ada examples. They are generated by the interface macro as detailed in the the interface Macro section.
Template Interfaces - These are required whenever a module is required in different domains and allows the type(s) to be redefined by adding a prefix supplied by the calling module. The basic idea is to set up an application in a domain that is suitable for the defined SELinux user and role to access but not others. These are generated by the template macro as detailed in the template Macro section that also explains the openoffice.if template.
  • A file labeling file that defines the labels to be added to files for the specified module. These files are named <module_name>.fc. The build process will amalgamate all the .fc files and finally form the file_contexts file that will be used to label the filesystem.
For example the ada.fc file shown below requires that the specified files are all labeled system_u:object_r:ada_exec_t:s0.

The <module_name> must be unique within the reference policy source tree and should reflect the specific GNU / Linux service being enforced by the policy.

The module files are constructed using a mixture of:

  1. Policy language statements as defined in the Kernel Policy Language section.
  2. Reference Policy macros that are defined in the Reference Policy Macros section.
  3. External interface calls defined within other modules (.te and .if only).

An example of each file taken from the ada module is as follows:

ada.te file contents:

policy_module(ada, 1.4.1)

########################################
#
# Declarations
#

attribute_role ada_roles;
roleattribute system_r ada_roles;

type ada_t;
type ada_exec_t;
application_domain(ada_t, ada_exec_t)
role ada_roles types ada_t;

########################################
#
# Local policy
#

allow ada_t self:process { execstack execmem };

userdom_use_inherited_user_terminals(ada_t)

optional_policy(`
    unconfined_domain(ada_t)
')

ada.if file contents:

## <summary>GNAT Ada95 compiler.</summary>

########################################
## <summary>
##Execute the ada program in the ada domain.
## </summary>
## <param name="domain">
##<summary>
##Domain allowed to transition.
##</summary>
## </param>
#
interface(`ada_domtrans',`
    gen_require(`
        type ada_t, ada_exec_t;
    ')

    corecmd_search_bin($1)
    domtrans_pattern($1, ada_exec_t, ada_t)
')

########################################
## <summary>
##Execute ada in the ada domain, and
##allow the specified role the ada domain.
## </summary>
## <param name="domain">
##<summary>
##Domain allowed to transition.
##</summary>
## </param>
## <param name="role">
##<summary>
##Role allowed access.
##</summary>
## </param>
#
interface(`ada_run',`
    gen_require(`
        attribute_role ada_roles;
    ')

ada_domtrans($1)
roleattribute $2 ada_roles;

')

ada.fc file contents:

/usr/bin/gnatbind--gen_context(system_u:object_r:ada_exec_t,s0)
/usr/bin/gnatls--gen_context(system_u:object_r:ada_exec_t,s0)
/usr/bin/gnatmake--gen_context(system_u:object_r:ada_exec_t,s0)

/usr/libexec/gcc(/.*)?/gnat1--gen_context(system_u:object_r:ada_exec_t,s0)

Reference Policy Documentation

One of the advantages of the reference policy is that it is possible to automatically generate documentation as a part of the build process. This documentation is defined in XML and generated as HTML files suitable for viewing via a browser.

The documentation for Fedora can be viewed in a browser by [file:///usr/share/doc/selinux-policy/html/index.html] once the selinux-policy-doc rpm has been installed.

The documentation for the Reference Policy source will be available at <location>/src/policy/doc/html once make html has been executed (the <location> is the location of the installed source after make install-src has been executed as described in the Installing and Building the Reference Policy Source section). The Reference Policy documentation may also be available at a default location of /usr/share/doc/refpolicy-VERSION/html if make install-doc has been executed (where VERSION is the entry from the source VERSION file.

The Documentation Screenshot shows an example produced for the ada module interfaces.

Reference Policy Source

This section explains the source layout and configuration files, with the actual installation and building covered in the Installing and Building the Reference Policy Source section.

The source has a README file containing information on the configuration and installation processes that has been used within this section (and updated with the authors comments as necessary). There is also a VERSION file that contains the Reference Policy release date which can be used to obtain the original source from the repository located at:

https://github.com/TresysTechnology/refpolicy/wiki

Source Layout

The Reference Policy Source tree diagram shows the layout of the reference policy source tree, that once installed would be located at:

/etc/selinux/<NAME>/src/policy

The following sections detail the source contents:

The Installing and Building the Reference Policy Source section then describes how the initial source is installed and configured to allow a policy to be built.

Reference Policy Files and Directories

Table 1 shows the major files and their directories with a description of each taken from the README file. All directories are relative to the root of the Reference Policy source directory ./policy.

Two of these configuration files (build.conf and modules.conf) are further detailed in the Source Configuration Files section as they define how the policy will be built.

During the build process, a file is generated in the ./policy directory called either policy.conf or base.conf depending whether a monolithic or modular policy is being built. This file is explained in the Modular Policy Build Structure section.

Table 1: The Reference Policy Files and Directories
File / Directory Name Comments
Makefile General rules for building the policy.
Rules.modular Makefile rules specific to building loadable module policies.
Rules.monolithic Makefile rules specific to building monolithic policies.
build.conf Options which influence the building of the policy, such as the policy type and distribution. This file is described in the Reference Policy Build Options - build.conf section.
config/appconfig-<type> Application configuration files for all configurations of the Reference Policy where <type> is taken from the build.conf TYPE entry that are currently: standard, MLS and MCS). These files are used by SELinux-aware programs and described in the SELinux Configuration Files section.
config/file_contexts.subs_dist outline contexts/files/file_contexts.subs and file_contexts.subs_dist File] section).
config/local.users The file read by load policy for adding SELinux users to the policy on the fly.

Note that this file is not used in the modular policy build.

doc/html/* When make html has been executed, contains the in-policy XML documentation, presented in web page form .
doc/policy.dtd The doc/policy.xml file is validated against this DTD.
doc/policy.xml This file is generated/updated by the conf and html make targets. It contains the complete XML documentation included in the policy.
doc/templates/* Templates used for documentation web pages.
man/* Various man pages for modules (ftp, http etc.)
support/* Tools used in the build process.
policy/flask/initial_sids This file has declarations for each initial SID.

The file usage in policy generation is described in the Modular Policy Build Structure section.

policy/flask/security_classes This file has declarations for each security class.

The file usage in policy generation is described in the Modular Policy Build Structure section.

policy/flask/access_vectors This file defines the common permissions and class specific permissions. The file is described in the Modular Policy Build Structure section.
policy/modules/* Each directory represents a layer in Reference Policy. All of the modules are contained in one of these layers. The contrib modules are supplied externally to the Reference Policy, then linked into the build.

The files present in each directory are:

metadata.xml - describes the layer.

<module_name>.te, .if & .fc - contains policy source as described in the Reference Policy Module Files section.

The file usage in policy generation is described in the Modular Policy Build Structure section.

policy/support/* Reference Policy support macros. These are described in the Reference Policy Macros section.
policy/booleans.conf This file is generated/updated by the conf make target. It contains the booleans in the policy, and their default values. If tunables are implemented as booleans, tunables will also be included. This file will be installed as the /etc/selinux/NAME/booleans file (note that this is not true for any system that implements the modular policy - see the Booleans, Global Booleans and Tunable Booleans section).
policy/constraints This file defines constraints on permissions in the form of boolean expressions that must be satisfied in order for specified permissions to be granted. These constraints are used to further refine the type enforcement rules and the role allow rules. Typically, these constraints are used to restrict changes in user identity or role to certain domains.

(Note that this file does not contain the MLS / MCS constraints as they are in the mls and mcs files described below).

The file usage in policy generation is described in the Modular Policy Build Structure section.

policy/context_defaults This would contain any specific default_user, default_role, default_type and/or default_range rules required by the policy.
policy/global_booleans This file defines all booleans that have a global scope, their default value, and documentation. See the Booleans, Global Booleans and Tunable Booleans section.
policy/global_tunables This file defines all tunables that have a global scope, their default value, and documentation. See the Booleans, Global Booleans and Tunable Booleans section.
policy/mcs This contains information used to generate the sensitivity, category, level and mlsconstraint statements used to define the MCS configuration.

The file usage in policy generation is described in the Modular Policy Build Structure section.

policy/mls This contains information used to generate the sensitivity, category, level and mlsconstraint statements used to define the MLS configuration.

The file usage in policy generation is described in the Modular Policy Build Structure section.

policy/modules.conf This file contains a listing of available modules, and how they will be used when building Reference Policy.

To prevent a module from being used, set the module to "off". For monolithic policies, modules set to "base" and "module" will be included in the policy. For modular policies, modules set to "base" will be included in the base module; those set to "module" will be compiled as individual loadable modules.

This file is described in the Reference Policy Build Options - modules.conf section.

policy/policy_capabilities This file defines the policy capabilities that can be enabled in the policy.

The file usage in policy generation is described in the Modular Policy Build Structure section.

policy/users This file defines the users included in the policy.

The file usage in policy generation is described in the Modular Policy Build Structure section.

securetty_types These files are not part of the standard Reference Policy distribution but are added by Fedora source updates.
setrans.conf


Source Configuration Files

There are two major configuration files (build.conf and modules.conf) that define the policy to be built and are detailed in this section.

Reference Policy Build Options - build.conf

This file defines the policy type to be built that will influence its name and where the source will be located once it is finally installed. An example file content is shown in the Installing and Building the Reference Policy Source section where it is used to install and then build the policy.

Table 2 explains the fields that can be defined within this file, however there are a number of m4 macro parameters that are set up when this file is read by the build process makefiles. These macro definitions are shown in Table 20 and are also used within the module source files to control how the policy is built with examples shown in the ifdef / ifndef Parameters section.

Table 2: build.conf Entries
Option Type Comments
OUTPUT_POLICY Integer Set the version of the policy created when building a monolithic policy. This option has no effect on modular policy.
TYPE String Available options are standard (uses RBAC/TE), mcs (uses RBAC/TE/MCS) and mls (uses RBAC/TE/MLS).

The mls and mcs options control the enable_mls, and enable_mcs policy blocks.

NAME String Sets the name of the policy; the NAME is used when installing files to e.g., /etc/selinux/NAME and /usr/share/selinux/NAME. If not set, the policy type field (TYPE) is used.
DISTRO String (optional) Enable distribution-specific policy. Available options are redhat, rhel4, gentoo, debian, and suse. This option controls distro_redhat, distro_rhel4, distro_suse policy blocks.
UNK_PERMS String Set the kernel behaviour for handling of permissions defined in the kernel but missing from the policy. The permissions can either be allowed, denied, or the policy loading can be rejected. See the SELinux Filesystem section for more details. If not set, then it will be taken from the semanage.conf file.
DIRECT_INITRC n) If 'y' sysadm will be allowed to directly run init scripts, instead of requiring the run_init tool. This is a build option instead of a tunable since role transitions do not work in conditional policy. This option controls direct_sysadm_daemon policy blocks.
MONOLITHIC n) If 'y' a monolithic policy is built, otherwise a modular policy is built.
UBAC n) If 'y' User Based Access Control policy is built. The default for Red Hat is 'n'. These are defined as constraints in the policy/constraints file. Note Version 1 of the Reference Policy did not have this entry and defaulted to Role Based Access Control.

The UBAC option is described at http://blog.siphos.be/2011/05/selinux-user-based-access-control/.

CUSTOM_BUILDOPT String Space separated list of custom build options.
MLS_SENS Integer Set the number of sensitivities in the MLS policy. Ignored on standard and MCS policies.
MLS_CATS Integer Set the number of categories in the MLS policy. Ignored on standard and MCS policies.
MCS_CATS Integer Set the number of categories in the MCS policy. Ignored on standard and MLS policies.
QUIET n) If 'y' the build system will only display status messages and error messages. This option has no effect on policy.


Table 3: m4 parameters set at build time - These have been extracted from the Reference Policy Makefile file.
m4 Parameter Name in Makefile From build.conf entry Comments
enable_mls TYPE Set if MLS policy build enabled.
enable_mcs TYPE Set if MCS policy build enabled.
enable_ubac UBAC Set if UBAC set to 'y'.
mls_num_sens MLS_SENS The number of MLS sensitivities configured.
mls_num_cats MLS_CATS The number of MLS categories configured.
mcs_num_cats MCS_CATS The number of MCS categories configured.
distro_$(DISTRO) DISTRO The distro name or blank.
direct_sysadm_daemon DIRECT_INITRC If DIRECT_INITRC entry set to 'y'.
hide_broken_symtoms This is set up in the Makefile and can be used in modules to hide errors with dontaudit rules (or even allow rules).


Reference Policy Build Options - policy/modules.conf

This file controls what modules are built within the policy with example entries as follows:

# Layer: kernel
# Module: kernel
# Required in base
#
# Policy for kernel threads, proc filesystem,and unlabeled processes and
# objects.
# 
kernel = base

# Module: amanda
#
# Automated backup program.
# 
amanda = module

# Layer: admin
# Module: ddcprobe
#
# ddcprobe retrieves monitor and graphics card information
# 
ddcprobe = off

As can be seen the only active line (those without comments[3]) is:

<module_name> = base | module | off

Where:

module_name The name of the module to be included within the build.
base The module will be in the base module for a modular policy build (build.conf entry MONOLITHIC = n).
module The module will be built as a loadable module for a modular policy build. If a monolithic policy is being built (build.conf entry MONOLITHIC = y), then this module will be built into the base module.
off The module will not be included in any build.

Generally it is up to the policy distributor to decide which modules are in the base and those that are loadable, however there are some modules that MUST be in the base module. To highlight this there is a special entry at the start of the modules interface file (.if) that has the entry <required val="true"> as shown below (taken from the kernel.if file):

## <summary>
##Policy for kernel threads, proc filesystem, 
##and unlabeled processes and objects.
## </summary>
## <required val="true">
##This module has initial SIDs.
## </required>

The modules.conf file will also reflect that a module is required in the base by adding a comment 'Required in base' when the make conf target is executed (as all the .if files are checked during this process and the modules.conf file updated).

# Layer: kernel
# Module: kernel
# Required in base
#
# Policy for kernel threads, proc filesystem,and unlabeled processes and objects.
# 
kernel = base

Those marked as required in base are shown in Table 4 (note that F-20 and the standard Reference Policy are different)

Table 4: Mandatory modules.conf Entries
Layer Module Name Comments
kernel corecommands Core policy for shells, and generic programs in:
/bin, /sbin, /usr/bin, and /usr/sbin. 

The .fc file sets up the labels for these items. 

All the interface calls start with 'corecmd_'.
kernel corenetwork Policy controlling access to network objects and also contains the initial SIDs for these.

The .if file is large and automatically generated. All the interface calls start with 'corenet_'.

kernel devices This module creates the device node concept and provides the policy for many of the device files. Notable exceptions are the mass storage and terminal devices that are covered by other modules (that is a char or block device file, usually in /dev). All types that are used to label device nodes should use the dev_node macro.

Additionally this module controls access to three things:

  1. the device directories containing device nodes.
  2. device nodes as a group
  3. individual access to specific device nodes covered by this module.

All the interface calls start with 'dev_'.

kernel domain Contains the core policy for forming and managing domains.

All the interface calls start with 'domain_'.

kernel files This module contains basic filesystem types and interfaces and includes:
  1. The concept of different file types including basic files, mount points, tmp files, etc.
  2. Access to groups of files and all files.
  3. Types and interfaces for the basic filesystem layout (/, /etc, /tmp, /usr, etc.).
  4. Contains the file initial SID.

All the interface calls start with 'files_'.

kernel filesystem Contains the policy for filesystems and the initial SID.

All the interface calls start with 'fs_'.

kernel kernel Contains the policy for kernel threads, proc filesystem, and unlabeled processes and objects. This module has initial SIDs.

All the interface calls start with 'kernel_'.

kernel mcs Policy for Multicategory security. The .te file only contains attributes used in MCS policy.

All the interface calls start with 'mcs_'.

kernel mls Policy for Multilevel security. The .te file only contains attributes used in MLS policy.

All the interface calls start with 'mls_'.

kernel selinux Contains the policy for the kernel SELinux security interface (selinuxfs).

All the interface calls start with 'selinux_'.

kernel terminal Contains the policy for terminals.

All the interface calls start with 'term_'.

kernel ubac Disabled by Fedora but enabled on standard Ref Policy.

Support user-based access control.

system application Enabled by Fedora but not standard Ref Policy.

Defines attributes and interfaces for all user apps.

system setrans Enabled by Fedora but not standard Ref Policy.

Support for mcstransd(8).


Building the modules.conf File

The file can be created by an editor, however it is generally built initially by make conf that will add any additional modules to the file. The file can then be edited to configure the required modules as base, module or off.

As will be seen in the Installing and Building the Reference Policy Source section, the Red Hat reference policy source comes with a number of pre-configured files that are used to produce the required policy including multiple versions of the modules.conf file.

Source Installation and Build Make Options

This section explains the various make options available that have been taken from the README file. Table 5 describes the general make targets, Table 6 describes the modular policy make targets and Table 7 describes the monolithic policy make targets.

Table 5: General Build Make Targets
Make Target Comments
install-src Install the policy sources into /etc/selinux/NAME/src/policy, where NAME is defined in the build.conf file. If it is not defined, then TYPE is used instead. If a build.conf does not have the information, then the Makefile will default to the current entry in the /etc/selinux/config file or default to refpolicy. A pre-existing source policy will be moved to /etc/selinux/NAME/src/policy.bak.
conf Regenerate policy.xml, and update/create modules.conf and booleans.conf. This should be done after adding or removing modules, or after running the bare target. If the configuration files exist, their settings will be preserved. This must be run on policy sources that are checked out from the CVS repository before they can be used.

Note that if make bare has been executed before this make target, or it is a first build, then the modules/kernel/corenetwork.??.in files will be used to generate the corenetwork.te and corenetwork.if module files. These *.in files may be edited to configure network ports etc. (see the # network_node examples entries).

clean Delete all temporary files, compiled policies, and file_contexts. Configuration files are left intact.
bare Do the clean make target and also delete configuration files, web page documentation, and policy.xml.
html Regenerate policy.xml and create web page documentation in the doc/html directory.
install-appconfig Installs the appropriate SELinux-aware configuration files.


Table 6: Modular Policy Build Make Targets
Make Target Comments
base Compile and package the base module. This is the default target for modular policies.
modules Compile and package all Reference Policy modules configured to be built as loadable modules.
MODULENAME.pp Compile and package the MODULENAME Reference Policy module.
all Compile and package the base module and all Reference Policy modules configured to be built as loadable modules.
install Compile, package, and install the base module and Reference Policy modules configured to be built as loadable modules.
load Compile, package, and install the base module and Reference Policy modules configured to be built as loadable modules, then insert them into the module store.
validate Validate if the configured modules can successfully link and expand.
install-headers Install the policy headers into /usr/share/selinux/NAME. The headers are sufficient for building a policy module locally, without requiring the complete Reference Policy sources. The build.conf settings for this policy configuration should be set before using this target.
install-docs Build and install the documentation and example module source with Makefile. The default location is /usr/share/doc/refpolicy-VERSION, where the version is the value in the VERSION file.


Table 7: Monolithic Policy Build Make Targets
Make Target Comments
policy Compile a policy locally for development and testing. This is the default target for monolithic policies.
install Compile and install the policy and file contexts.
load Compile and install the policy and file contexts, then load the policy.
enableaudit Remove all dontaudit rules from policy.conf.
relabel Relabel the filesystem.
checklabels Check the labels on the filesystem, and report when a file would be relabeled, but do not change its label.
restorelabels Relabel the filesystem and report each file that is relabeled.


Booleans, Global Booleans and Tunable Booleans

The three files booleans.conf, global_booleans and global_tunables are built and used as follows:

booleans.conf This file is generated / updated by make conf, and contains all the booleans in the policy with their default values. If tunable and global booleans are implemented then these are also included.

This file can also be delivered as a part of the Fedora reference policy source as shown in the Installing and Building the Reference Policy Source section. This is generally because other default values are used for booleans and not those defined within the modules themselves (i.e. distribution specific booleans). When the make install is executed, this file will be used to set the default values.

Note that if booleans are updated locally the policy store will contain a booleans.local file.

In SELinux enabled systems that support the policy store features (modular policies) this file is not installed as /etc/selinux/NAME/booleans.

global_booleans These are booleans that have been defined in the global_tunables file using the gen_bool macro. They are normally booleans for managing the overall policy and currently consist of the following (where the default values are false):
secure_mode
global_tunables These are booleans that have been defined in module files using the gen_tunable macro and added to the global_tunables file by make conf. The tunable_policy macros are defined in each module where policy statements or interface calls are required. They are booleans for managing specific areas of policy that are global in scope. An example is allow_execstack that will allow all processes running in unconfined_t to make their stacks executable.


Modular Policy Build Structure

This section explains the way a modular policy is constructed, this does not really need to be known but is used to show the files used that can then be investigated if required.

When make all or make load or make install are executed the build.conf and modules.conf files are used to define the policy name and what modules will be built in the base and those as individual loadable modules.

Basically the source modules (.te, .if and .fc) and core flask files are rebuilt in the tmp directory where the reference policy macros[4] in the source modules will be expanded to form actual policy language statements as described in the SELinux Policy Language Policy Language section. Layout 1 shows these temporary files that are used to form the base.conf[5] file during policy generation.

The base.conf file will consist of language statements taken from the module defined as base in the modules.conf file along with the constraints, users etc. that are required to build a complete policy.

The individual loadable modules are built in much the same way as shown in Layout 2.

Layout 1: Base Module Build - This shows the temporary build files used to build the base module 'base.conf' as a part of the 'make' process. Note that the modules marked as base in modules.conf are built here.
Base Policy Component Description Policy Source File Name (relative to ./policy/policy) ./policy/tmp

File Name

The object classes supported by the kernel. flask/security_classes pre_te_files.conf
The initial SIDs supported by the kernel. flask/initial_sids
The object class permissions supported by the kernel. flask/access_vectors
This is either the expanded mls or mcs file depending on the type of policy being built. mls or mcs
These are the policy capabilities that can be configured / enabled to support the policy. policy_capabilities
This area contains all the attribute, bool, type and typealias statements extracted from the *.te and *.if files that form the base module. modules/*/*.te

modules/*/*.if


all_attrs_types.conf
Contains the global and tunable bools extracted from the conf files. global_bools.conf

global_tunables.conf

global_bools.conf
Contains the rules extracted from each of the modules .te and .if files defined in the modules.conf file as 'base'. base modules only_te_rules.conf
Contains the expanded users from the users file. users all_post.conf
Contains the expanded constraints from the constraints file. constraints
Contains the default SID labeling extracted from the *.te files. modules/*/*.te
Contains the fs_use_xattr, fs_use_task, fs_use_trans and genfscon statements extracted from each of the modules .te and .if files defined in the modules.conf file as 'base'. modules/*/*.te

modules/*/*.if



Contains the netifcon, nodecon and portcon statements extracted from each of the modules .te and .if files defined in the modules.conf file as 'base'. modules/*/*.te

modules/*/*.if


Contains the expanded file context file entries extracted from the *.fc files defined in the modules.conf file as 'base'. modules/*/*.fc base.fc.tmp
Expanded seusers file. seusers seusers
These are the commands used to compile, link and load the base policy module:
checkmodule base.conf -o tmp/base.mod
semodule_package -o base.conf -m base_mod -f base_fc -u users_extra -s tmp/seusers
semodule -s $(NAME) -b base.pp) -i and each module .pp file

The 'NAME' is that defined in the build.conf file.


Layout 2: Module Build - This shows the module files and the temporary build files used to build each module as a part of the 'make' process (i.e. those modules marked as module in modules.conf).
Base Policy Component Description Policy Source File Name (relative to ./policy/policy) ./policy/tmp

File Name

For each module defined as 'module' in the modules.conf configuration file, a source module is produced that has been extracted from the *.te and *.if file for that module. modules/*/<module_name>.te

modules/*/<module_name>.if


<module_name>.tmp



For each module defined as 'module' in the modules.conf configuration file, an object module is produced from executing the checkmodule command shown below. tmp/<module_name>.tmp <module_name>.mod
For each module defined as 'module' in the modules.conf configuration file, an expanded file context file is built from the <module_name>.fc file. modules/*/<module_name>.fc base.fc.tmp
This command is used to compile each module:

checkmodule tmp/<module_name>.tmp -o tmp/<module_name>.mod


Each module is packaged and loaded with the base module using the following commands:

semodule_package -o base.conf -m base_mod -f base_fc -u users_extra -s tmp/seusers
semodule -s $(NAME) -b base.pp) -i and each module .pp file

The 'NAME' is that defined in the build.conf file.

Creating Additional Layers

One objective of the reference policy is to separate the modules into different layers reflecting their 'service' (e.g. kernel, system, app etc.). While it can sometimes be difficult to determine where a particular module should reside, it does help separation, however because the way the build process works, each module must have a unique name.

If a new layer is required, then the following will need to be completed:

  1. Create a new layer directory ./policy/modules/LAYERNAME that reflects the layer's purpose.
  2. In the ./policy/modules/LAYERNAME directory create a metadata.xml file. This is an XML file with a summary tag and optional desc (long description) tag that should describe the purpose of the layer and will be used as a part of the documentation. An example is as follows:
<summary>ABC modules for the XYZ components.</summary>

Installing and Building the Reference Policy Source

This section will give a brief overview of how to build the Reference Policy for an MCS modular build that is similar (but not the same) as the Fedora targeted policy. The Fedora F-20 version of the targeted policy build is discussed but building without using the rpm spec file is more complex.

Building Standard Reference Policy

This will run through a simple configuration process and build of a reference policy similar to the Fedora targeted policy. By convention the source is installed in a central location and then for each type of policy a copy of the source is installed at /etc/selinux/<NAME>/src/policy.

The basic steps are:

  • Install master Reference Policy Source and add the contributed modules:
# Check out the core policy:
git clone https://github.com/TresysTechnology/refpolicy.git
cd refpolicy

# Add the contibuted modules (policy/modules/contrib)
git submodule init
git submodule update
  • Edit the build.conf file to reflect the policy to be built, the minimum required is setting the NAME = entry. An example file with NAME = refpolicy-test is as follows:
############################################
# Policy build options
#

# Policy version
# By default, checkpolicy will create the highest version policy it supports. 
# Setting this will override the version. This only has an effect for
# monolithic policies.
#OUTPUT_POLICY = 18

# Policy Type
# standard, mls, mcs. ** Note Red Hat always build the MCS Policy Type
# for their 'targeted' version. **
TYPE = mcs

# Policy Name
# If set, this will be used as the policy name. Otherwise the policy type 
# will be used for the name. ** This entry is also used by the
#'make install-src' process to copy the source to the:
#     /etc/selinux/<NAME>/src/policy directory. **
NAME = refpolicy-test

# Distribution
# Some distributions have portions of policy for programs or configurations 
# specific to the distribution. Setting this will enable options for the
# distribution. redhat, gentoo, debian, suse, and rhel4 are current options.
# ** Fedora users should enable redhat.**
DISTRO = redhat

# Unknown Permissions Handling
# The behaviour for handling permissions defined in the kernel but missing
# from the policy. The permissions can either be allowed, denied, or
# the policy loading can be rejected.
# allow, deny, and reject are current options. ** Fedora use allow for all
# policies except MLS that uses 'deny'.**
UNK_PERMS = allow

# Direct admin init
# Setting this will allow sysadm to directly run init scripts, instead of 
# requiring run_init. This is a build option, as role transitions do not
# work in conditional policy.
DIRECT_INITRC = n

# Build monolithic policy. Putting y here will build a monolithic policy.
MONOLITHIC = n

# User-based access control (UBAC)
# Enable UBAC for role separations. ** Note Fedora disables UBAC.**
UBAC = n

# Custom build options. This field enables custom build options. Putting
# foo here will enable build option blocks foo. Options should be separated
# by spaces.
CUSTOM_BUILDOPT =

# Number of MLS Sensitivities
# The sensitivities will be s0 to s(MLS_SENS-1). Dominance will be in
# increasing numerical order with s0 being lowest.
MLS_SENS = 16

# Number of MLS Categories.
# The categories will be c0 to c(MLS_CATS-1).
MLS_CATS = 1024

# Number of MCS Categories
# The categories will be c0 to c(MLC_CATS-1).
MCS_CATS = 1024

# Set this to y to only display status messages during build.
QUIET = n
  • Run make install-src to install source at policy build location.
  • Change to the /etc/selinux/<NAME>/src/policy directory where an unconfigured basic policy has been installed.
  • Run make conf to build an initial policy/booleans.conf and policy/modules.conf files. For this simple configuration these files will not be edited.
This process will also build the policy/modules/kernel/corenetwork.te / corenetwork.if files if not already present. These would be based on the contents of corenetwork.te.in and corenetwork.if.in configuration files (for this simple configuration these files will not be edited).
Run make load to build the policy, add the modules to the store and install the binary kernel policy plus its supporting configuration files.
Note that if policy stores have been migrated, the store will default to /var/lib/selinux/refpolicy-test, with the modules in active/modules/400/<module_name>, there will also be a CIL version of the module (see [#4.1.1.Policy Store Migration|outline Policy Store Migration] for details).
  • The policy should now be built and can be checked using tools such as apol(8) or loaded by editing the /etc/selinux/config file, running 'touch /.autorelabel' and rebooting the system.

Building the Fedora Policy

Building Fedora policies by hand is complex as they use the rpmbuild/SPECS/selinux-policy.spec file, therefore this section will give an overview of how this can be achieved, the reader can then experiment (the spec file gives an insight). The build process assumes that an equivelent 'targeted' policy will be built named 'targeted-179'.

Install the source as follows:

rpm -Uvh selinux-policy-3.12.1-179.fc20.src.rpm

The rpmbuild/SOURCES directory contents should be as follows with comments on how the files should be installed:

File Name
Comments
serefpolicy-3.12.1.tgz The Reference Policy version 2.20120725

This should be unpacked into:

 rpmbuild/SOURCES/serefpolicy-3.12.1
policy-f20-base.patch Fedora changes to Reference Policy version 2.20120725.

These patches should be used to update the above

patch -p1 < policy-f20-base.patch
serefpolicy-contrib-3.12.1.tgz The Reference Policy contribution modules from version 2.20120725

Unpack the files, apply the policy-f20-contrib.patch and then installed into:

 ./serefpolicy-3.12.1/policy/modules/contrib
policy-f20-contrib.patch Fedora changes to Reference Policy contribution modules.
Once the above has been completed, run make conf from ./serefpolicy-3.12.1 to initialise the build (it creates two important files in ./serefpolicy-3.12.1/policy/modules/kernel called corenetwork.te and corenetwork.if).
config.tgz Fedora changes to Reference Policy version 2.20120725 application config files.

These should be unpacked to update the ./serefpolicy-3.12.1/config versions (some will be added and others updated).

permissivedomains.pp Contains Fedora domains currently sets to permissive. In selinux-policy-3.12.1-179.fc20 there are 31 permissive domains. Copy this to ./serefpolicy-3.12.1 as it will then be built into the policy.
selinux-policy.conf Allows the build process to determine network information.

Not required for this exercise as the corenetwork.te and corenetwork.if files have been built.

Makefile.devel Fedora makefile when using headers. This can replace the ./serefpolicy-3.12.1/support/Makefile.devel
booleans.subs_dist Common files installed for each policy type. Not required for this exercise.
customizable_types
file_contexts.subs_dist
Used to build "targeted" policy
booleans-targeted.conf Replace the ./serefpolicy-3.12.1/policy/booleans.conf file with this version.
modules-targeted-base.conf Concatenate both files and copy this to become:

./serefpolicy-3.12.1/policy/modules.conf

modules-targeted-contrib.conf
securetty_types-targeted Replace the ./serefpolicy-3.12.1/config/appconfig-mcs/securetty_types file with this version.
setrans-targeted.conf Not required for this exercise.
users-targeted Replace the ./serefpolicy-3.12.1/policy/users file with this version.
Used to build "minimum" policy
booleans-minimum.conf
modules-targeted-base.conf Uses the targeted modules.conf.
modules-targeted-contrib.conf
securetty_types-minimum
setrans-minimum.conf
users-minimum
Used to build "mls" policy
booleans-mls.conf
modules-mls-base.conf
modules-mls-contrib.conf
securetty_types-mls
setrans-mls.conf
users-mls


The basic steps are:

  • Edit the build.conf file to reflect the policy to be built:
############################################
# Policy build options
#

# Policy version
# By default, checkpolicy will create the highest version policy it supports. 
# Setting this will override the version. This only has an effect for
# monolithic policies.
#OUTPUT_POLICY = 18

# Policy Type
# standard, mls, mcs. ** Note Red Hat always build the MCS Policy Type
# for their 'targeted' version. **
TYPE = mcs

# Policy Name
# If set, this will be used as the policy name. Otherwise the policy type 
# will be used for the name. ** This entry is also used by the
# 'make install-src' process to copy the source to the:
#     /etc/selinux/<NAME>/src/policy directory.**
NAME = targeted-179

# Distribution
# Some distributions have portions of policy for programs or configurations 
# specific to the distribution. Setting this will enable options for the
# distribution. redhat, gentoo, debian, suse, and rhel4 are current options.
# Fedora users should enable ** redhat. **
DISTRO = redhat

# Unknown Permissions Handling
# The behaviour for handling permissions defined in the kernel but missing
# from the policy. The permissions can either be allowed, denied, or
# the policy loading can be rejected.
# allow, deny, and reject are current options. ** Fedora use allow for all
# policies except MLS that uses 'deny'.**
UNK_PERMS = allow

# Direct admin init
# Setting this will allow sysadm to directly run init scripts, instead of 
# requiring run_init. This is a build option, as role transitions do not
# work in conditional policy.
DIRECT_INITRC = n

# Build monolithic policy. Putting y here will build a monolithic policy.
MONOLITHIC = n

# User-based access control (UBAC)
# Enable UBAC for role separations. ** Note Fedora disables UBAC **
UBAC = n

# Custom build options. This field enables custom build options. Putting
# foo here will enable build option blocks foo. Options should be separated
# by spaces.
CUSTOM_BUILDOPT =

# Number of MLS Sensitivities
# The sensitivities will be s0 to s(MLS_SENS-1). Dominance will be in
# increasing numerical order with s0 being lowest.
MLS_SENS = 16

# Number of MLS Categories.
# The categories will be c0 to c(MLS_CATS-1).
MLS_CATS = 1024

# Number of MCS Categories
# The categories will be c0 to c(MLC_CATS-1).
MCS_CATS = 1024

# Set this to y to only display status messages during build.
QUIET = n
  • From rpmbuild/SOURCES/serefpolicy-3.12.1 run make install-src to install source at policy build location.
  • Change to the /etc/selinux/targeted-179/src/policy directory where the policy has been installed.
  • Run make load to build the policy, add the modules to the store and install the binary kernel policy plus its supporting configuration files.
Note that if policy stores have been migrated, the store will default to /var/lib/selinux/targeted-179, with the modules in active/modules/400/<module_name>, there will also be a CIL version of the module (see [#4.1.1.Policy Store Migration|outline Policy Store Migration] for details).
  • Install the permissivedomains.pp module as follows (this will set 31 permissive domains that are in the F-20 version of the policy):
semodule -s targeted-179 -i permissivedomains.pp
  • The policy should now be built and can be checked using tools such as apol(8) or loaded by editing the /etc/selinux/config file, running 'touch /.autorelabel' and rebooting the system.

Reference Policy Headers

This method of building policy and adding new modules is used for distributions that do not require access to the source code.

Note that the Reference Policy header and the Fedora policy header installations are slightly different as described below.

Building and Installing the Header Files

To be able to fully build the policy headers from the reference policy source two steps are required:

  • Ensure the source is installed and configured as described in the Installing and Building the Reference Policy Source section. This is because the make load (or make install) command will package all the modules as defined in the modules.conf file, producing a base.pp and the relevant .pp packages. The build process will then install these in the /usr/share/selinux/<NAME> directory.
  • Execute the make install-headers that will:
    • Produce a build.conf file that represents the contents of the master build.conf file and place it in the /usr/share/selinux/<NAME>/include directory.
    • Produce the XML documentation set that reflects the source and place it in the /usr/share/selinux/<NAME>/include directory.
    • Copy a development Makefile for building from policy headers to the /usr/share/selinux/<NAME>/include directory.
    • Copy the support macros .spt files to the /usr/share/selinux/<NAME>/include/support directory. This will also include an all_perms.spt file that will contain macros to allow all classes and permissions to be resolved.
    • Copy the module interface files (.if) to the relevant module directories at:
/usr/share/selinux/<NAME>/include/modules

Using the Reference Policy Headers

Note that this section describes the standard Reference Policy headers, the F-20 installation is slightly different and described in the Using Fedora Supplied Headers section.

Once the headers are installed as defined above, new modules can be built in any local directory. An example set of module files are located in the reference policy source at /etc/selinux/<NAME>/src/policy/doc and are called example.te, example.if, and example.fc.

During the header build process a Makefile was included in the headers directory. This Makefile can be used to build the example modules by using makes -f option as follows (assuming that the example module files are in the local directory):

make -f /usr/share/selinux/<NAME>/include/Makefile

However there is another Makefile that can be installed in the users home directory ($HOME) that will call the master Makefile. This is located at /etc/selinux/<NAME>/src/policy/doc in the reference policy source and is called Makefile.example. This is shown below (note that it extracts the <policy_nNAME /etc/selinux/config file):

AWK ?= gawk

NAME ?= $(shell $(AWK) -F= '/^SELINUXTYPE/{ print $$2 }' /etc/selinux/config)
SHAREDIR ?= /usr/share/selinux
HEADERDIR := $(SHAREDIR)/$(NAME)/include

include $(HEADERDIR)/Makefile

Table 8 shows the make targets for modules built from headers.

Table 8: Header Policy Build Make Targets
Make Target Comments
MODULENAME.pp Compile and package the MODULENAME local module.
all Compile and package the modules in the current directory.
load Compile and package the modules in the current directory, then insert them into the module store.
refresh Attempts to reinsert all modules that are currently in the module store from the local and system module packages.
xml Build a policy.xml from the XML included with the base policy headers and any XML in the modules in the current directory.


Using Fedora Supplied Headers

The F-20 distribution installs the headers in a slightly different manner as Fedora installs:

  • A modules-base.lst and modules-contrib.lst containing a list of installed modules under /usr/share/selinux/<NAME>.
  • The development header files are installed in the /usr/share/selinux/devel directory. The example modules are also in this directory and the Makefile is also slightly different to that used by the Reference Policy source.
  • The documentation is installed in the /usr/share/doc/selinux-policy/html directory.

Migrating Compiled Modules to CIL

As explained in the Policy Store Migration section, when libsepol etc. are upgraded to version 2.4, the policy stores will be migrated to the new location that will contain also contain CIL versions of the policy modules.

Reference Policy Support Macros

This section explains some of the support macros used to build reference policy source modules (see Table 9 for the list). These macros are located at:

  • ./policy/support for the reference policy source.
  • /usr/share/selinux/<NAME>/include/support for Reference Policy installed header files.
  • /usr/share/selinux/devel/support for Fedora installed header files.

The following support macro file contents are explained:

loadable_module.spt - Loadable module support.
misc_macros.spt - Generate users, bools and security contexts.
mls_mcs_macros.spt - MLS / MCS support.
file_patterns.spt - Sets up allow rules via parameters for files and directories.
ipc_patterns.spt - Sets up allow rules via parameters for Unix domain sockets.
misc_patterns.spt - Domain and process transitions.
obj_perm_sets.spt - Object classes and permissions.

When the header files are installed the all_perms.spt support macro file is also installed that describes all classes and permissions configured in the original source policy.

Table 9: Support Macros described in this section
Macro Name Function Macro file name
policy_module For adding the module statement and mandatory require block entries. loadable_module.spt
gen_require For use in interfaces to optionally insert a require block
template Generate template interface block
interface Generate the access interface block
optional_policy Optional policy handling
gen_tunable Tunable declaration
tunable_policy Tunable policy handling
gen_user Generate an SELinux user misc_macros.spt



gen_context Generate a security context
gen_bool Generate a boolean
gen_cats Declares categories c0 to c(N-1) mls_mcs_macros.spt



gen_sens Declares sensitivities s0 to s(N-1) with dominance in increasing numeric order with s0 lowest, s(N-1) highest.
gen_levels Generate levels from s0 to (N-1) with categories c0 to (M-1)
mls_systemlow Basic level names for system low and high
mls_systemhigh
mcs_systemlow
mcs_systemhigh
mcs_allcats Allocates all categories


Notes:

  • The macro calls can be in any configuration file read by the build process and can be found in (for example) the users, mls, mcs and constraints files.
  • There are four main m4 ifdef parameters used within modules:
    • enable_mcs - this is used to test if the MCS policy is being built.
    • enable_mls - this is used to test if the MLS policy is being built.
    • enable_ubac - this enables the user based access control within the constraints file.
    • hide_broken_symptoms - this is used to hide errors in modules with dontaudit rules.
These are also mentioned in Table 20 as they are set by the initial build process with examples shown in the ifdef / ifndef Parameters section.
  • The macro examples in this section have been taken from the reference policy module files and shown in each relevant "Example Macro" section. The macros are then expanded by the build process to form modules containing the policy language statements and rules in the tmp directory. These files have been extracted and modified for readability, then shown in each relevant "Expanded Macro" section.
  • An example policy that has had macros expanded is shown in the Module Expansion Process section.
  • Be aware that spaces between macro names and their parameters are not allowed:
    • Correct:
policy_module(ftp, 1.7.0)
    • Incorrect:
policy_module (ftp, 1.7.0)

Loadable Policy Macros

The loadable policy module support macros are located in the loadable_module.spt file.

policy_module Macro

This macro will add the module statement to a loadable module, and automatically add a require statement with pre-defined information for all loadable modules such as the system_r role, kernel classes and permissions, and optionally MCS / MLS information (sensitivity and category statements).

The macro definition is:

policy_module(module_name,version)

Where:

policy_module The policy_module macro keyword.
module_name The module identifier that must be unique in the module layers.
version_number The module version number in M.m.m format (where M = major version number and m = minor version numbers).


The macro is valid in:

Private Policy File (.te)
External Interface File (.if)
File Labeling Policy File (.fc)
Yes
No
No


Example Macro:

# This example is from the modules/services/ftp.te module:
#
policy_module(ftp, 1.7.0)

Expanded Macro:

# This is the expanded macro from the tmp/ftp.tmp file:
#
module ftp 1.7.0;
require {
    role system_r;
    class security {compute_av compute_create .... };
    ....
    class capability2 (mac_override mac_admin };

    # If MLS or MCS configured then the:
    sensitivity s0;
    ....
    category c0;
    ....
}

gen_require Macro

For use within module files to insert a require block.

The macro definition is:

gen_require(`require_statements`)

Where:

gen_require The gen_require macro keyword.
require_statements These statements consist of those allowed in the policy language require statement.


The macro is valid in:

Private Policy File (.te)
External Interface File (.if)
File Labeling Policy File (.fc)
Yes
Yes
No


Example Macro:

# This example is from the modules/services/ftp.te module:
#
gen_require(`type ftp_script_exec_t;')

Expanded Macro:

# This is the expanded macro from the tmp/ftp.tmp file:
#
require {
    type ftp_script_exec_t; 
}

optional_policy Macro

For use within module files to insert an optional block that will be expanded by the build process only if the modules containing the access or template interface calls that follow are present. If one module is present and the other is not, then the optional statements are not included (need to check).

The macro definition is:

optional_policy(`optional_statements`)

Where:

optional_policy The optional_policy macro keyword.
optional_statements These statements consist of those allowed in the policy language optional statement. However they can also be interface template, or support macro calls.


The macro is valid in:

Private Policy File (.te)
External Interface File (.if)
File Labeling Policy File (.fc)
Yes
Yes
No


Example Macro:

# This example is from the modules/services/ftp.te module and 
# shows the optional_policy macro with two levels.
#
optional_policy(`
    corecmd_exec_shell(ftpd_t)
    files_read_usr_files(ftpd_t)
    cron_system_entry(ftpd_t, ftpd_exec_t)

        optional_policy(`
        logrotate_exec(ftpd_t)
    ')
')

Expanded Macro:

# This is the expanded macro from the tmp/ftp.tmp file showing
# the policy language statements with both optional levels expanded.
#
##### Start optional_policy - Level 1 ###########
optional {
##### begin corecmd_exec_shell(ftpd_t)
    require {
        type bin_t, shell_exec_t;
    } # end require
    allow ftpd_t bin_t:dir { getattr search };
    allow ftpd_t bin_t:dir { getattr search read lock ioctl };
    allow ftpd_t bin_t:dir { getattr search };
    allow ftpd_t bin_t:lnk_file { getattr read };
    allow ftpd_t shell_exec_t:file { { getattr read execute ioctl } ioctl lock execute_no_trans };
##### end corecmd_exec_shell(ftpd_t)

##### begin files_read_usr_files(ftpd_t)
    require {
        type usr_t;
    } # end require
    allow ftpd_t usr_t:dir { getattr search read lock ioctl };
    allow ftpd_t usr_t:dir { getattr search };
    allow ftpd_t usr_t:file { getattr read lock ioctl };
    allow ftpd_t usr_t:dir { getattr search };
    allow ftpd_t usr_t:lnk_file { getattr read };
##### end files_read_usr_files(ftpd_t)

##### begin cron_system_entry(ftpd_t,ftpd_exec_t)
    require {
        type crond_t, system_crond_t;
    } # end require
    allow system_crond_t ftpd_exec_t:file { getattr read execute };
    allow system_crond_t ftpd_t:process transition;
    dontaudit system_crond_t ftpd_t:process { noatsecure siginh rlimitinh };
    type_transition system_crond_t ftpd_exec_t:process ftpd_t;
    # cjp: perhaps these four rules from the old
    # domain_auto_trans are not needed?
    allow ftpd_t system_crond_t:fd use;
    allow ftpd_t system_crond_t:fifo_file { getattr read write append ioctl lock };
    allow ftpd_t system_crond_t:process sigchld;
    allow ftpd_t crond_t:fifo_file { getattr read write append ioctl lock };
    allow ftpd_t crond_t:fd use;
    allow ftpd_t crond_t:process sigchld;
    role system_r types ftpd_t;
##### end cron_system_entry(ftpd_t,ftpd_exec_t)

##### Start optional_policy - Level 2 ##########
    optional {
##### begin logrotate_exec(ftpd_t)
        require {
            type logrotate_exec_t;
        } # end require
        allow ftpd_t logrotate_exec_t:file { { getattr read execute ioctl } ioctl lock execute_no_trans };
##### end logrotate_exec(ftpd_t)
    } # end optional 2nd level

} # end optional 1st level

gen_tunable Macro

This macro defines booleans that are global in scope. The corresponding tunable_policy macro contains the supporting statements allowed or not depending on the value of the boolean. These entries are extracted as a part of the build process (by the make conf target) and added to the global_tunables file where they can then be used to alter the default values for the make load or make install targets.

Note that the comments shown in the example MUST be present as they are used to describe the function and are extracted for the documentation.

The macro definition is:

gen_tunable(boolean_name,boolean_value)

Where:

gen_tunable The gen_tunable macro keyword.
boolean_name The boolean identifier.
boolean_value The boolean value that can be either true or false.


The macro is valid in:

Private Policy File (.te)
External Interface File (.if)
File Labeling Policy File (.fc)
Yes
Yes
No


Example Macro:

# This example is from the modules/services/ftp.te module:
#

## <desc>
## <p>
## Allow ftp servers to use nfs
## for public file transfer services.
## </p>
## </desc>
gen_tunable(allow_ftpd_use_nfs, false)

Expanded Macro:

# This is the expanded macro from the tmp/ftp.tmp file:
#
bool allow_ftpd_use_nfs false;

tunable_policy Macro

This macro contains the statements allowed or not depending on the value of the boolean defined by the gen_tunable macro.

The macro definition is:

tunable_policy(`gen_tunable_id',`tunable_policy_rules`)

Where:

tunable_policy The tunable_policy macro keyword.
gen_tunable_id This is the boolean identifier defined by the gen_tunable macro. It is possible to have multiple entries separated by && or as shown in the example.
tunable_policy_rules These are the policy rules and statements as defined in the if statement policy language section.


The macro is valid in:

Private Policy File (.te)
External Interface File (.if)
File Labeling Policy File (.fc)
Yes
Yes
No


Example Macro:

# This example is from the modules/services/ftp.te module
# showing the use of the boolean with the && operator.
#
tunable_policy(`allow_ftpd_use_nfs && allow_ftpd_anon_write',`
    fs_manage_nfs_files(ftpd_t)
')

Expanded Macro:

# This is the expanded macro from the tmp/ftp.tmp file.
#
if (allow_ftpd_use_nfs && allow_ftpd_anon_write) {

##### begin fs_manage_nfs_files(ftpd_t)
    require {
        type nfs_t;
    } # end require

    allow ftpd_t nfs_t:dir { read getattr lock search ioctl add_name remove_name write };
    allow ftpd_t nfs_t:file { create open getattr setattr read write append rename link unlink ioctl lock };
##### end fs_manage_nfs_files(ftpd_t)

} # end if

interface Macro

Access interface macros are defined in the interface module file (.if) and form the interface through which other modules can call on the modules services (as described in the Module Expansion section.

The macro definition is:

interface(`name`,`interface_rules`)

Where:

interface The interface macro keyword.
name The interface identifier that should be named to reflect the module identifier and its purpose.
interface_rules This can consist of the support macros, policy language statements or other interface calls as required to provide the service.


The macro is valid in:

Private Policy File (.te)
External Interface File (.if)
File Labeling Policy File (.fc)
No
Yes
No


Example Interface Definition:

Note that the comments shown in the example MUST be present as they are used to describe the function and are extracted for the documentation.

# This example is from the modules/services/ftp.if module
# showing the 'ftp_read_config' interface.
#

########################################
## <summary>
## Read ftpd etc files
## </summary>
## <param name="domain">
##<summary>
## Domain allowed access.
##</summary>
## </param>
#
interface(`ftp_read_config',`
    gen_require(`
        type ftpd_etc_t;
    ')

    files_search_etc($1)
    allow $1 ftpd_etc_t:file { getattr read };
')

Expanded Macro: (taken from the base.conf file):

# Access Interfaces are only expanded at policy compile time 
# if they are called by a module that requires their services.
#
# In this example the ftp_read_config interface is called from
# the init.te module via the optional_policy macro as shown
# below with the expanded code shown afterwards.
#
######## From ./policy/policy/modules/system/init.te ########
#
# optional_policy(`
#     ftp_read_config(initrc_t)
# ')
#
#
############# Expanded policy statements taken ##############
############# from the base.conf file that ##################
############# forms the base policy. ########################
#
optional { # Start optional_policy segment for ftp interface
    #
    # This is the resulting output contained the base.conf file
    # where init calls the ftp_read_config ($1) interface from
    # init.te with the parameter initrc_t:
    #
    require {
        type ftpd_etc_t;
    } 

    #
    # Call the files_search_etc ($1) interface contained in the 
    # ftp.if file with the parameter initrc_t:
    #
    require {
        type etc_t;
    } 
    allow initrc_t etc_t:dir { getattr search };
    #
    # end files_search_etc(initrc_t)
    #
    # This is the allow $1 ftpd_etc_t:file { getattr read };
    # statement with the initrc_t parameter resolved: 
    #
    allow initrc_t ftpd_etc_t:file { getattr read };
    #
    # end ftp_read_config(initrc_t)
} # End optional_policy segment for this ftp interface

template Macro

A template interface is used to help create a domain and set up the appropriate rules and statements to run an application / process. The basic idea is to set up an application in a domain that is suitable for the defined SELinux user and role to access but not others. Should a different user / role need to access the same application, another domain would be allocated (these are known as 'derived domains' as the domain name is derived from caller information).

The application template shown in the example below is for openoffice.org where the domain being set up to run the application is based on the SELinux user xguest (parameter $1) therefore a domain type is initialised called xguest_openoffice_t, this is then added to the user domain attribute xguest_usertype (parameter $2). Finally the role xguest_r (parameter $3) is allowed access to the domain type xguest_openoffice_t. If a different user / role required access to openoffice.org, then by passing different parameters (i.e. user_u), a different domain would be set up.

The main differences between an application interface and a template interface are:

  • An access interface is called by other modules to perform a service.
  • A template interface allows an application to be run in a domain based on user / role information to isolate different instances.

Note that the comments shown in the example MUST be present as they are used to describe the function and are extracted for the documentation.

The macro definition is:

template(`name`,`template_rules`)

Where:

template The template macro keyword.
name The template identifier that should be named to reflect the module identifier and its purpose. By convention the last component is _template (e.g. ftp_per_role_template).
template_rules This can consist of the support macros, policy language statements or interface calls as required to provide the service.



The macro is valid in:

Private Policy File (.te)
External Interface File (.if)
File Labeling Policy File (.fc)
No
Yes
No


Example Macro:

# This example is from the modules/apps/openoffice.if module
# showing the 'openoffice_per_role_template' template interface.
#
#######################################
## <summary>
##The per role template for the openoffice module.
## </summary>
## <desc>
##<p>
##This template creates a derived domains which are used
##for openoffice applications.
##</p>
## </desc>
## <param name="userdomain_prefix">
##<summary>
##The prefix of the user domain (e.g., user
##is the prefix for user_t).
##</summary>
## </param>
## <param name="user_domain">
##<summary>
##The type of the user domain.
##</summary>
## </param>
## <param name="user_role">
##<summary>
##The role associated with the user domain.
##</summary>
## </param>
#
template(`openoffice_per_role_template',`
    gen_require(`
        type openoffice_exec_t;
    ')

    type $1_openoffice_t;
    domain_type($1_openoffice_t)
    domain_entry_file($1_openoffice_t, openoffice_exec_t)
    role $3 types $1_openoffice_t;

    domain_interactive_fd($1_openoffice_t)

    userdom_unpriv_usertype($1, $1_openoffice_t)
    userdom_exec_user_home_content_files($1, $1_openoffice_t)

    allow $1_openoffice_t self:process { getsched sigkill execheap execmem execstack };

    allow $2 $1_openoffice_t:process { getattr ptrace signal_perms noatsecure siginh rlimitinh };
    allow $1_openoffice_t $2:tcp_socket { read write };

    domtrans_pattern($2, openoffice_exec_t, $1_openoffice_t)

    dev_read_urand($1_openoffice_t)
    dev_read_rand($1_openoffice_t)

    fs_dontaudit_rw_tmpfs_files($1_openoffice_t)

    allow $2 $1_openoffice_t:process { signal sigkill };
    allow $1_openoffice_t $2:unix_stream_socket connectto;

')

Expanded Macro:

# Template Interfaces are only expanded at policy compile time 
# if they are called by a module that requires their services.
# This has been expanded as a part of the roles/xguest.te
# module and extracted from tmp/xguest.tmp.
#
################# '''START Expanded code segment''' ###########
#
optional {
    ##### begin openoffice_per_role_template(xguest,xguest_usertype,xguest_r)
    require {
        type openoffice_exec_t;
    } # end require
    type xguest_openoffice_t; # Paremeter $1

    ......
    # This is a long set of rules, therefore has been cut down.
    ......
    ....
    typeattribute xguest_openoffice_t xguest_usertype; # Paremeter $2
    ..
    type_transition xguest_usertype openoffice_exec_t:process xguest_openoffice_t; 
    ..
    role xguest_r types xguest_openoffice_t; # Paremeter $3
    ....
    allow xguest_usertype xguest_openoffice_t:process { signal sigkill };
    allow xguest_openoffice_t xguest_usertype:unix_stream_socket connectto;
    ##### end openoffice_per_role_template(xguest,xguest_usertype,xguest_r)
} # end optional

Miscellaneous Macros

These macros are in the misc_macros.spt file.

gen_context Macro

This macro is used to generate a valid security context and can be used in any of the module files. Its most general use is in the .fc file where it is used to set the files security context.

The macro definition is:

gen_context(context[,mls | mcs]) 

Where:

gen_context The gen_context macro keyword.
context The security context to be generated. This can include macros that are relevant to a context as shown in the example below.
mcs MLS or MCS labels if enabled in the policy.


The macro is valid in:

Private Policy File (.te)
External Interface File (.if)
File Labeling Policy File (.fc)
Yes
Yes
Yes


Example Macro:

# This example shows gen_context being used to generate a
# security context for the security initial sid in the 
# selinux.te module:

sid security gen_context(system_u:object_r:security_t:mls_systemhigh)

Expanded Macro:

# This is the expanded entry built into the base.conf source
# file for an MLS policy:

sid security system_u:object_r:security_t:s15:c0.c255 

Example File Context .fc file:

# This is from the modules/apps/gnome.fc file. Note that the
# HOME_DIR and USER parameters will be entered during
# the contexts/file_contexts.homedirs file.
#

HOME_DIR/.gnome2(/.*)?gen_context(system_u:object_r:gnome_home_t,s0)
HOME_DIR/\.config/gtk-.*gen_context(system_u:object_r:gnome_home_t,s0)
HOME_DIR/\.gconf(d)?(/.*)?gen_context(system_u:object_r:gconf_home_t,s0)
HOME_DIR/\.local.*gen_context(system_u:object_r:gconf_home_t,s0)

/tmp/gconfd-USER/.*--gen_context(system_u:object_r:gconf_tmp_t,s0)

HOME_DIR/.pulse(/.*)?gen_context(system_u:object_r:gnome_home_t,s0)

Expanded File Context .fc file:

# The resulting expanded tmp/gnome.mod.fc file. This will be
# concatenated with the main file_contexts file during the
# policy build process.
#

HOME_DIR/.gnome2(/.*)?system_u:object_r:gnome_home_t:s0
HOME_DIR/\.config/gtk-.*system_u:object_r:gnome_home_t:s0
HOME_DIR/\.gconf(d)?(/.*)?system_u:object_r:gconf_home_t:s0
HOME_DIR/\.local.*system_u:object_r:gconf_home_t:s0

/tmp/gconfd-USER/.*--system_u:object_r:gconf_tmp_t:s0

HOME_DIR/.pulse(/.*)?system_u:object_r:gnome_home_t:s0

gen_user Macro

This macro is used to generate a valid user statement and add an entry in the users_extra configuration file if it exists.

The macro definition is:

gen_user(username, prefix, role_set, mls_defaultlevel, mls_range, [mcs_categories])

Where:

gen_user The gen_user macro keyword.
username The SELinux user id.
prefix SELinux users without the prefix will not be in the users_extra file. This is added to user directories by the genhomedircon as discussed in the modules/active/file_contexts.template file section.
role_set The user roles.
mls_defaultlevel The default level if MLS / MCS policy.
mls_range The range if MLS / MCS policy.
mcs_categories The categories if MLS / MCS policy.


The macro is valid in:

Private Policy File (.te)
External Interface File (.if)
File Labeling Policy File (.fc)
Yes
No
No


Example Macro:

# This example has been taken from the policy/policy/users file:
#

gen_user(root, user, unconfined_r sysadm_r staff_r ifdef(`enable_mls',`secadm_r auditadm_r') system_r, s0, s0 - mls_systemhigh, mcs_allcats) 

Expanded Macro:

# The expanded gen_user macro from the base.conf for an MLS
# build. Note that the prefix is not present. This is added to
# the users_extra file as shown below.
#
user root roles { unconfined_r sysadm_r staff_r secadm_r auditadm_r system_r } level s0 range s0 - s15:c0.c1023; 

# users_extra file entry:
#
user root prefix user; 

gen_bool Macro

This macro defines a boolean and requires the following steps:

  1. Declare the boolean in the global_booleans file.
  2. Use the boolean in the module files with an if / else statement as shown in the example.

Note that the comments shown in the example MUST be present as they are used to describe the function and are extracted for the documentation.

The macro definition is:

gen_bool(name,default_value) 

Where:

gen_bool The gen_bool macro keyword.
name The boolean identifier.
default_value The value true or false.


The macro is only valid in theglobal_booleansfile but the boolean declared can be used in the following module types:

Private Policy File (.te)
External Interface File (.if)
File Labeling Policy File (.fc)
Yes
Yes
No


Example Macro (in global_booleans):

# This example is from the global_booleans file where the bool
# is declared. The comments must be present as it is used to
# generate the documentation.
#

## <desc>
## <p>
## Disable transitions to insmod.
## </p>
## </desc>
gen_bool(secure_mode_insmod,false)
# Example usage from the system/modutils.te module:
#
if( ! secure_mode_insmod ) {
    kernel_domtrans_to(insmod_t,insmod_exec_t)
}

Expanded Macro:

# This has been taken from the base.conf source file after
# expansion by the build process of the modutils.te module.
#

if( ! secure_mode_insmod ) {
    ##### begin kernel_domtrans_to(insmod_t,insmod_exec_t)
    allow kernel_t insmod_exec_t:file { getattr read execute };
    allow kernel_t insmod_t:process transition;
    dontaudit kernel_t insmod_t:process { noatsecure siginh rlimitinh };
    type_transition kernel_t insmod_exec_t:process insmod_t;
    allow insmod_t kernel_t:fd use;
    allow insmod_t kernel_t:fifo_file { getattr read write append ioctl lock };
    allow insmod_t kernel_t:process sigchld;
    ##### end kernel_domtrans_to(insmod_t,insmod_exec_t)
}

MLS and MCS Macros

These macros are in the mls_mcs_macros.spt file.

gen_cats Macro

This macro will generate a category statement for each category defined. These are then used in the base.conf / policy.conf source file and also inserted into each module by the policy_module Macro. The policy/policy/mcs and mls configuration files are the only files that contain this macro in the current reference policy.

The macro definition is:

gen_cats(mcs_num_cats | mls_num_cats)

Where:

gen_cats The gen_cats macro keyword.
mcs_num_cats

mls_num_cats

These are the maximum number of categories that have been extracted from the build.conf file MCS_CATS or MLS_CATS entries and set as m4 parameters.


The macro is valid in:

Private Policy File (.te)
External Interface File (.if)
File Labeling Policy File (.fc)
na
na
na


Example Macro:

# This example is from the policy/policy/mls configuration file.
#

gen_cats(mls_num_cats)

Expanded Macro:

# This example has been extracted from the base.conf source file.

category c0;
category c1;
...
category c1023;

gen_sens Macro

This macro will generate a sensitivity statement for each sensitivity defined. These are then used in the base.conf / policy.conf source file and also inserted into each module by the policy_module Macro. The policy/policy/mcs and mls configuration files are the only files that contain this macro in the current reference policy (note that the mcs file has gen_sens(1) as only one sensitivity is required).

The macro definition is:

gen_sens(mls_num_sens)

Where:

gen_sens The gen_sens macro keyword.
mls_num_sens These are the maximum number of sensitivities that have been extracted from the build.conf file MLS_SENS entries and set as an m4 parameter.


The macro is valid in:

Private Policy File (.te)
External Interface File (.if)
File Labeling Policy File (.fc)
na
na
na


Example Macro:

# This example is from the policy/policy/mls configuration file.
#

gen_cats(mls_num_sens)

Expanded Macro:

# This example has been extracted from the base.conf source file.

sensitivity s0;
sensitivity s1;
...
sensitivity s15;

gen_levels Macro

This macro will generate a level statement for each level defined. These are then used in the base.conf / policy.conf source file. The policy/policy/mcs and mls configuration files are the only files that contain this macro in the current reference policy.

The macro definition is:

gen_levels(mls_num_sens,mls_num_cats)

Where:

gen_levels The gen_levels macro keyword.
mls_num_sens This is the parameter that defines the number of sensitivities to generate. The MCS policy is set to '1'.
mls_num_cats

mcs_num_cats

This is the parameter that defines the number of categories to generate.


The macro is valid in:

Private Policy File (.te)
External Interface File (.if)
File Labeling Policy File (.fc)
na
na
na


Example Macro:

# This example is from the policy/policy/mls configuration file.
#
gen_levels(mls_num_sens,mls_num_cats)

Expanded Macro:

# This example has been extracted from the base.conf source
# file. Note that the all categories are allocated to each
# sensitivity.

level s0:c0.c1023; 
level s1:c0.c1023; 
...
level s15:c0.c1023; 

System High/Low Parameters

These macros define system high etc. as shown.

mls_systemlow
# gives:
s0

mls_systemhigh
# gives:
s15:c0.c1023 

mcs_systemlow
# gives:
s0

mcs_systemhigh
# gives:
s0:c0.c1023

mcs_allcats
# gives:
c0.c1023

ifdef / ifndef Parameters

This section contains examples of the common ifdef / ifndef parameters that can be used in module source files.

hide_broken_symptoms

This is used within modules as shown in the example. The parameter is set up by the Makefile at the start of the build process.

Example Macro:

# This example is from the modules/kernel/domain.te module.
#
ifdef(`hide_broken_symptoms',`
    cron_dontaudit_rw_tcp_sockets(domain)
    allow domain domain:key { link search };
')

enable_mls and enable_mcs

These are used within modules as shown in the example. The parameters are set up by the Makefile with information taken from the build.conf file at the start of the build process.

Example Macros:

# This example is from the modules/kernel/kernel.te module.
#
ifdef(`enable_mls',`
    role secadm_r;
    role auditadm_r;
')
# This example is from the modules/kernel/kernel.if module.
#
ifdef(`enable_mcs',`
    range_transition kernel_t $2:process $3;
')

ifdef(`enable_mls',`
    range_transition kernel_t $2:process $3;
    mls_rangetrans_target($1)
')

enable_ubac

This is used within the ./policy/constraints configuration file to set up various attributes to support user based access control (UBAC). These attributes are then used within the various modules that want to support UBAC. This support was added in version 2 of the Reference Policy.

The parameter is set up by the Makefile with information taken from the build.conf file at the start of the build process (ubac = y | ubac = n).

Example Macro:

# This example is from the ./policy/constraints file.
# Note that the ubac_constrained_type attribute is defined in
# modules/kernel/ubac.te module.

define(`basic_ubac_conditions',`
    ifdef(`enable_ubac',`
        u1 == u2
        or u1 == system_u
        or u2 == system_u
        or t1 != ubac_constrained_type
        or t2 != ubac_constrained_type
    ')
')

direct_sysadm_daemon

This is used within modules as shown in the example. The parameter is set up by the Makefile with information taken from the build.conf file at the start of the build process (if DIRECT_INITRC = y).

Example Macros:

# This example is from the modules/system/selinuxutil.te module.
#
ifndef(`direct_sysadm_daemon',`
    ifdef(`distro_gentoo',`
    # Gentoo integrated run_init:
        init_script_file_entry_type(run_init_t)
    ')
')
# This example is from the modules/system/userdomain.te module.
#
ifdef(`direct_sysadm_daemon',`
    domain_system_change_exemption($1_t)
')

Module Expansion Process

The objective of this section is to show how the modules are expanded by the reference policy build process to form files that can then be compiled and then loaded into the policy store by using the make MODULENAME.pp target.

The files shown are those produced by the build process using the ada policy modules from the Reference Policy source tree (ada.te, ada.if and ada.fc) that are shown in the Reference Policy Module Files section.

The initial build process will build the source text files in the policy/tmp directory as ada.tmp and ada.mod.fc (that are basically build equivalent ada.conf and ada.fc formatted files). The basic steps are shown in the The make ada sequence of events diagram, and the resulting expanded code shown in the The expansion process diagram.


Previous
Home
Next



  1. These RPMs can be obtained from http://koji.fedoraproject.org.
  2. These can be installed by system administrators as required. The dynamic loading / unloading of policies as applications are loaded is not yet supported.
  3. The comments are also important as they form part of the documentation when it is generated by the make html target.
  4. These are explained in the Reference Policy Macros section.
  5. The base.conf gets built for modular policies and a policy.conf file gets built for a monolithic policy.