Discretionary access control (DAC)

File system objects and services added to the build frequently need separate, unique IDs, known as Android IDs (AIDs). Currently, many resources such as files and services use core (Android-defined) AIDs unnecessarily; in many cases you can use OEM (OEM-defined) AIDs instead.

Earlier versions of Android (Android 7.x and lower) extended the AIDs mechanism using a device-specific android_filesystem_config.h file to specify file system capabilities and/or custom OEM AIDs. However, this system was unintuitive as it did not support using nice names for OEM AIDs, requiring you to specify the raw numeric for user and group fields without a way to associate a friendly name with the numeric AID.

Newer versions of Android (Android 8.0 and higher) support a new method for extending file system capabilities. This new method has support for the following:

• Multiple source locations for configuration files (enables extensible build configurations).
• Build-time sanity checking of OEM AID values.
• Generation of a custom OEM AID header that can be used in source files as needed.
• Association of a friendly name with the actual OEM AID value. Supports nonnumeric string arguments for user and group, i.e. "foo" instead of "2901".

Additional improvements include the removal of the android_ids[] array from system/core/libcutils/include/private/android_filesystem_config.h. This array now exists in Bionic as a fully private generated array, with accessors with getpwnam() and getgrnam(). (This has the side effect of producing stable binaries as core AIDs are modified.) For tooling and a README file with more details, refer to build/make/tools/fs_config.

Add Android IDs (AIDs)

Android 8.0 removed the android_ids[] array from the Android Open Source Project (AOSP). All AID-friendly names are instead generated from the system/core/libcutils/include/private/android_filesystem_config.h header file when generating the Bionic android_ids[] array. Any define matching AID_* is picked up by the tooling and * becomes the lowercase name.

For example, in private/android_filesystem_config.h:

#define AID_SYSTEM 1000

Becomes:

• Friendly name: system
• uid: 1000
• gid: 1000

To add a new AOSP core AID, simply add the #define to the android_filesystem_config.h header file. The AID is generated at build and made available to interfaces that use user and group arguments. The tooling validates the new AID is not within the APP or OEM ranges; it also respects changes to those ranges and should automatically reconfigure on changes or new OEM-reserved ranges.

Configure AIDs

To enable the new AIDs mechanism, set TARGET_FS_CONFIG_GEN in the BoardConfig.mk file. This variable holds a list of configuration files, enabling you to append files as needed.

By convention, configuration files use the name config.fs, but in practice you can use any name. config.fs files are in the Python ConfigParser ini format and include a caps section (for configuring file system capabilities) and an AIDs section (for configuring OEM AIDs).

Configure the caps section

The caps section supports setting file system capabilities on file system objects within the build (the file system itself must also support this functionality).

Because running a stable service as root in Android causes a Compatibility Test Suite (CTS) failure, previous requirements for retaining a capability while running a process or service involved setting up capabilities then using setuid/setgid to a proper AID to run. With caps, you can skip these requirements and have the kernel do it for you. When control is handed to main(), your process already has the capabilities it needs so your service can use a nonroot user and group (this is the preferred way for starting privileged services).

The caps section uses the following syntax:

For a usage example, see Using file system capabilities.

Configure the AID section

The AID section contains OEM AIDs and uses the following syntax:

For usage examples, see Defining OEM AID names and Using OEM AIDs.

Usage examples

The following examples detail how to define and use an OEM AID and how to enable file system capabilities. OEM AID names ([AID_name]) must begin with a partition name such as "vendor_" to ensure they do not conflict with future AOSP names or other partitions.

Define OEM AID names

To define an OEM AID, create a config.fs file and set the AID value. For example, in device/x/y/config.fs, set the following:

[AID_VENDOR_FOO]
value: 2900

After creating the file, set the TARGET_FS_CONFIG_GEN variable and point to it in BoardConfig.mk. For example, in device/x/y/BoardConfig.mk, set the following:

TARGET_FS_CONFIG_GEN += device/x/y/config.fs

Your custom AID can now be consumed by the system at large on a new build.

Use OEM AIDs

To use an OEM AID, in your C code, include the oemaids_headers in your associated Makefile, and add #include "generated_oem_aid.h", then start using the declared identifiers. For example, in my_file.c, add the following:

#include "generated_oem_aid.h"
…

If (ipc->uid == AID_VENDOR_FOO) {
  // Do something
...

In your associated Android.bp file, add the following:

header_libs: ["oemaids_headers"],

If you're using an Android.mk file, then add the following:

LOCAL_HEADER_LIBRARIES := oemaids_headers

Use friendly names

In Android 9, you can use the friendly name for any interface that supports AID names. For example:

• In a chown command in some/init.rc:

  chown vendor_foo /vendor/some/vendor_foo/file
  

• In a service in some/init.rc:

  service vendor_foo /vendor/bin/foo_service
      user vendor_foo
      group vendor_foo
  

Because the internal mapping from friendly name to uid is performed by /vendor/etc/passwd and /vendor/etc/group, the vendor partition must be mounted.

Associate friendly names

Android 9 includes support for associating a friendly name with the actual OEM AID value. You can use nonnumeric string arguments for user and group, that is, "vendor_foo" instead of "2901".

Convert from AID to friendly names

For OEM AIDs, Android 8.x required the use of oem_#### with getpwnam and similar functions, as well in places that handle lookups with getpwnam (such as init scripts). In Android 9, you can use the getpwnam and getgrnam friends in Bionic for converting from Android IDs (AIDs) to friendly names and vice versa.

Use file system capabilities

To enable file system capabilities, create a caps section in the config.fs file. For example, in device/x/y/config.fs, add the following section:

[system/bin/foo_service]
mode: 0555
user: AID_VENDOR_FOO
group: AID_SYSTEM
caps: SYS_ADMIN | SYS_NICE

After creating the file, set the TARGET_FS_CONFIG_GEN to point to that file in BoardConfig.mk. For example, in device/x/y/BoardConfig.mk, set the following:

TARGET_FS_CONFIG_GEN += device/x/y/config.fs

When service vendor_foo is executed, it starts with capabilities CAP_SYS_ADMIN and CAP_SYS_NICE without setuid and setgid calls. In addition, the vendor_foo service's SELinux policy no longer needs capability setuid and setgid and can be deleted.

Configure overrides (Android 6.x-7.x)

Android 6.0 relocated fs_config and associated structure definitions (system/core/include/private/android_filesystem_config.h) to system/core/libcutils/fs_config.c where they could be updated or overridden by binary files installed in /system/etc/fs_config_dirs and /system/etc/fs_config_files. Using separate matching and parsing rules for directories and files (which could use additional glob expressions) enabled Android to handle directories and files in two different tables. Structure definitions in system/core/libcutils/fs_config.c not only allowed runtime reading of directories and files, but the host could use the same files during build time to construct file system images as ${OUT}/system/etc/fs_config_dirs and ${OUT}/system/etc/fs_config_files.

While the override method of extending the file system has been superseded by the modular config system introduced in Android 8.0, you can still use the old method if desired. The following sections detail how to generate and include override files and configure the file system.

Generate override files

You can generate the aligned binary files /system/etc/fs_config_dirs and /system/etc/fs_config_files using the fs_config_generate tool in build/tools/fs_config. The tool uses a libcutils library function (fs_config_generate()) to manage DAC requirements into a buffer and defines rules for an include file to institutionalize the DAC rules.

To use, create an include file in device/vendor/device/android_filesystem_config.h that acts as the override. The file must use the structure fs_path_config format defined in system/core/include/private/android_filesystem_config.h with the following structure initializations for directory and file symbols:

• For directories, use android_device_dirs[].
• For files, use android_device_files[].

When not using android_device_dirs[] and android_device_files[], you can define NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS and NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_FILES (see the example below). You can also specify the override file using TARGET_ANDROID_FILESYSTEM_CONFIG_H in the board configuration, with an enforced basename of android_filesystem_config.h.

Include override files

To include files, ensure that PRODUCT_PACKAGES includes fs_config_dirs and/or fs_config_files so it can install them to /system/etc/fs_config_dirs and /system/etc/fs_config_files, respectively. The build system searches for custom android_filesystem_config.h in $(TARGET_DEVICE_DIR), where BoardConfig.mk exists. If this file exists elsewhere, set board config variable TARGET_ANDROID_FILESYSTEM_CONFIG_H to point to that location.

Configure the file system

To configure the file system in Android 6.0 and higher:

1. Create the $(TARGET_DEVICE_DIR)/android_filesystem_config.h file.
2. Add the fs_config_dirs and/or fs_config_files to PRODUCT_PACKAGES in the board configuration file (e.g., $(TARGET_DEVICE_DIR)/device.mk).

Override example

This example shows a patch for overriding the system/bin/glgps daemon to add wake lock support in the device/vendor/device directory. Keep the following in mind:

• Each structure entry is the mode, uid, gid, capabilities, and the name. system/core/include/private/android_filesystem_config.h is included automatically to provide the manifest #defines (AID_ROOT, AID_SHELL, CAP_BLOCK_SUSPEND).
• The android_device_files[] section includes an action to suppress access to system/etc/fs_config_dirs when unspecified, which serves as an additional DAC protection for lack of content for directory overrides. However, this is weak protection; if someone has control over /system, they can typically do anything they want.

diff --git a/android_filesystem_config.h b/android_filesystem_config.h
new file mode 100644
index 0000000..874195f
--- /dev/null
+++ b/android_filesystem_config.h
@@ -0,0 +1,36 @@
+/*
+ * Copyright (C) 2015 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ * implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+/* This file is used to define the properties of the file system
+** images generated by build tools (eg: mkbootfs) and
+** by the device side of adb.
+*/
+
+#define NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS
+/* static const struct fs_path_config android_device_dirs[] = { }; */
+
+/* Rules for files.
+** These rules are applied based on "first match", so they
+** should start with the most specific path and work their
+** way up to the root. Prefixes ending in * denotes wildcard
+** and will allow partial matches.
+*/
+static const struct fs_path_config android_device_files[] = {
+  { 00755, AID_ROOT, AID_SHELL, (1ULL << CAP_BLOCK_SUSPEND),
"system/bin/glgps" },
+#ifdef NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS
+  { 00000, AID_ROOT, AID_ROOT, 0, "system/etc/fs_config_dirs" },
+#endif
+};


diff --git a/device.mk b/device.mk
index 0c71d21..235c1a7 100644
--- a/device.mk
+++ b/device.mk
@@ -18,7 +18,8 @@ PRODUCT_PACKAGES := \
     libwpa_client \
     hostapd \
     wpa_supplicant \
-    wpa_supplicant.conf
+    wpa_supplicant.conf \
+    fs_config_files

 ifeq ($(TARGET_PREBUILT_KERNEL),)
 ifeq ($(USE_SVELTE_KERNEL), true)

Migrate file systems from earlier releases

When migrating file systems from Android 5.x and earlier, keep in mind that Android 6.x

• Removes some includes, structures, and inline definitions.
• Requires a reference to libcutils instead of running directly from system/core/include/private/android_filesystem_config.h. Device manufacturer private executables that depend on system/code/include/private_filesystem_config.h for the file or directory structures or fs_config must add libcutils library dependencies.
• Requires device manufacturer private branch copies of the system/core/include/private/android_filesystem_config.h with extra content on existing targets to move to device/vendor/device/android_filesystem_config.h.
• Reserves the right to apply SELinux Mandatory Access Controls (MAC) to configuration files on the target system, implementations that include custom target executables using fs_config() must ensure access.