Introduction to Android SELinux and its Importance

Security-Enhanced Linux (SELinux) is a mandatory access control (MAC) system that provides a robust security architecture for Android. Unlike discretionary access control (DAC), where permissions are based on user/group ownership, SELinux policies define explicit permissions for every process and resource on the system. This granular control is crucial for isolating components, preventing privilege escalation, and safeguarding user data. For anyone involved in Android upgrades, custom ROM development (like LineageOS), or kernel modification, a deep understanding of SELinux contexts is indispensable for diagnosing and resolving often cryptic permission errors.

Two primary tools become your best friends when navigating the complex world of Android SELinux: ls -Z for examining file and directory contexts, and logcat for capturing SELinux Access Vector Cache (AVC) denial messages. This guide will walk you through interpreting their output, turning what often seems like arcane jargon into actionable insights.

Understanding File and Directory Contexts with ls -Z

Every file, directory, and process in an SELinux-enabled system has an associated security context. This context is a label that the kernel uses to make access control decisions. The ls -Z command allows you to view these contexts for files and directories. Let’s break down its output.

When you run ls -Z in an adb shell (or directly on a rooted device’s terminal), you’ll see output similar to this:

$ adb shell ls -Z /data/data/com.example.app
-rw-rw---- 1 u0_a100 u0_a100 u:object_r:app_data_file:s0 8192 2023-10-27 10:30 caches
drwxrwx--- 1 u0_a100 u0_a100 u:object_r:app_data_file:s0 4096 2023-10-27 10:30 code_cache

The critical part is the colon-separated string: u:object_r:app_data_file:s0.

• u (User): Represents the SELinux user. For Android, this is almost always u, indicating an unconfined user context.
• object_r (Role): For files and directories, the role is typically object_r, signifying an object (resource). For processes, you’d see roles like system_r, untrusted_app_r, etc.
• app_data_file (Type/Domain): This is the most important component. It’s the SELinux type that defines the characteristics and allowed interactions for this file or directory. In this example, app_data_file indicates data belonging to an application. For processes, this field would represent the domain (e.g., untrusted_app, system_server).
• s0 (MLS/MCS Label): This is the Multi-Level Security (MLS) or Multi-Category Security (MCS) level. For Android, it’s typically s0, representing a single-level security category.

By inspecting the ‘type’ field, you can immediately identify what kind of resource you’re dealing with. For instance, a file intended for the system partition might have a context like system_file, while a device node might have device or a specific hardware type.

Practical Examples of ls -Z

Let’s look at more examples:

$ adb shell ls -Z /system/bin/app_process
-rwxr-xr-x 1 root shell u:object_r:zygote_exec:s0 88264 2023-09-01 12:00 /system/bin/app_process

$ adb shell ls -Z /dev/block/bootdevice/by-name/userdata
lrwxrwxrwx 1 root root u:object_r:block_device:s0 21 2023-09-01 12:00 /dev/block/bootdevice/by-name/userdata -> /dev/block/dm-0

In the first example, zygote_exec tells us this is an executable related to the Zygote process, which is critical for Android app startup. In the second, block_device clearly labels the userdata partition as a block device. Incorrect contexts here can lead to boot loops or data access issues.

Decoding AVC Denials with logcat

When an SELinux policy prevents an action, the kernel generates an AVC (Access Vector Cache) denial message, which is logged to the kernel ring buffer and accessible via logcat. These denials are the bread and butter of SELinux troubleshooting.

A typical AVC denial looks like this:

$ adb logcat | grep 'avc: denied'
... E audit   : type=1400 audit(1698416700.123:456): avc: denied { read } for pid=1234 comm="my_daemon" name="sensitive_file" dev="tmpfs" ino=5678 scontext=u:r:my_daemon_domain:s0 tcontext=u:object_r:restricted_data_file:s0 tclass=file permissive=0

This single line contains all the information you need to understand *who* tried to do *what* to *whom* and *what* was denied.

• type=1400: Standard audit message type for SELinux.
• audit(timestamp:sequence): Provides the timestamp and a unique sequence number for the audit event.
• avc: denied { read }: This is the crucial part. It states that an Access Vector Cache denial occurred, and the specific permission denied was read. Other common permissions include write, execute, getattr, open, search, etc.
• for pid=1234 comm="my_daemon": Identifies the process ID (PID) and the command name (my_daemon) that initiated the action. This is your ‘subject’.
• name="sensitive_file" dev="tmpfs" ino=5678: Provides details about the target file or resource, including its name, device, and inode number.
• scontext=u:r:my_daemon_domain:s0: This is the ‘source context’ (the process trying to perform the action). Here, my_daemon_domain is the SELinux domain of the process.
• tcontext=u:object_r:restricted_data_file:s0: This is the ‘target context’ (the resource being accessed). Here, restricted_data_file is the SELinux type of the file.
• tclass=file: The ‘target class’ specifies the type of resource being accessed (e.g., file, dir, socket, device, process, fd).
• permissive=0: Indicates that SELinux is in enforcing mode (1 would mean permissive mode, where denials are logged but not enforced).

Step-by-Step Interpretation of an AVC Denial

Let’s use the example above:

1. Identify the Actor (scontext): The scontext=u:r:my_daemon_domain:s0 tells us that a process running in the my_daemon_domain was the one attempting the action.
2. Identify the Target (tcontext & tclass): The tcontext=u:object_r:restricted_data_file:s0 and tclass=file inform us that the target was a file with the security type restricted_data_file.
3. Identify the Action (permission): The denied { read } indicates that the my_daemon_domain process was denied the ability to read this file.
4. Conclusion: The process my_daemon (running in domain my_daemon_domain) tried to read a file labeled restricted_data_file, but the SELinux policy does not allow this interaction.

To resolve this, you would typically need to modify the SELinux policy (e.g., in a custom ROM or kernel) to explicitly permit my_daemon_domain to read files of type restricted_data_file, or ensure the file has the correct `tcontext` if it was mislabeled.

Common SELinux Domains and Types

Familiarity with common SELinux types helps in quicker diagnosis:

• Process Domains:
  • untrusted_app_domain: Standard user applications. Highly restricted.
  • system_app_domain: System applications, slightly more privileged than untrusted apps.
  • system_server: The core Android system server process.
  • zygote: The process responsible for forking new Android applications.
  • init: The first process started by the kernel, responsible for system initialization.
• File/Object Types:
  • app_data_file: Data files owned by an application in /data/data/<package>.
  • system_file: Files residing in /system.
  • vendor_file: Files residing in /vendor.
  • device, block_device, audio_device, gpu_device: Various types of device nodes.
  • tmpfs, tmpfs_file: Temporary file system entries.

Conclusion

Mastering ls -Z and interpreting logcat AVC denials are fundamental skills for anyone delving into Android’s deeper technical layers. These tools provide the necessary visibility into SELinux’s mandatory access control decisions, allowing you to pinpoint permission issues precisely. Whether you’re debugging a custom ROM, integrating a new kernel module, or simply trying to understand why a certain application behaves unexpectedly, the ability to decode SELinux contexts is an invaluable asset in your technical toolkit.

Always remember to exercise caution when modifying SELinux policies, as incorrect changes can introduce severe security vulnerabilities or render your device unbootable. Start by understanding the existing policy and the denied interactions, then craft the minimal necessary policy additions to achieve your desired functionality securely.