1page.title=Validating SELinux
2@jd:body
3
4<!--
5    Copyright 2014 The Android Open Source Project
6
7    Licensed under the Apache License, Version 2.0 (the "License");
8    you may not use this file except in compliance with the License.
9    You may obtain a copy of the License at
10
11        http://www.apache.org/licenses/LICENSE-2.0
12
13    Unless required by applicable law or agreed to in writing, software
14    distributed under the License is distributed on an "AS IS" BASIS,
15    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16    See the License for the specific language governing permissions and
17    limitations under the License.
18-->
19<div id="qv-wrapper">
20  <div id="qv">
21    <h2>In this document</h2>
22    <ol id="auto-toc">
23    </ol>
24  </div>
25</div>
26
27<p>Android strongly encourages OEMs to test their SELinux implementations
28thoroughly. As manufacturers implement SELinux, they should apply the new
29policy to a test pool of devices first.</p>
30
31<p>Once applied, make sure SELinux is running in the correct mode on the device by
32issuing the command:getenforce</p>
33
34<p>This will print the global SELinux mode: either Disabled, Enforcing, or
35Permissive. Please note, this command shows only the global SELinux mode. To
36determine the SELinux mode for each domain, you must examine the corresponding
37files or run the latest version of <code>sepolicy-analyze</code> with the appropriate (-p) flag, present in /platform/external/sepolicy/tools/.</p>
38
39<h2 id=reading_denials>Reading denials</h2>
40
41<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
42SELinux output to dmesg on these devices and refine settings prior to public
43release in permissive mode and eventual switch to enforcing mode. SELinux log
44messages contain "avc:" and so may easily be found with <code>grep</code>. It is
45possible to capture the ongoing denial logs by running <code>cat /proc/kmsg</code>
46or to capture denial logs from the previous boot by running cat <code>/proc/last_kmsg</code>.</p>
47
48<p>With this output, manufacturers can readily identify when system users or
49components are in violation of SELinux policy. Manufacturers can then repair
50this bad behavior, either by changes to the software, SELinux policy, or both.</p>
51
52<p>Specifically, these log messages indicate what processes would fail under
53enforcing mode and why. Here is an example:</p>
54
55<pre>
56avc: denied  { connectto } for  pid=2671 comm="ping" path="/dev/socket/dnsproxyd"
57scontext=u:r:shell:s0 tcontext=u:r:netd:s0 tclass=unix_stream_socket
58</pre>
59
60<p>Interpret this output like so:</p>
61
62<ul>
63  <li> The <code>{ connectto }</code> above represents the action being taken. Together with the
64<code>tclass</code> at the end (<code>unix_stream_socket</code>), it tells you roughly what was being done
65to what. In this case, something was trying to connect to a unix stream socket.
66  <li> The <code>scontext (u:r:shell:s0)</code> tells you what context initiated the action. In
67this case this is something running as the shell.
68  <li> The <code>tcontext (u:r:netd:s0)</code> tells you the context of the action’s target. In
69this case, that’s a unix_stream_socket owned by <code>netd</code>.
70  <li> The <code>comm="ping"</code> at the top gives you an additional hint about what was being
71run at the time the denial was generated. In this case, it’s a pretty good hint.
72</ul>
73
74<p>And here is another example:</p>
75
76<pre>
77$ adb shell su -c dmesg | grep 'avc: '
78&lt;5> type=1400 audit: avc:  denied  { read write } for  pid=177
79comm="rmt_storage" name="mem" dev="tmpfs" ino=6004 scontext=u:r:rmt:s0
80tcontext=u:object_r:kmem_device:s0 tclass=chr_file
81</pre>
82
83
84<p>Here are the key elements from this denial:</p>
85
86<ul>
87  <li><em>Action</em> - the attempted action is highlighted in brackets, <code>read write</code> or <code>setenforce</code>.
88  <li><em>Actor</em> - The <code>scontext</code> (source context) entry represents the actor, in this case the<code> rmt_storage</code> daemon.
89  <li><em>Object</em> - The <code>tcontext</code> (target context) entry represents the object being acted upon, in this case
90kmem.
91  <li><em>Result</em> - The <code>tclass</code> (target class) entry indicates the type of object being acted upon, in this
92case a <code>chr_file</code> (character device).
93</ul>
94
95<h2 id=switching_to_permissive>Switching to permissive</h2>
96
97<p class="caution"><strong>Important:</strong> Permissive mode is not supported on production devices. CTS tests confirm
98enforcing mode is enabled.</p>
99
100<p>To turn a device’s SELinux enforcement into globally permissive via ADB, as
101root issue:</p>
102
103<pre>
104$ adb shell su -c setenforce 0
105</pre>
106
107<p>Or at the kernel command line (during early device bring-up):</p>
108
109<pre>
110androidboot.selinux=permissive
111androidboot.selinux=disabled
112androidboot.selinux=enforcing
113</pre>
114
115<h2 id=using_audit2allow>Using audit2allow</h2>
116
117<p>The <code>selinux/policycoreutils/audit2allow</code> tool takes <code>dmesg</code> denials and converts them into corresponding SELinux policy statements. As
118such, it can greatly speed SELinux development. To install it, run:</p>
119
120<pre>
121$ sudo apt-get install policycoreutils
122</pre>
123
124<p>To use it on Ubuntu 12.04, run:</p>
125
126<pre>
127$ adb shell su -c dmesg | audit2allow
128</pre>
129
130<p>On Ubuntu 14.04 and newer, audit2allow requires you to specify the Android policy
131using the -p option, e.g.
132<pre>
133$ adb shell su -c dmesg | audit2allow -p out/target/product/&lt;device&gt;/root/sepolicy
134</pre>
135
136<p>Nevertheless, care must be taken to examine each potential addition for
137overreaching permissions. For example, feeding audit2allow the <code>rmt_storage</code> denial shown earlier results in the following suggested SELinux policy
138statement:</p>
139
140<pre>
141#============= shell ==============
142allow shell kernel:security setenforce;
143#============= rmt ==============
144allow rmt kmem_device:chr_file { read write };
145</pre>
146
147
148<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
149domain, the label of the target and the incorporation of proper macros may be
150required to arrive at a good policy. Sometimes the denial being examined should
151not result in any policy changes at all, but rather the offending application
152should be changed.</p>
153