1 page.title=Implementing 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>SELinux is set up to default-deny, which means that every single access for 28 which it has a hook in the kernel must be explicitly allowed by policy. This 29 means a policy file is comprised of a large amount of information regarding 30 rules, types, classes, permissions, and more. A full consideration of SELinux 31 is out of the scope of this document, but an understanding of how to write 32 policy rules is now essential when bringing up new Android devices. There is a 33 great deal of information available regarding SELinux already. See <a 34 href="{@docRoot}devices/tech/security/selinux/index.html#supporting_documentation">Supporting 35 documentation</a> for suggested resources.</p> 36 37 <h2 id=summary_of_steps>Summary of steps</h2> 38 39 <p>Here is a brief summary of the steps needed to implement SELinux on your 40 Android device:</p> 41 42 <ol> 43 <li>Add SELinux support in the kernel and configuration. 44 <li>Grant each service (process or daemon) started from <code>init</code> its own domain. 45 <li>Identify these services by: 46 <ul> 47 <li>Reviewing the init.<device>.rc file and finding all services. 48 <li>Examining warnings of the form <em>init: Warning! Service name needs a SELinux domain defined; please fix!</em> in <code>dmesg</code> output. 49 <li>Checking <code>ps -Z | grep init</code> output to see which services are running in the init domain. 50 </ul> 51 <li>Label all new processes, drivers, sockets, etc. 52 All objects need to be labeled 53 properly to ensure they interact properly with the policies you apply. See the 54 labels used in AOSP for examples to follow in label name creation. 55 <li>Institute security policies that fully cover all labels and restrict 56 permissions to their absolute minimum. 57 </ol> 58 59 <p>Ideally, OEMs start with the policies in the AOSP and then build upon them for 60 their own customizations.</p> 61 62 <h2 id=key_files>Key files</h2> 63 64 <p>SELinux for Android is accompanied by everything you need to enable SELinux 65 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/system/sepolicy/">system/sepolicy</a> directory:</p> 66 67 <p><a href="https://android.googlesource.com/kernel/common/">https://android.googlesource.com/kernel/common/ </a></p> 68 69 <p><a href="https://android.googlesource.com/platform/system/sepolicy/">https://android.googlesource.com/platform/system/sepolicy/</a></p> 70 71 <p>Those files when compiled comprise the SELinux kernel security policy and cover 72 the upstream Android operating system. You should not need to modify the 73 system/sepolicy files directly. Instead, add your own device-specific policy 74 files within the /device/manufacturer/device-name/sepolicy directory.</p> 75 76 <p>Here are the files you must create or edit in order to implement SELinux:</p> 77 78 <ul> 79 <li><em>New SELinux policy source (*.te) files</em> - Located in the 80 <root>/device/manufacturer/device-name/sepolicy directory. These files define 81 domains and their labels. The new policy files get 82 concatenated with the existing policy files during compilation into a single 83 SELinux kernel policy file. 84 <p class="caution"><strong>Important:</strong> Do not alter the app.te file 85 provided by the Android Open Source Project. 86 Doing so risks breaking all third-party applications.</p> 87 <li><em>Updated BoardConfig.mk makefile</em> - Located in the <device-name> 88 directory containing the sepolicy subdirectory. It must be updated to reference 89 the sepolicy subdirectory once created if it 90 wasnt in initial implementation. 91 <li><em>file_contexts</em> - Located in the sepolicy subdirectory. This file 92 assigns labels to files and is used by various userspace components. As you 93 create new policies, create or update this file to 94 assign new labels to files. In order to apply new file_contexts, you must 95 rebuild the filesystem image or run <code>restorecon</code> on the file to be 96 relabeled. On upgrades, changes to file_contexts are automatically applied to 97 the system and userdata partitions as part of the upgrade. Changes can also be 98 automatically applied on upgrade to other partitions by adding 99 restorecon_recursive calls to your init.<em>board</em>.rc file after the 100 partition has been mounted read-write. 101 <li><em>genfs_contexts</em> - Located in the sepolicy subdirectory. This file 102 assigns labels to filesystems such as proc or vfat that do not support extended 103 attributes. This configuration is loaded as part of the kernel policy but 104 changes may not take effect for in-core inodes, requiring a reboot or 105 unmounting and re-mounting the filesystem to fully apply the change. Specific 106 labels may also be assigned to specific mounts such as vfat using the context= 107 mount option. 108 <li><em>property_contexts</em> - Located in the sepolicy subdirectory. This 109 file assigns labels to Android system properties to control what processes can 110 set them. This configuration is read by the init process during startup. 111 <li><em>service_contexts</em> - Located in the sepolicy subdirectory. This 112 file assigns labels to Android binder services to control what processes can 113 add (register) and find (lookup) a binder reference for the service. This 114 configuration is read by the servicemanager process during startup. 115 <li><em>seapp_contexts</em> - Located in the sepolicy subdirectory. This file 116 assigns labels to app processes and /data/data directories. This configuration 117 is read by the zygote process on each app launch and by installd during 118 startup. 119 <li><em>mac_permissions.xml</em> - Located in the sepolicy subdirectory. This 120 file assigns a seinfo tag to apps based on their signature and optionally their 121 package name. The seinfo tag can then be used as a key in the seapp_contexts 122 file to assign a specific label to all apps with that seinfo tag. This 123 configuration is read by system_server during startup. 124 </ul> 125 126 <p>Then just update your BoardConfig.mk makefile - located in the directory 127 containing the sepolicy subdirectory - to reference the sepolicy subdirectory 128 and each policy file once created, as shown below. The BOARD_SEPOLICY variables 129 and their meaning is documented in the system/sepolicy/README file.</p> 130 131 <pre> 132 BOARD_SEPOLICY_DIRS += \ 133 <root>/device/manufacturer/device-name/sepolicy 134 135 BOARD_SEPOLICY_UNION += \ 136 genfs_contexts \ 137 file_contexts \ 138 sepolicy.te 139 </pre> 140 141 <p class="note"><strong>Note:</strong> As of the M release, 142 BOARD_SEPOLICY_UNION is no longer required as all policy files found within any 143 directory included in the BOARD_SEPOLICY_DIRS variable are joined with the 144 base policy automatically.</p> 145 146 <p>After rebuilding your device, it is enabled with SELinux. You can now either 147 customize your SELinux policies to accommodate your own additions to the 148 Android operating system as described in <a 149 href="customize.html">Customization</a> or verify your existing setup as 150 covered in <a href="validate.html">Validation</a>.</p> 151 152 <p>Once the new policy files and BoardConfig.mk updates are in place, the new 153 policy settings are automatically built into the final kernel policy file.</p> 154 155 <h2 id=use_cases>Use cases</h2> 156 157 <p>Here are specific examples of exploits to consider when crafting your own 158 software and associated SELinux policies:</p> 159 160 <p><strong>Symlinks</strong> - Because symlinks appear as files, they are often read just as that. This can 161 lead to exploits. For instance, some privileged components such as init change 162 the permissions of certain files, sometimes to be excessively open.</p> 163 164 <p>Attackers might then replace those files with symlinks to code they control, 165 allowing the attacker to overwrite arbitrary files. But if you know your 166 application will never traverse a symlink, you can prohibit it from doing so 167 with SELinux.</p> 168 169 <p><strong>System files</strong> - Consider the class of system files that should only be modified by the 170 system server. Still, since netd, init, and vold run as root, they can access 171 those system files. So if netd became compromised, it could compromise those 172 files and potentially the system server itself.</p> 173 174 <p>With SELinux, you can identify those files as system server data files. 175 Therefore, the only domain that has read/write access to them is system server. 176 Even if netd became compromised, it could not switch domains to the system 177 server domain and access those system files although it runs as root.</p> 178 179 <p><strong>App data</strong> - Another example is the class of functions that must run as root but should 180 not get to access app data. This is incredibly useful as wide-ranging 181 assertions can be made, such as certain domains unrelated to application data 182 being prohibited from accessing the internet.</p> 183 184 <p><strong>setattr</strong> - For commands such as chmod and chown, you could identify the set of files 185 where the associated domain can conduct setattr. Anything outside of that could 186 be prohibited from these changes, even by root. So an application might run 187 chmod and chown against those labeled app_data_files but not shell_data_files 188 or system_data_files.</p> 189 190 <h2 id=steps_in_detail>Steps in detail</h2> 191 192 <p>Here is a detailed view of how Android recommends you employ and customize 193 SELinux to protect your devices:</p> 194 195 <ol> 196 <li>Enable SELinux in the kernel: 197 <code>CONFIG_SECURITY_SELINUX=y</code> 198 <li>Change the kernel_cmdline parameter so that:<br/> 199 <code>BOARD_KERNEL_CMDLINE := androidboot.selinux=permissive</code>. 200 <br/> 201 This is only for initial development of policy for the device. Once you have 202 an initial bootstrap policy, remove this parameter so that your device is 203 enforcing or it will fail CTS. 204 <li>Boot up the system in permissive and see what denials are encountered on boot:<br/> 205 On Ubuntu 14.04 or newer: 206 <br/> 207 <code>adb shell su -c dmesg | grep denied | audit2allow -p out/target/product/<em>board</em>/root/sepolicy</code> 208 <br/> 209 On Ubuntu 12.04: 210 <code>adb shell su -c dmesg | grep denied | audit2allow</code> 211 <li>Evaluate the output. See <a href="validate.html">Validation</a> for instructions and tools. 212 <li>Identify devices, and other new files that need labeling. 213 <li>Use existing or new labels for your objects. 214 Look at the *_contexts files to 215 see how things were previously labeled and use knowledge of the label meanings 216 to assign a new one. Ideally, this will be an existing label which will fit 217 into policy, but sometimes a new label will be needed, and rules for access to 218 that label will be needed, as well. 219 <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/> 220 <code>$ adb shell su -c ps -Z | grep init</code><br/> 221 <code>$ adb shell su -c dmesg | grep 'avc: '</code> 222 <li>Review init.<device>.rc to identify any which are without a type. 223 These should 224 be given domains EARLY in order to avoid adding rules to init or otherwise 225 confusing <code>init</code> accesses with ones that are in their own policy. 226 <li>Set up <code>BOARD_CONFIG.mk</code> to use <code>BOARD_SEPOLICY_*</code> variables. See 227 the README in system/sepolicy for details on setting this up. 228 <li> Examine the init.<device>.rc and fstab.<device> file and make sure every use of mount 229 corresponds to a properly labeled filesystem or that a context= mount option is specified. 230 <li> Go through each denial and create SELinux policy to properly handle each. See 231 the examples within <a href="customize.html">Customization</a>. 232 </ol> 233
