Merge commit '9d8090cec4f0e484132a11e83ce99f44b9117336' into HEAD
diff --git a/src/compatibility/android-cts-manual.pdf b/src/compatibility/android-cts-manual.pdf
index ac6a125..d551495 100644
--- a/src/compatibility/android-cts-manual.pdf
+++ b/src/compatibility/android-cts-manual.pdf
Binary files differ
diff --git a/src/devices/tech/security/selinux/concepts.jd b/src/devices/tech/security/selinux/concepts.jd
index a0eb2cc..1958474 100644
--- a/src/devices/tech/security/selinux/concepts.jd
+++ b/src/devices/tech/security/selinux/concepts.jd
@@ -110,7 +110,7 @@
<p>The policy rules come in the form: allow <em>domains</em> <em>types</em>:<em>classes</em> <em>permissions</em>;, where:</p>
<ul>
- <li><em>Domain</em> - A label for the process or set of processes.
+ <li><em>Domain</em> - A label for the process or set of processes. Also called a domain type as it is just a type for a process.
<li><em>Type</em> - A label for the object (e.g. file, socket) or set of objects.
<li><em>Class</em> - The kind of object (e.g. file, socket) being accessed.
<li><em>Permission</em> - The operation (e.g. read, write) being performed.
@@ -119,23 +119,22 @@
<p>And so an example use of this would follow the structure:</p>
<code>allow appdomain app_data_file:file rw_file_perms;</code>
-<p>This says an application is allowed to read and write files labeled
+<p>This says that all application domains are allowed to read and write files labeled
app_data_file. Note that this rule relies upon macros defined in the
global_macros file, and other helpful macros can also be found in the te_macros
-file. Macros are provided for common groupings of classes, permissions and
+file, both of which can be found in the <a href="https://android.googlesource.com/platform/external/sepolicy/">external/sepolicy</a> directory in the AOSP source tree. Macros are provided for common groupings of classes, permissions and
rules, and should be used whenever possible to help reduce the likelihood of
-failures due to denials on related permissions. During compilation, those
-overrides are concatenated to the existing SELinux settings and into a single
-security policy. These overrides add to the base security policy rather than
-subtract from existing settings.</p>
+failures due to denials on related permissions.</p>
+
+<p>In addition to individually listing domains or types in a rule, one can also refer to a set of domains or types via an <em>attribute</em>. An attribute is simply a name for a set of domains or types. Each domain or type can be associated with any number of attributes. When a rule is written that specifies an attribute name, that name is automatically expanded to the list of domains or types associated with the attribute. For example, the <em>domain</em> attribute is associated with all process domains, and the <em>file_type</em> attribute is associated with all file types.</p>
<p>Use the syntax above to create avc rules that comprise the essence of an
SELinux policy. A rule takes the form:
<pre>
-<rule variant> <source_type> <target_type> : <class> <permission>
+<rule variant> <source_types> <target_types> : <classes> <permissions>
</pre>
-<p>The rule indicates what should happen when an object labeled with the <em>source_type </em>attempts an action corresponding to <em>permission </em>on an object of class <em>class </em>which has the <em>target_type </em>label. The most common example of one of these rules is an allow rule, e.g.:</p>
+<p>The rule indicates what should happen when a subject labeled with any of the <em>source_types</em> attempts an action corresponding to any of the <em>permissions</em> on an object with any of the class <em>classes</em> which has any of the <em>target_types</em> label. The most common example of one of these rules is an allow rule, e.g.:</p>
<pre>
allow domain null_device:chr_file { open };
@@ -143,32 +142,33 @@
<p>
-This rule allows a process with <em>source_type</em> of ‘domain’to take the action described by the <em>permission</em> ‘open’ on an object of <em>class</em> ‘chr_file’ that has the <em>target_type</em> label of ‘null_device.’ In practice, this rule may be extended to include other permissions: </p>
+This rule allows a process with any <em>domain</em> associated with the ‘domain’ attribute to take the action described by the <em>permission</em> ‘open’ on an object of <em>class</em> ‘chr_file’ (character device file) that has the <em>target_type</em> label of ‘null_device.’ In practice, this rule may be extended to include other permissions: </p>
<pre>
-allow domain null_device:chr_file { getattr open read ioctl lock append write};
+allow domain null_device:chr_file { getattr open read ioctl lock append write};
</pre>
-<p>When combined with the knowledge that ‘domain’ is a label for all processes and
-that null_device is the label for the ‘chr_file’ /dev/null, this rule basically
+<p>When combined with the knowledge that ‘domain’ is an attribute assigned to
+all process domains and
+that null_device is the label for the character device /dev/null, this rule basically
permits reading and writing to <code>/dev/null</code>.</p>
<p>A <em>domain</em> generally corresponds to a process and will have a label associated with it.</p>
-<p>For example, a typical Android app is running it its own process and has the
+<p>For example, a typical Android app is running in its own process and has the
label of untrusted_app that grants it certain restricted permissions.</p>
<p>Platform apps built into the system run under a separate label and are granted
-a distinct set of permissions. System apps that are part of the core Android
+a distinct set of permissions. System UID apps that are part of the core Android
system run under the system_app label for yet another set of privileges.</p>
-<p>These generic labels require further specification:</p>
+<p>Access to the following generic labels should never be directly allowed to domains; instead, a more specific type should be created for the object or objects:</p>
<ul>
<li> socket_device
<li> device
<li> block_device
<li> default_service
- <li> system_data_type
+ <li> system_data_file
<li> tmpfs
</ul>
diff --git a/src/devices/tech/security/selinux/customize.jd b/src/devices/tech/security/selinux/customize.jd
index 79ca5d6..592b9b4 100644
--- a/src/devices/tech/security/selinux/customize.jd
+++ b/src/devices/tech/security/selinux/customize.jd
@@ -100,7 +100,7 @@
<p>First, note SELinux is based upon the <a href="https://www.gnu.org/software/m4/manual/index.html">M4</a> computer language and therefore supports a variety of macros to save time.</p>
-<p>In the following example, all domains are granted access to read or write to <code>/dev/null</code> and read from <code>/dev/0</code>.</p>
+<p>In the following example, all domains are granted access to read from or write to <code>/dev/null</code> and read from <code>/dev/zero</code>.</p>
<pre>
# Allow read / write access to /dev/null
@@ -181,10 +181,10 @@
<table>
<tr>
<td>
-<p><strong>Domain</strong></p>
+<p><strong>Class</strong></p>
</td>
<td>
-<p><strong>Capability</strong></p>
+<p><strong>Permission</strong></p>
</td>
</tr>
<tr>
diff --git a/src/devices/tech/security/selinux/implement.jd b/src/devices/tech/security/selinux/implement.jd
index 1f671fb..2a42746 100644
--- a/src/devices/tech/security/selinux/implement.jd
+++ b/src/devices/tech/security/selinux/implement.jd
@@ -44,9 +44,9 @@
<li>Grant each service (process or daemon) started from <code>init</code> its own domain.
<li>Identify these services by:
<ul>
- <li>Reviewing the init file and finding all services.
- <li>Examining warnings in <code>dmesg</code>.
- <li>Searching (<code>grep</code>) through processes to see which run in the init domain.
+ <li>Reviewing the init.<device>.rc file and finding all services.
+ <li>Examining warnings of the form <em>init: Warning! Service name needs a SELinux domain defined; please fix!</em> in <code>dmesg</code> output.
+ <li>Checking <code>ps -Z | grep init</code> output to see which services are running in the init domain.
</ul>
<li>Label all new processes, drivers, sockets, etc.
All objects need to be labeled
@@ -76,16 +76,53 @@
<p>Here are the files you must create or edit in order to implement SELinux:</p>
<ul>
- <li><em>New SELinux policy source (*.te) files</em> - Located in the <root>/device/manufacturer/device-name/sepolicy directory. These files define domains and their labels. The new policy files get
+ <li><em>New SELinux policy source (*.te) files</em> - Located in the
+<root>/device/manufacturer/device-name/sepolicy directory. These files define
+domains and their labels. The new policy files get
concatenated with the existing policy files during compilation into a single
SELinux kernel policy file.
-<p class="caution"><strong>Important:</strong> Do not alter the app.te file provided by the Android Open Source Project.
+<p class="caution"><strong>Important:</strong> Do not alter the app.te file
+provided by the Android Open Source Project.
Doing so risks breaking all third-party applications.</p>
- <li><em>Updated BoardConfig.mk makefile</em> - Located in the <device-name> directory containing the sepolicy subdirectory. It must be updated to reference the sepolicy subdirectory once created if it
+ <li><em>Updated BoardConfig.mk makefile</em> - Located in the <device-name>
+directory containing the sepolicy subdirectory. It must be updated to reference
+the sepolicy subdirectory once created if it
wasn’t in initial implementation.
- <li><em>Updated *_contexts files</em> - Located in the sepolicy subdirectory. These label files and
-are managed in the userspace. As you create new policies, update these files to
-reference them. In order to apply new *_contexts, you must run <code>restorecon</code> on the file to be relabeled.
+ <li><em>file_contexts</em> - Located in the sepolicy subdirectory. This file
+assigns labels to files and is used by various userspace components. As you
+create new policies, create or update this file to
+assign new labels to files. In order to apply new file_contexts, you must
+rebuild the filesystem image or run <code>restorecon</code> on the file to be
+relabeled. On upgrades, changes to file_contexts are automatically applied to
+the system and userdata partitions as part of the upgrade. Changes can also be
+automatically applied on upgrade to other partitions by adding
+restorecon_recursive calls to your init.<em>board</em>.rc file after the
+partition has been mounted read-write.
+ <li><em>genfs_contexts</em> - Located in the sepolicy subdirectory. This file
+assigns labels to filesystems such as proc or vfat that do not support extended
+attributes. This configuration is loaded as part of the kernel policy but
+changes may not take effect for in-core inodes, requiring a reboot or
+unmounting and re-mounting the filesystem to fully apply the change. Specific
+labels may also be assigned to specific mounts such as vfat using the context=
+mount option.
+ <li><em>property_contexts</em> - Located in the sepolicy subdirectory. This
+file assigns labels to Android system properties to control what processes can
+set them. This configuration is read by the init process during startup and
+whenever the selinux.reload_policy property is set to 1.
+ <li><em>service_contexts</em> - Located in the sepolicy subdirectory. This
+file assigns labels to Android binder services to control what processes can
+add (register) and find (lookup) a binder reference for the service. This
+configuration is read by the servicemanager process during startup and whenever
+the selinux.reload_policy property is set to 1.
+ <li><em>seapp_contexts</em> - Located in the sepolicy subdirectory. This file
+assigns labels to app processes and /data/data directories. This configuration
+is read by the zygote process on each app launch and by installd during startup
+and whenever the selinux.reload_policy property is set to 1.
+ <li><em>mac_permissions.xml</em> - Located in the sepolicy subdirectory. This
+file assigns a seinfo tag to apps based on their signature and optionally their
+package name. The seinfo tag can then be used as a key in the seapp_contexts
+file to assign a specific label to all apps with that seinfo tag. This
+configuration is read by system_server during startup.
</ul>
<p>Then just update your BoardConfig.mk makefile - located in the directory
@@ -156,12 +193,19 @@
<li>Enable SELinux in the kernel:
<code>CONFIG_SECURITY_SELINUX=y</code>
<li>Change the kernel_cmdline parameter so that:<br/>
-<code>BOARD_KERNEL_CMDLINE := androidboot.selinux=permissive</code>
+<code>BOARD_KERNEL_CMDLINE := androidboot.selinux=permissive</code>.
+<br/>
+This is only for initial development of policy for the device. Once you have
+an initial bootstrap policy, remove this parameter so that your device is
+enforcing or it will fail CTS.
<li>Boot up the system in permissive and see what denials are encountered on boot:<br/>
-<code>su -c dmesg | grep denied > ~/t.tmp su -c dmesg | grep denied | audit2allow</code>
+On Ubuntu 12.04:
+<code>adb shell su -c dmesg | grep denied | audit2allow</code>
+<br/>
+On Ubuntu 14.04 or newer:
+<code>adb shell su -c dmesg | grep denied | audit2allow -p out/target/product/<em>board</em>/root/sepolicy</code>
<li>Evaluate the output. See <a href="validate.html">Validation</a> for instructions and tools.
- <li>Identify devices, and other new files that need labeling.Identify devices, and
-other new files that need labeling.
+ <li>Identify devices, and other new files that need labeling.
<li>Use existing or new labels for your objects.
Look at the *_contexts files to
see how things were previously labeled and use knowledge of the label meanings
@@ -171,14 +215,14 @@
<li>Identify domains/processes that should have their own security domains. A policy will likely need to be written for each of these from scratch. All services spawned from <code>init</code>, for instance, should have their own. The following commands help reveal those that remain running (but ALL services need such a treatment):<br/>
<code>$ adb shell su -c ps -Z | grep init</code><br/>
<code>$ adb shell su -c dmesg | grep 'avc: '</code>
- <li>Review init.<device>.rc to identify any which are without a type.
+ <li>Review init.<device>.rc to identify any which are without a type.
These should
be given domains EARLY in order to avoid adding rules to init or otherwise
confusing <code>init</code> accesses with ones that are in their own policy.
<li>Set up <code>BOARD_CONFIG.mk</code> to use <code>BOARD_SEPOLICY_UNION</code> and <code>BOARD_SEPOLICY_DIRS</code>. See
the README in /sepolicy for details on setting this up.
- <li> Examine the init.<device>.rc file and make sure every use of “mount”
-corresponds to a properly labeled filesystem.
+ <li> Examine the init.<device>.rc and fstab.<device> file and make sure every use of “mount”
+corresponds to a properly labeled filesystem or that a context= mount option is specified.
<li> Go through each denial and create SELinux policy to properly handle each. See
the examples within <a href="customize.html">Customization</a>.
</ol>
diff --git a/src/devices/tech/security/selinux/index.jd b/src/devices/tech/security/selinux/index.jd
index bbc6ed8..3553bc7 100644
--- a/src/devices/tech/security/selinux/index.jd
+++ b/src/devices/tech/security/selinux/index.jd
@@ -85,16 +85,20 @@
<p><a href="https://www.codeproject.com/Articles/806904/Android-Security-Customization-with-SEAndroid">https://www.codeproject.com/Articles/806904/Android-Security-Customization-with-SEAndroid</a></p>
-<p><a href="https://www.nsa.gov/research/_files/publications/implementing_selinux.pdf">https://www.nsa.gov/research/_files/publications/implementing_selinux.pdf</a></p>
-
<p><a href="https://events.linuxfoundation.org/sites/events/files/slides/abs2014_seforandroid_smalley.pdf">https://events.linuxfoundation.org/sites/events/files/slides/abs2014_seforandroid_smalley.pdf</a></p>
<p><a href="https://www.internetsociety.org/sites/default/files/02_4.pdf">https://www.internetsociety.org/sites/default/files/02_4.pdf</a></p>
-<p><a href="https://www.gnu.org/software/m4/manual/index.html">https://www.gnu.org/software/m4/manual/index.html</a></p>
-
<p><a href="http://freecomputerbooks.com/books/The_SELinux_Notebook-4th_Edition.pdf">http://freecomputerbooks.com/books/The_SELinux_Notebook-4th_Edition.pdf</a></p>
+<p><a href="http://selinuxproject.org/page/ObjectClassesPerms">http://selinuxproject.org/page/ObjectClassesPerms</a></p>
+
+<p><a href="https://www.nsa.gov/research/_files/publications/implementing_selinux.pdf">https://www.nsa.gov/research/_files/publications/implementing_selinux.pdf</a></p>
+
+<p><a href="https://www.nsa.gov/research/_files/publications/selinux_configuring_policy.pdf">https://www.nsa.gov/research/_files/publications/selinux_configuring_policy.pdf</a></p>
+
+<p><a href="https://www.gnu.org/software/m4/manual/index.html">https://www.gnu.org/software/m4/manual/index.html</a></p>
+
<h2 id=help>Help</h2>
<p>Over time, Android intends to support common manufacturer additions in its
diff --git a/src/devices/tech/security/selinux/validate.jd b/src/devices/tech/security/selinux/validate.jd
index 2734665..34199f5 100644
--- a/src/devices/tech/security/selinux/validate.jd
+++ b/src/devices/tech/security/selinux/validate.jd
@@ -41,7 +41,7 @@
<p>Then check for errors. Errors are routed as event logs to dmesg and <code>logcat</code> and are viewable locally on the device. Manufacturers should examine the
SELinux output to dmesg on these devices and refine settings prior to public
release in permissive mode and eventual switch to enforcing mode. SELinux log
-messages contain "AVC" and so may easily be found with <code>grep</code>. It is
+messages contain "avc:" and so may easily be found with <code>grep</code>. It is
possible to capture the ongoing denial logs by running <code>cat /proc/kmsg</code>
or to capture denial logs from the previous boot by running cat <code>/proc/last_kmsg</code>.</p>
@@ -53,7 +53,7 @@
enforcing mode and why. Here is an example:</p>
<pre>
-denied { connectto } for pid=2671 comm="ping" path="/dev/socket/dnsproxyd"
+avc: denied { connectto } for pid=2671 comm="ping" path="/dev/socket/dnsproxyd"
scontext=u:r:shell:s0 tcontext=u:r:netd:s0 tclass=unix_stream_socket
</pre>
@@ -121,12 +121,18 @@
$ sudo apt-get install policycoreutils
</pre>
-<p>To use it:</p>
+<p>To use it on Ubuntu 12.04, run:</p>
<pre>
$ adb shell su -c dmesg | audit2allow
</pre>
+<p>On Ubuntu 14.04 and newer, audit2allow requires you to specify the Android policy
+using the -p option, e.g.
+<pre>
+$ adb shell su -c dmesg | audit2allow -p out/target/product/<device>/root/sepolicy
+</pre>
+
<p>Nevertheless, care must be taken to examine each potential addition for
overreaching permissions. For example, feeding audit2allow the <code>rmt_storage</code> denial shown earlier results in the following suggested SELinux policy
statement:</p>