1 /** 2 * Copyright (C) 2018 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 package android.hardware.drm@1.2; 17 18 import @1.0::KeyedVector; 19 import @1.0::KeyType; 20 import @1.0::SessionId; 21 import @1.0::Status; 22 import @1.1::IDrmPlugin; 23 import @1.1::KeyRequestType; 24 import @1.2::IDrmPluginListener; 25 26 /** 27 * IDrmPlugin is used to interact with a specific drm plugin that was 28 * created by IDrm::createPlugin. A drm plugin provides methods for 29 * obtaining drm keys to be used by a codec to decrypt protected video 30 * content. 31 */ 32 interface IDrmPlugin extends @1.1::IDrmPlugin { 33 34 /** 35 * The keys in an offline license allow protected content to be 36 * played even if the device is not connected to a network. 37 * Offline licenses are stored on the device after a key 38 * request/response exchange when the key request KeyType is 39 * OFFLINE. Normally each app is responsible for keeping track of 40 * the KeySetIds it has created. In some situations however, it 41 * will be necessary to request the list of stored offline license 42 * KeySetIds. If an app loses the KeySetId for any stored licenses 43 * that it created, for example, it must be able to recover the 44 * stored KeySetIds so those licenses will be removed when they 45 * expire or when the app is uninstalled. 46 * <p> 47 * This method returns a list of the KeySetIds for all offline 48 * licenses. The offline license KeySetId allows an app to query 49 * the status of an offline license or remove it. 50 * 51 * @return status the status of the call. Must be OK or 52 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the 53 * KeySetIds can't be returned. 54 * @return a list of offline license keySetIds. If there are no offline 55 * licenses, the list must be empty and OK must be returned as the 56 * status. 57 */ 58 getOfflineLicenseKeySetIds() generates (@1.0::Status status, 59 vec<KeySetId> keySetIds); 60 61 /** 62 * Normally offline licenses are released using a key 63 * request/response exchange using getKeyRequest where the KeyType 64 * is RELEASE, followed by provideKeyResponse. This allows the 65 * server to cryptographically confirm that the license has been 66 * removed and then adjust the count of offline licenses allocated 67 * to the device. 68 * <p> 69 * In some exceptional situations it will be necessary to directly 70 * remove offline licenses without notifying the server, which is 71 * performed by this method. 72 * 73 * @param keySetId the id of the offline license to remove 74 * @return status the status of the call. Must be one of OK on 75 * success, BAD_VALUE if the license is not found or 76 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the 77 * KeySetIds can't be removed. 78 */ 79 removeOfflineLicense(KeySetId keySetId) generates (@1.0::Status status); 80 81 /** 82 * Request the state of an offline license. An offline license must 83 * be usable or inactive. The keys in a usable offline license are 84 * available for decryption. When the offline license state is 85 * inactive, the keys have been marked for release using 86 * getKeyRequest with KeyType RELEASE but the key response has not 87 * been received. The keys in an inactive offline license are not 88 * usable for decryption. 89 * 90 * @param keySetId the id of the offline license 91 * @return status the status of the call. Must be one of OK on 92 * success, BAD_VALUE if the license is not found or 93 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the 94 * offline license state can't be queried. 95 * @return the offline license state, one of USABLE or INACTIVE. 96 * If the return status is not OK then state must be set to 97 * UNKNOWN. 98 */ 99 getOfflineLicenseState(KeySetId keySetId) generates ( 100 @1.0::Status status, OfflineLicenseState state); 101 102 /** 103 * A key request/response exchange occurs between the app and a License 104 * Server to obtain the keys required to decrypt the content. 105 * getKeyRequest_1_2() is used to obtain an opaque key request blob that is 106 * delivered to the license server. 107 * 108 * getKeyRequest_1_2() only differs from getKeyRequest_1_1() in that 109 * additional status codes must be returned. 110 * 111 * @param scope either a sessionId or a keySetId, depending on the 112 * specified keyType. When the keyType is OFFLINE or STREAMING, scope 113 * must be set to the sessionId the keys will be provided to. When the 114 * keyType is RELEASE, scope must be set to the keySetId of the keys 115 * being released. 116 * @param initData container-specific data, its meaning is interpreted 117 * based on the mime type provided in the mimeType parameter. It could 118 * contain, for example, the content ID, key ID or other data obtained 119 * from the content metadata that is required to generate the key 120 * request. initData must be empty when keyType is RELEASE. 121 * @param mimeType identifies the mime type of the content 122 * @param keyType specifies if the keys are to be used for streaming, 123 * offline or a release 124 * @param optionalParameters included in the key request message to 125 * allow a client application to provide additional message parameters 126 * to the server. 127 * @return status the status of the call. The status must be OK or one of 128 * the following errors: ERROR_DRM_SESSION_NOT_OPENED if the session is 129 * not opened, ERROR_DRM_NOT_PROVISIONED if the device requires 130 * provisioning before it is able to generate a key request, 131 * ERROR_DRM_RESOURCE_CONTENTION if client applications using the hal 132 * are temporarily exceeding the available crypto resources such that a 133 * retry of the operation is likely to succeed, ERROR_DRM_CANNOT_HANDLE 134 * if getKeyRequest is not supported at the time of the call, BAD_VALUE 135 * if any parameters are invalid or ERROR_DRM_INVALID_STATE if the HAL 136 * is in a state where a key request cannot be generated. 137 * @return request if successful, the opaque key request blob is returned 138 * @return requestType indicates type information about the returned 139 * request. The type must be one of INITIAL, RENEWAL, RELEASE, NONE or 140 * UPDATE. An INITIAL request is the first key request for a 141 * license. RENEWAL is a subsequent key request used to refresh the 142 * keys in a license. RELEASE corresponds to a keyType of RELEASE, 143 * which indicates keys are being released. NONE indicates that no 144 * request is needed because the keys are already loaded. UPDATE 145 * indicates that the keys need to be refetched after the initial 146 * license request. 147 * @return defaultUrl the URL that the request may be sent to, if 148 * provided by the drm HAL. The app can choose to override this URL. 149 */ 150 getKeyRequest_1_2(vec<uint8_t> scope, vec<uint8_t> initData, 151 string mimeType, KeyType keyType, KeyedVector optionalParameters) 152 generates (Status status, vec<uint8_t> request, 153 KeyRequestType requestType, string defaultUrl); 154 155 /** 156 * A provision request/response exchange occurs between the app and a 157 * provisioning server to retrieve a device certificate. getProvisionRequest 158 * is used to obtain an opaque provisioning request blob that is delivered 159 * to the provisioning server. 160 * 161 * getProvisionRequest_1_2() only differs from getProvisionRequest_1_0() in 162 * that additional status codes must be returned. 163 * 164 * @param certificateType the type of certificate requested, e.g. "X.509" 165 * @param certificateAuthority identifies the certificate authority. A 166 * certificate authority (CA) is an entity which issues digital 167 * certificates for use by other parties. It is an example of a trusted 168 * third party. 169 * @return status the status of the call. The status must be OK or one of 170 * the following errors: ERROR_DRM_RESOURCE_CONTENTION if client 171 * applications using the hal are temporarily exceeding the available 172 * crypto resources such that a retry of the operation is likely to 173 * succeed, ERROR_DRM_CANNOT_HANDLE if the drm scheme does not require 174 * provisioning or ERROR_DRM_INVALID_STATE if the HAL is in a state 175 * where the provision request cannot be generated. 176 * @return request if successful the opaque certificate request blob 177 * is returned 178 * @return defaultUrl URL that the provisioning request may be 179 * sent to, if known by the HAL implementation. An app can choose to 180 * override this URL. If the HAL implementation does not provide a 181 * defaultUrl, the returned string must be empty. 182 */ 183 getProvisionRequest_1_2(string certificateType, string certificateAuthority) 184 generates (Status status, vec<uint8_t> request, string defaultUrl); 185 186 /** 187 * Return the currently negotiated and max supported HDCP levels. 188 * 189 * This method only differs from @1.1 version by the addition of 190 * support for HDCP 2.3. 191 * 192 * The current level is based on the display(s) the device is connected to. 193 * If multiple HDCP-capable displays are simultaneously connected to 194 * separate interfaces, this method returns the lowest negotiated HDCP level 195 * of all interfaces. 196 * 197 * The maximum HDCP level is the highest level that can potentially be 198 * negotiated. It is a constant for any device, i.e. it does not depend on 199 * downstream receiving devices that could be connected. For example, if 200 * the device has HDCP 1.x keys and is capable of negotiating HDCP 1.x, but 201 * does not have HDCP 2.x keys, then the maximum HDCP capability would be 202 * reported as 1.x. If multiple HDCP-capable interfaces are present, it 203 * indicates the highest of the maximum HDCP levels of all interfaces. 204 * 205 * This method should only be used for informational purposes, not for 206 * enforcing compliance with HDCP requirements. Trusted enforcement of HDCP 207 * policies must be handled by the DRM system. 208 * 209 * @return status the status of the call. The status must be OK or 210 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the HDCP 211 * level cannot be queried. 212 * @return connectedLevel the lowest HDCP level for any connected 213 * displays 214 * @return maxLevel the highest HDCP level that can be supported 215 * by the device 216 */ 217 getHdcpLevels_1_2() generates (Status status, HdcpLevel connectedLevel, 218 HdcpLevel maxLevel); 219 220 /** 221 * Send a session lost state event to the listener. This event 222 * indicates that a session's state has become invalid because the 223 * device crypto hardware is incapable of retaining crypto session 224 * state across suspend and resume cycles. 225 * 226 * @param sessionId identifies the session the event originated from 227 */ 228 sendSessionLostState(SessionId sessionId); 229 230 /** 231 * Send a keys change event to the listener. The keys change event 232 * indicates the status of each key in the session. Keys can be 233 * indicated as being usable, expired, outputnotallowed or statuspending. 234 * 235 * This method only differs from @1.0 version by the addition of new 236 * KeyStatusType(s) in keyStatusList. 237 * 238 * @param sessionId identifies the session the event originated from 239 * @param keyStatusList indicates the status for each key ID in the 240 * session. 241 * @param hasNewUsableKey indicates if the event includes at least one 242 * key that has become usable. 243 */ 244 sendKeysChange_1_2(SessionId sessionId, vec<KeyStatus> keyStatusList, 245 bool hasNewUsableKey); 246 247 }; 248
