This document provides an overview of the Android DRM framework, and introduces the interfaces a DRM plug-in must implement. This document does not describe robustness rules or compliance rules that may be defined by a DRM scheme.
Introduction
The Android platform provides an extensible DRM framework that lets applications 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 introduced in Android 3.0 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 non-protected content. DRM schemes can define very 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 non-protected content. See MediaDrm for the class to obtain keys for decrypting protected media streams.
Figure 1. DRM Hardware Abstraction Layer
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 at least one consistent DRM available across all devices, Google provides DRM without license fees on compatible Android devices. On Android 3.0 and higher platforms, the DRM plug-in 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 plug-in depends on the security and content protection capabilities of the underlying hardware platform. The hardware capabilities of the device include hardware secure boot to establish a chain of trust of security and protection of cryptographic keys. Content protection capabilities of the device include protection of decrypted frames in the device and content protection via 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 plug-in. The DRM framework includes simple APIs to handle complex DRM operations, register users and devices to online DRM services, extract constraint information from the license, 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 applications through the Android application framework and runs through the Dalvik VM for standard applications.
- A native code DRM manager, which implements the DRM framework and exposes an interface for DRM plug-ins (agents) to handle rights management and decryption for various DRM schemes.
Figure 2. DRM framework
For details, refer to the Android DRM package reference.
Plug-ins
As shown in the figure below, the DRM framework uses a plug-in architecture to support various DRM schemes. The DRM manager service runs in an independent process to ensure isolated execution of DRM plug-ins. Each API call from DrmManagerClient to DrmManagerService goes across process boundaries by using the binder IPC mechanism. The DrmManagerClient provides a Java programming language implementation as a common interface to runtime applications; it also provides a DrmManagerClient-native implementation as the interface to native modules. The caller of DRM framework accesses only the DrmManagerClient and does not have to be aware of each DRM scheme.
Figure 3. DRM framework with plug-ins
Plug-ins are loaded automatically when DrmManagerService is launched. As shown in the figure below, the DRM plug-in manager loads/unloads all the available plug-ins. The DRM framework loads plug-ins automatically by finding them under:
/system/lib/drm/plugins/native/
Figure 4. DRM plug-in lifecycle
The plug-in developer should ensure the plug-in is located in the DRM framework plug-in discovery directory. See implementation instructions below for details.
Implementation
IDrmEngine
IDrmEngine is an interface with a set of APIs for DRM use cases. Plug-in developers must implement the interfaces specified in IDrmEngine and the listener interfaces specified below. The interface definition is available in the source tree at:
PLATFORM_ROOT/frameworks/av/drm/libdrmframework/plugins/common/include
DRM Info
DrmInfo is a wrapper class that wraps the protocol for communicating with the DRM server. Server registration, deregistration, license acquisition, or any other server-related transaction can be achieved by processing an instance of DrmInfo. The protocol should be described by the plug-in in XML format. Each DRM plug-in would accomplish the transaction by interpreting the protocol. The DRM framework defines an API to retrieve an instance of DrmInfo called acquireDrmInfo().
DrmInfo* acquireDrmInfo(int uniqueId, const DrmInfoRequest* drmInfoRequest);
Retrieves necessary information for registration, deregistration or rights acquisition information. See DrmInfoRequest for more information.
DrmInfoStatus* processDrmInfo(int uniqueId, const DrmInfo* drmInfo);
processDrmInfo() behaves asynchronously and the results of the transaction can be retrieved either from OnEventListener or OnErrorListener.
DRM rights
The association of DRM content and the license is required to allow playback of DRM content. Once the association has been made, the license will be handled in the DRM framework so the Media Player application is abstracted from the existence of license.
int checkRightsStatus(int uniqueId, const String8& path, int action);
Check whether the given content has valid rights or not. The input parameters are the content file path where the content was saved and the action to query rights for, for example: Action::DEFAULT, Action::PLAY. Returns the status of the rights for the protected content, such as RightsStatus::RIGHTS_VALID, RightsStatus::RIGHTS_EXPIRED.
status_t saveRights(int uniqueId, const DrmRights& drmRights, const String8& rightsPath, const String8& contentPath);
Save DRM rights to the specified rights path and make association with content path. The input parameters are the DrmRights to be saved, the rights file path where rights are to be saved, and the content file path where content was saved.
License Metadata
License metadata such as license expiry time, repeatable count and etc., may be embedded inside the rights of the protected content. The Android DRM framework provides APIs to return constraints associated with input content. See DrmManagerClient for more information.
DrmConstraints* getConstraints(int uniqueId, const String path, int action);
The getConstraint function call returns key-value pairs of constraints embedded in protected content. To retrieve the constraints, the uniqueIds (the Unique identifier for a session and path of the protected content) are required. The action, defined as Action::DEFAULT, Action::PLAY, etc., is also required.
Figure 5. Retrieve license metadata
DrmMetadata* getMetadata(int uniqueId, const String path);
Get metadata information associated with input content for a given path of the protected content to return key-value pairs of metadata.
Decrypt session
To maintain the decryption session, the caller of the DRM framework must invoke openDecryptSession() at the beginning of the decryption sequence. openDecryptSession() asks each DRM plug-in if it can handle input DRM content.
status_t openDecryptSession( int uniqueId, DecryptHandle* decryptHandle, int fd, off64_t offset, off64_t length);
The above call allows you to save DRM rights to specified rights path and make association with content path. DrmRights parameter is the rights to be saved, file path where rights should be and content file path where content should be saved.
DRM plug-in Listeners
Some APIs in DRM framework behave asynchronously in a DRM transaction. An application can register three listener classes to DRM framework.
- OnEventListener for results of asynchronous APIs
- OnErrorListener for receiving errors of asynchronous APIs
- OnInfoListener for any supplementary information during DRM transactions.
Source
The Android DRM framework includes a couple of samples, a passthru plug-in and a forward lock plug-in, which can be found at:
PLATFORM_ROOT/frameworks/av/drm/libdrmframework/plugins/passthru PLATFORM_ROOT/frameworks/av/drm/libdrmframework/plugins/forward-lock
Build and Integration
Add the following to the Android.mk of the plug-in implementation. The passthruplugin is used as a sample.
PRODUCT_COPY_FILES += $(TARGET_OUT_SHARED_LIBRARIES)/PLUGIN_LIBRARY:system/lib/drm/plugins/native/PLUGIN_LIBRARY
e.g.,
PRODUCT_COPY_FILES += $(TARGET_OUT_SHARED_LIBRARIES)/libdrmpassthruplugin.so:system/lib/drm/plugins/native/libdrmpassthruplugin.so
Plug-in developers must locate their respective plug-ins under this directory like so:
/system/lib/drm/plugins/native/libdrmpassthruplugin.so