Docs: Adding SELinux doc to site and nav.
Bug: 9175117
Staging location:
http://claym.mtv.corp.google.com:8093/devices/tech/security/se-linux.html
Change-Id: I2b87d71f8a5416df187f75705e7b334a74a6771e
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 64ff7dc..5446c74 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -169,10 +169,15 @@
<span class="en">Security Enhancements in Android 4.3</span>
</a>
</li>
+ <li>
+ <a href="<?cs var:toroot ?>devices/tech/security/se-linux.html">
+ <span class="en">Security-Enhanced Linux</span>
+ </a>
+ </li>
+
</ul>
</li>
-
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/index.html">
diff --git a/src/devices/tech/security/se-linux.jd b/src/devices/tech/security/se-linux.jd
new file mode 100644
index 0000000..19d8f73
--- /dev/null
+++ b/src/devices/tech/security/se-linux.jd
@@ -0,0 +1,281 @@
+page.title=Security-Enhanced Linux
+@jd:body
+
+<!--
+ Copyright 2010 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.
+-->
+
+<h2 id="introduction">Introduction</h2> <p>In Android 4.3,
+Android begins supporting Security-Enhanced Linux (SELinux), a tool for applying
+access control policies. 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 this same site <a
+href="http://source.android.com/">source.android.com</a>. With SELinux, Android
+can better control access to application data and system logs, reduce the
+effects of malicious software, and protect users from potential flaws in mobile
+code. </p>
+
+<p>In this release, Android includes SELinux in permissive mode and a
+corresponding security policy that works by default across the <a
+href="https://android.googlesource.com/">Android Open Source Project</a>. In
+permissive mode, no actions are prevented. Instead, all potential violations are
+logged by the kernel to dmesg. This allows Android and Android device
+manufacturers to gather information about errors so they may refine their
+software and SELinux policies before enforcing them.</p>
+
+<h2 id="background">Background</h2> <p>Used properly, SELinux greatly limits the
+potential damage of compromised machines and accounts. When you adopt SELinux,
+you instill a structure by which software runs at only the minimum privilege
+level. This mitigates the effects of attacks and reduces the likelihood of
+errant processes overwriting or even transmitting data.</p>
+
+<p>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 user role assigned the root privilege can write to
+only those specified in the associated policy. In this way, root 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>
+
+<h2 id="implementation">Implementation</h2> <p>Android’s initial SELinux
+implementation is launching in permissive mode - rather than the non-functional
+disabled mode or the most stringent enforcing mode - to act as a reference and
+facilitate testing and development.</p>
+
+<p>SELinux is launching in permissive mode on Android to enable the first phase
+of policy development, and it is accompanied by everything you need to enable
+SELinux now.</p>
+
+<p>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/">platform/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>Those files when compiled comprise the SELinux kernel security policy and
+cover the upstream Android operating system. Place those files within the
+<root>/device/manufacturer/device-name/sepolicy directory.</p>
+
+<p>Then just update your BoardConfig.mk makefile - located in the
+<device-name> directory containing the sepolicy subdirectory - to
+reference the sepolicy subdirectory once created, like so: <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 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.</p>
+
+<p>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>See section 9.7 of the Android 4.3 Compatibility Definition document for
+specific requirements:<br><a
+href="{@docRoot}compatibility/android-4.3-cdd.pdf">http://source.android.com/compatibility/android-4.3-cdd.pdf</a></p>
+
+<p>SELinux uses a whitelist approach, meaning it grants special privileges based
+upon role. Because the default policy provided by Android is so permissive, OEMs
+have great leeway in strengthening it. Here is how we recommend proceeding:</p>
+
+<ol> <li> <p>Use the <a
+href="https://android.googlesource.com/kernel/common/">latest Android
+kernel</a>.</p> </li> <li> <p>Adopt the <a
+href="http://en.wikipedia.org/wiki/Principle_of_least_privilege">principle of
+least privilege</a>.</p> </li> <li> <p>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.</p> </li> <li> <p>Compartmentalize software components
+into modules that conduct singular tasks.</p> </li> <li> <p>Create SELinux
+policies that isolate those tasks from unrelated functions.</p> </li> <li>
+<p>Put those policies in *.te files (the extension for SELinux policy source
+files) within the <root>/device/manufacturer/device-name/sepolicy
+directory.</p> </li> <li> <p>Release your SELinux implementation in permissive
+mode first.</p> </li> <li> <p>Analyze results and refine policy settings.</p>
+</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 you’ve added a component that conducts a
+new function, the manufacturer 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 enforcement.</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="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>Symlinks - 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.</p>
+
+<p>But if you know your application will never traverse a symlink, you can
+prohibit it from doing so with SELinux.</p>
+
+<p>System files - 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>App data - Another example is the class of things that must run as root that
+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>setattr - 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="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/">platform/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 on a single domain, you could set that domain to be permissive and
+then have all other functions and their domains set to enforcement. Domains are
+associated with applications by the key used to sign each application. This
+setting is made at the top of each SELinux policy source (*.te) file.</p>
+
+<p>Here are the files you must create or edit in order to customize SELinux:</p>
+<ul> <li> <p>New SELinux policy source (*.te) files - 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> </li> <li> <p>Updated BoardConfig.mk makefile - 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>Updated file_contexts - 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 file_contexts, you must run restorecon 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 files come in the form: allow, domain, and
+context, for a set of actions:</p>
+
+<ul> <li> <p>Allow - Gives the role permission to carry out the action described
+in the context within the specified domain.</p> </li> <li> <p>Domain - Domain
+represents scope of the rule and gets converted to a security identifier (SID)
+in the kernel.</p> </li> <li> <p>Context - An identifier for the rule, converted
+to an integer in the kernel.</p> </li> </ul>
+
+<p>And so the an example use of this would follow the structure:</p> <p>allow
+appdomain app_data_file:file rw_file_perms;</p>
+
+<p>This says an application is allowed to read and write files labeled
+app_data_file. 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 BoardConfig.mk updates are in place, the new
+policy settings get automatically uploaded to the device.</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 devices of employees first as a test.</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 SELinux mode: either Disabled, Enforcing, or Permissive.
+If permissive, you are compliant. Enforcing is explicitly not compliant in
+Android 4.3. (Because of its risk, enforcing mode comes with a much heavier
+testing burden.)</p>
+
+<p>Then check for errors. Errors are routed as event logs to dmesg and 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.</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 roles and processes would fail
+under policy enforcement and why. 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>
+
+<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:<br><a
+href="{@docRoot}compatibility/android-4.3-cdd.pdf">http://source.android.com/compatibility/android-4.3-cdd.pdf</a></p>
+
+<p>If you run the devices through the CTS and find no errors in dmesg, you can
+consider your SELinux implementation compatible.</p>
+
+<p>Finally, if possible, turn on enforcement 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 <a
+href="mailto:security@android.com">security@android.com</a> or Geremy Condra (<a
+href="mailto:gcondra@google.com">gcondra@google.com</a>) directly.
