1 <html devsite> 2 <head> 3 <title>DRM</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 26 <img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_drm.png" alt="Android DRM HAL icon"/> 27 28 <p>This document provides an overview of the Android DRM framework, and 29 introduces the interfaces a DRM plug-in must implement. This document does not 30 describe robustness rules or compliance rules that may be defined by a DRM 31 scheme.</p> 32 33 <h2 id="introduction">Introduction</h2> 34 35 <p>The Android platform provides an extensible DRM framework that lets 36 applications manage rights-protected content according to the license 37 constraints associated with the content. The DRM framework supports many DRM 38 schemes; which DRM schemes a device supports is up to the device manufacturer. 39 The DRM framework introduced in Android 3.0 provides a unified interface for 40 application developers and hides the complexity of DRM operations. The DRM 41 framework provides a consistent operation mode for protected and non-protected 42 content. DRM schemes can define very complex usage models by license metadata. 43 The DRM framework provides the association between DRM content and license, and 44 handles the rights management. This enables the media player to be abstracted 45 from DRM-protected or non-protected content. See <a 46 href="https://developer.android.com/reference/android/media/MediaDrm.html">MediaDrm</a> 47 for the class to obtain keys for decrypting protected media streams.</p> 48 49 <img src="/devices/images/ape_fwk_drm.png" alt="Android DRM HAL" /> 50 51 <p class="img-caption"><strong>Figure 1.</strong> DRM Hardware Abstraction 52 Layer</p> 53 54 <p> 55 Availability of rich digital content is important to users on mobile devices. To 56 make their content widely available, Android developers and digital content 57 publishers need a consistent DRM implementation supported across the Android 58 ecosystem. To make that digital content available on Android devices and to ensure at least one consistent DRM available across all 59 devices, Google provides DRM without license fees on compatible Android devices. 60 On Android 3.0 and higher platforms, the DRM plug-in is integrated with the 61 Android DRM framework and can use hardware-backed protection to secure premium 62 content and user credentials. 63 </p> 64 65 <p> 66 The content protection provided by the DRM plug-in depends on the security and 67 content protection capabilities of the underlying hardware platform. The 68 hardware capabilities of the device include hardware secure boot to establish a 69 chain of trust of security and protection of cryptographic keys. Content 70 protection capabilities of the device include protection of decrypted frames in 71 the device and content protection via a trusted output protection mechanism. Not 72 all hardware platforms support all of the above security and content protection 73 features. Security is never implemented in a single place in the 74 stack, but instead relies on the integration of hardware, software, and 75 services. The combination of hardware security functions, a trusted boot 76 mechanism, and an isolated secure OS for handling security functions is critical 77 to providing a secure device.</p> 78 79 80 <h2 id="architecture">Architecture</h2> 81 <p>The DRM framework is designed to be implementation agnostic and 82 abstracts the details of the specific DRM scheme implementation in a 83 scheme-specific DRM plug-in. The DRM framework includes simple APIs to handle 84 complex DRM operations, register users and devices to online DRM services, 85 extract constraint information from the license, associate DRM content and its 86 license, and finally decrypt DRM content.</p> 87 88 <p>The Android DRM framework is implemented in two architectural layers:</p> 89 <ul> 90 <li>A DRM framework API, which is exposed to applications through the Android 91 application framework and runs through the Dalvik VM for standard 92 applications.</li> 93 <li>A native code DRM manager, which implements the DRM framework and exposes an 94 interface for DRM plug-ins (agents) to handle rights management and decryption 95 for various DRM schemes.</li> 96 </ul> 97 98 <img src="images/ape_fwk_drm_2.png" alt="Android DRM Framework" /> 99 100 <p class="img-caption"><strong>Figure 2.</strong> DRM framework</p> 101 102 <p>For details, refer to the <a 103 href="http://developer.android.com/reference/android/drm/package-summary.html">Android 104 DRM package reference</a>.</p> 105 106 <h2 id="plug-ins">Plug-ins</h2> 107 <p>As shown in the figure below, the DRM framework uses a plug-in architecture 108 to support various DRM schemes. The DRM manager service runs in an independent 109 process to ensure isolated execution of DRM plug-ins. Each API call from 110 DrmManagerClient to DrmManagerService goes across process boundaries by using 111 the binder IPC mechanism. The DrmManagerClient provides a Java programming 112 language implementation as a common interface to runtime applications; it 113 also provides a DrmManagerClient-native implementation as the interface to 114 native modules. The caller of DRM framework accesses only the DrmManagerClient 115 and does not have to be aware of each DRM scheme. </p> 116 117 <img src="images/ape_fwk_drm_plugins.png" alt="Android DRM Plug-in" /> 118 119 <p class="img-caption"><strong>Figure 3.</strong> DRM framework with plug-ins</p> 120 121 <p>Plug-ins are loaded automatically when DrmManagerService is launched. As 122 shown in the figure below, the DRM plug-in manager loads/unloads all the 123 available plug-ins. The DRM framework loads plug-ins automatically by finding 124 them under:</p> 125 <pre class="devsite-click-to-copy"> 126 /system/lib/drm/plugins/native/ 127 </pre> 128 129 <img src="images/ape_fwk_drm_plugins_life.png" alt="Android DRM Plug-in Lifecycle" /> 130 131 <p class="img-caption"><strong>Figure 4.</strong> DRM plug-in lifecycle</p> 132 133 <p>The plug-in developer should ensure the plug-in is located in the DRM 134 framework plug-in discovery directory. See implementation instructions below for details.</p> 135 136 <h2 id="implementation">Implementation</h2> 137 138 <h3 id="IDrmEngine">IDrmEngine</h3> 139 140 <p>IDrmEngine is an interface with a set of APIs for DRM use cases. Plug-in 141 developers must implement the interfaces specified in IDrmEngine and the 142 listener interfaces specified below. The interface definition is available in 143 the source tree at:<p/> 144 <pre class="devsite-click-to-copy"> 145 <var>PLATFORM_ROOT</var>/frameworks/av/drm/libdrmframework/plugins/common/include 146 </pre> 147 148 <h3 id="DrmInfo">DRM Info</h3> 149 <p>DrmInfo is a wrapper class that wraps the protocol for communicating with the 150 DRM server. Server registration, deregistration, license acquisition, or any other 151 server-related transaction can be achieved by processing an instance of DrmInfo. 152 The protocol should be described by the plug-in in XML format. Each DRM plug-in 153 would accomplish the transaction by interpreting the protocol. The DRM framework 154 defines an API to retrieve an instance of DrmInfo called acquireDrmInfo().</p> 155 156 <pre class="devsite-click-to-copy prettyprint"> 157 DrmInfo* acquireDrmInfo(int uniqueId, const DrmInfoRequest* drmInfoRequest); 158 </pre> 159 <p>Retrieves necessary information for registration, deregistration or rights 160 acquisition information. See <a 161 href="http://developer.android.com/reference/android/drm/DrmInfoRequest.html">DrmInfoRequest</a> for more information.</p> 162 163 <pre class="devsite-click-to-copy prettyprint"> 164 DrmInfoStatus* processDrmInfo(int uniqueId, const DrmInfo* drmInfo); 165 </pre> 166 <p>processDrmInfo() behaves asynchronously and the results of the transaction can 167 be retrieved either from OnEventListener or OnErrorListener.</p> 168 169 <h3 id="drm-rights">DRM rights</h3> 170 171 <p>The association of DRM content and the license is required to allow playback 172 of DRM content. Once the association has been made, the license will be handled in 173 the DRM framework so the Media Player application is abstracted from the existence 174 of license.</p> 175 176 <pre class="devsite-click-to-copy prettyprint"> 177 int checkRightsStatus(int uniqueId, const String8& path, int action); 178 </pre> 179 180 <p>Check whether the given content has valid rights or not. The input 181 parameters are the content file path where the content was saved and the action 182 to query rights for, for example: Action::DEFAULT, Action::PLAY. Returns the 183 status of the rights for the protected content, such as 184 RightsStatus::RIGHTS_VALID, RightsStatus::RIGHTS_EXPIRED.</p> 185 186 <pre class="devsite-click-to-copy prettyprint"> 187 status_t saveRights(int uniqueId, const DrmRights& drmRights, const String8& rightsPath, const String8& contentPath); 188 </pre> 189 190 <p>Save DRM rights to the specified rights path and make association with content path. 191 The input parameters are the DrmRights to be saved, the rights file path where rights 192 are to be saved, and the content file path where content was saved.</p> 193 194 <h3 id="metadata">License Metadata</h3> 195 <p>License metadata such as license expiry time, repeatable count and etc., may be 196 embedded inside the rights of the protected content. The Android DRM framework 197 provides APIs to return constraints associated with input content. See <a 198 href="http://developer.android.com/reference/android/drm/DrmManagerClient.html">DrmManagerClient</a> 199 for more information.</p> 200 201 <pre class="devsite-click-to-copy prettyprint"> 202 DrmConstraints* getConstraints(int uniqueId, const String path, int 203 action); 204 </pre> 205 <p>The getConstraint function call returns key-value pairs of constraints 206 embedded in protected content. To retrieve the constraints, the uniqueIds (the 207 Unique identifier for a session and path of the protected content) are required. 208 The action, defined as Action::DEFAULT, Action::PLAY, etc., is also required.</p> 209 210 <img src="images/ape_fwk_drm_retrieve_license.png" alt="Android DRM License Metadata" /> 211 212 <p class="img-caption"><strong>Figure 5.</strong> Retrieve license metadata</p> 213 214 <pre class="devsite-click-to-copy prettyprint"> 215 DrmMetadata* getMetadata(int uniqueId, const String path); 216 </pre> 217 <p>Get metadata information associated with input content for a given path of the 218 protected content to return key-value pairs of metadata.</p> 219 220 <h3 id="metadata">Decrypt session</h3> 221 <p>To maintain the decryption session, the caller of the DRM framework must 222 invoke openDecryptSession() at the beginning of the decryption sequence. 223 openDecryptSession() asks each DRM plug-in if it can handle input DRM 224 content.</p> 225 <pre class="devsite-click-to-copy prettyprint"> 226 status_t openDecryptSession( 227 int uniqueId, DecryptHandle* decryptHandle, int fd, off64_t offset, off64_t length); 228 </pre> 229 230 <p>The above call allows you to save DRM rights to specified rights path and make 231 association with content path. DrmRights parameter is the rights to be saved, 232 file path where rights should be and content file path where content should be 233 saved.</p> 234 235 <h3 id="listeners">DRM plug-in Listeners</h3> 236 237 <p>Some APIs in DRM framework behave asynchronously in a DRM transaction. An 238 application can register three listener classes to DRM framework.</p> 239 240 <ul> 241 <li>OnEventListener for results of asynchronous APIs</li> 242 <li>OnErrorListener for receiving errors of asynchronous APIs</li> 243 <li>OnInfoListener for any supplementary information during DRM 244 transactions.</li> 245 </ul> 246 247 <h3 id="source">Source</h3> 248 249 <p>The Android DRM framework includes a couple of samples, a passthru plug-in 250 and a forward lock plug-in, which can be found at:</p> 251 <pre class="devsite-click-to-copy"> 252 <var>PLATFORM_ROOT</var>/frameworks/av/drm/libdrmframework/plugins/passthru 253 <var>PLATFORM_ROOT</var>/frameworks/av/drm/libdrmframework/plugins/forward-lock 254 </pre> 255 256 <h3 id="build">Build and Integration</h3> 257 258 <p>Add the following to the Android.mk of the plug-in implementation. The 259 passthruplugin is used as a sample.</p> 260 261 <pre class="devsite-click-to-copy"> 262 PRODUCT_COPY_FILES += $(TARGET_OUT_SHARED_LIBRARIES)/<var>PLUGIN_LIBRARY</var>:system/lib/drm/plugins/native/<var>PLUGIN_LIBRARY</var> 263 </pre> 264 <p>e.g.,</p> 265 <pre class="devsite-click-to-copy"> 266 PRODUCT_COPY_FILES += $(TARGET_OUT_SHARED_LIBRARIES)/libdrmpassthruplugin.so:system/lib/drm/plugins/native/libdrmpassthruplugin.so 267 </pre> 268 <p>Plug-in developers must locate their respective plug-ins under this 269 directory like so:</p> 270 <pre class="devsite-click-to-copy"> 271 /system/lib/drm/plugins/native/libdrmpassthruplugin.so 272 </pre> 273 274 </body> 275 </html> 276
