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