Privileged Permission Whitelist Requirement

Historically device implementers had little control over which signature|privileged permissions could be granted to privileged apps. Privileged applications are system applications that are located in /system/priv-app directory on the system image.

Starting in Android 8.0, all privileged apps must be explicitly whitelisted in system configuration XML files in the /etc/permissions directory. If they are not, then the device will boot, but the device implementation will not pass CTS.

Adding the 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, it can be decided by the device implementer 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.

The following organization is recommended:

  • Permissions for apps that are already included in AOSP tree are listed in this file: /etc/permissions/privapp-permissions-platform.xml
  • Permissions for Google applications are listed in this file: /etc/permissions/privapp-permissions-google.xml
  • For other applications, use files of the form: /etc/permissions/privapp-permissions-<device_name>.xml

Whitelist generation tool

A whitelist for all applications available on the system image can be automatically generated using a command-line tool available in AOSP, at the following location:

development/tools/privapp_permissions/privapp_permissions.py
    

To generate an initial version of device-specific privapp-permissions.xml, complete the following steps:

  1. Build a system image, as follows:
    $ . build/envsetup.sh
    $ lunch product_name
    $ make -j
  2. Run the following tool to generate a privapp-permissions.xml file that lists all signature|privileged permissions that are 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 device already includes whitelists in the /etc/permissions directory, the tool prints the difference, that is, only the missing signature|privileged permissions that need to be added to the whitelist. This is also useful for audit purposes, when a new version of the app is added, the tool will detect the additional permissions needed.
  3. Copy the generated files to the /etc/permissions directory, where the system will read it during boot.

Whitelist format

  • Since the implementation is already in AOSP, only customization is needed.
  • Permissions for apps that are included in AOSP tree are already whitelisted in /etc/permissions/privapp-permissions-platform.xml
<!--
    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">
	    <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>
    ...

Enabling logs to find missing permissions

When bringing up a new device, we recommend enabling transitional log-mode at first, as follows:

ro.control_privapp_permission=log

The violations will be reported in the log file, but permissions will still be granted. This will keep device in a working state, while providing the list of violations.

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 them to whitelists. Otherwise device will not pass CTS tests.

CTS tests for whitelists

Your device implementation will not pass CTS if it contains privileged apps that do not appear in a whitelist at /etc/permissions.

The PrivappPermissionsTest.java test enforces the signature|privileged permission whitelist, as follows:

  • Reports the permissions that are granted into the CTS log.
  • Ensures all priv permissions are exclusively granted to applications declared in <privapp-permissions>, i.e. it will fail if a privileged application is requesting signature|privileged permission that is not whitelisted or a whitelisted permission wasn't granted by the system.

Run-time enforcement of whitelists

Once the whitelists are in place, run-time enforcement can be enabled by setting a build property ro.control_privapp_permission=enforce.

Note: Please note that regardless of ro.control_privapp_permission property state, only devices with properly whitelisted privileged permissions for all privileged applications will pass CTS tests.