谷歌安全patch集成指導

Integrating Modules

This article describes how to obtain and integrate a Mainline module release package with an Android device build and provides technical guidance on implementing GPSU UX requirements in the Settings application.

Integrating Mainline module release packages

To integrate a module release package into your device build:

1. In your Android implementation repository:

   1. Delete all files in the vendor/partner_modules.

   2. Get the module release package using one of the following options:

      • From the shared Drive, extract package contents to the root of your Android implementation repository.

      • From the partner gerrit, using the following command:

        repo init -u persistent-https://partner-android.googlesource.com/platform/manifest -b q-aml-prebuilt-release

   3. Confirm the directory structure contains vendor/partner_modules.

      Example directory structure (tentative)

2. In the device product.mk file, add the following lines:

   # GPSU modules

   PRODUCT_PACKAGES += \

      GoogleDocumentsUIPrebuilt \

      GoogleExtServicesPrebuilt \

      ModuleMetadataGooglePrebuilt \

      GooglePermissionControllerPrebuilt

    

   # GPSU module overlay

   PRODUCT_PACKAGES += \

      GoogleExtServicesConfigOverlay \

      GooglePermissionControllerOverlay \

      GooglePermissionControllerFrameworkOverlay

3. Determine if the device supports updatable APEX files and configure the appropriate properties:

   Device supports updatable APEX

   Devices launching with Android 10 must support updatable APEX files, while devices upgrading to Android 10 can support updatable APEX with a properly configured kernel. To ensure APEX files are updatable, add the following to your product.mk file: # Enable updating of APEXes $(call inherit-product, $(SRC_TARGET_DIR)/product/updatable_apex.mk) This also adds the com.android.apex.cts.shim.*.apex file required for passing CTS when supporting updatable APEX.

   Device does not support updatable APEX

   Devices upgrading to Android 10 that do not use a properly configured kernel can't support updatable APEX. These devices must use flattened APEX files that are not updatable.  First, set the following property in your product.mk file to ensure APEX files aren't updatable: PRODUCT_PROPERTY_OVERRIDES += ro.apex.updatable=false Then, in BoardConfig.mk, add the following property to flatten the APEX files: TARGET_FLATTEN_APEX := true ALERT: It is invalid to include both flattened and updatable apex files (including com.android.runtime.[release|debug].apex) in the /system/apex or /product/apex directories. Doing so may cause installation and rollback issues with APEX modules; expect future versions of CTS to verify correct directory contents.

4. Determine which modules must be pre-loaded and remove modules that do not need to be pre-loaded.

   1. Review the Android 10 GMS Requirements for Google-signed module pre-load requirements. The number of modules that need to be pre-loaded vary depending on the type of device build (upgrades, new launches, or Android Go).

   2. For any module that is not required to be pre-loaded, you can (optionally) remove the module from the build by deleting the corresponding module directory under vendor/partner_modules/.

5. Determine how to handle the three STRONGLY RECOMMENDED network framework modules (Network Stack, Captive Portal Login, Network Stack Permission Config):

   When preloading modules

   Add the following lines in the device product.mk file (this is in addition to what is in step 2). You MUST add lines for all three modules even if you intend to preload only one module. # GPSU network framework modules PRODUCT_PACKAGES += \    GoogleCaptivePortalLogin \    GoogleNetworkPermissionConfig \    GoogleNetworkStack Copy the networkstack.x509.pem file in vendor/partner_modules/NetworkStackPrebuilt to $DEFAULT_SYSTEM_DEV_CERTIFICATE (typically located in build/make/target/product/security/), overwriting the existing networkstack.x509.pem file.

   When NOT preloading modules

   Add the following lines in the device product.mk file (this is in addition to what is in step 2). You MUST add all lines: # GPSU network framework modules PRODUCT_PACKAGES += \    InProcessNetworkStack \    PlatformCaptivePortalLogin \    PlatformNetworkPermissionConfig Copy the platform.pk8 and platform.x509.pem of your device to $DEFAULT_SYSTEM_DEV_CERTIFICATE (typically located in build/make/target/product/security/) as networkstack.pk8 and networkstack.x509.pem , overwriting the existing networkstack.pk8 and networkstack.x509.pem file. The three modules must be configured together as shown above. Using only one or two Google signed module is an invalid configuration (verified by GTS).

6. Configure the device to receive module updates from the Google Play Store. In the device overlay directory, append the following to frameworks/base/core/res/res/values/config.xml:

   <!-- The Google provided GPSU module metadata package -->

   <string name="config_defaultModuleMetadataProvider" translatable="false">com.google.android.modulemetadata</string>

   Note: If the config.xml file does not exist, create it.

7. Run a regular build command for the target. The build does the following:

   1. Installs APK-based, Google-signed, pre-built modules in /system/priv-apps, replacing AOSP counterparts (the package does not install AOSP APK-based modules in the system target image).

   2. Installs ModuleMetaDataGooglePrebuilt.apk to /product/apps.

   3. Installs APEX-based, Google-signed, pre-built module for the corresponding device architecture in /system/apex.

      1. APEX files are named com.google.android.module-name.apex.

      2. Package names for Google-signed APEX files are com.google.android.module-name.

      3. Installs *_permissions.xml files per module in /system/etc/permissions or /product/etc/permissions.

      4. Builds all Runtime Resource Overlay (RRO) packages and installs the resultant APK file in /product/overlay.

Integrating Mainline in Settings

In GMS devices, the Google Play Store injects the menu entry for Mainline named Google Play system update into Settings > Security as part of Security Status group, so you do not need to use the following code snippets; they are provided only for your information. 

To display the current Mainline train version in the Settings application, get the version using the following Android APIs.

Android APIs

For the Settings option that enables end users to trigger a GPSU (Mainline) update manually, you can use the following code snippet (requires Google Play Store application version 15.1.23 or higher).

Intent intent = new Intent("android.settings.MODULE_UPDATE_SETTINGS");

ComponentName componentName = intent.resolveActivity(getPackageManager());

if (componentName != null) {

   startActivity(intent);

}

Modules without Google Play Store updates

While all modules are updatable, some modules are not expected to need updates except for critical bug fixes or security patches. For these modules, updates will not be be delivered using the Google Play Store infrastructure and are instead expected to be updated in maintenance release builds.

The list of modules that are not expected to need updates is as follows:

• Permission Controller

• ExtServices

• Network Stack Permission Config

Preloading APEX files conditionally

To conditionally preload APEX files into a system image, use one of the following options.

Option 1	Delete the folder containing Google-prebuilt APEX file.
Option 2	For any prebuilt APEX file for which you don't want to use the Google-prebuilt file, change "prefer: true" to "prefer: false" in Android.bp.
Option 3	For devices that don't use any Google-prebuilt APEX files, switch the device configuration to use flatten APEX (which ignores prebuilt APEX files), as shown in step 3 of "Integrating GPSU module release packages" section. You may need to also use the following patches. https://android-review.googlesource.com/c/platform/build/soong/+/1014352 https://android-review.googlesource.com/c/platform/build/soong/+/1012160 (optional) https://android-review.googlesource.com/c/platform/build/soong/+/1027109 (optional)

 

Signing APEX files

You can sign (or re-sign) some APEX files with a different key, if needed. APEX files that can be signed/re-signed include:

• Any STRONGLY-RECOMMENDED or OPTIONAL APEX module. If you've customized one of these modules, you can re-sign the customized module using your own key. 

• com.android.runtime.release.apex. Google does not provide a prebuilt APEX file for this module, so you must sign it using your own key.

APEX files are signed with two different set of keys, one for the file system image and one for the container (for details, refer to APEX File Format on source.android.com). To sign the zip container, use your platform key. To sign the filesystem image, create your own Android Verified Boot (AVB) public/private key pairs.

When generating key pairs:

• Create your own AVB key pairs; do not use AOSP keys (verified by CTS in a future release).

• Make sure the keys are RSA_4096.

• Use different keys for each APEX file (you can't share a single key multiple APEX files). 

Resigning APEX files

You can use the sign_target_files_apks script to re-sign APEX files. While this script was designed for APK signing, it also works for APEX signing when using the following parameters:

Parameter	Description & Example
--extra_apex_payload	Specifies a payload signing key. Example: --extra_apex_payload_key com.android.foo.apex=path-to-avb_private_key-for-apex-file This is the private key for the filesystem image inside the apex. You could create your own, by following information here.
-e	Specifies a container signing key (same as for APK signing). Example: -e com.android.foo.apex=path-to-private-key-for-apex-file If the certificate and the private keys are at /foo/bar/com.android.foo.x509.pem and com.android.foo.pk8, then this should be set to /foo/bar/com.android.foo

 

The script reads the key information from the given target_files.zip (META/apexkeys.txt). Then, for any APEX that is NOT explicitly marked as PRESIGNED, the script signs the APEX files found in the given target_files.zip with the keys specified in META/apexkeys.txt.

The script identifies an APEX file based on filename. For example, to re-sign the runtime APEX file, the command is:

--extra_apex_payload_key com.android.runtime.debug.apex=path-to-key

Overriding signing keys

You can override the signing keys from the command line.

• To override the payload signing key, use the --extra_apex_payload parameter.

• To override the container signing key, use the -e parameter.

For example, to override the signing keys for com.android.resolv.apex and com.android.tzdata.apex,  use the following commands:

$ build/make/tools/releasetools/sign_target_files_apks -v -d ~/.android-certs \
      -e com.android.resolv.apex=path-to-dir-with-container-key-pairs-for-DNS-resolver
      --extra_apex_payload_key com.android.resolv.apex=external/avb/test/data/testkey_rsa4096.pem \
      -e com.android.tzdata.apex= \
      --extra_apex_payload_key com.android.tzdata.apex= \
      target_files.zip \
      signed-target_files.zip

After running this command:

• com.android.resolv.apex is signed with the specified keys (resolv_apex_container).

• com.android.tzdata.apex is treated as PRESIGNED.

• Any other APEXes are handled by the default config specified in META/apexkeys.txt.

• The signing log shows the following:

  ...
signing: com.android.resolv.apex   container

  (path-to-dir-with-container-key-pairs-for-DNS-resolver)
       : com.android.resolv.apex   payload          (external/avb/test/data/testkey_rsa4096.pem)
....
NOT signing: com.android.tzdata.apex (skipped due to special cert string)

Handling presigned APEX files

For the APEX files provided by Google, the build system must use PRESIGNED. To ensure the flag isn't missed during signing, set the following parameters in the Android.bp file for all PRESIGNED APEX files:

-e com.android.foo.apex=

--extra_apex_payload_key com.android.foo.apex=

Using the parameter without a value ensures that when the build system encounters com.android.foo.apex, it doesn't find a mapped key to sign the APEX.

Delivering partner-built APEX modules

You can create new APEX modules for components owned by you. You can also create derivative APEX modules based on optional (devices upgrading to Android 10) and strongly-recommended (devices launching with Android 10) modules. 

However, you cannot use the Google Play Store to deliver partner-build APEX modules. To deliver such modules, you can:

• Use a system image OTA (strongly recommended).

• Use a partner-owned application distribution channel (strongly discouraged and technically invalid). The Android 10 Mainline infrastructure can't handle module installation and rollback from a non-Google Play Store or from multiple sources. 

Recommendations against using an alternative application distribution channel apply to both GMS and non-GMS market devices. Google will not provide any support on any issue related to using an alternative application distribution channel. 

Mount namespace for apexd

In Android 10, apexd starts very early in bootstrap process, called as apexd-bootstrap for activating APEX files needed during boot sequence. In this state, APEX files are mounted in the bootstrap mount namespace. After /data is mounted, init starts apexd as a daemon, where apexd scans for both pre-installed and downloaded APEX files and mounts them in the default namespace. 

apexd and apexd-bootstrap must use different mount namespaces (verified by CTS in a future release). Using the same mount namespace causes problems during APEX file installation and roll back, so if you have customized the boot sequence or made any other changes that might affect mount namespace, you should verify the device configuration to ensure the namespaces are different for apexd and apexd-bootstrap.

To check if a device has an invalid configuration, use the following commands:

#  ls -l /proc/`pidof servicemanager`/ns/mnt

lrwxrwxrwx 1 system system 0 2019-08-16 16:46 /proc/625/ns/mnt -> mnt:[4026531840]

# ls -l /proc/`pidof apexd`/ns/mnt  

lrwxrwxrwx 1 root system 0 2019-08-16 16:46 /proc/809/ns/mnt -> mnt:[4026533692]

The numbers inside mnt:[****] must be:

• Different if the device supports APEX updates (that is, ro.apex.updatable=true)

• Identical if the device does not support APEX updates (that is, ro.apex.updatable=false or is not set)

Troubleshooting GTS failures

Permission Controller RROs

PermissionController includes a second RRO that overlays help_app_permissions configuration, which is verified by the following GTS test:

com.google.android.permission.gts.PermissionControllerResourceTest#testPermissionHelpLink

In addition, the existing RRO has been renamed from PermissionControllerConfigOverlay to GooglePermissionControllerFrameworkOverlay. To avoid the need for partners to write their own overlays to pass GTS, the Android team has created a patch.

DocumentsUI module required app for managed profile

When a Google-signed, Google-prebuilt DocumentsUI module is preloaded, the following GTS might fail:

com.google.android.gts.devicepolicy.managedprovisioning.ManagedProfileProvisioningHostsideTest#testRequiredApps

This test fails because the test can't find the default handler for required apps due to the following:

• In AOSP, frameworks/base/core/res/res/values contains required_apps_managed_profile.xml and required_apps_managed_device.xml files, both of which use com.android.documentsui as the default handler for android.intent.action.VIEW_DOWNLOADS.

• In GMS application distributions, the GmsConfigOverlay package includes vendor_required_apps_managed_profile.xml and vendor_required_apps_managed_device.xml files, which are used instead of the AOSP versions (see example GmsConfigOverlay).

• During Mainline module integration, adding the Google-prebuilt DocumentsUI module replaces com.android.documentsui package in device target files, causing the GTS test that verifies required apps to fail (as it can't find the default handler).

To avoid test failure, you can manually add the following into vendor_required_apps_managed_profile.xml and vendor_required_apps_managed_device.xml xml files.  

com.google.android.documentsui

The DocumentsUI module is optional for devices upgrading to Android 10, so it is the partner responsibility to ensure the correct package is included when the target system image preloads Google-signed, Google-prebuilt DocumentsUI module.