Docs: Updating SELinux docs for full enforcement.
Bug: 17376045
Change-Id: I8f78ae474f8a90a6d4f73a2db157bcee549fcc3a
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 38134c4..c5075d9 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -152,11 +152,19 @@
<span class="en">Encryption</span>
</a>
</li>
- <li>
+ <li class="nav-section">
+ <div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/tech/security/se-linux.html">
<span class="en">Security-Enhanced Linux</span>
</a>
- </li>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/concepts.html">Concepts</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/implement.html">Implementation</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/customize.html">Customization</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/validate.html">Validation</a></li>
+ </ul>
+ </li>
</ul>
</li>
<li class="nav-section">
diff --git a/src/devices/tech/security/se-linux.jd b/src/devices/tech/security/se-linux.jd
index ad06fee..6c34a02 100644
--- a/src/devices/tech/security/se-linux.jd
+++ b/src/devices/tech/security/se-linux.jd
@@ -1,4 +1,4 @@
-page.title=Validating Security-Enhanced Linux in Android
+page.title=Security-Enhanced Linux in Android
@jd:body
<!--
@@ -24,416 +24,78 @@
</div>
</div>
-<h2 id="introduction">Introduction</h2>
-<p>
-As part of the Android <a href="{@docRoot}devices/tech/security/index.html">security
-model</a>, Android uses Security-Enhanced Linux (SELinux) to enforce Mandatory
-Access Control (MAC) over all processes, even processes running
-with root/superuser privileges (a.k.a. Linux capabilities). SELinux enhances
-Android security, and contributions to it have been made by a number of
-companies and organizations; all Android code and contributors are publicly
-available for review on
-<a href="https://android.googlesource.com/">android.googlesource.com</a>. With
-SELinux, Android can better protect and confine system services, control access
-to application data and system logs, reduce the effects of malicious software,
-and protect users from potential flaws in code on mobile devices.
-</p>
-<p>
-Android includes SELinux in enforcing mode and a corresponding security policy
-that works by default across the <a
-href="https://android.googlesource.com/">Android Open Source
-Project</a>. In enforcing mode, illegitimate
-actions are prevented and all potential violations are logged by the kernel to
-<code>dmesg</code>. Android device manufacturers should gather information about
-errors so they may refine their software and SELinux policies before enforcing
-them.
-</p>
+<h2 id=introduction>Introduction</h2>
-<h2 id="background">Background</h2>
-<p>
-SELinux can operate in one of two global modes: permissive mode, in
-which permission denials are logged but not enforced, and enforcing
-mode, in which permission denials are both logged and
-enforced. SELinux also supports a per-domain permissive mode in which
-specific domains (processes) can be made permissive while placing the
-rest of the system in global enforcing mode. A domain is simply a
-label identifying a process or set of processes in the security
-policy, where all processes labeled with the same domain are treated
-identically by the security policy. Per-domain permissive mode enables
-incremental application of SELinux to an ever-increasing portion of
-the system. Per-domain permissive mode also enables policy
-development for new services while keeping the rest of the system
-enforcing.
-</p>
+<p>The Android security model is based in part on the concept of application
+sandboxes. Each application runs in its own sandbox. Prior to Android 4.3,
+these sandboxes were defined by the creation of a unique Linux UID for each
+application at time of installation. Starting with Android 4.3,
+Security-Enhanced Linux (SELinux) is used to further define the boundaries of
+the Android application sandbox.</p>
-<p>
-In Android 4.3, SELinux was fully permissive. In Android 4.4, SELinux
-was made enforcing for the domains for several root processes:
-<code>installd</code>, <code>netd</code>, <code>vold</code> and
-<code>zygote</code>. <em>All other processes, including other
-services and all apps, remain in permissive mode to allow further
-evaluation and prevent failures in Android 4.4. Still, an errant
-application could trigger an action in a root process that is not
-allowed, thereby causing the process or the application to crash.</em>
-</p>
-<p>
-For this reason, device manufacturers should retain the default settings
-provided by Android and limit enforcing mode to system services only until
-they've resolved issues reported in dmesg. That said, device manufacturers may
-need to augment their SELinux implementation to account for their additions and
-other changes to the operating system. See the <em>Customization</em> section for
-instructions.
-</p>
+<p>As part of the Android <a href="{@docRoot}devices/tech/security/index.html">security model</a>, Android uses SELinux to enforce mandatory access control (MAC) over all
+processes, even processes running with root/superuser privileges (a.k.a. Linux
+capabilities). SELinux enhances Android security by confining privileged
+processes and automating security policy creation.</p>
-<h2 id="mac">Mandatory access control</h2>
-<p>
-In conjunction with other Android security measures, Android's access control
-policy greatly limits the potential damage of compromised
-machines and accounts. Using tools like Android's discretionary and mandatory
-access controls gives you a structure to ensure your software runs
-only at the minimum privilege level. This mitigates the effects of
-attacks and reduces the likelihood of errant processes overwriting or even
-transmitting data.
-</p>
-<p>
-Starting in Android 4.3, SELinux provides a mandatory access control (MAC)
-umbrella over traditional discretionary access control (DAC) environments.
-For instance, software must typically run as the root user account to write
-to raw block devices. In a traditional DAC-based Linux environment, if the root
-user becomes compromised that user can write to every raw block device. However,
-SELinux can be used to label these devices so the process assigned the root
-privilege can write to only those specified in the associated policy. In this
-way, the process cannot overwrite data and system settings outside of the
-specific raw block device.
-</p>
-<p>
-See the <em>Use Cases</em> section for more examples of threats and ways to
-address them with SELinux.
-</p>
+<p>Contributions to it have been made by a number of companies and organizations;
+all Android code and contributors are publicly available for review on <a href="https://android.googlesource.com/">android.googlesource.com</a>. With SELinux, Android can better protect and confine system services, control
+access to application data and system logs, reduce the effects of malicious
+software, and protect users from potential flaws in code on mobile devices.</p>
-<h2 id="implementation">Implementation</h2>
-<p>
-Android's SELinux implementation is in enforcing mode - rather than the
-non-functional disabled mode or the notification-only permissive mode - to act
-as a reference and facilitate testing and development. Although enforcing mode
-is set globally, please remember this can be overridden on a per-domain basis
-as is in the case of the application domain.
-</p>
-<p>
-SELinux for Android is accompanied by everything you need to enable SELinux
-now. You merely need to integrate the <a
-href="https://android.googlesource.com/kernel/common/">latest Android
-kernel</a> and then incorporate the files found in the
-<a
-href="https://android.googlesource.com/platform/external/sepolicy/">
-external/sepolicy</a> directory:<br/>
-<a
-href="https://android.googlesource.com/kernel/common/">
-https://android.googlesource.com/kernel/common/</a>
-<br/>
-<a
-href="https://android.googlesource.com/platform/external/sepolicy/">
-https://android.googlesource.com/platform/external/sepolicy/</a>
-</p>
+<p>Android includes SELinux in enforcing mode and a corresponding security policy
+that works by default across the <a href="https://android.googlesource.com/">Android Open Source Project</a>. In enforcing mode, illegitimate actions are prevented and all attempted
+violations are logged by the kernel to <code>dmesg</code> and <code>logcat</code>. Android device manufacturers should gather information about errors so they
+may refine their software and SELinux policies before enforcing them.</p>
-<p>
- Those files when compiled comprise the SELinux kernel security policy and cover
-the upstream Android operating system. You should not need to modify
-the <root>external/sepolicy</root> files directly. Instead, add your own
-device-specific policy files within the
-<root>/device/manufacturer/device-name/sepolicy directory.
-</p>
+<h2 id=background>Background</h2>
-<p>
-Then just update your <code>BoardConfig.mk</code> makefile - located in the
-<device-name> directory containing the sepolicy subdirectory - to reference the
-sepolicy subdirectory and any policy file once created, as shown below. The
-BOARD_SEPOLICY variables and their meaning is documented in the
-external/sepolicy/README file.
-</p>
+<p>SELinux operates on the ethos of default denial. Anything that is not
+explicitly allowed is denied. SELinux can operate in one of two global modes:
+permissive mode, in which permission denials are logged but not enforced, and
+enforcing mode, in which denials are both logged and enforced. SELinux also
+supports a per-domain permissive mode in which specific domains (processes) can
+be made permissive while placing the rest of the system in global enforcing
+mode. A domain is simply a label identifying a process or set of processes in
+the security policy, where all processes labeled with the same domain are
+treated identically by the security policy. Per-domain permissive mode enables
+incremental application of SELinux to an ever-increasing portion of the system.
+Per-domain permissive mode also enables policy development for new services
+while keeping the rest of the system enforcing.</p>
-<pre>
-BOARD_SEPOLICY_DIRS += \
- <root>/device/manufacturer/device-name/sepolicy
+<p>In the L release, Android moves to full enforcement of SELinux. This builds
+upon the permissive release of 4.3 and the partial enforcement of 4.4. In
+short, Android is shifting from enforcement on a limited set of crucial domains
+(<code>installd</code>, <code>netd</code>, <code>vold</code> and <code>zygote</code>) to everything (more than 60 domains). This means manufacturers will have to
+better understand and scale their SELinux implementations to provide compatible
+devices. Understand that:</p>
-BOARD_SEPOLICY_UNION += \
- genfs_contexts \
- file_contexts \
- sepolicy.te
-</pre>
-
-<p>
-After rebuilding your device, it is enabled with SELinux. You can now either
-customize your SELinux policies to accommodate your own additions to the Android
-operating system as described in the <em>Customization</em> section or verify
-your existing setup as covered in the <em>Validation</em> section.
-</p>
-
-<h2 id="customization">Customization</h2>
-<p>
-Once you've integrated this base level of functionality and thoroughly analyzed
-the results, you may add your own policy settings to cover your customizations
-to the Android operating system. Of course, these policies must still meet the
-<a href="http://source.android.com/compatibility/index.html">Android
-Compatibility
-program</a> requirements and
-not remove the default SELinux settings.
-</p>
-<p>
-Manufacturers should not remove existing security settings. Otherwise, they risk
-breaking the Android SELinux implementation and the applications it governs.
-This includes third-party applications that will likely need to be improved to
-be compliant and operational. Applications must require no modification to
-continue functioning on SELinux-enabled devices.
-</p>
-<p>
-See the <em>Kernel Security Features</em> section of the Android Compatibility
-Definition document for specific requirements:<br/>
-<a
-href="http://source.android.com/compatibility/index.html">
-http://source.android.com/compatibility/index.html</a>
-</p>
-<p>
-SELinux uses a whitelist approach, meaning all access must be explicitly allowed
-in policy in order to be granted. Since Android's default SELinux policy already
-supports the Android Open Source Project, OEMs are not required to modify
-SELinux settings in any way. If they do customize SELinux settings, they should
-take great care not to break existing applications. Here is how we recommend
-proceeding:
-</p>
-
-<ol>
-<li>Use the <a href="https://android.googlesource.com/kernel/common/">latest
-Android
-kernel</a>.</li>
-<li>Adopt the <a
-href="http://en.wikipedia.org/wiki/Principle_of_least_privilege">principle of
-least
-privilege</a>.</li>
-<li>Address only your own additions to Android. The default policy works with
-the
-<a href="https://android.googlesource.com/">Android Open Source Project</a>
-codebase
-automatically.</li>
-<li>Compartmentalize software components into modules that conduct singular
-tasks.</li>
-<li>Create SELinux policies that isolate those tasks from unrelated
-functions.</li>
-<li>Put those policies in *.te files (the extension for SELinux policy source
-files) within the <root>/device/manufacturer/device-name/sepolicy
-directory and use BOARD_SEPOLICY variables to include them in your build.</li>
-<li>Make new domains permissive initially. In Android 4.4 and earlier, this
-is done using a permissive declaration. In later versions of Android,
-per-domain permissive mode is specified using the permissive_or_unconfined()
-macro.</li>
-<li>Analyze results and refine your domain definitions.</li>
-<li>Remove the permissive declaration when no further denials appear
-in userdebug builds.</li>
-</ol>
-
-<p>
-Once integrated, OEM Android development should include a step to ensure
-SELinux
-compatibility going forward. In an ideal software development process, SELinux
-policy changes only when the software model changes and not the actual
-implementation.
-</p>
-<p>
-As device manufacturers begin to customize SELinux, they should first audit
-their additions to Android. If they've added a component that conducts a new
-function, the manufacturers will need to ensure the component meets the security
-policy applied by Android, as well as any associated policy crafted by the OEM,
-before turning on enforcing mode.
-</p>
-<p>
-To prevent unnecessary issues, it is better to be overbroad and over-compatible
-than too restrictive and incompatible, which results in broken device functions.
-Conversely, if a manufacturer's changes will benefit others, it should supply
-the modifications to the default SELinux policy as a
-<a href="http://source.android.com/source/submit-patches.html">patch</a>. If the
-patch is
-applied to the default security policy, the manufacturer will no longer need to
-make this change with each new Android release.
-</p>
-
-<h2 id="use-cases">Use Cases</h2> <p>Here are specific examples of exploits to
-consider when crafting your own software and associated SELinux policies:</p>
-
-<p><strong>Symlinks</strong> - Because symlinks appear as files, they are often
-read just as that. This can lead to exploits. For instance, some privileged
-components such as <code>init</code> change the permissions of certain files,
-sometimes to be excessively open.</p>
-
-<p>Attackers might then replace those files with symlinks to code they control,
-allowing the attacker to overwrite arbitrary files. But if you know your
-application will never traverse a symlink, you can prohibit it from doing so
-with SELinux.</p>
-
-<p><strong>System files</strong> - Consider the class of system files that
-should only be modified by the system server. Still, since <code>netd</code>,
-<code>init</code>, and <code>vold</code> run as root, they can access those
-system files. So if <code>netd</code> became compromised, it could compromise
-those files and potentially the system server itself.</p>
-
-<p>With SELinux, you can identify those files as system server data files.
-Therefore, the only domain that has read/write access to them is system server.
-Even if <code>netd</code> became compromised, it could not switch domains to the
-system server domain and access those system files although it runs as root.</p>
-
-<p><strong>App data</strong> - Another example is the class of functions that
-must run as root but should not get to access app data. This is incredibly
-useful as wide-ranging assertions can be made, such as certain domains
-unrelated to application data being prohibited from accessing the internet.</p>
-
-<p><strong>setattr</strong> - For commands such as <code>chmod</code> and
-<code>chown</code>, you could identify the set of files where the associated
-domain can conduct <code>setattr</code>. Anything outside of that could be
-prohibited from these changes, even by root. So an application might run
-<code>chmod</code> and <code>chown</code> against those labeled app_data_files
-but not shell_data_files or system_data_files.</p>
-
-<h2 id="related-files">Related Files</h2>
-<p>This section serves to guide you once you’ve decided to
-customize the SELinux policy settings. See the <em>Customization</em> section
-for steps. We recommend device manufacturers start with the default Android
-SELinux policy and make the minimum possible set of changes to address their
-additions to Android. Existing Android SELinux policy files are found in the
-root of the <a
-href="https://android.googlesource.com/platform/external/sepolicy/">
-external/sepolicy</a> directory.</p>
-
-<p>Android upgraded its SELinux policy version to allow the SELinux mode to be
-set to permissive on a per-domain basis. For example, if you run all of your
-applications in a single domain, you could set that domain to be permissive and
-then have all other functions and their domains set to enforcing. Domains are
-associated with applications by the key used to sign each application. The
-mapping of app certificates to domains is specified via the
-mac_permissions.xml and seapp_contexts configuration files.</p>
-
-<p>Here are the files you must create or edit in order to customize SELinux:</p>
<ul>
-<li>
-<p><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>
-<p><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>
-<li>
-<p><em>Updated <code>BoardConfig.mk</code> 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.</p> </li>
-<li>
-<p><em>Updated <code>file_contexts</code></em> - Located in
-the sepolicy subdirectory. It labels files and is managed in the userspace. As
-you create new policies, update this file to reference them. In order to apply
-new <code>file_contexts</code>, you must run <code>restorecon</code> on the file
-to be relabeled.</p>
-</li> </ul>
-
-<p>The remaining files in the sepolicy directory are either auto-generated or
-should remain static. The policy rules come in the form: allow <em>domains</em>
-<em>types</em>:<em>classes</em> <em>permissions</em>;, where:</p>
-<ul>
-<li>
-<p><em>Domain</em> - A label for the process or set of processes.
-</p></li>
-<li>
-<p><em>Type</em> - A label for the object (e.g. file, socket) or set of objects.
-</p></li>
-<li>
-<p><em>Class</em> - The kind of object (e.g. file, socket) being accessed.
-</p></li>
-<li>
-<p><em>Permission</em> - The operation (e.g. read, write) being performed.
-</p></li>
-
-<p>And so an example use of this would follow the structure:<br>
-<code>allow appdomain app_data_file:file rw_file_perms;</code></p>
-
-<p>This says an application is 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 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>
-
-<p>Once the new policy files and <code>BoardConfig.mk</code> updates are in
-place, the new policy settings are automatically built into the final kernel
-policy file.</p>
-
-<h2 id="validation">Validation</h2> <p>Android strongly encourages OEMs to test
-their SELinux implementations thoroughly. As manufacturers implement SELinux,
-they should initially release their own policies in permissive mode. If
-possible, apply the new policy to a test pool of devices first.</p>
-
-<p>Once applied, make sure SELinux is running in the correct mode on the device
-by issuing the command: <code>getenforce</code></p>
-
-<p>This will print the global SELinux mode: either Disabled, Enforcing, or
-Permissive.
-Please note, this command shows only the global SELinux mode. To determine the
-SELinux mode for each domain, you must examine the corresponding files.</p>
-
-<p>Then check for errors. Errors are routed as event logs to <code>dmesg</code>
-and viewable locally on the device. Manufacturers should examine the SELinux
-output to <code>dmesg</code> on these devices and refine settings prior to
-public release in permissive mode and eventual switch to enforcing mode. 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 <code>cat /proc/last_kmsg</code>.</p>
-
-<p>With this output, manufacturers can readily identify when system users or
-components are in violation of SELinux policy. Manufacturers can then repair
-this bad behavior, either by changes to the software, SELinux policy, or
-both.</p>
-
-<p>Specifically, these log messages indicate what processes would fail
-under enforcing mode and why. Here is an example:</p>
-
-<pre>
-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>
-
-<p>Interpret this output like so:</p>
-<ul>
-<li>The { connectto } above represents the action being taken. Together with the
-tclass at the end (unix_stream_socket) it tells you roughly what was being done
-to what. In this case, something was trying to connect to a unix stream
-socket.</li>
-<li>The scontext (u:r:shell:s0) tells you what context initiated the action. In
-this case this is something running as the shell.</li>
-<li>The tcontext (u:r:netd:s0) tells you the context of the action’s target. In
-this case, that’s a unix_stream_socket owned by netd.</li>
-<li>The comm="ping" at the top gives you an additional hint about what was being
-run at the time the denial was generated. In this case, it’s a pretty good
-hint.</li>
+ <li> Everything is in enforcing mode in the L release
+ <li> No processes other than <code>init</code> should run in the <code>init</code> domain
+ <li> Any generic denial (for a block_device, socket_device, default_service, etc.)
+indicates that device needs a special domain
</ul>
-<p>Android is taking this information, analyzing
-it and refining its default security policy so that it works on a wide range of
-Android devices with little customization. With this policy, OEMs must only
-accommodate their own changes to the Android operating system.</p>
+<h2 id=supporting_documentation>Supporting documentation</h2>
-<p>Then run the SELinux-enabled devices through the <a
-href="{@docRoot}compatibility/cts-intro.html">Android
-Compatibility Test Suite</a> (CTS).</p> <p>As said, any new policies must still
-meet the <a href="{@docRoot}compatibility/index.html">Android
-Compatibility program</a> requirements.</p>
+<p>See the documentation below for details on constructing useful policies:</p>
-<p>Finally, if possible, turn on enforcing mode internally (on devices of
-employees) to raise the visibility of failures. Identify any user issues and
-resolve them. </p> <h2 id="help">Help</h2> Device manufacturers are strongly
-encouraged to work with their Android account managers to analyze SELinux
-results and improve policy settings. Over time, Android intends to support
-common manufacturer additions in its default SELinux policy. For more
-information, contact security@android.com.
+<p><a href="https://seandroid.bitbucket.org/PapersandPresentations.html">https://seandroid.bitbucket.org/PapersandPresentations.html</a></p>
+
+<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="https://freecomputerbooks.com/books/The_SELinux_Notebook-4th_Edition.pdf">https://freecomputerbooks.com/books/The_SELinux_Notebook-4th_Edition.pdf</a></p>
+
+<h2 id=help>Help</h2>
+
+<p>Over time, Android intends to support common manufacturer additions in its
+default SELinux policy. For more information, contact <a href="mailto:security@android.com">security@android.com</a>.</p>
diff --git a/src/devices/tech/security/selinux/concepts.jd b/src/devices/tech/security/selinux/concepts.jd
new file mode 100644
index 0000000..a0eb2cc
--- /dev/null
+++ b/src/devices/tech/security/selinux/concepts.jd
@@ -0,0 +1,174 @@
+page.title=SELinux concepts
+@jd:body
+
+<!--
+ Copyright 2014 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>Review this page to become familar with the concepts at play within SELinux.</p>
+
+<h2 id=mandatory_access_control>Mandatory access control</h2>
+
+<p>Security Enhanced Linux (SELinux), is a mandatory access control (MAC) system
+for the Linux operating system. As a MAC system, it differs from Linux’s
+familiar discretionary access control (DAC) system. In a DAC system, a concept
+of ownership exists, whereby an owner of a particular resource controls access
+permissions associated with it. This is generally coarse-grained and subject
+to unintended privilege escalation. A MAC system, however, consults a central
+authority for a decision on all access attempts.</p>
+
+<p>SELinux has been implemented as part of the Linux Security Module (LSM)
+framework, which recognizes various kernel objects, and sensitive actions
+performed on them. At the point at which each of these actions would be
+performed, an LSM hook function is called to determine whether or not the
+action should be allowed based on the information for it stored in an opaque
+security object. SELinux provides an implementation for these hooks and
+management of these security objects, which combine with its own policy, to
+determine the access decisions.</p>
+
+<p>In conjunction with other Android security measures, Android's access control
+policy greatly limits the potential damage of compromised machines and
+accounts. Using tools like Android's discretionary and mandatory access
+controls gives you a structure to ensure your software runs only at the minimum
+privilege level. This mitigates the effects of attacks and reduces the
+likelihood of errant processes overwriting or even transmitting data.</p>
+
+<p>Starting in Android 4.3, SELinux provides a mandatory access control (MAC)
+umbrella over traditional discretionary access control (DAC) environments. For
+instance, software must typically run as the root user account to write to raw
+block devices. In a traditional DAC-based Linux environment, if the root user
+becomes compromised that user can write to every raw block device. However,
+SELinux can be used to label these devices so the process assigned the root
+privilege can write to only those specified in the associated policy. In this
+way, the process cannot overwrite data and system settings outside of the
+specific raw block device.</p>
+
+<p>See <a href="implement.html#use_cases">Use Cases</a> for more examples of threats and ways to address them with SELinux.</p>
+
+<h2 id=enforcement_levels>Enforcement levels</h2>
+
+<p>Become familiar with the following terms to understand how SELinux can be
+implemented to varying strengths.</p>
+
+<ul>
+ <li><em>Permissive</em> - SELinux security policy is not enforced, only logged.
+ <li><em>Enforcing</em> - Security policy is enforced and logged. Failures appear as EPERM errors.
+</ul>
+
+<p>This choice is binary and determines whether your policy takes action or merely
+allows you to gather potential failures. Permissive is especially useful during
+implementation.</p>
+
+<ul>
+ <li><em>Unconfined</em> - A very light policy that prohibits certain tasks and provides a temporary
+stop-gap during development. Should not be used for anything outside of the
+Android Open Source Project (AOSP).
+ <li><em>Confined</em> - A custom-written policy designed for the service. That policy should define
+precisely what is allowed.
+</ul>
+
+<p>Unconfined policies are available to help implement SELinux in Android quickly.
+They are suitable for most root-level applications. But they should be
+converted to confined policies wherever possible over time to restrict each
+application to precisely the resources it needs.</p>
+
+<p>Ideally, your policy is both in enforcing mode and confined. Unconfined
+policies in enforcement mode can mask potential violations that would have been
+logged in permissive mode with a confined policy. Therefore, we strongly
+recommend partners implement true confined policies.</p>
+
+<h2 id=labels_rules_and_domains>Labels, rules and domains</h2>
+
+<p>SELinux depends upon <em>labels</em> to match actions and policies. Labels determine what is allowed. Sockets,
+files, and processes all have labels in SELinux. SELinux decisions are based
+fundamentally on labels assigned to these objects and the policy defining how
+they may interact. In SELinux, a label takes the form:
+user:role:type:mls_level, where the type is the primary component of the access
+decisions, which may be modified by the other sections components which make up
+the label. The objects are mapped to classes and the different types of access
+for each class are represented by permissions. </p>
+
+<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>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.
+</ul>
+
+<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
+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
+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>
+
+<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>
+</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>
+
+<pre>
+allow domain null_device:chr_file { open };
+</pre>
+
+
+<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>
+
+<pre>
+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
+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
+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
+system run under the system_app label for yet another set of privileges.</p>
+
+<p>These generic labels require further specification:</p>
+
+<ul>
+ <li> socket_device
+ <li> device
+ <li> block_device
+ <li> default_service
+ <li> system_data_type
+ <li> tmpfs
+</ul>
diff --git a/src/devices/tech/security/selinux/customize.jd b/src/devices/tech/security/selinux/customize.jd
new file mode 100644
index 0000000..79ca5d6
--- /dev/null
+++ b/src/devices/tech/security/selinux/customize.jd
@@ -0,0 +1,274 @@
+page.title=Customizing SELinux
+@jd:body
+
+<!--
+ Copyright 2014 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>Once you've integrated this base level of functionality and thoroughly analyzed
+the results, you may add your own policy settings to cover your customizations
+to the Android operating system. Of course, these policies must still meet the <a href="{@docRoot}compatibility/index.html">Android Compatibility program</a> requirements and not remove the default SELinux settings.</p>
+
+<p>Manufacturers should not remove existing security settings. Otherwise, they
+risk breaking the Android SELinux implementation and the applications it
+governs. This includes third-party applications that will likely need to be
+improved to be compliant and operational. Applications must require no
+modification to continue functioning on SELinux-enabled devices.</p>
+
+<p>When embarking upon customizing SELinux, manufacturers should remember to:</p>
+
+<ul>
+ <li>Write SELinux policy for all new daemons
+ <li>Use predefined domains whenever appropriate
+ <li>Assign a domain to any process spawned as an <code>init</code> service
+ <li>Become familiar with the macros before writing policy
+ <li>Submit changes to core policy to AOSP
+</ul>
+
+<p>And not to:</p>
+
+<ul>
+ <li>Create incompatible policy
+ <li>Allow end user policy customization
+ <li>Allow MDM policy customizations
+ <li>Scare users with policy violations
+ <li>Add backdoors
+</ul>
+
+<p>See the <em>Kernel Security Features</em> section of the <a href="{@docRoot}compatibility/android-cdd.pdf">Android Compatibility Definition document</a> for specific requirements.</p>
+
+<p>SELinux uses a whitelist approach, meaning all access must be explicitly
+allowed in policy in order to be granted. Since Android's default SELinux
+policy already supports the Android Open Source Project, OEMs are not required
+to modify SELinux settings in any way. If they do customize SELinux settings,
+they should take great care not to break existing applications. Here is how we
+recommend proceeding:</p>
+
+<ol>
+ <li>Use the <a href="https://android.googlesource.com/kernel/common/">latest Android kernel</a>.
+ <li>Adopt the <a href="http://en.wikipedia.org/wiki/Principle_of_least_privilege">principle of least privilege</a>.
+ <li>Address only your own additions to Android. The default policy works with the <a href="https://android.googlesource.com/">Android Open Source Project</a> codebase automatically.
+ <li>Compartmentalize software components into modules that conduct singular tasks.
+ <li>Create SELinux policies that isolate those tasks from unrelated functions.
+ <li>Put those policies in *.te files (the extension for SELinux policy source
+files) within the <code>/device/manufacturer/device-name/sepolicy</code> directory and use
+<code>BOARD_SEPOLICY</code> variables to include them in your build.
+ <li>Make new domains permissive initially. In Android 4.4 and earlier, this is done
+using a permissive declaration. In later versions of Android, per-domain
+permissive mode is specified using the <code>permissive_or_unconfined()</code> macro.
+ <li>Analyze results and refine your domain definitions.
+ <li>Remove the permissive declaration when no further denials appear in userdebug
+builds.
+</ol>
+
+<p>Once integrated, OEM Android development should include a step to ensure
+SELinux compatibility going forward. In an ideal software development process,
+SELinux policy changes only when the software model changes and not the actual
+implementation.</p>
+
+<p>As device manufacturers begin to customize SELinux, they should first audit
+their additions to Android. If they've added a component that conducts a new
+function, the manufacturers will need to ensure the component meets the
+security policy applied by Android, as well as any associated policy crafted by
+the OEM, before turning on enforcing mode.</p>
+
+<p>To prevent unnecessary issues, it is better to be overbroad and over-compatible
+than too restrictive and incompatible, which results in broken device
+functions. Conversely, if a manufacturer's changes will benefit others, it
+should supply the modifications to the default SELinux policy as a <a href="{@docRoot}source/submit-patches.html">patch</a>. If the patch is applied to the default security policy, the manufacturer will no longer need to make this change with each new Android release.</p>
+
+<h2 id=example_policy_statements>Example policy statements</h2>
+
+<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>
+
+<pre>
+# Allow read / write access to /dev/null
+allow domain null_device:chr_file { getattr open read ioctl lock append write};
+
+# Allow read-only access to /dev/zero
+allow domain zero_device:chr_file { getattr open read ioctl lock };
+</pre>
+
+
+<p>This same statement can be written with SELinux <code>*_file_perms</code> macros (shorthand):</p>
+
+<pre>
+# Allow read / write access to /dev/null
+allow domain null_device:chr_file rw_file_perms;
+
+# Allow read-only access to /dev/zero
+allow domain zero_device:chr_file r_file_perms;
+</pre>
+
+<h2 id=example_policy>Example policy</h2>
+
+<p>Here is a complete example policy for DHCP, which we examine below:</p>
+
+<pre>
+type dhcp, domain;
+permissive_or_unconfined(dhcp)
+type dhcp_exec, exec_type, file_type;
+type dhcp_data_file, file_type, data_file_type;
+
+init_daemon_domain(dhcp)
+net_domain(dhcp)
+
+allow dhcp self:capability { setgid setuid net_admin net_raw net_bind_service
+};
+allow dhcp self:packet_socket create_socket_perms;
+allow dhcp self:netlink_route_socket { create_socket_perms nlmsg_write };
+allow dhcp shell_exec:file rx_file_perms;
+allow dhcp system_file:file rx_file_perms;
+# For /proc/sys/net/ipv4/conf/*/promote_secondaries
+allow dhcp proc_net:file write;
+allow dhcp system_prop:property_service set ;
+unix_socket_connect(dhcp, property, init)
+
+type_transition dhcp system_data_file:{ dir file } dhcp_data_file;
+allow dhcp dhcp_data_file:dir create_dir_perms;
+allow dhcp dhcp_data_file:file create_file_perms;
+
+allow dhcp netd:fd use;
+allow dhcp netd:fifo_file rw_file_perms;
+allow dhcp netd:{ dgram_socket_class_set unix_stream_socket } { read write };
+allow dhcp netd:{ netlink_kobject_uevent_socket netlink_route_socket
+netlink_nflog_socket } { read write };
+</pre>
+
+<p>Let’s dissect the example:</p>
+
+<p>In the first line, the type declaration, the DHCP daemon inherits from the base
+security policy (<code>domain</code>). From the previous statement examples, we know DHCP can read from and write
+to <code>/dev/null.</code></p>
+
+<p>In the second line, DHCP is identified as an experimental domain (<code>permissive_or_unconfined</code>) with only minimal rules enforced.</p>
+
+<p>In the <code>init_daemon_domain(dhcp)</code> line, the policy states DHCP is spawned from <code>init</code> and is allowed to communicate with it.</p>
+
+<p>In the <code>net_domain(dhcp)</code> line, the policy allows DHCP to use common network functionality from the <code>net</code> domain such as reading and writing TCP packets, communicating over sockets, and conducting DNS requests.</p>
+
+<p>In the line <code>allow dhcp proc_net:file write;</code>, the policy states DHCP can write to specific files in <code>/proc</code>. This line demonstrates SELinux’s fine-grained file labeling. It uses the <code>proc_net</code> label to limit write access to only the files under <code>/proc/sys/net</code>.</p>
+
+<p>The final block of the example starting with <code>allow dhcp netd:fd use;</code> depicts how applications may be allowed to interact with one another. The
+policy says DHCP and netd may communicate with one another via file
+descriptors, FIFO files, datagram sockets, and UNIX stream sockets. DHCP may
+only read to and write from the datagram sockets and UNIX stream sockets and
+not create or open them.</p>
+
+<h2 id=available_controls>Available controls</h2>
+
+<table>
+ <tr>
+ <td>
+<p><strong>Domain</strong></p>
+</td>
+ <td>
+<p><strong>Capability</strong></p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>file</p>
+</td>
+ <td>
+<pre>
+ioctl read write create getattr setattr lock relabelfrom relabelto append
+unlink link rename execute swapon quotaon mounton</pre>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>directory</p>
+</td>
+ <td>
+<pre>
+add_name remove_name reparent search rmdir open audit_access execmod</pre>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>socket</p>
+</td>
+ <td>
+<pre>
+ioctl read write create getattr setattr lock relabelfrom relabelto append bind
+connect listen accept getopt setopt shutdown recvfrom sendto recv_msg send_msg
+name_bind</pre>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>filesystem</p>
+</td>
+ <td>
+<pre>
+mount remount unmount getattr relabelfrom relabelto transition associate
+quotamod quotaget</pre>
+ </td>
+ </tr>
+ <tr>
+ <td>
+<p>process</p>
+ </td>
+ <td>
+<pre>
+fork transition sigchld sigkill sigstop signull signal ptrace getsched setsched
+getsession getpgid setpgid getcap setcap share getattr setexec setfscreate
+noatsecure siginh setrlimit rlimitinh dyntransition setcurrent execmem
+execstack execheap setkeycreate setsockcreate</pre>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>security</p>
+</td>
+ <td>
+<pre>
+compute_av compute_create compute_member check_context load_policy
+compute_relabel compute_user setenforce setbool setsecparam setcheckreqprot
+read_policy</pre>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>capability</p>
+</td>
+ <td>
+<pre>
+chown dac_override dac_read_search fowner fsetid kill setgid setuid setpcap
+linux_immutable net_bind_service net_broadcast net_admin net_raw ipc_lock
+ipc_owner sys_module sys_rawio sys_chroot sys_ptrace sys_pacct sys_admin
+sys_boot sys_nice sys_resource sys_time sys_tty_config mknod lease audit_write
+audit_control setfcap</pre>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p><strong>MORE</strong></p>
+</td>
+ <td>
+<p><strong>AND MORE</strong></p>
+</td>
+ </tr>
+</table>
diff --git a/src/devices/tech/security/selinux/implement.jd b/src/devices/tech/security/selinux/implement.jd
new file mode 100644
index 0000000..9e2e724
--- /dev/null
+++ b/src/devices/tech/security/selinux/implement.jd
@@ -0,0 +1,184 @@
+page.title=Implementing SELinux
+@jd:body
+
+<!--
+ Copyright 2014 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>SELinux is set up to default-deny, which means that every single access for
+which it has a hook in the kernel must be explicitly allowed by policy. This
+means a policy file is comprised of a large amount of information regarding
+rules, types, classes, permissions, and more. A full consideration of SELinux
+is out of the scope of this document, but an understanding of how to write
+policy rules is now essential when bringing up new Android devices. There is a
+great deal of information available regarding SELinux already. See <a
+href="{@docRoot}devices/tech/security/se-linux.html#supporting_documentation">Supporting
+documentation</a> for suggested resources.</p>
+
+<h2 id=summary_of_steps>Summary of steps</h2>
+
+<p>Here is a brief summary of the steps needed to implement SELinux on your
+Android device:</p>
+
+<ol>
+ <li>Add SELinux support in the kernel and configuration.
+ <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.
+ </ul>
+ <li>Label all new processes, drivers, sockets, etc.
+All objects need to be labeled
+properly to ensure they interact properly with the policies you apply. See the
+labels used in AOSP for examples to follow in label name creation.
+ <li>Institute security policies that fully cover all labels and restrict
+permissions to their absolute minimum.
+</ol>
+
+<p>Ideally, OEMs start with the policies in the AOSP and then build upon them for
+their own customizations.</p>
+
+<h2 id=key_files>Key files</h2>
+
+<p>SELinux for Android is accompanied by everything you need to enable SELinux
+now. You merely need to integrate the <a href="https://android.googlesource.com/kernel/common/">latest Android kernel</a> and then incorporate the files found in the <a href="https://android.googlesource.com/platform/external/sepolicy/">external/sepolicy</a> directory:</p>
+
+<p><a href="https://android.googlesource.com/kernel/common/">https://android.googlesource.com/kernel/common/ </a></p>
+
+<p><a href="https://android.googlesource.com/platform/external/sepolicy/">https://android.googlesource.com/platform/external/sepolicy/</a></p>
+
+<p>Those files when compiled comprise the SELinux kernel security policy and cover
+the upstream Android operating system. You should not need to modify the
+external/sepolicy files directly. Instead, add your own device-specific policy
+files within the /device/manufacturer/device-name/sepolicy directory.</p>
+
+<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
+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.
+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
+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.
+</ul>
+
+<p>Then just update your BoardConfig.mk makefile - located in the directory
+containing the sepolicy subdirectory - to reference the sepolicy subdirectory
+and each policy file once created, as shown below. The BOARD_SEPOLICY variables
+and their meaning is documented in the external/sepolicy/README file.</p>
+
+<pre>
+BOARD_SEPOLICY_DIRS += \
+ <root>/device/manufacturer/device-name/sepolicy
+
+BOARD_SEPOLICY_UNION += \
+ genfs_contexts \
+ file_contexts \
+ sepolicy.te
+</pre>
+
+<p>After rebuilding your device, it is enabled with SELinux. You can now either
+customize your SELinux policies to accommodate your own additions to the
+Android operating system as described in <a
+href="customize.html">Customization</a> or verify your existing setup as
+covered in <a href="validate.html">Validation</a>.</p>
+
+<p>Once the new policy files and BoardConfig.mk updates are in place, the new
+policy settings are automatically built into the final kernel policy file.</p>
+
+<h2 id=use_cases>Use cases</h2>
+
+<p>Here are specific examples of exploits to consider when crafting your own
+software and associated SELinux policies:</p>
+
+<p><strong>Symlinks</strong> - Because symlinks appear as files, they are often read just as that. This can
+lead to exploits. For instance, some privileged components such as init change
+the permissions of certain files, sometimes to be excessively open.</p>
+
+<p>Attackers might then replace those files with symlinks to code they control,
+allowing the attacker to overwrite arbitrary files. But if you know your
+application will never traverse a symlink, you can prohibit it from doing so
+with SELinux.</p>
+
+<p><strong>System files</strong> - Consider the class of system files that should only be modified by the
+system server. Still, since netd, init, and vold run as root, they can access
+those system files. So if netd became compromised, it could compromise those
+files and potentially the system server itself.</p>
+
+<p>With SELinux, you can identify those files as system server data files.
+Therefore, the only domain that has read/write access to them is system server.
+Even if netd became compromised, it could not switch domains to the system
+server domain and access those system files although it runs as root.</p>
+
+<p><strong>App data</strong> - Another example is the class of functions that must run as root but should
+not get to access app data. This is incredibly useful as wide-ranging
+assertions can be made, such as certain domains unrelated to application data
+being prohibited from accessing the internet.</p>
+
+<p><strong>setattr</strong> - For commands such as chmod and chown, you could identify the set of files
+where the associated domain can conduct setattr. Anything outside of that could
+be prohibited from these changes, even by root. So an application might run
+chmod and chown against those labeled app_data_files but not shell_data_files
+or system_data_files.</p>
+
+<h2 id=steps_in_detail>Steps in detail</h2>
+
+<p>Here is a detailed view of how Android recommends you employ and customize
+SELinux to protect your devices:</p>
+
+<ol>
+ <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>
+ <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>
+ <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>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
+to assign a new one. Ideally, this will be an existing label which will fit
+into policy, but sometimes a new label will be needed, and rules for access to
+that label will be needed, as well.
+ <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.
+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> 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/validate.jd b/src/devices/tech/security/selinux/validate.jd
new file mode 100644
index 0000000..2734665
--- /dev/null
+++ b/src/devices/tech/security/selinux/validate.jd
@@ -0,0 +1,146 @@
+page.title=Validating SELinux
+@jd:body
+
+<!--
+ Copyright 2014 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>Android strongly encourages OEMs to test their SELinux implementations
+thoroughly. As manufacturers implement SELinux, they should apply the new
+policy to a test pool of devices first.</p>
+
+<p>Once applied, make sure SELinux is running in the correct mode on the device by
+issuing the command:getenforce</p>
+
+<p>This will print the global SELinux mode: either Disabled, Enforcing, or
+Permissive. Please note, this command shows only the global SELinux mode. To
+determine the SELinux mode for each domain, you must examine the corresponding
+files or run the latest version of <code>sepolicy-analyze</code> with the appropriate (-p) flag, present in /platform/external/sepolicy/tools/.</p>
+
+<h2 id=reading_denials>Reading denials</h2>
+
+<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
+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>
+
+<p>With this output, manufacturers can readily identify when system users or
+components are in violation of SELinux policy. Manufacturers can then repair
+this bad behavior, either by changes to the software, SELinux policy, or both.</p>
+
+<p>Specifically, these log messages indicate what processes would fail under
+enforcing mode and why. Here is an example:</p>
+
+<pre>
+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>
+
+<p>Interpret this output like so:</p>
+
+<ul>
+ <li> The <code>{ connectto }</code> above represents the action being taken. Together with the
+<code>tclass</code> at the end (<code>unix_stream_socket</code>), it tells you roughly what was being done
+to what. In this case, something was trying to connect to a unix stream socket.
+ <li> The <code>scontext (u:r:shell:s0)</code> tells you what context initiated the action. In
+this case this is something running as the shell.
+ <li> The <code>tcontext (u:r:netd:s0)</code> tells you the context of the action’s target. In
+this case, that’s a unix_stream_socket owned by <code>netd</code>.
+ <li> The <code>comm="ping"</code> at the top gives you an additional hint about what was being
+run at the time the denial was generated. In this case, it’s a pretty good hint.
+</ul>
+
+<p>And here is another example:</p>
+
+<pre>
+$ adb shell su -c dmesg | grep 'avc: '
+<5> type=1400 audit: avc: denied { read write } for pid=177
+comm="rmt_storage" name="mem" dev="tmpfs" ino=6004 scontext=u:r:rmt:s0
+tcontext=u:object_r:kmem_device:s0 tclass=chr_file
+</pre>
+
+
+<p>Here are the key elements from this denial:</p>
+
+<ul>
+ <li><em>Action</em> - the attempted action is highlighted in brackets, <code>read write</code> or <code>setenforce</code>.
+ <li><em>Actor</em> - The <code>scontext</code> (source context) entry represents the actor, in this case the<code> rmt_storage</code> daemon.
+ <li><em>Object</em> - The <code>tcontext</code> (target context) entry represents the object being acted upon, in this case
+kmem.
+ <li><em>Result</em> - The <code>tclass</code> (target class) entry indicates the type of object being acted upon, in this
+case a <code>chr_file</code> (character device).
+</ul>
+
+<h2 id=switching_to_permissive>Switching to permissive</h2>
+
+<p class="caution"><strong>Important:</strong> Permissive mode is not supported on production devices. CTS tests confirm
+enforcing mode is enabled.</p>
+
+<p>To turn a device’s SELinux enforcement into globally permissive via ADB, as
+root issue:</p>
+
+<pre>
+$ adb shell su -c setenforce 0
+</pre>
+
+<p>Or at the kernel command line (during early device bring-up):</p>
+
+<pre>
+androidboot.selinux=permissive
+androidboot.selinux=disabled
+androidboot.selinux=enforcing
+</pre>
+
+<h2 id=using_audit2allow>Using audit2allow</h2>
+
+<p>The <code>selinux/policycoreutils/audit2allow</code> tool takes <code>dmesg</code> denials and converts them into corresponding SELinux policy statements. As
+such, it can greatly speed SELinux development. To install it, run:</p>
+
+<pre>
+$ sudo apt-get install policycoreutils
+</pre>
+
+<p>To use it:</p>
+
+<pre>
+$ adb shell su -c dmesg | audit2allow
+</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>
+
+<pre>
+#============= shell ==============
+allow shell kernel:security setenforce;
+#============= rmt ==============
+allow rmt kmem_device:chr_file { read write };
+</pre>
+
+
+<p>This would grant <code>rmt</code> the ability to write kernel memory, a glaring security hole. Often the <code>audit2allow</code> statements are only a starting point, after which changes to the source
+domain, the label of the target and the incorporation of proper macros may be
+required to arrive at a good policy. Sometimes the denial being examined should
+not result in any policy changes at all, but rather the offending application
+should be changed.</p>