diff options
author | Clay Murphy <claym@google.com> | 2014-10-14 19:04:29 -0700 |
---|---|---|
committer | Clay Murphy <claym@google.com> | 2014-10-14 19:04:29 -0700 |
commit | 29a7b5b629294c74cbd741ca2eb7f53003469dca (patch) | |
tree | d4758b7c66e922781ea3730b9e599155e7b18119 /src/devices/tech | |
parent | d01c551151026d1f4b6eadf291421425d1fa3212 (diff) | |
download | source.android.com-29a7b5b629294c74cbd741ca2eb7f53003469dca.tar.gz |
Docs: Updating SELinux docs for full enforcement.
Bug: 17376045
Change-Id: I8f78ae474f8a90a6d4f73a2db157bcee549fcc3a
Diffstat (limited to 'src/devices/tech')
-rw-r--r-- | src/devices/tech/security/se-linux.jd | 464 | ||||
-rw-r--r-- | src/devices/tech/security/selinux/concepts.jd | 174 | ||||
-rw-r--r-- | src/devices/tech/security/selinux/customize.jd | 274 | ||||
-rw-r--r-- | src/devices/tech/security/selinux/implement.jd | 184 | ||||
-rw-r--r-- | src/devices/tech/security/selinux/validate.jd | 146 |
5 files changed, 841 insertions, 401 deletions
diff --git a/src/devices/tech/security/se-linux.jd b/src/devices/tech/security/se-linux.jd index ad06feed..6c34a026 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 @@ page.title=Validating Security-Enhanced Linux in Android </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> + +<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>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> + +<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> + +<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> + +<h2 id=background>Background</h2> + +<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> + +<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> -<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> -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> - -<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> - -<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> - 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> - -<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> - -<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. 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> + <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> -<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> +<h2 id=supporting_documentation>Supporting documentation</h2> -<p>Once applied, make sure SELinux is running in the correct mode on the device -by issuing the command: <code>getenforce</code></p> +<p>See the documentation below for details on constructing useful policies:</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><a href="https://seandroid.bitbucket.org/PapersandPresentations.html">https://seandroid.bitbucket.org/PapersandPresentations.html</a></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><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>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><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>Specifically, these log messages indicate what processes would fail -under enforcing mode and why. Here is an example:</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> -<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><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>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> -</ul> +<p><a href="https://www.gnu.org/software/m4/manual/index.html">https://www.gnu.org/software/m4/manual/index.html</a></p> -<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> +<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> -<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> +<h2 id=help>Help</h2> -<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>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 00000000..a0eb2cc9 --- /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 00000000..79ca5d65 --- /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 00000000..9e2e7244 --- /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 00000000..27346656 --- /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> |