Building SELinux Policy

This article covers how SELinux policy is built. SELinux policy is built from the combination of core AOSP policy (platform) and device-specific policy (vendor). The SELinux policy build flow for Android 4.4 through Android 7.0 merged all sepolicy fragments then generated monolithic files in the root directory. This meant that SoC vendors and ODM manufacturers modified boot.img (for non-A/B devices) or system.img (for A/B devices) every time policy was modified.

In Android 8.0 and higher, platform and vendor policy is built separately. SOCs and OEMs can update their parts of the policy, build their images (such as, vendor.img and boot.img), then update those images independent of platform updates.

However, as modularized SELinux policy files are stored on /vendor partitions, the init process must mount the system and vendor partitions earlier so it can read SELinux files from those partitions and merge them with core SELinux files in the system directory (before loading them into the kernel).

Source files

The logic for building SELinux is in these files:

  • external/selinux: External SELinux project, used to build HOST command line utilities to compile SELinux policy and labels.
  • system/sepolicy: Core Android SELinux policy configurations, including contexts and policy files. Major sepolicy build logic is also here (system/sepolicy/Android.mk).

For more details on the files in system/sepolicy Implementing SELinux.

Android 7.0 and earlier

This section covers how SELinux policy is built in Android 7.x and earlier.

Building SELinux policy

SELinux policy is created by combining the core AOSP policy with device-specific customizations. The combined policy is then passed to the policy compiler and various checkers. Device-specific customization is done through the BOARD_SEPOLICY_DIRS variable defined in device-specific Boardconfig.mk file. This global build variable contains a list of directories that specify the order in which to search for additional policy files.

For example, a SoC vendor and an ODM might each add a directory, one for the SoC-specific settings and another for device-specific settings, to generate the final SELinux configurations for a given device:

  • BOARD_SEPOLICY_DIRS += device/SOC/common/sepolicy
  • BOARD_SEPOLICY_DIRS += device/SoC/DEVICE/sepolicy

The content of file_contexts files in system/sepolicy and BOARD_SEPOLICY_DIRS are concatenated to generate the file_contexts.bin on the device:

This image shows the SELinux build logic for Android 7.x.
Figure 1. SELinux build logic

The sepolicy file consists of multiple source files:

  • The plain text policy.conf is generated by concatenating security_classes, initial_sids, *.te files, genfs_contexts, and port_contexts in that order.
  • For each file (such as security_classes), its content is the concatenation of the files with the same name under system/sepolicy/ and BOARDS_SEPOLICY_DIRS.
  • The policy.conf is sent to SELinux compiler for syntax checking and compiled into binary format as sepolicy on the device.
    This image shows the files that generate the SELinux policy file for Android 7.x.
    Figure 2. SELinux policy file

SELinux files

After compiling, Android devices running 7.x and earlier typically contain the following SELinux-related files:

  • selinux_version
  • sepolicy: binary output after combining policy files (such as, security_classes, initial_sids, and *.te)
  • file_contexts
  • property_contexts
  • seapp_contexts
  • service_contexts
  • system/etc/mac_permissions.xml

For more details, see Implementing SELinux.

SELinux initialization

When the system boots up, SELinux is in permissive mode (and not in enforcing mode). The init process performs the following tasks:

  • Loads sepolicy files from ramdisk into the kernel through /sys/fs/selinux/load.
  • Switches SELinux to enforcing mode.
  • Runs re-exec() to apply the SELinux domain rule to itself.

To shorten the boot time, perform the re-exec() on the init process as soon as possible.

Android 8.0 and higher

In Android 8.0, SELinux policy is split into platform and vendor components to allow independent platform/vendor policy updates while maintaining compatibility.

The platform sepolicy is further split into platform private and platform public parts to export specific types and attributes to vendor policy writers. The platform public types/attributes are guaranteed to be maintained as stable APIs for a given platform version. Compatibility with previous platform public types/attributes can be guaranteed for several versions using platform mapping files.

Platform public sepolicy

The platform public sepolicy includes everything defined under system/sepolicy/public. The platform can assume the types and attributes defined under public policy are stable APIs for a given platform version. This forms the part of the sepolicy that is exported by platform on which vendor (i.e. device) policy developers may write additional device-specific policy.

Types are versioned according to the version of the policy that vendor files are written against, defined by the PLATFORM_SEPOLICY_VERSION build variable. The versioned public policy is then included with the vendor policy and (in its original form) in the platform policy. Thus, the final policy includes the private platform policy, the current platform's public sepolicy, the device-specific policy, and the versioned public policy corresponding to the platform version against which the device policy was written.

Platform private sepolicy

The platform private sepolicy includes everything defined under /system/sepolicy/private. This part of the policy forms platform-only types, permissions, and attributes required for platform functionality. These are not exported to the vendor/device policy writers. Non-platform policy writers must not write their policy extensions based on types/attributes/rules defined in platform private sepolicy. Moreover, these rules are allowed to be modified or may disappear as part of a framework-only update.

Platform private mapping

The platform private mapping includes policy statements that map the attributes exposed in platform public policy of the previous platform versions to the concrete types used in current platform public sepolicy. This ensures vendor policy that was written based on platform public attributes from the previous platform public sepolicy version(s) continues to work. The versioning is based on the PLATFORM_SEPOLICY_VERSION build variable set in AOSP for a given platform version. A separate mapping file exists for each previous platform version from which this platform is expected to accept vendor policy. For more details, see Compatibility.

Building SELinux policy

SELinux policy in Android 8.0 is made by combining pieces from /system and /vendor. Logic for setting this up appropriately is in /platform/system/sepolicy/Android.mk.

Policy exists in the following locations:

Location Contains
system/sepolicy/public The platform's sepolicy API
system/sepolicy/private Platform implementation details (vendors can ignore)
system/sepolicy/vendor Policy and context files that vendors can use (vendors can ignore if desired)
BOARD_SEPOLICY_DIRS Vendor sepolicy

The build system takes this policy and produces platform and vendor policy components on the system partition and vendor partition, respectively. Steps include:

  1. Converting policies to the SELinux Common Intermediate Language (CIL) format, specifically:
    1. public platform policy
    2. combined private + public policy
    3. public + vendor and BOARD_SEPOLICY_DIRS policy
  2. Versioning the policy provided by public as part of the vendor policy. Done by using the produced public CIL policy to inform the combined public + vendor + BOARD_SEPOLICY_DIRS policy as to which parts must be turned into attributes that will be linked to the platform policy.
  3. Creating a mapping file linking the platform and vendor parts. Initially, this just links the types from the public policy with the corresponding attributes in the vendor policy; later it will also provide the basis for the file maintained in future platform versions, enabling compatibility with vendor policy targeting this platform version.
  4. Combining policy files (describe both on-device and precompiled solutions).
    1. Combine mapping, platform and vendor policy.
    2. Compile output binary policy file.