Difference between revisions of "SEforAndroid"

From SELinux Wiki
Jump to: navigation, search
(Fedora-Specific Notes)
(535 intermediate revisions by 2 users 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.
  
SE Android was first publically described in a presentation at the
+
Presentations and papers describing SE for Android included:
Linux Security Summit 2011. The slides from that talk can be found at
+
* The Case for SE Android, Linux Security Summit 2011, Sep 2011. [http://selinuxproject.org/~jmorris/lss2011_slides/caseforseandroid.pdf Slides]
http://selinuxproject.org/~jmorris/lss2011_slides/caseforseandroid.pdf.
+
* 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]
 +
* 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.  [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. [http://events.linuxfoundation.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]
  
Some distinctive features of our SE Android reference implementation in comparison to prior efforts of which we are aware include:
+
Further talks describing the impact of SELinux on Android security and further SELinux development in Android include:
* Per-file security labeling support for yaffs2,
+
* ioctl command whitelisting in SELinux, Linux Security Summit 2015, Aug 2015. [http://kernsec.org/files/lss2015/vanderstoep.pdf Slides]
* Filesystem images labeled at build time,
+
* Android: protecting the kernel, Linux Security Summit, Aug 2016. [http://events17.linuxfoundation.org/sites/events/files/slides/Android-%20protecting%20the%20kernel.pdf Slides]
* Kernel permission checks controlling Binder IPC,
+
* 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]
* Labeling of service sockets and socket files created by init,
+
* 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]
* Labeling of device nodes created by ueventd,
+
* Year in Review: Android Kernel Security, Linux Security Summit 2018, Aug 2018. [https://events.linuxfoundation.org/wp-content/uploads/2017/11/LSS2018.pdf Slides]
* Flexible, configurable labeling of apps and app data directories,
+
* Userspace permission checks controlling use of the Zygote socket commands,
+
* Minimal port of SELinux userspace,
+
* SELinux support for the Android toolbox,
+
* Small TE policy written from scratch for Android,
+
* Confined domains for system services and apps,
+
* Use of MLS categories to isolate apps.
+
  
== 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.
+
 
+
You should clone the master branch of AOSP as SE Android is based on it.
+
The AOSP instructions are for Ubuntu or MacOS X users; we are building on
+
64-bit Fedora (14 and 15 are known to work, with minor modifications).
+
Some Fedora-specific notes can be found further below.
+
 
+
General questions about building and running Android should be directed to the android-building discussion group, not to the selinux mailing list.  Only questions specific to SE Android should be directed to the selinux mailing list.
+
 
+
Once you have successfully built and run AOSP, you can obtain a local manifest specifying the SE Android git trees from
+
http://selinuxproject.org/~seandroid/local_manifest.xml.
+
Copy this file to the .repo subdirectory of your AOSP clone, and
+
then run repo sync.  Your tree should now include the SE Android modifications.
+
 
+
== 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 git://git.selinuxproject.org/~seandroid/ + project path.
+
</pre>
+
 
+
The specific trees and branches are enumerated in
+
http://selinuxproject.org/~seandroid/local_manifest.xml.
+
 
+
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 origin/android-<board>-<version>.
+
 
+
Each modified AOSP tree has a seandroid branch that was forked from
+
the master branch.  You can extract individual patches from the AOSP trees
+
by running git format-patch aosp/master.
+
 
+
libselinux and sepolicy are new trees added for SE Android; libselinux
+
is a port of a subset of the regular libselinux to Android + some new
+
Android-specific interfaces, and sepolicy is a completely new SELinux
+
policy written from scratch for Android.
+
 
+
== Fedora-Specific Notes ==
+
 
+
AOSP only officially supports building on specific versions of Ubuntu and MacOS X.
+
We however have been building on Fedora. This section contains some tips for building
+
on Fedora, but you should also be able to build on Ubuntu.  We do require that the build host provide
+
a copy of checkpolicy to compile the SELinux policy, so you will need checkpolicy to be installed.
+
 
+
We have successfully built on 64-bit Fedora 14 and 15.  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>
+
 
+
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.
+
<pre>
+
rpm -i jdk-6u29-linux-amd64.rpm
+
export PATH=/usr/java/jdk1.6.0_29/bin:$PATH
+
</pre>
+
 
+
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"
+
</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/prebuilt/linux-x86/toolchain/arm-eabi-4.4.3/bin/arm-eabi-
+
</pre>
+
 
+
You can build the Android userspace in the usual manner:
+
<pre>
+
cd $PREFIX
+
source build/envsetup.sh
+
lunch full-eng
+
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 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 and kernel
+
configuration for your device; the defconfig files have been modified
+
to enable the necessary options for SELinux.  For example, to build
+
for the Nexus S phone, you would do the following:
+
<pre>
+
export PREFIX=/path/to/your/aospclone
+
cd $PREFIX/kernel/samsung
+
make ARCH=arm herring_defconfig
+
make ARCH=arm CROSS_COMPILE=$PREFIX/prebuilt/linux-x86/toolchain/arm-eabi-4.4.3/bin/arm-eabi-
+
</pre>
+
 
+
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/samsung/crespo/device_base.mk file to
+
refer to our kernel and wireless module rather than the prebuilt ones.
+
You can alternatively unpack the boot image and repack it with your own
+
kernel after building AOSP.
+
 
+
Otherwise, follow the AOSP instructions for building for your device
+
as per
+
http://source.android.com/source/building-devices.html.
+
 
+
== 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).
+
 
+
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 dmesg | grep avc
+
</pre>
+
should show no output.
+
 
+
To just 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.
+
 
+
== 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, 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 seapp_contexts configuration is used to label
+
app processes and app package directories. seapp_contexts is unique to
+
SE Android.  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.
+
 
+
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.  We are still investigating approaches for runtime policy management.
+
 
+
== For More Information ==
+
 
+
Questions about SE Android may be directed to the public selinux mailing list.
+
Information about subscribing to the selinux mailing list can be found at
+
http://www.nsa.gov/research/selinux/subscribe.shtml.
+
Search http://marc.info/?l=selinux before posting to see if your question has already been answered.
+
 
+
You may also send private email to selinux-team AT tycho.nsa.gov.
+
However, whenever possible, please use the public mailing list.
+

Revision as of 12:50, 5 October 2018

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 describing 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

Further talks describing the impact of SELinux on Android security and further SELinux development in Android include:

  • 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

(Android is a trademark of Google LLC)