diff options
author | Clay Murphy <claym@google.com> | 2013-07-22 12:54:07 -0700 |
---|---|---|
committer | Clay Murphy <claym@google.com> | 2013-07-22 12:54:07 -0700 |
commit | 51dbe2deeb83cc5265789b66a47f000e46a58099 (patch) | |
tree | 1ba0193a34b7356e7ef0c7d9e5e0e32cfe5b5017 | |
parent | 3b2ef63c2f0f6b837bc800e4ab92fe3517d135ed (diff) | |
download | source.android.com-51dbe2deeb83cc5265789b66a47f000e46a58099.tar.gz |
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
-rw-r--r-- | src/devices/devices_toc.cs | 7 | ||||
-rw-r--r-- | src/devices/tech/security/se-linux.jd | 281 |
2 files changed, 287 insertions, 1 deletions
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs index 64ff7dce..5446c740 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 00000000..19d8f735 --- /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. |