Difference between revisions of "SEforAndroid"

From SELinux Wiki
Jump to: navigation, search
(Git Trees and Branches)
 
(368 intermediate revisions by the same user not shown)
Line 1: Line 1:
== What is SE Android? ==
+
Security Enhancements (SE) for Android™ was a NSA-led project that created and released an open source reference implementation of how to enable and apply SELinux to Android, made the case for adopting SELinux into mainline Android, and worked with the Android Open Source Project (AOSP) to integrate
 +
the changes into mainline Android. As a result, SELinux is now a core part of Android.
 +
See https://source.android.com/security/selinux/ for further information on SELinux in Android.
  
Security Enhanced (SE) Android is a project to identify and address critical gaps in the security of Android. Initially, the SE Android 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 SE Android project is not limited to SELinux.
+
SE for Android was originally called Security Enhanced Android (SE Android) but was renamed to comply with the Android brand guidelines.
 +
Hence, you will see the older name in many of the presentations and papers below.
  
SE Android also refers to the reference implementation produced by the SE Android project. The current SE Android 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.
+
SE for Android used to maintain its own source code repositories on bitbucket.org but these have been removed since the code has all been merged to AOSP.
 
+
Some distinctive features of our SE Android reference implementation in comparison to prior efforts of which we are aware include:
+
* Per-file security labeling support for yaffs2,
+
* Filesystem images (yaffs2 and ext4) labeled at build time,
+
* Labeling support in the recovery console and updater program,
+
* Kernel permission checks controlling Binder IPC,
+
* Labeling of service sockets and socket files created by init,
+
* Labeling of device nodes created by ueventd,
+
* Flexible, configurable labeling of apps and app data directories,
+
* Minimal port of SELinux userspace,
+
* SELinux support for the Android toolbox,
+
* JNI bindings for SELinux APIs,
+
* Userspace permission checks controlling use of the Zygote socket commands,
+
* Userspace permission checks controlling setting of Android properties,
+
* Small TE policy written from scratch for Android,
+
* Confined domains for system services and apps,
+
* Use of MLS categories to isolate apps.
+
 
+
== SE Android Presentations ==
+
  
 +
Presentations and papers related to SE for Android included:
 
* The Case for SE Android, Linux Security Summit 2011, Sep 2011. [http://selinuxproject.org/~jmorris/lss2011_slides/caseforseandroid.pdf Slides]
 
* 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]
+
* The Case for Security Enhanced (SE) Android, Android Builders Summit 2012, Feb 2012. [https://events.static.linuxfound.org/images/stories/pdf/lf_abs12_smalley.pdf Slides]
* 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.static.linuxfound.org/images/stories/pdf/lcna_co2012_smalley.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]
 
* 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.  [https://www.ndss-symposium.org/ndss2013/ndss-2013-programme/security-enhanced-se-android-bringing-flexible-mac-android Paper and Slides]
 +
*  Laying a Secure Foundation for Mobile Devices, 20th Annual Network and Distributed System Security Symposium (NDSS '13), Feb 2013. [https://www.ndss-symposium.org/ndss2013/ndss-2013-programme/laying-secure-foundation-mobile-devices/ Slides]
 +
* Security Enhancements (SE) for Android, Android Builders Summit 2014, Apr 2014. [https://events.static.linuxfound.org/sites/events/files/slides/abs2014_seforandroid_smalley.pdf Slides]
 +
* Protecting the Android TCB with SELinux, Linux Security Summit 2014, Aug 2014. [http://kernsec.org/files/lss2014/lss2014_androidtcb_smalley.pdf Slides]
 +
* SELinux in Android Lollipop and Marshmallow, Linux Security Summit 2015, Aug 2015. [http://kernsec.org/files/lss2015/lss2015_selinuxinandroidlollipopandm_smalley.pdf Slides]
 +
* ioctl command whitelisting in SELinux, Linux Security Summit 2015, Aug 2015. [http://kernsec.org/files/lss2015/vanderstoep.pdf Slides]
 +
* Android: protecting the kernel, Linux Security Summit, Aug 2016. [http://events17.linuxfoundation.org/sites/events/files/slides/Android-%20protecting%20the%20kernel.pdf Slides]
 +
* Honey I Shrunk the Attack Surface: Adventures in Android Security Hardening, Black Hat USA 2017, July 2017. [https://www.blackhat.com/docs/us-17/thursday/us-17-Kralevich-Honey-I-Shrunk-The-Attack-Surface-Adventures-In-Android-Security-Hardening.pdf Slides]
 +
* SELinux in Android Oreo or: How I Learned to Stop Worrying and Love Attributes, Linux Security Summit 2017, Sep 2017. [http://events17.linuxfoundation.org/sites/events/files/slides/LSS%20-%20Treble%20%27n%27%20SELinux_0.pdf Slides]
 +
* Year in Review: Android Kernel Security, Linux Security Summit 2018, Aug 2018. [https://events.linuxfoundation.org/wp-content/uploads/2017/11/LSS2018.pdf Slides]
 +
* Retrospective: 26 Years of Flexible MAC, Linux Security Summit 2019, Aug 2019. [https://static.sched.com/hosted_files/lssna19/e5/LSS2019-Retrospective-16-9.pdf Slides]
  
== How do I get the SE Android code? ==
+
(Android is a trademark of Google LLC)
 
+
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 (14-16 are known to work, with minor modifications).
+
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 Android should be directed to the seandroid-list mailing list.
+
 
+
=== Using the master branch ===
+
 
+
SE 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 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 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 -j1.  Your tree should now include the SE Android modifications.
+
 
+
An abbreviated example sequence of commands is shown below for downloading the AOSP master branch with
+
the SE Android modifications.
+
<pre>
+
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 -j1
+
</pre>
+
 
+
=== Using a release version ===
+
 
+
We have created branches of SE Android relative to specific Android release versions.
+
For example, the seandroid-4.1.2 branch is relative to the android-4.1.2_r1 tag in AOSP, the
+
seandroid-4.1.1 branch is relative to the android-4.1.1_r6 tag in AOSP, and the seandroid-4.0.4 branch is relative to the android-4.0.4_r2.1 tag in AOSP.
+
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 -j1.  Your tree should now include the SE Android modifications relative
+
to the released version.
+
 
+
An abbreviated example sequence of commands is shown below for downloading Android 4.1.2 with
+
the SE Android modifications.
+
<pre>
+
git clone -b seandroid-4.1.2 https://bitbucket.org/seandroid/manifests.git
+
mkdir seandroid-4.1.2
+
cd seandroid-4.1.2
+
repo init -u https://android.googlesource.com/platform/manifest -b android-4.1.2_r1
+
repo sync
+
cp ../manifests/local_manifest.xml .repo/
+
repo sync -j1
+
</pre>
+
 
+
An abbreviated example sequence of commands is shown below for downloading Android 4.1.1 with
+
the SE Android modifications.
+
<pre>
+
git clone -b seandroid-4.1.1 https://bitbucket.org/seandroid/manifests.git
+
mkdir seandroid-4.1.1
+
cd seandroid-4.1.1
+
repo init -u https://android.googlesource.com/platform/manifest -b android-4.1.1_r6
+
repo sync
+
cp ../manifests/local_manifest.xml .repo/
+
repo sync -j1
+
</pre>
+
 
+
An abbreviated example sequence of commands is shown below for downloading Android 4.0.4 with the SE Android modifications.
+
<pre>
+
git clone -b seandroid-4.0.4 https://bitbucket.org/seandroid/manifests.git
+
mkdir seandroid-4.0.4
+
cd seandroid-4.0.4
+
repo init -u https://android.googlesource.com/platform/manifest -b android-4.0.4_r2.1
+
repo sync
+
cp ../manifests/local_manifest.xml .repo/
+
repo sync -j1
+
</pre>
+
 
+
== Git Trees and Branches ==
+
 
+
In addition to using repo to clone SE Android, it is also possible to
+
directly clone the SE Android git repos via git if you merely want to
+
examine the trees.  The trees 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.
+
 
+
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:
+
<pre>
+
cd kernel/omap
+
git branch -r
+
git checkout bitbucket/seandroid-omap-tuna-3.0
+
git format-patch bitbucket/android-omap-tuna-3.0
+
</pre>
+
 
+
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:
+
<pre>
+
cd seandroid/frameworks/base
+
git format-patch bitbucket/master
+
</pre>
+
 
+
Example for frameworks/base relative to the 4.1.2 release,
+
assuming you cloned the seandroid-4.1.2 branch:
+
<pre>
+
cd seandroid-4.1.2/frameworks/base
+
git format-patch android-4.1.2_r1
+
</pre>
+
 
+
Example for frameworks/base relative to the 4.0.4 release,
+
assuming you cloned the seandroid-4.0.4 branch:
+
<pre>
+
cd seandroid-4.0.4/frameworks/base
+
git format-patch android-4.0.4_r2.1
+
</pre>
+
 
+
libsepol, checkpolicy, libselinux and sepolicy are new trees added for SE 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 14, 15, and 16.  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
+
yum install glibc.i686 glibc-devel.i686 libstdc++.i686 zlib-devel.i686 ncurses-devel.i686 libX11-devel.i686 libXrender.i686 libXrandr.i686 readline-devel.i386 mesa-libGL-devel.i686
+
</pre>
+
 
+
On Fedora 16, you also have to install Switch.pm via CPAN as it is no longer packaged.
+
 
+
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.
+
 
+
The Android build process requires allowing executable stacks.
+
<pre>
+
setsebool allow_execstack=1
+
</pre>
+
 
+
Use setsebool -P if you want this change to persist across reboots.
+
 
+
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:
+
<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 ==
+
 
+
In order to run SE Android on the Android emulator, you need a
+
modified kernel with the necessary support for SELinux.  The
+
emulator kernel is located under kernel/goldfish.
+
<pre>
+
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-
+
</pre>
+
 
+
If building 4.0.4, the compiler toolchain has a different path,
+
<pre>
+
make ARCH=arm CROSS_COMPILE=$PREFIX/prebuilt/linux-x86/toolchain/arm-eabi-4.4.3/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>
+
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:
+
<pre>
+
cd $PREFIX
+
source build/envsetup.sh
+
lunch full-eng
+
export HAVE_SELINUX=true
+
make
+
</pre>
+
 
+
 
+
You must run the emulator with the kernel you built:
+
<pre>
+
emulator -show-kernel -kernel kernel/goldfish/arch/arm/boot/zImage
+
</pre>
+
 
+
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:
+
<pre>
+
export PREFIX=/path/to/your/aospclone
+
cd $PREFIX/kernel/goldfish
+
../../external/qemu/distrib/build-kernel.sh --arch=x86
+
</pre>
+
 
+
You can build the Android userspace for x86 as follows:
+
<pre>
+
cd $PREFIX
+
source build/envsetup.sh
+
lunch full_x86-eng
+
export HAVE_SELINUX=true
+
make
+
</pre>
+
 
+
You must run the emulator with the kernel you built:
+
<pre>
+
emulator -show-kernel -kernel kernel/goldfish/arch/x86/boot/bzImage
+
</pre>
+
 
+
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:
+
<pre>
+
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-
+
</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>
+
 
+
If building 4.0.4, the compiler toolchain has a different path,
+
<pre>
+
make ARCH=arm CROSS_COMPILE=$PREFIX/prebuilt/linux-x86/toolchain/arm-eabi-4.4.3/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 (e.g. samsung) or different
+
devices (e.g. omap, tegra).
+
 
+
{|
+
! align="left" | Device
+
! align="left" | Version
+
! align="left" | Project
+
! align="left" | Branch
+
! align="left" | Config
+
|-
+
| Nexus S
+
| 4.0/ICS
+
| kernel/samsung
+
| seandroid-samsung-3.0-ics-mr1
+
| herring_defconfig
+
|-
+
|-
+
| Nexus S
+
| 4.1/JB
+
| kernel/samsung
+
| seandroid-samsung-3.0-jb
+
| herring_defconfig
+
|-
+
| Motorola Xoom
+
|
+
| kernel/tegra
+
| seandroid-tegra-moto-2.6.39
+
| stingray_defconfig
+
|-
+
| Nexus 7
+
|
+
| kernel/tegra
+
| seandroid-tegra3-grouper-3.1-jb-fr2
+
| tegra3_android_defconfig
+
|-
+
| Galaxy Nexus
+
|
+
| kernel/omap
+
| seandroid-omap-tuna-3.0
+
| tuna_defconfig
+
|-
+
| PandaBoard
+
+
| kernel/omap
+
| seandroid-omap-panda-3.0
+
| panda_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 for the Nexus S, Motorola Xoom,
+
and Galaxy Nexus to refer to our kernel and wireless module 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.
+
<pre>
+
cd $PREFIX
+
source build/envsetup.sh
+
lunch full_maguro-userdebug
+
export HAVE_SELINUX=true
+
make
+
</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.  Some information about how to do this is included in the (old, removed from source.android.com) Android Platform Developer Guide, in the development/pdk/docs/porting/release_keys.jd file.  Note that if you generate your own keys for signing, you need to update the external/sepolicy/mac-permissions.xml configuration accordingly.
+
 
+
== Getting Started with SE Android ==
+
 
+
Once you have the emulator or a device running SE Android, you can run adb shell and then look for signs that SELinux is present, e.g.
+
<pre>
+
getenforce
+
ls -Z
+
ps -Z
+
dmesg
+
</pre>
+
 
+
The Settings app will also show you your current SELinux status
+
(disabled, permissive, or enforcing) under About phone or tablet.
+
The separate SEAndroidManager app allows you to change your enforcing status and policy booleans.
+
 
+
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.
+
<pre>
+
adb shell su 0 dmesg | grep avc
+
</pre>
+
should show no output.
+
 
+
To set enforcing mode at runtime, you can run "setenforce 1"
+
from an adb root shell, e.g.:
+
<pre>
+
adb shell su 0 setenforce 1
+
</pre>
+
 
+
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 SEAndroidManager app to set your enforcing status.
+
The enforcing status will be saved and restored by the app on each boot.
+
 
+
You can capture policy denials for later use in policy debugging as follows:
+
<pre>
+
adb shell su 0 cat /proc/kmsg > dmesg.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 < dmesg.txt
+
</pre>
+
 
+
However, note that you must specify that you are using a policy other than the SELinux policy
+
active on the build host.
+
 
+
== SE Android Policy ==
+
 
+
The SE 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
+
(new) property_contexts configuration, and a (new) seapp_contexts 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. We are still exploring the space of what selectors we can and should use to label apps, so this configuration is still open to change.  The property_contexts and seapp_contexts configurations are unique to SE Android (i.e. they were not part of the regular SELinux policy).
+
 
+
Device-specific additions for the policy configuration can be placed in a sepolicy.te file (for kernel TE policy rules), a sepolicy.fc file (for file_contexts entries), a sepolicy.pc file (for property_contexts entries), a sepolicy.genfs_contexts file (for genfscon entries) or a seapp_contexts file under any of the target/board/<device>, device/<vendor>/<device>, or vendor/<vendor>/<device> directories.  These files if present are merged into the policy during the build.
+
 
+
SE Android 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/system by placing policy files under /data/system 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/system, not the source .te files.
+
 
+
== Running the CTS ==
+
 
+
If you want to run the Android Compatibility Test Suite (CTS) with SE 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 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.
+
<pre>
+
adb shell su 0 setsebool android_cts=1
+
adb shell su 0 setenforce 1
+
</pre>
+
 
+
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.
+
 
+
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.
+
<pre>
+
adb shell su 0 cat /proc/kmsg > dmesg.txt &
+
adb shell logcat *:E > log.txt &
+
</pre>
+
 
+
== Middleware MAC ==
+
 
+
In addition to the base SE Android code, we have a set of experimental extensions to the Android middleware that provide different forms of mandatory restrictions over the Android permissions model.  One of these extensions, install-time MAC (described below), is now merged into the base SE Android code.  The other two extensions, permission revocation and
+
tag propagation, are only presently available in their own separate feature branches. The three mechanisms and their
+
individual feature branches are:
+
* Install-time MAC (merged to seandroid and seandroid-4.1.1),
+
* Permission revocation (revoke-perms-master, revoke-perms-4.1.1), and
+
* Tag propagation (tagprop-master, tagprop-4.1.1).
+
 
+
We are also exploring additional mechanisms for middleware MAC beyond these three mechanisms; in particular, we plan to implement a middleware Flask-based mechanism in the future.
+
 
+
=== 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.mac_enforcing_mode system property controls whether the MAC restrictions are enforced; this can be set via
+
SEManager app or via setprop.  If permissive, then the mechanism will simply log MAC denials, which can be viewed and saved via SEManager.  An updated mac_permissions.xml configuration can be pushed to /data/system/mac_permissions.xml to override the configuration on the system image on the next boot.  This support is included in the base SE Android code.  The setool utility included in external/mac-policy/tools can be used to generate policy stanzas for mac_permissions.xml.
+
 
+
=== 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-master or revoke-perms-4.1.1 branches.
+
 
+
=== Tag Propagation ===
+
 
+
This mechanism implements a form of taint tracking.  Android permissions are mapped to abstract tags as part of the MAC
+
policy configuration (same file as for install-time MAC above, but with a different set of XML tags).  The initial set of tags for each app
+
is determined based on its set of granted permissions.  On inter-component communications, both apps are tainted with the union of the tags.  If set to enforcing, communications that would violate policy rules are blocked.  SEManager can be used to control the enforcing status (the persist.tagprop_enforcing_mode system property), to review and modify the set of tags associated with each app, and to view denials in the logs.  Future extensions will likely include support for marking certain communications as unidirectional for tagging purposes and more expressive ways of specifying policy invariants.  This support is available from the tagprop-master or tagprop-4.1.1 branches.
+
 
+
== For More Information ==
+
 
+
Questions about SE 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 [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 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
+

Latest revision as of 17:37, 20 July 2021

Security Enhancements (SE) for Android™ was a NSA-led project that created and released an open source reference implementation of how to enable and apply SELinux to Android, made the case for adopting SELinux into mainline Android, and worked with the Android Open Source Project (AOSP) to integrate the changes into mainline Android. As a result, SELinux is now a core part of Android. See https://source.android.com/security/selinux/ for further information on SELinux in Android.

SE for Android was originally called Security Enhanced Android (SE Android) but was renamed to comply with the Android brand guidelines. Hence, you will see the older name in many of the presentations and papers below.

SE for Android used to maintain its own source code repositories on bitbucket.org but these have been removed since the code has all been merged to AOSP.

Presentations and papers related to SE for Android included:

  • 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
  • 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 and Slides
  • Laying a Secure Foundation for Mobile Devices, 20th Annual Network and Distributed System Security Symposium (NDSS '13), Feb 2013. Slides
  • Security Enhancements (SE) for Android, Android Builders Summit 2014, Apr 2014. Slides
  • Protecting the Android TCB with SELinux, Linux Security Summit 2014, Aug 2014. Slides
  • SELinux in Android Lollipop and Marshmallow, Linux Security Summit 2015, Aug 2015. Slides
  • ioctl command whitelisting in SELinux, Linux Security Summit 2015, Aug 2015. Slides
  • Android: protecting the kernel, Linux Security Summit, Aug 2016. Slides
  • Honey I Shrunk the Attack Surface: Adventures in Android Security Hardening, Black Hat USA 2017, July 2017. Slides
  • SELinux in Android Oreo or: How I Learned to Stop Worrying and Love Attributes, Linux Security Summit 2017, Sep 2017. Slides
  • Year in Review: Android Kernel Security, Linux Security Summit 2018, Aug 2018. Slides
  • Retrospective: 26 Years of Flexible MAC, Linux Security Summit 2019, Aug 2019. Slides

(Android is a trademark of Google LLC)