1 page.title=Customizing 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>Once you've integrated this base level of functionality and thoroughly analyzed 28 the results, you may add your own policy settings to cover your customizations 29 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> 30 31 <p>Manufacturers should not remove existing security settings. Otherwise, they 32 risk breaking the Android SELinux implementation and the applications it 33 governs. This includes third-party applications that will likely need to be 34 improved to be compliant and operational. Applications must require no 35 modification to continue functioning on SELinux-enabled devices.</p> 36 37 <p>When embarking upon customizing SELinux, manufacturers should remember to:</p> 38 39 <ul> 40 <li>Write SELinux policy for all new daemons 41 <li>Use predefined domains whenever appropriate 42 <li>Assign a domain to any process spawned as an <code>init</code> service 43 <li>Become familiar with the macros before writing policy 44 <li>Submit changes to core policy to AOSP 45 </ul> 46 47 <p>And not to:</p> 48 49 <ul> 50 <li>Create incompatible policy 51 <li>Allow end user policy customization 52 <li>Allow MDM policy customizations 53 <li>Scare users with policy violations 54 <li>Add backdoors 55 </ul> 56 57 <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> 58 59 <p>SELinux uses a whitelist approach, meaning all access must be explicitly 60 allowed in policy in order to be granted. Since Android's default SELinux 61 policy already supports the Android Open Source Project, OEMs are not required 62 to modify SELinux settings in any way. If they do customize SELinux settings, 63 they should take great care not to break existing applications. Here is how we 64 recommend proceeding:</p> 65 66 <ol> 67 <li>Use the <a href="https://android.googlesource.com/kernel/common/">latest Android kernel</a>. 68 <li>Adopt the <a href="http://en.wikipedia.org/wiki/Principle_of_least_privilege">principle of least privilege</a>. 69 <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. 70 <li>Compartmentalize software components into modules that conduct singular tasks. 71 <li>Create SELinux policies that isolate those tasks from unrelated functions. 72 <li>Put those policies in *.te files (the extension for SELinux policy source 73 files) within the <code>/device/manufacturer/device-name/sepolicy</code> directory and use 74 <code>BOARD_SEPOLICY</code> variables to include them in your build. 75 <li>Make new domains permissive initially. This is done by 76 using a permissive declaration in the domain's .te file. 77 <li>Analyze results and refine your domain definitions. 78 <li>Remove the permissive declaration when no further denials appear in userdebug 79 builds. 80 </ol> 81 82 <p>Once integrated, OEM Android development should include a step to ensure 83 SELinux compatibility going forward. In an ideal software development process, 84 SELinux policy changes only when the software model changes and not the actual 85 implementation.</p> 86 87 <p>As device manufacturers begin to customize SELinux, they should first audit 88 their additions to Android. If they've added a component that conducts a new 89 function, the manufacturers will need to ensure the component meets the 90 security policy applied by Android, as well as any associated policy crafted by 91 the OEM, before turning on enforcing mode.</p> 92 93 <p>To prevent unnecessary issues, it is better to be overbroad and over-compatible 94 than too restrictive and incompatible, which results in broken device 95 functions. Conversely, if a manufacturer's changes will benefit others, it 96 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> 97 98 <h2 id=example_policy_statements>Example policy statements</h2> 99 100 <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> 101 102 <p>In the following example, all domains are granted access to read from or write to <code>/dev/null</code> and read from <code>/dev/zero</code>.</p> 103 104 <pre> 105 # Allow read / write access to /dev/null 106 allow domain null_device:chr_file { getattr open read ioctl lock append write}; 107 108 # Allow read-only access to /dev/zero 109 allow domain zero_device:chr_file { getattr open read ioctl lock }; 110 </pre> 111 112 113 <p>This same statement can be written with SELinux <code>*_file_perms</code> macros (shorthand):</p> 114 115 <pre> 116 # Allow read / write access to /dev/null 117 allow domain null_device:chr_file rw_file_perms; 118 119 # Allow read-only access to /dev/zero 120 allow domain zero_device:chr_file r_file_perms; 121 </pre> 122 123 <h2 id=example_policy>Example policy</h2> 124 125 <p>Here is a complete example policy for DHCP, which we examine below:</p> 126 127 <pre> 128 type dhcp, domain; 129 permissive dhcp; 130 type dhcp_exec, exec_type, file_type; 131 type dhcp_data_file, file_type, data_file_type; 132 133 init_daemon_domain(dhcp) 134 net_domain(dhcp) 135 136 allow dhcp self:capability { setgid setuid net_admin net_raw net_bind_service 137 }; 138 allow dhcp self:packet_socket create_socket_perms; 139 allow dhcp self:netlink_route_socket { create_socket_perms nlmsg_write }; 140 allow dhcp shell_exec:file rx_file_perms; 141 allow dhcp system_file:file rx_file_perms; 142 # For /proc/sys/net/ipv4/conf/*/promote_secondaries 143 allow dhcp proc_net:file write; 144 allow dhcp system_prop:property_service set ; 145 unix_socket_connect(dhcp, property, init) 146 147 type_transition dhcp system_data_file:{ dir file } dhcp_data_file; 148 allow dhcp dhcp_data_file:dir create_dir_perms; 149 allow dhcp dhcp_data_file:file create_file_perms; 150 151 allow dhcp netd:fd use; 152 allow dhcp netd:fifo_file rw_file_perms; 153 allow dhcp netd:{ dgram_socket_class_set unix_stream_socket } { read write }; 154 allow dhcp netd:{ netlink_kobject_uevent_socket netlink_route_socket 155 netlink_nflog_socket } { read write }; 156 </pre> 157 158 <p>Lets dissect the example:</p> 159 160 <p>In the first line, the type declaration, the DHCP daemon inherits from the base 161 security policy (<code>domain</code>). From the previous statement examples, we know DHCP can read from and write 162 to <code>/dev/null.</code></p> 163 164 <p>In the second line, DHCP is identified as a permissive domain.</p> 165 166 <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> 167 168 <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> 169 170 <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 SELinuxs 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> 171 172 <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 173 policy says DHCP and netd may communicate with one another via file 174 descriptors, FIFO files, datagram sockets, and UNIX stream sockets. DHCP may 175 only read to and write from the datagram sockets and UNIX stream sockets and 176 not create or open them.</p> 177 178 <h2 id=available_controls>Available controls</h2> 179 180 <table> 181 <tr> 182 <td> 183 <p><strong>Class</strong></p> 184 </td> 185 <td> 186 <p><strong>Permission</strong></p> 187 </td> 188 </tr> 189 <tr> 190 <td> 191 <p>file</p> 192 </td> 193 <td> 194 <pre> 195 ioctl read write create getattr setattr lock relabelfrom relabelto append 196 unlink link rename execute swapon quotaon mounton</pre> 197 </td> 198 </tr> 199 <tr> 200 <td> 201 <p>directory</p> 202 </td> 203 <td> 204 <pre> 205 add_name remove_name reparent search rmdir open audit_access execmod</pre> 206 </td> 207 </tr> 208 <tr> 209 <td> 210 <p>socket</p> 211 </td> 212 <td> 213 <pre> 214 ioctl read write create getattr setattr lock relabelfrom relabelto append bind 215 connect listen accept getopt setopt shutdown recvfrom sendto recv_msg send_msg 216 name_bind</pre> 217 </td> 218 </tr> 219 <tr> 220 <td> 221 <p>filesystem</p> 222 </td> 223 <td> 224 <pre> 225 mount remount unmount getattr relabelfrom relabelto transition associate 226 quotamod quotaget</pre> 227 </td> 228 </tr> 229 <tr> 230 <td> 231 <p>process</p> 232 </td> 233 <td> 234 <pre> 235 fork transition sigchld sigkill sigstop signull signal ptrace getsched setsched 236 getsession getpgid setpgid getcap setcap share getattr setexec setfscreate 237 noatsecure siginh setrlimit rlimitinh dyntransition setcurrent execmem 238 execstack execheap setkeycreate setsockcreate</pre> 239 </td> 240 </tr> 241 <tr> 242 <td> 243 <p>security</p> 244 </td> 245 <td> 246 <pre> 247 compute_av compute_create compute_member check_context load_policy 248 compute_relabel compute_user setenforce setbool setsecparam setcheckreqprot 249 read_policy</pre> 250 </td> 251 </tr> 252 <tr> 253 <td> 254 <p>capability</p> 255 </td> 256 <td> 257 <pre> 258 chown dac_override dac_read_search fowner fsetid kill setgid setuid setpcap 259 linux_immutable net_bind_service net_broadcast net_admin net_raw ipc_lock 260 ipc_owner sys_module sys_rawio sys_chroot sys_ptrace sys_pacct sys_admin 261 sys_boot sys_nice sys_resource sys_time sys_tty_config mknod lease audit_write 262 audit_control setfcap</pre> 263 </td> 264 </tr> 265 <tr> 266 <td> 267 <p><strong>MORE</strong></p> 268 </td> 269 <td> 270 <p><strong>AND MORE</strong></p> 271 </td> 272 </tr> 273 </table> 274
