Privileged Permission Whitelisting

Privileged applications are system applications located in the /system/priv-app directory on the system image. Historically, device implementers had little control over which signature|privileged permissions could be granted to privileged apps. Starting in Android 8.0, implementors can explicitly whitelist privileged apps in the system configuration XML files in the /etc/permissions directory. Apps not explicitly listed in these XML files are not granted privileged permissions.

Adding whitelists

Permission whitelists for applications can be listed in a single or multiple XML files located in the frameworks/base/etc/permissions directory as follows:

  • /etc/permissions/privapp-permissions-OEM_NAME.xml
  • /etc/permissions/privapp-permissions-DEVICE_NAME.xml

There is no strict rule for organizing content. Device implementers can determine content structure as long as all applications from /system/priv-app are whitelisted. For example, Google has a single whitelist for all privileged applications developed by Google. We recommend the following organization:

  • Permissions for apps that are already included in the Android Open Source Project (AOSP) tree are listed in /etc/permissions/privapp-permissions-platform.xml.
  • Permissions for Google applications are listed in /etc/permissions/privapp-permissions-google.xml.
  • For other applications, use files of the form: /etc/permissions/privapp-permissions-DEVICE_NAME.xml.

Generating whitelists

To automatically generate a whitelist for all applications available on the system image, use the AOSP command line tool at development/tools/privapp_permissions/privapp_permissions.py. To generate an initial version of device-specific privapp-permissions.xml:

  1. Build a system image:
        . build/envsetup.sh
        lunch PRODUCT_NAME
        make -j
  2. Run the privapp_permissions.py script to generate a privapp-permissions.xmlfile that lists all signature|privileged permissions required to be whitelisted:
    development/tools/privapp_permissions/privapp_permissions.py
    This tool prints XML content that can be used as a single file or split into multiple files in /etc/permissions. If the device already includes whitelists in the /etc/permissions directory, the tool prints the differences only (i.e. the missing signature|privileged permissions to be added to the whitelist). This is also useful for audit purposes: When a new version of the app is added, the tool detects the additional permissions needed.
  3. Copy the generated files to the /etc/permissions directory, where the system will read those files during boot.

Customizing whitelists

AOSP includes a whitelist implementation that can be customized as needed. Permissions for apps included in AOSP are already whitelisted in /etc/permissions/privapp-permissions-platform.xml.

By default, the privapp_permissions.py script generates output that automatically grants any permission requested by a privileged application. If there are permissions that should be denied, edit the XML to use a "deny-permission" tag instead of a "permission" tag. Example:

<!--
    This XML file declares which signature|privileged permissions should be
    granted to privileged applications that come with the platform
    -->
    <permissions>
<privapp-permissions package="com.android.backupconfirm">
    <permission name="android.permission.BACKUP"/>
    <permission name="android.permission.CRYPT_KEEPER"/>
</privapp-permissions>
<privapp-permissions package="com.android.cellbroadcastreceiver">
    <!-- don't allow application to interact across users -->
    <deny-permission name="android.permission.INTERACT_ACROSS_USERS"/>
    <permission name="android.permission.MANAGE_USERS"/>
    <permission name="android.permission.MODIFY_PHONE_STATE"/>
    <permission name="android.permission.READ_PRIVILEGED_PHONE_STATE"/>
    <permission name="android.permission.RECEIVE_EMERGENCY_BROADCAST"/>
</privapp-permissions>
    ...

Finding missing permissions

When bringing up a new device, find missing permissions by enabling transitional log-mode:

ro.control_privapp_permission=log

Violations are reported in the log file, but permissions are still granted. This keeps the device in a working state while providing the list of violations. The error message format is as follows:

PackageManager: Privileged permission {PERMISSION_NAME} for package {PACKAGE_NAME} - not in privapp-permissions whitelist

All violations must be addressed by adding the apps to whitelists. If not added, the apps will not be granted the missing permissions even if they are in the priv-app path.

Enforcing whitelists

After whitelists are in place, enable runtime enforcement by setting the build property ro.control_privapp_permission=enforce.