From 51dbe2deeb83cc5265789b66a47f000e46a58099 Mon Sep 17 00:00:00 2001 From: Clay Murphy Date: Mon, 22 Jul 2013 12:54:07 -0700 Subject: Docs: Adding SELinux doc to site and nav. Bug: 9175117 Staging location: http://claym.mtv.corp.google.com:8093/devices/tech/security/se-linux.html Change-Id: I2b87d71f8a5416df187f75705e7b334a74a6771e --- src/devices/devices_toc.cs | 7 +- src/devices/tech/security/se-linux.jd | 281 ++++++++++++++++++++++++++++++++++ 2 files changed, 287 insertions(+), 1 deletion(-) create mode 100644 src/devices/tech/security/se-linux.jd diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs index 64ff7dce..5446c740 100644 --- a/src/devices/devices_toc.cs +++ b/src/devices/devices_toc.cs @@ -169,10 +169,15 @@ Security Enhancements in Android 4.3 +
  • + + Security-Enhanced Linux + +
    • + -
  • diff --git a/src/devices/tech/security/se-linux.jd b/src/devices/tech/security/se-linux.jd new file mode 100644 index 00000000..19d8f735 --- /dev/null +++ b/src/devices/tech/security/se-linux.jd @@ -0,0 +1,281 @@ +page.title=Security-Enhanced Linux +@jd:body + + + +

    Introduction

    In Android 4.3, +Android begins supporting Security-Enhanced Linux (SELinux), a tool for applying +access control policies. SELinux enhances Android security, and contributions to +it have been made by a number of companies and organizations; all Android code +and contributors are publicly available for review on this same site source.android.com. With SELinux, Android +can better control access to application data and system logs, reduce the +effects of malicious software, and protect users from potential flaws in mobile +code.

    + +

    In this release, Android includes SELinux in permissive mode and a +corresponding security policy that works by default across the Android Open Source Project. In +permissive mode, no actions are prevented. Instead, all potential violations are +logged by the kernel to dmesg. This allows Android and Android device +manufacturers to gather information about errors so they may refine their +software and SELinux policies before enforcing them.

    + +

    Background

    Used properly, SELinux greatly limits the +potential damage of compromised machines and accounts. When you adopt SELinux, +you instill a structure by which software runs at only the minimum privilege +level. This mitigates the effects of attacks and reduces the likelihood of +errant processes overwriting or even transmitting data.

    + +

    SELinux provides a mandatory access control (MAC) umbrella over traditional +discretionary access control (DAC) environments. For instance, software must +typically run as the root user account to write to raw block devices. In a +traditional DAC-based Linux environment, if the root user becomes compromised +that user can write to every raw block device. However, SELinux can be used to +label these devices so the user role assigned the root privilege can write to +only those specified in the associated policy. In this way, root cannot +overwrite data and system settings outside of the specific raw block device.

    + +

    See the Use Cases section for more examples of threats and ways to +address them with SELinux.

    + +

    Implementation

    Android’s initial SELinux +implementation is launching in permissive mode - rather than the non-functional +disabled mode or the most stringent enforcing mode - to act as a reference and +facilitate testing and development.

    + +

    SELinux is launching in permissive mode on Android to enable the first phase +of policy development, and it is accompanied by everything you need to enable +SELinux now.

    + +

    You merely need to integrate the latest Android kernel +and then incorporate the files found in the ~platform/external/sepolicy +directory:
    +https://android.googlesource.com/kernel/common/ +
    +https://android.googlesource.com/platform/external/sepolicy/

    + +

    Those files when compiled comprise the SELinux kernel security policy and +cover the upstream Android operating system. Place those files within the +<root>/device/manufacturer/device-name/sepolicy directory.

    + +

    Then just update your BoardConfig.mk makefile - located in the +<device-name> directory containing the sepolicy subdirectory - to +reference the sepolicy subdirectory once created, like so: 

    +BOARD_SEPOLICY_DIRS := \ /device/manufacturer/device-name/sepolicy
+
+BOARD_SEPOLICY_UNION := \ genfs_contexts \ file_contexts \ sepolicy.te
    +

    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 Customization section or verify +your existing setup as covered in the Validation section.

    + +

    Customization

    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 Android Compatibility +program requirements and not remove the default SELinux settings.

    + +

    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.

    + +

    See section 9.7 of the Android 4.3 Compatibility Definition document for +specific requirements:
    http://source.android.com/compatibility/android-4.3-cdd.pdf

    + +

    SELinux uses a whitelist approach, meaning it grants special privileges based +upon role. Because the default policy provided by Android is so permissive, OEMs +have great leeway in strengthening it. Here is how we recommend proceeding:

    + +

    1. Use the latest Android +kernel.

    2. Adopt the principle of +least privilege.

    3. Address only your own additions to +Android. The default policy works with the Android Open Source Project +codebase automatically.

    4. Compartmentalize software components +into modules that conduct singular tasks.

    5. Create SELinux +policies that isolate those tasks from unrelated functions.

    6. +

      Put those policies in *.te files (the extension for SELinux policy source +files) within the <root>/device/manufacturer/device-name/sepolicy +directory.

    7. Release your SELinux implementation in permissive +mode first.

    8. Analyze results and refine policy settings.

      +
    + +

    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.

    + +

    As device manufacturers begin to customize SELinux, they should first audit +their additions to Android. If you’ve added a component that conducts a +new function, the manufacturer will need to ensure the component meets the +security policy applied by Android, as well as any associated policy crafted by +the OEM, before turning on enforcement.

    + +

    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 patch. 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.

    + +

    Use Cases

    Here are specific examples of exploits to +consider when crafting your own software and associated SELinux policies:

    + +

    Symlinks - Because symlinks appear as files, they are often read just as +that. This can lead to exploits. For instance, some privileged components such +as init change the permissions of certain files, sometimes to be excessively +open.

    + +

    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.

    + +

    System files - Consider the class of system files that should only be +modified by the system server. Still, since netd, init, and vold run as root, +they can access those system files. So if netd became compromised, it could +compromise those files and potentially the system server itself.

    + +

    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.

    + +

    App data - Another example is the class of things that must run as root that +should not get to access app data. This is incredibly useful as wide-ranging +assertions can be made, such as certain domains unrelated to application data +being prohibited from accessing the internet.

    + +

    setattr  - For commands such as chmod and chown, you could identify the +set of files where the associated domain can conduct setattr. Anything outside +of that could be prohibited from these changes, even by root. So an application +might run chmod and chown against those labeled app_data_files but not +shell_data_files or system_data_files.

    This section serves to guide you once you’ve decided to +customize the SELinux policy settings. See the Customization 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 ~platform/external/sepolicy +directory.

    + +

    Android upgraded its SELinux policy version to allow the SELinux mode to be +set to permissive on a per-domain basis. For example, if you run all of your +applications on a single domain, you could set that domain to be permissive and +then have all other functions and their domains set to enforcement. Domains are +associated with applications by the key used to sign each application. This +setting is made at the top of each SELinux policy source (*.te) file.

    + +

    Here are the files you must create or edit in order to customize SELinux:

    +

    • New SELinux policy source (*.te) files - Located in the +<root>/device/manufacturer/device-name/sepolicy directory These files +define domains and their labels. The new policy files get concatenated with the +existing policy files during compilation into a single SELinux kernel policy +file.

    • Updated BoardConfig.mk makefile - Located in the +<device-name> directory containing the sepolicy subdirectory. It must be +updated to reference the sepolicy subdirectory once created if it wasn’t +in initial implementation.

    • Updated file_contexts - Located in +the sepolicy subdirectory. It labels files and is managed in the userspace. As +you create new policies, update this file to reference them. In order to apply +new file_contexts, you must run restorecon on the file to be relabeled.

      +
    + +

    The remaining files in the /sepolicy directory are either auto-generated or +should remain static. The policy files come in the form: allow, domain, and +context, for a set of actions:

    + +

    • Allow - Gives the role permission to carry out the action described +in the context within the specified domain.

    • Domain - Domain +represents scope of the rule and gets converted to a security identifier (SID) +in the kernel.

    • Context - An identifier for the rule, converted +to an integer in the kernel.

    + +

    And so the an example use of this would follow the structure:

    allow +appdomain app_data_file:file rw_file_perms;

    + +

    This says an application is allowed to read and write files labeled +app_data_file. During compilation, those overrides are concatenated to the +existing SELinux settings and into a single security policy. These overrides add +to the base security policy rather than subtract from existing settings.

    + +

    Once the new policy files and BoardConfig.mk updates are in place, the new +policy settings get automatically uploaded to the device.

    + +

    Validation

    Android strongly encourages OEMs to test +their SELinux implementations thoroughly. As manufacturers implement SELinux, +they should initially release their own policies in permissive mode. If +possible, apply the new policy to devices of employees first as a test.

    + +

    Once applied, make sure SELinux is running in the correct mode on the device +by issuing the command: getenforce

    + +

    This will print the SELinux mode: either Disabled, Enforcing, or Permissive. +If permissive, you are compliant. Enforcing is explicitly not compliant in +Android 4.3. (Because of its risk, enforcing mode comes with a much heavier +testing burden.)

    + +

    Then check for errors. Errors are routed as event logs to dmesg and viewable +locally on the device. Manufacturers should examine the SELinux output to dmesg +on these devices and refine settings prior to public release in permissive +mode.

    + +

    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.

    + +

    Specifically, these log messages indicate what roles and processes would fail +under policy enforcement and why. Android is taking this information, analyzing +it and refining its default security policy so that it works on a wide range of +Android devices with little customization. With this policy, OEMs must only +accommodate their own changes to the Android operating system.

    + +

    Then run the SELinux-enabled devices through the Android +Compatibility Test Suite (CTS).

    As said, any new policies must still +meet the Android +Compatibility program requirements:
    http://source.android.com/compatibility/android-4.3-cdd.pdf

    + +

    If you run the devices through the CTS and find no errors in dmesg, you can +consider your SELinux implementation compatible.

    + +

    Finally, if possible, turn on enforcement internally (on devices of +employees) to raise the visibility of failures. Identify any user issues and +resolve them.

    Help

    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 or Geremy Condra (gcondra@google.com) directly. -- cgit v1.2.3