<!-- Common Interface Language (CIL) Reference Guide -->
<!-- container_statements.xml -->
<sect1>
<title>Container Statements</title>
<sect2 id="block">
<title>block</title>
<para>Start a new namespace where any CIL statement is valid.</para>
<para><emphasis role="bold">Statement definition:</emphasis></para>
<programlisting><![CDATA[
(block block_id
cil_statement
...
)]]>
</programlisting>
<para><emphasis role="bold">Where:</emphasis></para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colwidth="2 *"/>
<colspec colwidth="6 *"/>
<tbody>
<row>
<entry>
<para><literal>block</literal></para>
</entry>
<entry>
<para>The <literal><link linkend="block">block</link></literal> keyword.</para>
</entry>
</row>
<row>
<entry>
<para><literal>block_id</literal></para>
</entry>
<entry>
<para>The namespace identifier.</para>
</entry>
</row>
<row>
<entry>
<para><literal>cil_statement</literal></para>
</entry>
<entry>
<para>Zero or more valid CIL statements.</para>
</entry>
</row>
</tbody></tgroup>
</informaltable>
<para><emphasis role="bold">Example:</emphasis></para>
<para>See the <literal><link linkend="blockinherit">blockinherit</link></literal> statement for an example.</para>
</sect2>
<sect2 id="blockabstract">
<title>blockabstract</title>
<para>Declares the namespace as a 'template' and does not generate code until instantiated by another namespace that has a <literal><link linkend="blockinherit">blockinherit</link></literal> statement.</para>
<para><emphasis role="bold">Statement definition:</emphasis></para>
<programlisting><![CDATA[
(block block_id
(blockabstract template_id)
cil_statement
...
)]]>
</programlisting>
<para><emphasis role="bold">Where:</emphasis></para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colwidth="2 *"/>
<colspec colwidth="6 *"/>
<tbody>
<row>
<entry>
<para><literal>block</literal></para>
</entry>
<entry>
<para>The <literal><link linkend="block">block</link></literal> keyword.</para>
</entry>
</row>
<row>
<entry>
<para><literal>block_id</literal></para>
</entry>
<entry>
<para>The namespace identifier.</para>
</entry>
</row>
<row>
<entry>
<para><literal>blockabstract</literal></para>
</entry>
<entry>
<para>The <literal><link linkend="blockabstract">blockabstract</link></literal> keyword.</para>
</entry>
</row>
<row>
<entry>
<para><literal>template_id</literal></para>
</entry>
<entry>
<para>The abstract namespace identifier. This must match the <literal><link linkend="block">block_id</link></literal> entry.</para>
</entry>
</row>
<row>
<entry>
<para><literal>cil_statement</literal></para>
</entry>
<entry>
<para>Zero or more valid CIL statements forming the abstract block.</para>
</entry>
</row>
</tbody></tgroup>
</informaltable>
<para><emphasis role="bold">Example:</emphasis></para>
<para>See the <literal><link linkend="blockinherit">blockinherit</link></literal> statement for an example.</para>
</sect2>
<sect2 id="blockinherit">
<title>blockinherit</title>
<para>Used to add common policy rules to the current namespace via a template that has been defined with the <literal><link linkend="blockabstract">blockabstract</link></literal> statement. All <literal><link linkend="blockinherit">blockinherit</link></literal> statements are resolved first and then the contents of the block are copied. This is so that inherited blocks will not be inherited. For a concrete example, please see the examples section.</para>
<para><emphasis role="bold">Statement definition:</emphasis></para>
<programlisting><![CDATA[
(block block_id
(blockinherit template_id)
cil_statement
...
)]]>
</programlisting>
<para><emphasis role="bold">Where:</emphasis></para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colwidth="2 *"/>
<colspec colwidth="6 *"/>
<tbody>
<row>
<entry>
<para><literal>block</literal></para>
</entry>
<entry>
<para>The <literal><link linkend="block">block</link></literal> keyword.</para>
</entry>
</row>
<row>
<entry>
<para><literal>block_id</literal></para>
</entry>
<entry>
<para>The namespace identifier.</para>
</entry>
</row>
<row>
<entry>
<para><literal>blockinherit</literal></para>
</entry>
<entry>
<para>The <literal><link linkend="blockinherit">blockinherit</link></literal> keyword.</para>
</entry>
</row>
<row>
<entry>
<para><literal>template_id</literal></para>
</entry>
<entry>
<para>The inherited namespace identifier.</para>
</entry>
</row>
<row>
<entry>
<para><literal>cil_statement</literal></para>
</entry>
<entry>
<para>Zero or more valid CIL statements.</para>
</entry>
</row>
</tbody></tgroup>
</informaltable>
<para><emphasis role="bold">Example:</emphasis></para>
<para>This example contains a template <literal>client_server</literal> that is instantiated in two blocks (<literal>netserver_app</literal> and <literal>netclient_app</literal>):</para>
<programlisting><![CDATA[
; This is the template block:
(block client_server
(blockabstract client_server)
; Log file labeling
(type log_file)
(typeattributeset file_type (log_file))
(typeattributeset data_file_type (log_file))
(allow process log_file (dir (write search create setattr add_name)))
(allow process log_file (file (create open append getattr setattr)))
(roletype object_r log_file)
(context log_file_context (u object_r log_file low_low))
; Process labeling
(type process)
(typeattributeset domain (process))
(call app_domain (process))
(call net_domain (process))
)
; This is a policy block that will inherit the abstract block above:
(block netclient_app
; Add common policy rules to namespace:
(blockinherit client_server)
; Label the log files
(filecon "/data/data/com.se4android.netclient/.*" file log_file_context)
)
; This is another policy block that will inherit the abstract block above:
(block netserver_app
; Add common policy rules to namespace:
(blockinherit client_server)
; Label the log files
(filecon "/data/data/com.se4android.netserver/.*" file log_file_context)
)
; This is an example of how blockinherits resolve inherits before copying
(block a
(type one))
(block b
; Notice that block a is declared here as well
(block a
(type two)))
; This will first copy the contents of block b, which results in type b.a.two being copied.
; Next, the contents of block a will be copied which will result in type a.one.
(block ab
(blockinherit b)
(blockinherit a))]]>
</programlisting>
</sect2>
<sect2 id="optional">
<title>optional</title>
<para>Declare an <literal><link linkend="optional">optional</link></literal> namespace. All CIL statements in the optional block must be satisfied before instantiation in the binary policy. <literal><link linkend="tunableif">tunableif</link></literal> and <literal><link linkend="macro">macro</link></literal> statements are not allowed in optional containers. The same restrictions apply to CIL policy statements within <literal><link linkend="optional">optional</link></literal>'s that apply to kernel policy statements, i.e. only the policy statements shown in the following table are valid:</para>
<informaltable frame="all">
<tgroup cols="4">
<tbody>
<row>
<entry>
<para><literal><link linkend="allow">allow</link></literal></para>
</entry>
<entry>
<para><literal><link linkend="auditallow">auditallow</link></literal></para>
</entry>
<entry>
<para><literal><link linkend="booleanif">booleanif</link></literal></para>
</entry>
<entry>
<para><literal><link linkend="dontaudit">dontaudit</link></literal></para>
</entry>
</row>
<row>
<entry>
<para><literal><link linkend="typepermissive">typepermissive</link></literal></para>
</entry>
<entry>
<para><literal><link linkend="rangetransition">rangetransition</link></literal></para>
</entry>
<entry>
<para><literal><link linkend="role">role</link></literal></para>
</entry>
<entry>
<para><literal><link linkend="roleallow">roleallow</link></literal></para>
</entry>
</row>
<row>
<entry>
<para><literal><link linkend="roleattribute">roleattribute</link></literal></para>
</entry>
<entry>
<para><literal><link linkend="roletransition">roletransition</link></literal></para>
</entry>
<entry>
<para><literal><link linkend="type">type</link></literal></para>
</entry>
<entry>
<para><literal><link linkend="typealias">typealias</link></literal></para>
</entry>
</row>
<row>
<entry>
<para><literal><link linkend="typeattribute">typeattribute</link></literal></para>
</entry>
<entry>
<para><literal><link linkend="typechange">typechange</link></literal></para>
</entry>
<entry>
<para><literal><link linkend="typemember">typemember</link></literal></para>
</entry>
<entry>
<para><literal><link linkend="typetransition">typetransition</link></literal></para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para><emphasis role="bold">Statement definition:</emphasis></para>
<programlisting><![CDATA[
(optional optional_id
cil_statement
...
)]]>
</programlisting>
<para><emphasis role="bold">Where:</emphasis></para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colwidth="2 *"/>
<colspec colwidth="6 *"/>
<tbody>
<row>
<entry>
<para><literal>optional</literal></para>
</entry>
<entry>
<para>The <literal><link linkend="optional">optional</link></literal> keyword.</para>
</entry>
</row>
<row>
<entry>
<para><literal>optional_id</literal></para>
</entry>
<entry>
<para>The <literal><link linkend="optional">optional</link></literal> namespace identifier.</para>
</entry>
</row>
<row>
<entry>
<para><literal>cil_statement</literal></para>
</entry>
<entry>
<para>Zero or more valid CIL statements.</para>
</entry>
</row>
</tbody></tgroup>
</informaltable>
<para><emphasis role="bold">Example:</emphasis></para>
<para>This example will instantiate the optional block <literal>ext_gateway.move_file</literal> into policy providing all optional CIL statements can be resolved:</para>
<programlisting><![CDATA[
(block ext_gateway
......
(optional move_file
(typetransition process msg_filter.move_file.in_queue file msg_filter.move_file.in_file)
(allow process msg_filter.move_file.in_queue (dir (read getattr write search add_name)))
(allow process msg_filter.move_file.in_file (file (write create getattr)))
(allow msg_filter.move_file.in_file unconfined.object (filesystem (associate)))
(typetransition msg_filter.int_gateway.process msg_filter.move_file.out_queue file
msg_filter.move_file.out_file)
(allow msg_filter.int_gateway.process msg_filter.move_file.out_queue (dir (read write search)))
(allow msg_filter.int_gateway.process msg_filter.move_file.out_file (file (read getattr unlink)))
) ; End optional block
.....
) ; End block]]>
</programlisting>
</sect2>
<sect2 id="in">
<title>in</title>
<para>Allows the insertion of CIL statements into a named container (<literal><link linkend="block">block</link></literal>, <literal><link linkend="optional">optional</link></literal> or <literal><link linkend="macro">macro</link></literal>). This statement is not allowed in <literal><link linkend="booleanif">booleanif</link></literal> or <literal><link linkend="tunableif">tunableif</link></literal> statements.</para>
<para><emphasis role="bold">Statement definition:</emphasis></para>
<programlisting><![CDATA[
(in container_id
cil_statement
...
)]]>
</programlisting>
<para><emphasis role="bold">Where:</emphasis></para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colwidth="2 *"/>
<colspec colwidth="6 *"/>
<tbody>
<row>
<entry>
<para><literal>in</literal></para>
</entry>
<entry>
<para>The <literal>in</literal> keyword.</para>
</entry>
</row>
<row>
<entry>
<para><literal>container_id</literal></para>
</entry>
<entry>
<para>A valid <literal><link linkend="block">block</link></literal>, <literal><link linkend="optional">optional</link></literal> or <literal><link linkend="macro">macro</link></literal> namespace identifier.</para>
</entry>
</row>
<row>
<entry>
<para><literal>cil_statement</literal></para>
</entry>
<entry>
<para>Zero or more valid CIL statements.</para>
</entry>
</row>
</tbody></tgroup>
</informaltable>
<para><emphasis role="bold">Example:</emphasis></para>
<para>This will add rules to the container named <literal>system_server</literal>:</para>
<programlisting><![CDATA[
(in system_server
(dontaudit process secmark_demo.dns_packet (packet (send recv)))
(allow process secmark_demo.dns_packet (packet (send recv)))
)]]>
</programlisting>
</sect2>
</sect1>