Difference between revisions of "SEforAndroid"

From SELinux Wiki
Jump to: navigation, search
(How do I get the code?)
(Replacing page with 'The content of this page has moved to http://seandroid.bitbucket.org/, please update your bookmarks or links.')
Line 1: Line 1:
== What is SE for Android? ==
+
The content of this page has moved to http://seandroid.bitbucket.org/,
 
+
please update your bookmarks or links.
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.
+
 
+
== Merge Status ==
+
 
+
Android 4.3 was the first Android release version to fully include and enable the SELinux support contributed by the SE for Android project.  Android 4.4 is the first release to put SELinux into enforcing mode, beginning by confining a specific set of root daemons.
+
 
+
The Android SELinux support is discussed in https://source.android.com/devices/tech/security/se-linux.html.
+
 
+
You can build Android 4.3 or later and drop in a SELinux-enabled kernel without requiring further changes if you only want the core SELinux functionality.  Under 4.3, you will still need to put the device into enforcing mode, which you can do temporarily via an adb shell su 0 setenforce 1 or permanently by putting setenforce 1 into the init.rc file (make sure the device boots and operates without denials first, as per [[#Getting_Started | Getting Started]]). Under 4.4, the system starts in global enforcing mode although many domains are in per-domain permissive mode by default.
+
 
+
What is missing from mainline Android presently is:
+
* Any of the [[#Middleware_MAC | middleware MAC]] mechanisms, including install-time MAC, except for a restricted form of its seinfo support for labeling apps.
+
 
+
* Our tools for building and using [[#Policy_Updates | policy update]] bundles.
+
 
+
* Our sample policy configuration (Android 4.3 shipped with a policy that was fully permissive and unconfined, while Android 4.4 begins to apply enforcing mode to a specific set of domains).
+
 
+
* Some improvements to how policy reloading is handled, particularly avoiding the need to restart daemons.
+
 
+
* Proper security labeling of multi-user data directories.
+
 
+
If you want this additional functionality or our sample policy configuration, you will still need to download and use our modified projects as described below.
+
 
+
== Papers and Presentations ==
+
 
+
* The Case for SE Android, Linux Security Summit 2011, Sep 2011. [http://selinuxproject.org/~jmorris/lss2011_slides/caseforseandroid.pdf Slides]
+
* The Case for Security Enhanced (SE) Android, Android Builders Summit 2012, Feb 2012. [https://events.linuxfoundation.org/images/stories/pdf/lf_abs12_smalley.pdf Slides] [http://video.linux.com/videos/the-case-for-security-enhanced-se-android Video]
+
* Security Enhanced (SE) Android, 16th Semi-Annual Software Assurance Forum, Mar 2012. [https://buildsecurityin.us-cert.gov/swa/presentations_032612/SE%20Android%20(Panel%20on%20Securing%20Mobile%20Operatins%20Systems)%20-%20Stephen%20Smalley.pdf Slides]
+
* Security Enhanced (SE) Android, LinuxCon North America 2012, Aug 2012.  [https://events.linuxfoundation.org/images/stories/pdf/lcna_co2012_smalley.pdf Slides]
+
* Middleware MAC for Android, Linux Security Summit 2012, Aug 2012.  [http://kernsec.org/files/LSS2012-MiddlewareMAC.pdf Slides]
+
* Security Enhanced (SE) Android:  Bringing Flexible MAC to Android, 20th Annual Network and Distributed System Security Symposium (NDSS '13), Feb 2013.  [http://www.internetsociety.org/sites/default/files/02_4.pdf Paper] [http://www.internetsociety.org/sites/default/files/Presentation02_4.pdf Slides]
+
*  Laying a Secure Foundation for Mobile Devices, 20th Annual Network and Distributed System Security Symposium (NDSS '13), Feb 2013. [http://www.internetsociety.org/sites/default/files/Presentation_Smalley.pdf Slides]
+
* Laying a Secure Foundation for Mobile Devices, International Council on Systems Engineering (INCOSE) Chesapeake Chapter Monthly Meeting, Aug 2013. [http://www.incose-cc.org/http://www.incose-cc.org/images/LayingASecureFoundation-Smalley-2013-08.pdf Slides]
+
* Security Enhancements (SE) for Android, Android Builders Summit 2014, Apr 2014. [http://events.linuxfoundation.org/sites/events/files/slides/abs2014_seforandroid_smalley.pdf 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 [http://source.android.com/source/community/index.html  android-building] discussion group; please ensure that any problems you report there are reproducible when building vanilla AOSP without our modifications.  Questions specific to SE for Android, such as a build problem that only occurs on our branches and not on vanilla AOSP, should be directed to our [[#For_More_Information | seandroid-list]] mailing list, not to android-building.
+
 
+
=== Using the master branch ===
+
 
+
SE for Android development is done relative to the master branch of AOSP, with our remaining 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.  As the bulk of our changes have been merged to AOSP master, you can
+
work directly with the AOSP master branch and not follow the remaining steps below if you only want to use
+
the features and policy that have been merged to AOSP.  You only need to follow the instructions below if you
+
want our remaining changes that have not yet been merged to AOSP, such as the ability to assign seinfo values to
+
third party apps, our [[#Middleware_MAC | middleware MAC]] mechanisms, or our policy configuration.
+
 
+
You can obtain a seandroid.xml local manifest file specifying the projects
+
to override with our remaining modified ones from
+
https://bitbucket.org/seandroid/manifests.
+
Create a local_manifests subdirectory under the .repo subdirectory of your AOSP clone, copy the
+
seandroid.xml file to .repo/local_manifests, and then run repo sync.  Your tree should now include our modifications.
+
 
+
The git projects can be accessed using https or ssh.  Cloning via https from bitbucket.org 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
+
our modifications using https-based access.
+
<pre>
+
git clone https://bitbucket.org/seandroid/manifests.git
+
mkdir seandroid
+
cd seandroid
+
repo init -u https://android.googlesource.com/platform/manifest
+
repo sync
+
mkdir .repo/local_manifests
+
cp ../manifests/seandroid.xml .repo/local_manifests
+
repo sync
+
</pre>
+
 
+
If you have set up an account on bitbucket.org and uploaded a ssh public key, you can use the seandroid-ssh.xml local manifest file instead.
+
 
+
=== Using a release version ===
+
 
+
We have created branches of SE for Android relative to specific Android release versions.
+
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.
+
 
+
You can obtain a seandroid-x.y.z.xml local manifest file specifying the projects to override with our modified ones from
+
https://bitbucket.org/seandroid/manifests.
+
Create a local_manifests subdirectory under the .repo subdirectory of your AOSP clone, copy the
+
seandroid-x.y.z.xml file to .repo/local_manifests, and then run repo sync.  Your tree should now include our modifications relative
+
to the released version.
+
 
+
An abbreviated example sequence of commands is shown below for downloading the android-4.4.3_r1.1 release with
+
our modifications.
+
<pre>
+
git clone https://bitbucket.org/seandroid/manifests.git
+
mkdir seandroid-4.4.3
+
cd seandroid-4.4.3
+
repo init -u https://android.googlesource.com/platform/manifest -b android-4.4.3_r1.1
+
repo sync
+
mkdir .repo/local_manifests
+
cp ../manifests/seandroid-4.4.3.xml .repo/local_manifests
+
repo sync
+
</pre>
+
 
+
If you have set up an account on bitbucket.org and uploaded a ssh public key,
+
you can use the seandroid-4.4.3-ssh.xml local manifest file instead.
+
 
+
== 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 projects can be cloned via:
+
<pre>
+
git clone https://bitbucket.org/seandroid/ + project path
+
</pre>
+
where the "+ project path" is replaced by the path to the specific git project
+
you wish to clone.
+
 
+
Each kernel project has a seandroid-<board>-<version> branch that was
+
forked from the existing android-<board>-<version> branch.  You can
+
extract individual patches from the kernel project 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 Nexus 5 kernel for Android 4.4.3:
+
<pre>
+
cd kernel/msm
+
git checkout bitbucket/seandroid-msm-hammerhead-3.4-kitkat-mr2
+
git format-patch bitbucket/android-msm-hammerhead-3.4-kitkat-mr2
+
</pre>
+
 
+
Each modified AOSP project has a seandroid-<release> branch that was forked from
+
the corresponding release tag.  You can extract individual patches from the AOSP trees
+
by running
+
git format-patch <release-tag>. 
+
 
+
Example for frameworks/base relative to the 4.4.3 release,
+
assuming you cloned the seandroid-4.4.3 branch:
+
<pre>
+
cd seandroid-4.4.3/frameworks/base
+
git format-patch android-4.4.3_r1.1
+
</pre>
+
 
+
== 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.
+
<pre>
+
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
+
</pre>
+
 
+
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:
+
<pre>
+
$ cat /etc/udev/rules.d/51-android.rules
+
ATTR{idVendor}=="18d1", MODE="0666"
+
ATTR{idVendor}=="22b8", MODE="0666"
+
ATTR{idVendor}=="04e8", MODE="0666"
+
</pre>
+
 
+
You can get adb, fastboot, etc in your path by running the
+
following:
+
<pre>
+
export PREFIX=/path/to/your/aospclone
+
cd $PREFIX
+
source build/envsetup.sh
+
setpaths
+
</pre>
+
 
+
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 ==
+
 
+
You can build the Android userspace in the usual manner:
+
<pre>
+
cd $PREFIX
+
source build/envsetup.sh
+
lunch aosp_arm-eng
+
make
+
</pre>
+
 
+
In 4.4, you can start the emulator with SELinux in permissive mode via:
+
<pre>
+
emulator -qemu -append androidboot.selinux=permissive
+
</pre>
+
 
+
On AOSP master, a direct emulator option has been added for the same functionality:
+
<pre>
+
emulator -selinux permissive
+
</pre>
+
 
+
== 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.
+
 
+
Follow the AOSP instructions for building for your device
+
as per
+
http://source.android.com/source/building-devices.html, e.g. for the Nexus 5:
+
<pre>
+
cd $PREFIX
+
source build/envsetup.sh
+
lunch full_hammerhead-userdebug
+
make
+
</pre>
+
 
+
The above example uses the userdebug build variant.  For a production build, you should use a user build instead, e.g.
+
<pre>
+
lunch full_hammerhead-user
+
</pre> 
+
 
+
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.  The build/tools/releasetools/sign_target_files_apks script has been updated to automatically rewrite mac_permissions.xml with the new certificate values when re-signing apks.
+
 
+
== Building Kernels ==
+
 
+
To use SE for Android, you will need a kernel with the necessary support for SELinux.  On 4.3 or later, the
+
prebuilt kernels include SELinux support so you do not need to build your own kernel.  However,
+
you may still wish to build your own kernel to enable
+
more complete auditing support (in particular pathname collection for syscall audit) and other features
+
that are only presently in our kernel trees.
+
 
+
Various kernel source trees are available under the kernel/ directory.  Use the right kernel tree, branch and
+
configuration for your device.  For example, to build
+
for the Nexus 5 phone, you would do the following:
+
<pre>
+
export PREFIX=/path/to/your/aospclone
+
cd $PREFIX/kernel/msm
+
git checkout seandroid-msm-hammerhead-3.4-kitkat-mr2
+
make ARCH=arm hammerhead_defconfig
+
make ARCH=arm CROSS_COMPILE=$PREFIX/prebuilts/gcc/linux-x86/arm/arm-eabi-4.6/bin/arm-eabi-
+
</pre>
+
 
+
On MacOS X, you need to specify the darwin-x86 compiler toolchain instead of the linux-x86 toolchain:
+
<pre>
+
make ARCH=arm CROSS_COMPILE=$PREFIX/prebuilts/gcc/darwin-x86/arm/arm-eabi-4.6/bin/arm-eabi-
+
</pre>
+
 
+
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 or different
+
devices.  Older branches may also exist for earlier Android releases.
+
{|
+
! align="left" | Version
+
! align="left" | Device
+
! align="left" | Project
+
! align="left" | Branch
+
! align="left" | Config
+
! align="left" | Notes
+
|-
+
| 4.4.3
+
| Nexus 5 (hammerhead)
+
| kernel/msm
+
| seandroid-msm-hammerhead-3.4-kitkat-mr2
+
| hammerhead_defconfig
+
| zImage-dtb
+
|-
+
| 4.4.3
+
| Nexus 7 2013 (flo/deb)
+
| kernel/msm
+
| seandroid-msm-flo-3.4-kitkat-mr2
+
| flo_defconfig
+
|
+
|-
+
| 4.4.3
+
| Nexus 10 (manta)
+
| kernel/exynos
+
| seandroid-exynos-manta-3.4-kitkat-mr2
+
| manta_defconfig
+
|
+
|-
+
| 4.4.3
+
| Nexus 4 (mako)
+
| kernel/msm
+
| seandroid-msm-mako-3.4-kitkat-mr2
+
| mako_defconfig
+
| Does not support TARGET_PREBUILT_KERNEL.
+
|-
+
| 4.4.3
+
| Nexus 7 (grouper/tilapia)
+
| kernel/tegra
+
| seandroid-tegra3-grouper-3.1-kitkat-mr2
+
| tegra3_android_defconfig
+
|
+
|-
+
| Any
+
| emulator (goldfish)
+
| kernel/goldfish
+
| seandroid-goldfish-3.4
+
| goldfish_armv7_defconfig
+
| Use -kernel option to emulator.
+
|-
+
|}
+
 
+
For the device, you need your modified kernel to be included in the
+
boot partition image (boot.img) rather than the prebuilt kernel.
+
You can do this by specifying TARGET_PREBUILT_KERNEL to refer to the location of your kernel.
+
You can alternatively unpack the boot image and repack it with your own
+
kernel after building AOSP.
+
 
+
== 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.
+
<pre>
+
getenforce
+
ls -Z
+
ps -Z
+
dmesg | grep SELinux
+
</pre>
+
 
+
On 4.3 and earlier, SELinux defaults to permissive mode, i.e. it will log denials but not enforce them, unless set to enforcing via SEAdmin or by placing
+
a setenforce 1 command in an init.rc file.  On 4.4 and later, SELinux defaults to enforcing unless
+
androidboot.selinux=permissive is passed as a command line argument to the kernel.
+
 
+
Before putting a new board/device into enforcing mode, make sure you don't have any residual denials to address in your
+
policy, e.g.
+
<pre>
+
adb shell su 0 dmesg | grep avc:
+
</pre>
+
should show no output.
+
 
+
In AOSP master, avc denials are also logged to logcat, so you can instead check for denials in your logcat output, e.g.
+
<pre>
+
adb logcat | grep avc:
+
</pre>
+
 
+
To change enforcing mode at runtime, you can run the setenforce command
+
from an adb root shell, e.g.:
+
<pre>
+
# Check current enforcing status.
+
adb shell getenforce
+
# Switch to enforcing.
+
adb shell su 0 setenforce 1
+
# Switch back to permissive.
+
adb shell su 0 setenforce 0
+
</pre>
+
 
+
In addition to the global enforcing mode, SELinux supports a per-domain permissive mode that allows specific processes
+
to operate in permissive mode while the rest of the system remains enforcing.  Per-domain permissive mode is specified
+
in the policy sources via "permissive" declarations.
+
 
+
You can capture policy denials for later use in policy debugging as follows:
+
<pre>
+
adb shell su 0 cat /proc/kmsg > log.txt &
+
</pre>
+
 
+
If on AOSP master, you can redirect logcat output to a file to capture policy denials for later use,
+
<pre>
+
adb logcat > log.txt &
+
</pre>
+
 
+
You can later apply standard SELinux tools such as audit2allow to these logs, as in:
+
<pre>
+
audit2allow -p out/target/product/<device>/root/sepolicy < log.txt
+
</pre>
+
 
+
However, note that you must specify that you are using a policy other than the SELinux policy
+
active on the build host by using the -p option as shown above.
+
 
+
== 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 updated by placing policy files under a subdirectory of /data/security, creating a symbolic link named current under
+
/data/security to that subdirectory, and setting the selinux.reload_policy property to 1 (setprop selinux.reload_policy 1).  This will trigger a reload of policy by init.  Note that for the kernel policy, you must recompile the sepolicy file (make sepolicy) on the build host and push that to the subdirectory of /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 (we have done this on our branches).
+
 
+
Historical note:  The location for updated policy files was originally the existing /data/system directory and then later moved to its own /data/security directory.  In 4.3, the code was further changed to look under /data/security/current, where current is expected to be a symlink to the actual location (typically a subdirectory of /data/security), in order to more easily support policy updates.  See below for an example of using this mechanism to load a policy with dontaudit rules removed.
+
 
+
== Policy Updates ==
+
 
+
Prior to Android 4.3, we developed a set of extensions to the Android device admin APIs for setting enforcing mode, policy booleans, and providing updated policy files to drop under the /data/security directory.  Those APIs were demonstrated by the SEAdmin app.  However, the APIs were not accepted into AOSP and have been dropped from our branches.
+
 
+
Android 4.3 extended the ConfigUpdate mechanism for handling various kinds of configuration updates to also support SELinux policy updates (via
+
the SELinuxPolicyInstallReceiver).  Using this mechanism requires creating a signed policy bundle that can be shipped to the device and then broadcasting an android.intent.action.UPDATE_SEPOLICY Intent on the device to trigger the SELinuxPolicyInstallReceiver to validate the bundle, unpack the policy files from it under /data/security/contexts (with a symbolic link created from /data/security/current) and trigger a policy reload to load the new policy files.
+
 
+
We have added a buildsebundle tool to our external/sepolicy project to support building the policy bundle file and metadata file required by the ConfigUpdate mechanism and packaging them into a zip file that can be pushed to the device.  We have also extended SEAdmin to support taking one of these zip files, unzip it, and generate the Intent to trigger the policy update.  The use of a zip file to package the bundle and the metadata file isn't necessary but is merely a convenience for delivering the files to the device.  SEAdmin was also extended to extract the certificate from otacerts.zip on the device and insert it into the Settings.Secure database on boot, which is required for the ConfigUpdate code to verify the bundle signature.  Normally this would be handled in some other way as part of the original provisioning of the device.
+
 
+
You can run buildsebundle without any arguments to see a help message.
+
Sample usage is shown below (presumes you already have built SE for Android):
+
<pre>
+
source build/envsetup.sh
+
lunch full_manta-userdebug
+
make buildsebundle
+
buildsebundle -k build/target/product/security/testkey.pk8 out/target/product/manta/root/* out/target/product/manta/system/etc/security/mac_permissions.xml
+
adb push selinux_bundle.zip /sdcard/
+
</pre>
+
 
+
Note that buildsebundle will look for files with the expected names for the SELinux policy files from the list of
+
files passed to it and will ignore any others, which is why we can pass a wildcard path above.  All of the SELinux
+
policy files must be included in the update; you cannot only include a subset of them.  Also note that the key specified above is the
+
testkey used by default in AOSP builds; if you generated and are using your own keys for a production device, you will need to specify
+
the path to it.  If you create subsequent policy update bundles, you will need to specify the -v option to buildsebundle with an incrementing
+
version number in order for the update to be applied; the default is 1.  You can optionally specify a -r option with
+
the hash of the previously installed bundle to make installation dependent on a specific prior update.  The hash can be computed via openssl sha512 update_bundle, where update_bundle can be extracted from the zip file for the prior update.
+
 
+
Then, on the device, run SEAdmin, select Kernel and MMAC Policy under POLICY UPDATE OPTIONS, and select Reload Kernel Policies.
+
From an adb shell, check dmesg to confirm that policy was reloaded from /data/security/current/sepolicy,
+
and check the contents of /data/security to see the unpacked policy files under /data/security/contexts.
+
 
+
We have also extended the ConfigUpdate mechanism to handle policy reloads for eops.xml policy files.  A new EopsInstallReceiver has been created to support eops.xml updates. The new receiver works in a similar manner to the SELinuxPolicyInstallReceiver; using a signed bundle to deliver the policy update files after receiving an android.intent.action.UPDATE_EOPS broadcast. Each new mechanism will drop the relevant policy files under /data/security and take precedence over their /system equivalents. Note, the eops.xml file will be loaded and applied at runtime whereas the new mac_permissions.xml policy requires a reboot of the device.
+
 
+
We have also extended the buildbundle suite of tools (external/sepolicy/tools/build_bundle) to help construct the needed signed bundles to deliver to the ConfigUpdate mechanism; buildeopbundle for eops.xml bundles.  The output of each will produce a zip file ready to be delivered to the sdcard and then loaded via new SEAdmin app mechanisms
+
 
+
Lastly, we have started to make use of the IntentFirewall code already present in AOSP since 4.3. A very simple policy can be found at external/sepolicy/ifw.xml which serves to just document the syntax rather than provide a full policy at this time. IntentFirewall can place restrictions on ICC much like our now defunct intent_mac code could do; providing the ability to restrict startActivity, startService, bindService, stopService and sendBroadcast requests. No /system intent firewall policy file is supported at this time but rather new policies are loaded to /data/system/ifw via our SEAdmin app through existing ConfigUpdater backend code. Each new policy that is reloaded is applied dynamically and thus requires no reboot of the device. We have likewise built a new buildifwbundle tool to help build a signed zip to deliver to the existing IntentFirewallInstallReceiver mechanism and then reloaded via a trigger in our SEAdmin app.
+
 
+
== Addressing Hidden Denials ==
+
 
+
If you encounter permission denials while in enforcing mode but do not see any avc: denied messages in the dmesg or logcat output, 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:
+
<pre>
+
cd out/target/product/<device>/obj/ETC/sepolicy_intermediates
+
adb push sepolicy.dontaudit /data/local/tmp
+
adb shell
+
su
+
cd /data/local/tmp
+
mkdir /data/security/dontaudit
+
cp sepolicy.dontaudit /data/security/dontaudit/sepolicy
+
cd /data/security
+
ln -s dontaudit current
+
setprop selinux.reload_policy 1
+
</pre>
+
 
+
Then re-test the operation that was failing and collect the avc: denied messages from dmesg.  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:
+
<pre>
+
adb shell
+
su
+
rm /data/security/current
+
setprop selinux.reload_policy 1
+
</pre>
+
 
+
== 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/.
+
 
+
On 4.3 and earlier, 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 command before running the CTS.  You should make sure you can run the CTS successfully in permissive mode before trying enforcing mode.
+
<pre>
+
adb shell su 0 setenforce 1
+
</pre>
+
 
+
You can also add the setenforce command to your init.rc file to cause it to be executed automatically
+
on each boot of the device, or you can set the enforcing status using SEAdmin.
+
 
+
On 4.4 or later, SELinux is always enforcing.
+
 
+
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.
+
<pre>
+
adb shell su 0 cat /proc/kmsg > dmesg.txt &
+
adb shell logcat > log.txt &
+
</pre>
+
 
+
== 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.  These extensions are collectively referred to as middleware MAC or MMAC. The MMAC mechanisms are described further below.
+
 
+
=== Install-time MAC ===
+
 
+
Install-time MAC assigns a seinfo value to each app when it is installed based on a MAC policy configuration (found in
+
external/sepolicy/mac_permissions.xml in the source tree and as /system/etc/security/mac_permissions.xml on the device). The assignment can be based on the app certificate and optionally refined on a per-package basis.  If there is no matching entry in mac_permissions.xml and there is no default stanza, then our implementation will refuse to install/load the app at all (this behavior is not present in AOSP however).
+
The seinfo value is subsequently used to determine the SELinux security context for the app process and its /data/data directory based on the seapp_contexts configuration (external/sepolicy/seapp_contexts in the source tree, installed to /seapp_contexts).  Our external/sepolicy project includes a tool named setool that 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:
+
<pre>
+
# Generate a stanza assigning the release seinfo value to this package only.
+
setool --seinfo release --build package /path/to/foo.apk
+
# Generate a stanza assigning the release seinfo value to all packages with this signature.
+
setool --seinfo release --build keys /path/to/foo.apk
+
# Check if the apk is assigned a seinfo value by mac_permissions.xml
+
setool --policy /path/to/mac_permissions.xml /path/to/foo.apk
+
</pre>
+
 
+
=== Enterprise Operations (EOps) ===
+
 
+
This MMAC mechanism builds upon the AppOps functionality introduced in Android 4.3 and extends it to support enterprise
+
control over certain runtime application operations.  EOps can be configured via the external/sepolicy/eops.xml file in the source tree (installed as /system/etc/security/eops.xml).  EOps leverages the existing seinfo tags that are assigned to apps upon installation by the Install-time MAC mechanism as a way to group apps into equivalence classes for identifying what operations to block.  Operations identified in the eops.xml configuration are locked and cannot be allowed via AppOps.  The SEAdmin app
+
has been extended to enable the hidden AppOps interface, but
+
the EOps mechanism is not in any way dependent on the SEAdmin app for operation and the SEAdmin app cannot override settings locked by the eops.xml configuration.  Further xml configuration files can be pushed to /data/security/eops to further restrict the configuration.  See the [[#Policy_Updates | Policy Updates]] section for
+
a discussion of how to load additional configurations for EOps at runtime.
+
 
+
=== IntentFirewall ===
+
 
+
IntentFirewall is a mechanism introduced in Android 4.3 and later.  We are presently exploring its use as
+
a potential replacement for our experimental Intent MAC mechanism.  See the [[#Policy_Updates | Policy Updates]] section for
+
a discussion of how to load a configuration for IntentFirewall.
+
 
+
== 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 to seandroid-list-join AT tycho.nsa.gov.  You must subscribe before posting to seandroid-list AT tycho.nsa.gov.  List archives are available
+
via [http://marc.info/?l=seandroid-list MARC] or [http://dir.gmane.org/gmane.comp.security.seandroid GMANE] or [http://www.mail-archive.com/seandroid-list@tycho.nsa.gov/info.html 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 [http://marc.info/?l=selinux MARC] or [http://dir.gmane.org/gmane.comp.security.selinux GMANE] for "android" if you want to read those early discussions.
+
 
+
== External Tools ==
+
 
+
* [https://bitbucket.org/billcroberts/fixup/overview fixup] : script for converting allow rules to use macros
+
* [https://bitbucket.org/joshua_brindle/sepolicy-inject sepolicy-inject] : tool for adding rules to an existing binary policy
+
* [https://bitbucket.org/joshua_brindle/packages-apps-seandroidadmin seandroidadmin] : fork of SEAdmin for GS4
+
 
+
== External Documentation ==
+
 
+
* [http://selinuxproject.org/page/NB_SEforAndroid_1 SELinux Notebook section on SE for Android]
+
 
+
    Android is a trademark of Google Inc.
+

Revision as of 12:54, 17 June 2014

The content of this page has moved to http://seandroid.bitbucket.org/, please update your bookmarks or links.