Take our usability survey to improve this site.

DRM

Android DRM HAL icon

This document provides an overview of the Android digital rights management (DRM) framework and introduces the interfaces that a DRM plugin must implement. This document doesn't describe robustness rules or compliance rules that may be defined by a DRM scheme.

Framework

The Android platform provides an extensible DRM framework that lets apps manage rights-protected content according to the license constraints associated with the content. The DRM framework supports many DRM schemes; which DRM schemes a device supports is up to the device manufacturer. The DRM framework provides a unified interface for application developers and hides the complexity of DRM operations. The DRM framework provides a consistent operation mode for protected and nonprotected content. DRM schemes can define complex usage models by license metadata. The DRM framework provides the association between DRM content and license, and handles the rights management. This enables the media player to be abstracted from DRM-protected or nonprotected content. See MediaDrm for the class to obtain keys for decrypting protected media streams.

Android DRM HAL
Figure 1a. DRM hardware abstraction Layer before Android 11
Android DRM HAL post R
Figure 1b. DRM hardware abstraction Layer starting in Android 11

The availability of rich digital content is important to users on mobile devices. To make their content widely available, Android developers and digital content publishers need a consistent DRM implementation supported across the Android ecosystem. To make that digital content available on Android devices and to ensure that there's at least one consistent DRM available across all devices, Google provides DRM without license fees on compatible Android devices. The DRM plugin is integrated with the Android DRM framework and can use hardware-backed protection to secure premium content and user credentials.

The content protection provided by the DRM plugin depends on the security and content protection capabilities of the underlying hardware platform. The hardware capabilities of the device should include hardware secure boot to establish a chain of trust of security and protection of cryptographic keys. Content protection capabilities of the device should include protection of decrypted frames in the device and content protection through a trusted output protection mechanism. Not all hardware platforms support all of the above security and content protection features. Security is never implemented in a single place in the stack, but instead relies on the integration of hardware, software, and services. The combination of hardware security functions, a trusted boot mechanism, and an isolated secure OS for handling security functions is critical to providing a secure device.

Architecture

The DRM framework is designed to be implementation agnostic and abstracts the details of the specific DRM scheme implementation in a scheme-specific DRM plugin. The DRM framework includes simple APIs to handle complex DRM operations, acquire licenses, provision the device, associate DRM content and its license, and finally decrypt DRM content.

The Android DRM framework is implemented in two architectural layers:

  • A DRM framework API, which is exposed to apps through the Android application framework.
  • A native code DRM framework, which exposes an interface for DRM plugins (agents) to handle rights management and decryption for various DRM schemes.
Android DRM Framework
Figure 2a. DRM framework before Android 11
Android DRM Framework
Figure 2b. DRM framework starting in Android 11

See Android Media DRM and Android Media Crypto for more details.

DRM Plugins

At system startup, the DRM framework scans for HAL instances/services (described in .rc files) and plugins are discovered through the HIDL registry. Media DRM Server (mediadrmserver) creates both CryptoHal and DrmHal objects. CryptoHal and DrmHal then call the plugins with vendor- specific implementations.

Plugins should implement binderized HALs. Binderized HALs use the HAL interface definition language (HIDL), which allows the framework to be replaced without having to rebuild HALs.

Plugins are built by vendors or SOC makers and put in a /vendor partition on the device. All devices launching with Android 8.0 or higher must support binderized HALs written in the HIDL language.

Implementation

To implement new DRM frameworks APIs by a plugin:

  1. Add plugin service to the device’s build files.
  2. Update the device manifest.
  3. Add SELinux permissions.
  4. Create a .rc file under /vendor.
  5. Implement the plugin.

APIs are defined in each version of IDrmPlugin.hal, ICryptoPlugin.hal, IDrmFactory.hal, and ICryptoFactory.hal

PLATFORM_ROOT/hardware/interfaces/drm/VERSION/

Adding plugin service to device build files

For example, to add interface 1.3 support, the VENDOR DEVICE/device.mk file must include the android.hardware.drm@1.3-service.* packages:

Versions 1.0 to 1.2 are deprecated in R / Android 11. Devices upgrading to R are still allowed to run versions 1.0 to 1.2. However, new devices launching with R must run only version1.3.


  PRODUCT_PACKAGES += \
    android.hardware.drm@1.0-impl \
    android.hardware.drm@1.0-service \
    android.hardware.drm@1.3-service.clearkey \
    android.hardware.drm@1.3-service.widevine

Updating the device manifest

The vendor manifest.xml file for the device must include the following entries:


  <hal format="hidl">
    <name>android.hardware.drm</name>
      <transport>hwbinder</transport>
      <fqname>@1.3::ICryptoFactory/clearkey</fqname>
      <fqname>@1.3::IDrmFactory/clearkey</fqname>
      <fqname>@1.3::ICryptoFactory/widevine</fqname>
      <fqname>@1.3::IDrmFactory/widevine</fqname>
  </hal>

Alternately, we recommend using vintf_fragments.

Adding SELinux permissions

  1. Add to VENDOR DEVICE/sepolicy/vendor/file.te
    type mediadrm_vendor_data_file, file_type, data_file_type;
  2. Add to VENDOR DEVICE/sepolicy/vendor/file_contexts

    We recommend using regular expressions to specify the version numbers to avoid making updates for new releases, for example:

    /vendor/bin/hw/android\.hardware\.drm@\[0-9]+\.[0-9]+-service\.clearkey
      u:object_r:hal_drm_clearkey_exec:s0
    
    /data/vendor/mediadrm(/.*)? u:object_r:mediadrm_vendor_data_file:s0

    Alternately, update the version numbers as shown below.

    /vendor/bin/hw/android\.hardware\.drm@1\.3-service\.clearkey
      u:object_r:hal_drm_clearkey_exec:s0
    
    /data/vendor/mediadrm(/.*)? u:object_r:mediadrm_vendor_data_file:s0
  3. Add to device/sepolicy/vendor/hal_drm_clearkey.te
    allow hal_drm_clearkey mediadrm_vendor_data_file:dir create_dir_perms;
    allow hal_drm_clearkey mediadrm_vendor_data_file:file create_file_perms;

Creating an .rc file under /vendor

The .rc file specifies the actions to be taken when a service is launched.

See Android Init Language for details.

Implementing the plugin

  1. Implement the main() entry point in service.cpp of the plugin service.
  2. Implement ICryptoPlugin, IDrmPlugin, ICryptoFactory, and IDrmFactory.
  3. Implement the new APIs in the plugin.

DRM plugin details

DRM plugin vendors implement DrmFactory, CryptoFactory, and DRM plugin.

DrmFactory

The DrmHal class searches for registered DRM plugin services and constructs corresponding plugins that support a given crypto scheme through the DrmFactory class.

IDrmFactory is the main entry point for interacting with a vendor's drm HAL through the createPlugin API. The createPlugin API is used to create IDrmPlugin instances. The 1.3 IDrmFactory must always create 1.2 IDrmPlugin interfaces, which are returned via the 1.0 createPlugin method.

Return<void> getSupportedCryptoSchemes(getSupportedCryptoSchemes_cb _hidl_cb);

New in 1.3 IDrmFactory, getSupportedCryptoSchemes returns a list of supported crypto schemes for the HIDL drm HAL instance.

Return<bool> isCryptoSchemeSupported(const hidl_array<uint8_t, 16>uuid);

Determines if the plugin factory is able to construct DRM plugins that support a given crypto scheme, which is specified by a UUID.

Return<bool> isContentTypeSupported(const hidl_string &mimeType);

Determines if the plugin factory is able to construct DRM plugins that support a given media container format specified by mimeType.

Return<void> createPlugin(const hidl_array<uint8_t, 16>uuid,
        const hidl_string& appPackageName, createPlugin_cb _hidl_cb);

Constructs a DRM plugin for the crypto scheme specified by UUID.

CryptoFactory

The CryptoHal class searches for registered DRM plugin services and constructs corresponding plugins that support a given crypto scheme through the CryptoFactory class.

Return<bool> isCryptoSchemeSupported(const hidl_array<uint8_t, 16>uuid);

Determines if the crypto factory is able to construct crypto plugins that support a given crypto scheme, which is specified by a UUID.

Return<void> createPlugin(const hidl_array<uint8_t, 16>uuid,
        const hidl_vec<uint8_t>initData, createPlugin_cb _hidl_cb)

Determines if the plugin factory is able to construct crypto plugins that support a given crypto scheme, which is specified by a UUID.

DRM plugin

The APIs are defined in hardware/interfaces/drm/VERSION /IDrmPlugin.hal. The corresponding IDrmPlugin.h file can be found in out/Soong after the build.