DRM

This page provides an overview of the Android digital rights management (DRM) framework and introduces the interfaces that a DRM plugin must implement. This page doesn't describe robustness rules or compliance rules that might 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; the device manufacturer determines which DRM schemes a device supports. The DRM framework provides a unified interface for app 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.

Figure 1 shows the DRM hardware extraction layer before Android 11, and Figure 2 shows the layer in Android 11 and higher:

Figure 1. DRM hardware abstraction layer before Android 11.

Figure 2. 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 app framework
• A native code DRM framework, which exposes an interface for DRM plugins (agents) to handle rights management and decryption for various DRM schemes

Figure 3 shows the DRM framework before Android 11, and Figure 4 shows the framework in Android 11 and higher:

Figure 3. DRM framework before Android 11.

Figure 4. DRM framework starting in Android 11.

See MediaDrm and MediaCrypto for more details.

DRM plugins

At system startup, the DRM framework scans for HAL instances and services (described in .rc files) and discovers plugins. 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 Android Interface Definition Language (AIDL), 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 13 or higher must support binderized HALs written in the AIDL 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 an .rc file under /vendor.
5. Implement the plugin.

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

aidl/PLATFORM_ROOT/hardware/interfaces/drm/

Add plugin service to device build files

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

  PRODUCT_PACKAGES += \
    android.hardware.drm-service.clearkey \
    android.hardware.drm-service.widevine

Update the device manifest

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

  <hal format="aidl">
    <name>android.hardware.drm</name>
    <version>STABLE AIDL VERSION</version>
      <fqname>ICryptoFactory/clearkey</fqname>
      <fqname>IDrmFactory/clearkey</fqname>
      <fqname>ICryptoFactory/widevine</fqname>
      <fqname>IDrmFactory/widevine</fqname>
  </hal>

The stable AIDL version is the version number of each AIDL API release (for example, 1, 2). Alternately, we recommend using vintf_fragments.

Add SELinux permissions

1. Add permissions to VENDOR DEVICE/sepolicy/vendor/file.te:
   

   type mediadrm_vendor_data_file, file_type, data_file_type;

2. Add permissions to VENDOR DEVICE/sepolicy/vendor/file_contexts:
   

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

3. Add permissions to device/sepolicy/vendor/hal_drm_clearkey.te:
   

       vndbinder_use(hal_drm_clearkey)
       allow hal_drm_clearkey servicemanager:binder { call transfer };
       allow hal_drm_clearkey hal_drm_service:service_manager add;
       allow hal_drm_clearkey { appdomain -isolated_app }:fd use;
       get_prop(ramdump, public_vendor_default_prop)
       

Create 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.

Implement 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 the DRM plugin.

DrmFactory class

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 method. Use this method to create IDrmPlugin instances.

::ndk::ScopedAStatus getSupportedCryptoSchemes(
    std::vector<::aidl::android::hardware::drm::Uuid>* _aidl_return);

getSupportedCryptoSchemes returns a list of supported crypto schemes for the AIDL DRM HAL instance. This sequence determines if the plugin factory can construct DRM plugins that support a given crypto scheme, which is specified by a UUID:

::ndk::ScopedAStatus isCryptoSchemeSupported(
    const ::aidl::android::hardware::drm::Uuid& in_uuid,
    const std::string& in_mimeType,
    ::aidl::android::hardware::drm::SecurityLevel in_securityLevel,
    bool* _aidl_return);

This sequence determines if the plugin factory can construct DRM plugins that support a given media container format specified by mimeType:

::ndk::ScopedAStatus isContentTypeSupported(const std::string& in_mimeType,
    bool* _aidl_return);

This sequence constructs a DRM plugin for the crypto scheme specified by UUID:

::ndk::ScopedAStatus createPlugin(
    const ::aidl::android::hardware::drm::Uuid& in_uuid,
    const std::string& in_appPackageName,
    std::shared_ptr<::aidl::android::hardware::drm::IDrmPlugin>* _aidl_return);

CryptoFactory class

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

This sequence determines if the crypto factory can construct crypto plugins that support a given crypto scheme, which is specified by a UUID:

::ndk::ScopedAStatus isCryptoSchemeSupported(
    const ::aidl::android::hardware::drm::Uuid& in_uuid,
    bool* _aidl_return);

This sequence determines if the plugin factory can construct crypto plugins that support a given crypto scheme, which is specified by a UUID:

::ndk::ScopedAStatus createPlugin(
    const ::aidl::android::hardware::drm::Uuid& in_uuid,
    const std::vector<uint8_t>& in_initData,
    std::shared_ptr<::aidl::android::hardware::drm::ICryptoPlugin>* _aidl_return);

DRM plugin APIs