SEforAndroid

From SELinux Wiki
Revision as of 17:04, 20 June 2013 by StephenSmalley (Talk | contribs)

Jump to: navigation, search

What is SE for Android?

Security Enhancements for Android™ (SE for Android) is a project to identify and address critical gaps in the security of Android. Initially, the project is enabling the use of SELinux in Android in order to limit the damage that can be done by flawed or malicious apps and in order to enforce separation guarantees between apps. However, the scope of the project is not limited to SELinux.

SE for Android also refers to the reference implementation produced by the project. The current reference implementation provides a worked example of how to enable and apply SELinux at the lower layers of the Android software stack and provides a working demonstration of the value provided by SELinux in confining various root exploits and application vulnerabilities.

Papers and Presentations

  • The Case for SE Android, Linux Security Summit 2011, Sep 2011. Slides
  • The Case for Security Enhanced (SE) Android, Android Builders Summit 2012, Feb 2012. Slides Video
  • Security Enhanced (SE) Android, 16th Semi-Annual Software Assurance Forum, Mar 2012. Slides
  • Security Enhanced (SE) Android, LinuxCon North America 2012, Aug 2012. Slides
  • Middleware MAC for Android, Linux Security Summit 2012, Aug 2012. Slides
  • Security Enhanced (SE) Android: Bringing Flexible MAC to Android, 20th Annual Network and Distributed System Security Symposium (NDSS '13), Feb 2013. Paper Slides
  • Laying a Secure Foundation for Mobile Devices, 20th Annual Network and Distributed System Security Symposium (NDSS '13), Feb 2013. Slides

How do I get the code?

First, you should make sure that you are able to successfully download, build and run the Android Open Source Project (AOSP) source code by following the instructions starting from http://source.android.com/source/initializing.html.

The AOSP instructions are for Ubuntu or MacOS X users; we are building on 64-bit Fedora. Some Fedora-specific notes can be found further below. Ubuntu or MacOS X should also work as build hosts; see the AOSP instructions for specific information about building AOSP on those operating systems.

General questions about building and running Android should be directed to the android-building discussion group. Only questions specific to SE for Android should be directed to the seandroid-list mailing list.

Using the master branch

SE for Android development is done relative to the master branch of AOSP, with our changes on a seandroid branch. If you want to work with the latest SE for Android code, you should clone the master branch of AOSP as your starting point.

Once you have successfully built and run AOSP, you can obtain a local_manifest.xml file specifying the SE for Android git trees from https://bitbucket.org/seandroid/manifests. Copy this file to the .repo subdirectory of your AOSP clone, and then run repo sync. Your tree should now include the SE for Android modifications.

The git projects can be accessed using https or ssh. Cloning via https can sometimes fail, particularly for large repos. Cloning via ssh requires that you first set up an account on bitbucket.org and upload a public key.

An abbreviated example sequence of commands is shown below for downloading the AOSP master branch with the SE for Android modifications using https-based access.

git clone https://bitbucket.org/seandroid/manifests.git
mkdir seandroid
cd seandroid
repo init -u https://android.googlesource.com/platform/manifest
repo sync
cp ../manifests/local_manifest.xml .repo
repo sync

If you have set up an account on bitbucket.org and uploaded a ssh public key, you can use the ssh-based local manifest instead, as shown below.

git clone -b master-ssh git@bitbucket.org:seandroid/manifests.git
mkdir seandroid
cd seandroid
repo init -u https://android.googlesource.com/platform/manifest
repo sync
cp ../manifests/local_manifest.xml .repo
repo sync

Using a release version

We have created branches of SE for Android relative to specific Android release versions. The base version is the name of the AOSP release tag from which the branch was forked. If you want to use a stable release of Android as your baseline, then you should clone the corresponding release tag of AOSP as your starting point.

Once you have successfully built and run the AOSP sources, you can obtain the version-specific local_manifest.xml file from the corresponding seandroid-4.x.y branch of https://bitbucket.org/seandroid/manifests. Copy this file to the .repo subdirectory of your AOSP clone, and then run repo sync. Your tree should now include the SE for Android modifications relative to the released version.

An abbreviated example sequence of commands is shown below for downloading Android 4.2 with the SE for Android modifications.

git clone -b seandroid-4.2 https://bitbucket.org/seandroid/manifests.git
mkdir seandroid-4.2
cd seandroid-4.2
repo init -u https://android.googlesource.com/platform/manifest -b android-4.2.2_r1
repo sync
cp ../manifests/local_manifest.xml .repo/
repo sync

If you want to use ssh-based access instead, have set up an account on bitbucket.org and have uploaded a ssh public key, you can use the -ssh branch of the manifests project.

git clone -b seandroid-4.2-ssh git@bitbucket.org:seandroid/manifests.git
mkdir seandroid-4.2
cd seandroid-4.2
repo init -u https://android.googlesource.com/platform/manifest -b android-4.2.2_r1
repo sync
cp ../manifests/local_manifest.xml .repo/
repo sync

The same instructions can be applied for other versions such as 4.1.2, but we recommend using the latest version.

Git Trees and Branches

In addition to using repo to clone SE for Android, it is also possible to directly clone the SE for Android git repos via git if you merely want to examine the trees. The trees can be cloned via:

git clone https://bitbucket.org/seandroid/ + project path

where the "+ project path" is replaced by the path to the specific git project you wish to clone.

The manifests git project contains the local_manifest.xml files. The master branch contains a local_manifest.xml file referencing the seandroid branch relative to AOSP master, while the seandroid-4.x.y branches contain a local_manifest.xml file referencing the seandroid-4.x.y branches relative to specific AOSP releases.

Each kernel tree has a seandroid-<board>-<version> branch that was forked from the existing android-<board>-<version> branch. You can extract individual patches from the kernel trees by running git format-patch <remote-name>/android-<board>-<version>. If you cloned via repo, then the <remote-name> will be bitbucket; if you cloned directly via git clone, then the <remote-name> will be origin. Example for the Galaxy Nexus kernel:

cd kernel/omap
git branch -r
git checkout bitbucket/seandroid-omap-tuna-3.0-jb-mr1.1
git format-patch bitbucket/android-omap-tuna-3.0-jb-mr1.1

Each modified AOSP tree has a seandroid branch that was forked from the master branch and a set of seandroid-x.y.z branches. You can extract individual patches from the AOSP trees by running git format-patch <remote-name>/master (for the seandroid branch) or git format-patch <release-tag> (for the seandroid-x.y.z branches). Example for frameworks/base relative to the master branch, assuming you cloned the seandroid branch:

cd seandroid/frameworks/base
git format-patch bitbucket/master

Example for frameworks/base relative to the 4.2 release, assuming you cloned the seandroid-4.2 branch:

cd seandroid-4.2/frameworks/base
git format-patch android-4.2.2_r1

libsepol, checkpolicy, libselinux and sepolicy are new trees added for SE for Android. libsepol and checkpolicy are a port of the SELinux policy compiler, modified slightly to build as part of Android and to build on MacOS X. These two components are only built for the build host and are not installed to the device. libselinux is a port of a subset of the upstream libselinux to Android plus some new Android-specific interfaces, while sepolicy is a completely new SELinux policy written from scratch for Android. libselinux is built for both the build host (for use by certain build tools) and for the device. sepolicy is built once; the binary policy format is architecture-independent.

Fedora-Specific Notes

AOSP only officially supports building on specific versions of Ubuntu and MacOS X. We have been building on Fedora in addition to Ubuntu and MacOS X. This section contains some tips for building on Fedora if you wish to do so. We have successfully built on 64-bit Fedora. Beyond a typical install, we typically have to install the following to build AOSP. The precise package list may vary for different versions of Fedora.

yum groupinstall "Development Tools" "Development Libraries"
yum install gperf perl-Switch
yum install glibc.i686 glibc-devel.i686 libstdc++.i686 zlib-devel.i686 ncurses-devel.i686 libX11-devel.i686 libXrender.i686 libXrandr.i686 readline-devel.i686 mesa-libGL-devel.i686

AOSP only officially supports the Oracle/Sun JDK, not OpenJDK. Improved support for OpenJDK has been going into the master branch, but it is unclear as to whether it yields a working result. We are presently building with the Sun JDK. Obtain the Oracle/Sun JDK, install it, and remove OpenJDK or make sure the Oracle/Sun JDK location comes first in your PATH.

You may need to patch the LOCAL_LDLIBS definitions of some makefiles to include all library dependencies. We had to add LOCAL_LDLIBS += -lX11 to development/tools/emulator/opengl/host/renderer/Android.mk.

You will need to add udev rules under /etc/udev/rules.d if you want to be able to access a device via adb without being root. For example:

$ cat /etc/udev/rules.d/51-android.rules
ATTR{idVendor}=="18d1", MODE="0666"
ATTR{idVendor}=="22b8", MODE="0666"
ATTR{idVendor}=="04e8", MODE="0666"

You can get adb, fastboot, etc in your path by running the following:

export PREFIX=/path/to/your/aospclone
cd $PREFIX
source build/envsetup.sh
setpaths

If you have run lunch in the same shell in order to build AOSP, then your path is already set correctly.

Building for the Emulator

In order to run SE for Android on the Android emulator, you need a modified kernel with the necessary support for SELinux. The emulator kernel is located under kernel/goldfish.

export PREFIX=/path/to/your/aospclone
cd $PREFIX/kernel/goldfish
make ARCH=arm goldfish_armv7_defconfig
make ARCH=arm CROSS_COMPILE=$PREFIX/prebuilts/gcc/linux-x86/arm/arm-eabi-4.6/bin/arm-eabi-

On MacOS X, you need to specify the darwin-x86 compiler toolchain instead of the linux-x86 toolchain:

make ARCH=arm CROSS_COMPILE=$PREFIX/prebuilts/gcc/darwin-x86/arm/arm-eabi-4.6/bin/arm-eabi-

and you must follow the steps described in: http://code.google.com/p/android/issues/detail?id=2755

You can build the Android userspace in the usual manner, except that you must specify HAVE_SELINUX=true on the make command line or set it in your environment prior to running make:

cd $PREFIX
source build/envsetup.sh
lunch full-eng
export HAVE_SELINUX=true
make

(It is no longer necessary to set HAVE_SELINUX=true for master builds, but it remains true for 4.2.)

You must run the emulator with the kernel you built:

emulator -show-kernel -kernel kernel/goldfish/arch/arm/boot/zImage

The above command presumes that you previously ran lunch (as during a build) or manually set your ANDROID_PRODUCT_OUT and PATH variables appropriately.

Building for the x86-based Emulator

Building for the Android x86 emulator is similar to the above instructions, but using the x86 goldfish_defconfig as the kernel configuration and the full_x86-eng userspace build target. To build the kernel, you can do the following:

export PREFIX=/path/to/your/aospclone
cd $PREFIX/kernel/goldfish
../../external/qemu/distrib/build-kernel.sh --arch=x86

You can build the Android userspace for x86 as follows:

cd $PREFIX
source build/envsetup.sh
lunch full_x86-eng
export HAVE_SELINUX=true
make

You must run the emulator with the kernel you built:

emulator -show-kernel -kernel kernel/goldfish/arch/x86/boot/bzImage

The above command presumes that you previously ran lunch (as during a build) or manually set your ANDROID_PRODUCT_OUT and PATH variables appropriately.

Building for a Device

It is advisable to make a backup of your device prior to trying to install AOSP on it, typically using a recovery ROM such as ClockworkMod. Also note that you will erase your user data when you unlock the bootloader. Finally, keep in mind that AOSP does not include various proprietary apps such as the Google apps so you will not have them in your build unless you extract a copy from your device and re-package them for your build.

As in the emulator case, you will need to build a modified kernel with the necessary support for SELinux. Various kernels are available under the kernel/ directory. Use the right kernel tree, branch and configuration for your device; the defconfig files have been modified to enable the necessary options for SELinux. For example, to build for the Galaxy Nexus phone, you would do the following:

export PREFIX=/path/to/your/aospclone
cd $PREFIX/kernel/omap
make ARCH=arm tuna_defconfig
make ARCH=arm CROSS_COMPILE=$PREFIX/prebuilts/gcc/linux-x86/arm/arm-eabi-4.6/bin/arm-eabi-

On MacOS X, you need to specify the darwin-x86 compiler toolchain instead of the linux-x86 toolchain:

make ARCH=arm CROSS_COMPILE=$PREFIX/prebuilts/gcc/darwin-x86/arm/arm-eabi-4.6/bin/arm-eabi-

General AOSP instructions for building kernels can be found at: http://source.android.com/source/building-kernels.html. However, those instructions are for rebuilding the kernel that matches the AOSP prebuilt kernel; you will need to instead use our branches or port our modifications over to the kernel you are using. The correct kernel project, branch, and config to use for each device is shown below. Note that there may be multiple branches in the same kernel project for different Android versions (e.g. samsung) or different devices (e.g. omap, tegra). Older branches may also exist for earlier Android releases.

Version Device Project Branch Config
4.2.2 Nexus 10 kernel/exynos seandroid-exynos-manta-3.4-jb-mr1.1 manta_defconfig
4.2.2 Nexus 4 kernel/msm seandroid-msm-mako-3.4-jb-mr1.1 mako_defconfig
4.2.2 Nexus 7 kernel/tegra seandroid-tegra3-grouper-3.1-jb-mr1.1 tegra3_android_defconfig
4.2.2 Galaxy Nexus kernel/omap seandroid-omap-tuna-3.0-jb-mr1.1 tuna_defconfig

For the device, you need your modified kernel to be included in the boot partition image (boot.img) rather than the prebuilt kernel. We have modified the device/<vendor>/<board>/device.mk files in our branches to refer to a locally built kernel rather than the prebuilt ones. You can do the same for other devices. You can alternatively unpack the boot image and repack it with your own kernel after building AOSP.

Follow the AOSP instructions for building for your device as per http://source.android.com/source/building-devices.html except that you will need to specify HAVE_SELINUX=true on the make command line or set it in your environment prior to running make, e.g.

cd $PREFIX
source build/envsetup.sh
lunch full_maguro-userdebug
export HAVE_SELINUX=true
make

(It is no longer necessary to set HAVE_SELINUX=true for master builds, but it remains true for 4.2.)

The above example uses the userdebug build variant. For a production build, you should use a user build instead, e.g.

lunch full_maguro-user

The build system signs packages with the testkeys provided in the source tree. Because the testkeys are part of the standard Android open source distribution, they should never be used for production devices. Instead, you should generate and use your own private keys for creating production builds. The development/tools/make_key script can be used to generate keys; you can see how it was used to generate the test keys in the build/target/product/security/README file. Note that if you generate your own keys for signing, you need to update the external/sepolicy/keys.conf configuration with the paths to the production keys. This configuration is used to generate the final mac_permissions.xml configuration.

Getting Started

Once you have the emulator or a device running SE for Android, you can run adb shell and then look for signs that SELinux is present, e.g.

getenforce
ls -Z
ps -Z
dmesg | grep SELinux

The separate SEAdmin app allows you to view or change your enforcing status and policy booleans. You must first activate it as a device admin, then activate it as a SELinux admin, and then select the SELinux Admin to view or change the SELinux settings (and similarly for MMAC administration, which deals with the middleware MAC mechanisms).

By default, the system will be in permissive mode, i.e. it will log SELinux denials but not enforce them. Before putting it into enforcing mode, make sure you don't have any residual denials to address in your policy, e.g.

adb shell su 0 dmesg | grep avc

or, if running auditd,

adb shell su 0 cat /data/misc/audit/audit.log | grep avc

should show no output.

To set enforcing mode at runtime, you can run "setenforce 1" from an adb root shell, e.g.:

adb shell su 0 setenforce 1

To cause the phone to always boot in enforcing mode, add "setenforce 1" to one of the init.rc files, rebuild, and reflash your boot image.

Alternatively, you can use the SEAdmin app to set your enforcing status. The enforcing status will be saved and restored by the app on each boot.

If not running auditd, you can capture policy denials for later use in policy debugging as follows:

adb shell su 0 cat /proc/kmsg > dmesg.txt &

If running auditd, the denials will be written instead to /data/misc/audit/audit.log on the device.

You can later apply standard SELinux tools such as audit2allow to these logs, as in:

audit2allow -p out/target/product/<device>/root/sepolicy < dmesg.txt

However, note that you must specify that you are using a policy other than the SELinux policy active on the build host.

Policy

The SE for Android policy sources are located under external/sepolicy. The policy consists of source files used to generate the SELinux kernel policy file, a file_contexts configuration, a property_contexts configuration, a seapp_contexts configuration, and a mac_permissions.xml configuration. The file_contexts configuration is used to label files at build time (e.g. the system partition) and at runtime (e.g. device nodes, service socket files, /data directories created by init.rc, ...). The property_contexts configuration is used to specify the security context of Android properties for permission checking purposes. The seapp_contexts configuration is used to label app processes and app package directories. The mac_permissions.xml configuration is the middleware MAC policy. The property_contexts, seapp_contexts, and mac_permissions.xml configurations are unique to SE for Android (i.e. they were not part of the regular SELinux policy).

Device-specific policy can be specified by defining BOARD_SEPOLICY_DIRS, BOARD_SEPOLICY_UNION and/or BOARD_SEPOLICY_REPLACE variables in a BoardConfig.mk file under the device/<vendor>/<device> or vendor/<vendor>/<device> directories. An example can be found in device/samsung/tuna/BoardConfig.mk, which defines these variables to reference device-specific policy files under device/samsung/tuna/sepolicy. Documentation for per-device policy can be found in external/sepolicy/README.

SELinux kernel policy is presently compiled as part of the Android build and added to the ramdisk image so that it can be loaded by init very early in boot, before mounting the system partition. Once the data partition has been mounted, policy can be reloaded from /data/security by placing policy files under /data/security and setting the selinux.reload_policy property to 1 (setprop selinux.reload_policy 1). This will trigger a reload of policy by init, which will also restart ueventd and installd so that they can reload the policy configuration files relevant to their operation. Note that for the kernel policy, you must recompile the sepolicy file (make sepolicy) on the build host and push that to /data/security, not the source .te files. If you want the policy to be loaded from /data/security automatically on each boot, add the setprop command to the post-fs-data section of the init.rc file.

Addressing Hidden Denials

If you encounter permission denials while in enforcing mode but do not see any avc: denied messages in the dmesg output or /data/misc/audit/audit.log (if running auditd), then you may need to install a modified policy with dontaudit rules stripped in order to find the underlying cause. The dontaudit rules are normally present to avoid noise in the audit logs from harmless application probing or permission tests used to select a different code path rather than being required for operation. To install and load the policy with dontaudit rules removed, do the following:

cd out/target/product/<device>/obj/ETC/sepolicy_intermediates
adb push sepolicy.dontaudit /data/local/tmp
adb shell
su
cd /data/local/tmp
cp sepolicy.dontaudit /data/security/sepolicy
setprop selinux.reload_policy 1 

Then re-test the operation that was failing and collect the avc: denied messages from dmesg or /data/misc/audit/audit.log. Be careful to not blindly allow all such permissions as many of them will be unnecessary and not directly relevant to the operation that was failing. When you are finished testing, revert to the original policy as follows:

adb shell
su
rm /data/security/sepolicy
setprop selinux.reload_policy 1

Running the CTS

If you want to run the Android Compatibility Test Suite (CTS) with SE for Android, you should follow the standard instructions as per http://source.android.com/compatibility/.

Additionally, you will need to set the android_cts policy boolean to enable certain policy rules that are specific to the CTS instrumentation that runs on the device, and you will need to enable enforcing mode if you want to test the impact of an enforcing SE for Android system. This can be done by executing the following commands before running the CTS. You should make sure you can run the CTS successfully in permissive mode before trying enforcing mode.

adb shell su 0 setsebool android_cts=1
adb shell su 0 setenforce 1

You can also add the setsebool and setenforce commands to your init.rc file to cause them to be executed automatically on each boot of the device, or you can set the booleans and enforcing status using SEAdmin.

You may wish to collect any permission denials and log messages that occur during the CTS execution for later use in diagnosing failures and amending the policy to better support the CTS. Policy changes that are specific to the CTS instrumentation on the device should go into the sepolicy/cts.te file within the if (android_cts) conditional block, while generic changes suitable for production devices should be integrated into the appropriate policy files.

adb shell su 0 cat /proc/kmsg > dmesg.txt &
adb shell logcat *:E > log.txt &

Middleware MAC

In addition to the SELinux enhancements to Android, we have a set of extensions to the Android middleware that provide different forms of mandatory restrictions over the Android permissions and Inter-Component Communication (ICC) model. One of these extensions, install-time MAC, is now merged into our main seandroid branch. The other extensions are only presently available in their own separate feature branches.

Install-time MAC

This mechanism applies an install-time check of app permissions against a MAC policy configuration (found in external/sepolicy/mac_permissions.xml in the source tree and as etc/security/mac_permissions.xml on the system image). The persist.mmac.enforce system property controls whether the MAC restrictions are enforced; this can be set via SEAdmin app or via setprop. If permissive, then the mechanism will simply log MAC denials, which can be viewed and saved via SEAdmin. An updated mac_permissions.xml configuration can be pushed to /data/security/mac_permissions.xml to override the configuration on the system image on the next boot. This support is included in the main seandroid branch. The setool program can be used to generate policy stanzas for mac_permissions.xml, or to check whether a given apk would violate a given mac_permissions.xml configuration.

setool --build whitelist /path/to/foo.apk
setool --policy /path/to/mac_permissions.xml /path/to/foo.apk

Permission Revocation

This mechanism, based on a similar mechanism in CyanogenMod, supports revocation of permissions from installed apps. A revoked permission list is maintained for each package and checked at runtime on permission checks. A revoked permissions configuration (found in external/mac-policy/revoke_permissions.xml in the source tree and as etc/security/revoke_permissions.xml on the system image) can specify revocation lists that are applied automatically on each boot. An updated revoke_permissions.xml configuration can be pushed to /data/system/revoke_permissions.xml to override the configuration on the system image on the next boot. This support is available from the revoke-perms branch.

Intent MAC

Intent MAC provides control over the delivery of Intents to Activities, Broadcast Receivers, and Services. Intent MAC is configured via the mmac_types.xml file and the intent_mac.xml file under external/sepolicy (on the intent_mac branch). This support is available from the intent_mac branch.

Content Provider MAC

Content Provider MAC provides control over the ability to use, read, and write Content Providers. Content Provider MAC is configured via the content_permissions.xml file under external/sepolicy (on the cp_mac branch). This support is available from the cp_mac branch.

For More Information

Questions about SE for Android may be directed to the public seandroid-list AT tycho.nsa.gov mailing list. You can subscribe to the list by sending an email containing "subscribe seandroid-list" as the body (not the subject) to majordomo AT tycho.nsa.gov. You must subscribe before posting to seandroid-list AT tycho.nsa.gov. List archives are available via majordomo (using the index and get commands). The archives can also be read or searched via GMANE or mail-archive.com.

You may also send private email to our team alias, seandroid AT tycho.nsa.gov. However, whenever possible, please use the public mailing list.

Early SE for Android discussions occurred on the public selinux mailing list prior to the creation of the seandroid-list. You can search the selinux mailing list archives at MARC or GMANE for "android" if you want to read those early discussions.

External Tools

  • fixup : script for converting allow rules to use macros

External Documentation

   Android is a trademark of Google Inc.