Chris PeBenito 3d76be

Getting Started

Chris PeBenito 3d76be

Chris PeBenito 3d76be
This guide will walk you through the basics of creating a new reference policy module. This will also serve as an introduction to the basics concepts and philosophy of refpolicy.
Chris PeBenito 7c347c
To install and use a targeted Reference Policy on a Fedora Core 4 system, see the
Chris PeBenito 7c347c
switching guide.
Chris PeBenito 3d76be

Chris PeBenito 3d76be

Creating A Module

Chris PeBenito 3d76be

Chris PeBenito 3d76be
Modules are the principal organizing component in refpolicy. They are conceptually similar to the source modules in the current strict and targeted policy, but have additional meaning. A module contains the policy for an application or related group of applications, private and shared resources, labeling information, and interfaces that allow other modules access to the modules resources. The majority of the global policy has been eliminated in refpolicy. Certain policy components, like users and object classes, are still global in refpolicy, but almost all TE policy is now contained within a module. 
Chris PeBenito 3d76be

Chris PeBenito 3d76be

Chris PeBenito bd113c
Modules should be placed in refpolicy/policy/LAYER, where LAYER is the name of the appropriate layer. The current layers can be seen in the interface documentation. Let's create a new module in the services layer called myapp. This is done by creating three files: myapp.te, mayapp.fc, and myapp.if, all in directory refpolicy/policy/services. The file myapp.te file will contain all of the policy private to this module, including any types or attributes. The file myapp.fc file will contain the file context labeling statement for this module. Finally, the file myapp.if will contain the interfaces for this module (interfaces will be explained below).
Chris PeBenito 3d76be

Chris PeBenito 3d76be

Module TE Policy

Chris PeBenito 3d76be

Karl MacMillan 5ba9f0
First create myapp.te and add the following:
Chris PeBenito 3d76be
Chris PeBenito 3d76be
Chris PeBenito 3d76be
# Private type declarations
Chris PeBenito 3d76be
type myapp_t;
Chris PeBenito 3d76be
type myapp_exec_t;
Chris PeBenito 3d76be
type myapp_log_t;
Chris PeBenito 3d76be
type myapp_tmp_t;
Chris PeBenito 3d76be
Chris PeBenito 3d76be
domain_type(myapp_t)
Chris PeBenito 3d76be
domain_entry_file(myapp_t, myapp_exec_t)
Chris PeBenito 3d76be
logging_log_file(myapp_log_t)
Chris PeBenito 3d76be
files_tmp_file(myapp_tmp_t)
Chris PeBenito 3d76be
Chris PeBenito 3d76be
Chris PeBenito 3d76be

Chris PeBenito 3d76be

Chris PeBenito 5fa782
This creates all of the types needed for this module, including a type for the process, executables, log files, and temporary files. The first thing to notice is that there are no attributes applied to any of these types. In refpolicy all types and attributes can only be referred to in the module that declares them. This means that it is not possible, for example, to directly refer to the domain attribute. Instead, macros in other modules are used to declare that a type will be used for a certain purpose. These macros will likely use attributes (but not necessarily), but it allows the module that declared the attribute to strictly control how it can be used. In this example interfaces are used to transform the types into a domain, entry file, log file, and temporary file.
Chris PeBenito 3d76be

Chris PeBenito 3d76be

Chris PeBenito 3d76be
Let's expand this example further by allowing some access for these types. My application needs access between it's own types and access to read random numbers. The access between private types is written exactly the same way current policy rules are written, i.e.:
Chris PeBenito 3d76be
Chris PeBenito 3d76be
Chris PeBenito 347f40
allow myapp_t myapp_log_t:file ra_file_perms;
Chris PeBenito 347f40
allow myapp_t myapp_tmp_t:file create_file_perms;
Chris PeBenito 3d76be
Chris PeBenito 3d76be
Karl MacMillan 5ba9f0

This allows myapp_t to write to it's private types, but it needs to be able to

Karl MacMillan 5ba9f0
create its temporary files in /tmp.  This requires a call to the files module.

Chris PeBenito 347f40
Chris PeBenito 347f40
Chris PeBenito 347f40
files_create_tmp_files(myapp_t,myapp_tmp_t,file)
Chris PeBenito 347f40
Chris PeBenito 347f40
Karl MacMillan 5ba9f0

Chris PeBenito 347f40
This call to the files module allows myapp_t to create myapp_tmp_t files in
Chris PeBenito 347f40
the /tmp directory.
Chris PeBenito 347f40

Chris PeBenito 347f40

Module IF Policy

Chris PeBenito 347f40

Chris PeBenito 16e8e2
The interface file creates the macros that other modules will use to gain access
Chris PeBenito 16e8e2
to my resources. This allows the module that created the type or attribute to
Chris PeBenito 16e8e2
define appropriate uses. Additionally, it provides a single point for
Chris PeBenito 16e8e2
documentation. Create myapp.if and add the following:
Chris PeBenito 347f40
Chris PeBenito 347f40
Chris PeBenito 347f40
## <summary>Myapp example policy</summary>
Chris PeBenito 16e8e2
## <desc>
Chris PeBenito 16e8e2
##	<p>
Chris PeBenito 16e8e2
##		More descriptive text about myapp.  The <desc>
Chris PeBenito 16e8e2
##		tag can also use <p>, <ul>, and <ol>
Chris PeBenito 16e8e2
##		html tags for formatting.
Chris PeBenito 16e8e2
##	</p>
Chris PeBenito 16e8e2
##	<p>
Chris PeBenito 16e8e2
##		This policy supports the following myapp features:
Chris PeBenito 16e8e2
##		<ul>
Chris PeBenito 16e8e2
##		<li>Feature A</li>
Chris PeBenito 16e8e2
##		<li>Feature B</li>
Chris PeBenito 16e8e2
##		<li>Feature C</li>
Chris PeBenito 16e8e2
##		</ul>
Chris PeBenito 16e8e2
##	</p>
Chris PeBenito 16e8e2
## </desc>
Chris PeBenito 347f40
Chris PeBenito 347f40
## <summary>
Chris PeBenito 347f40
##	Execute a domain transition to run myapp.
Chris PeBenito 347f40
## </summary>
Chris PeBenito 16e8e2
## <param name="domain">
Chris PeBenito 347f40
##	Domain allowed to transition.
Chris PeBenito 16e8e2
## </param>
Chris PeBenito 16e8e2
interface(`myapp_domtrans',`
Chris PeBenito 347f40
	gen_requires(`
Chris PeBenito 347f40
		type myapp_t, myapp_exec_t;
Chris PeBenito 347f40
	')
Chris PeBenito 347f40
Chris PeBenito 347f40
	domain_auto_trans($1,myapp_exec_t,myapp_t)
Chris PeBenito 347f40
Chris PeBenito 347f40
	allow $1 myapp_t:fd use;
Chris PeBenito 347f40
	allow myapp_t $1:fd use;
Chris PeBenito 347f40
	allow $1 myapp_t:fifo_file rw_file_perms;
Chris PeBenito 347f40
	allow $1 myapp_t:process sigchld;
Chris PeBenito 347f40
')
Chris PeBenito 347f40
Chris PeBenito 347f40
## <summary>
Chris PeBenito 347f40
##	Read myapp log files.
Chris PeBenito 347f40
## </summary>
Chris PeBenito 16e8e2
## <param name="domain">
Chris PeBenito 347f40
##	Domain allowed to read the log files.
Chris PeBenito 16e8e2
## </param>
Chris PeBenito 16e8e2
interface(`myapp_read_log',`
Chris PeBenito 347f40
	gen_requires(`
Chris PeBenito 347f40
		type myapp_log_t;
Chris PeBenito 347f40
	')
Chris PeBenito 347f40
Chris PeBenito 347f40
	logging_search_logs($1)
Chris PeBenito 347f40
	allow $1 myapp_log_t:file r_file_perms;
Chris PeBenito 347f40
')
Chris PeBenito 347f40
Chris PeBenito 347f40
Karl MacMillan 5ba9f0

Chris PeBenito 347f40
The first interface allows other domains to do a domain
Chris PeBenito 347f40
transition to myapp_t, by executing a program labeled myapp_exec_t.
Chris PeBenito 347f40

Chris PeBenito 347f40

Chris PeBenito 347f40
The second interface allows other domains to read myapp's log files.  Myapp's
Chris PeBenito 347f40
log files are in the /var/log directory, so the access to search the /var/log
Chris PeBenito 347f40
directory is also given by the interface.  The gen_requires() macro is used to
Chris PeBenito 1d85c7
support loadable policy modules, and must explicitly list the type and attributes
Chris PeBenito 1d85c7
used by this interface.  If object classes of a userland object manager are used,
Chris PeBenito 1d85c7
the class and the permissions used by the interface must also be listed.
Chris PeBenito 347f40