1 /** 2 * Copyright (C) 2017 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.1; 17 18 import @1.0::IDrmPlugin; 19 import @1.0::IDrmPluginListener; 20 import @1.0::KeyedVector; 21 import @1.0::KeyType; 22 import @1.0::Status; 23 import @1.1::DrmMetricGroup; 24 import @1.1::HdcpLevel; 25 import @1.1::KeyRequestType; 26 import @1.0::SecureStopId; 27 import @1.1::SecureStopRelease; 28 import @1.1::SecurityLevel; 29 import @1.0::SessionId; 30 31 /** 32 * IDrmPlugin is used to interact with a specific drm plugin that was created by 33 * IDrm::createPlugin. A drm plugin provides methods for obtaining drm keys that 34 * may be used by a codec to decrypt protected video content. 35 */ 36 interface IDrmPlugin extends @1.0::IDrmPlugin { 37 /** 38 * Open a new session at a requested security level. The security level 39 * represents the robustness of the device's DRM implementation. By default, 40 * sessions are opened at the native security level of the device which is 41 * the maximum level that can be supported. Overriding the security level is 42 * necessary when the decrypted frames need to be manipulated, such as for 43 * image compositing. The security level parameter must be equal to or lower 44 * than the native level. If the requested level is not supported, the next 45 * lower supported security level must be set. The level can be queried 46 * using {@link #getSecurityLevel}. A session ID is returned. When the 47 * drm (at) 1.0 openSession is called, which has no securityLevel parameter, the 48 * security level is defaulted to the native security level of the device. 49 * 50 * @return status the status of the call. The status must be OK or one of 51 * the following errors: ERROR_DRM_NOT_PROVISIONED if the device 52 * requires provisioning before it can open a session, 53 * ERROR_DRM_RESOURCE_BUSY if there are insufficent resources available 54 * to open a session, ERROR_DRM_CANNOT_HANDLE if the requested security 55 * level is higher than the native level or lower than the lowest 56 * supported level or if openSession is not supported at the time of 57 * the call, or ERROR_DRM_INVALID_STATE if the HAL is in a state where 58 * a session cannot be opened. 59 * @param level the requested security level 60 * @return sessionId the session ID for the newly opened session 61 */ 62 openSession_1_1(SecurityLevel securityLevel) generates (Status status, 63 SessionId sessionId); 64 65 /** 66 * A key request/response exchange occurs between the app and a License 67 * Server to obtain the keys required to decrypt the content. 68 * getKeyRequest_1_1() is used to obtain an opaque key request blob that is 69 * delivered to the license server. 70 * 71 * getKeyRequest_1_1() only differs from getKeyRequest() in that additional 72 * values are returned in 1.1::KeyRequestType as compared to 73 * 1.0::KeyRequestType 74 * 75 * @param scope may be a sessionId or a keySetId, depending on the 76 * specified keyType. When the keyType is OFFLINE or STREAMING, 77 * scope should be set to the sessionId the keys will be provided 78 * to. When the keyType is RELEASE, scope should be set to the 79 * keySetId of the keys being released. 80 * @param initData container-specific data, its meaning is interpreted 81 * based on the mime type provided in the mimeType parameter. 82 * It could contain, for example, the content ID, key ID or 83 * other data obtained from the content metadata that is 84 * required to generate the key request. initData may be empty 85 * when keyType is RELEASE. 86 * @param mimeType identifies the mime type of the content 87 * @param keyType specifies if the keys are to be used for streaming, 88 * offline or a release 89 * @param optionalParameters included in the key request message to 90 * allow a client application to provide additional message 91 * parameters to the server. 92 * @return status the status of the call. The status must be OK or one of 93 * the following errors: ERROR_DRM_SESSION_NOT_OPENED if the 94 * session is not opened, ERROR_DRM_NOT_PROVISIONED if the device 95 * requires provisioning before it can generate a key request, 96 * ERROR_DRM_CANNOT_HANDLE if getKeyRequest is not supported 97 * at the time of the call, BAD_VALUE if any parameters are 98 * invalid or ERROR_DRM_INVALID_STATE if the HAL is in a 99 * state where a key request cannot be generated. 100 * @return request if successful, the opaque key request blob is returned 101 * @return requestType indicates type information about the returned 102 * request. The type may be one of INITIAL, RENEWAL, RELEASE, 103 * NONE or UPDATE. An INITIAL request is the first key request 104 * for a license. RENEWAL is a subsequent key request used to 105 * refresh the keys in a license. RELEASE corresponds to a 106 * keyType of RELEASE, which indicates keys are being released. 107 * NONE indicates that no request is needed because the keys are 108 * already loaded. UPDATE indicates that the keys need to be 109 * refetched after the initial license request. 110 * @return defaultUrl the URL that the request may be sent to, if 111 * provided by the drm HAL. The app may choose to override this URL. 112 */ 113 getKeyRequest_1_1(vec<uint8_t> scope, vec<uint8_t> initData, 114 string mimeType, KeyType keyType, KeyedVector optionalParameters) 115 generates (Status status, vec<uint8_t> request, 116 KeyRequestType requestType, string defaultUrl); 117 118 /** 119 * Return the currently negotiated and max supported HDCP levels. 120 * 121 * The current level is based on the display(s) the device is connected to. 122 * If multiple HDCP-capable displays are simultaneously connected to 123 * separate interfaces, this method returns the lowest negotiated HDCP level 124 * of all interfaces. 125 * 126 * The maximum HDCP level is the highest level that can potentially be 127 * negotiated. It is a constant for any device, i.e. it does not depend on 128 * downstream receiving devices that could be connected. For example, if 129 * the device has HDCP 1.x keys and is capable of negotiating HDCP 1.x, but 130 * does not have HDCP 2.x keys, then the maximum HDCP capability would be 131 * reported as 1.x. If multiple HDCP-capable interfaces are present, it 132 * indicates the highest of the maximum HDCP levels of all interfaces. 133 * 134 * This method should only be used for informational purposes, not for 135 * enforcing compliance with HDCP requirements. Trusted enforcement of HDCP 136 * policies must be handled by the DRM system. 137 * 138 * @return status the status of the call. The status must be OK or 139 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the HDCP 140 * level cannot be queried. 141 * @return connectedLevel the lowest HDCP level for any connected 142 * displays 143 * @return maxLevel the highest HDCP level that can be supported 144 * by the device 145 */ 146 getHdcpLevels() generates (Status status, HdcpLevel connectedLevel, 147 HdcpLevel maxLevel); 148 149 /** 150 * Return the current number of open sessions and the maximum number of 151 * sessions that may be opened simultaneosly among all DRM instances for the 152 * active DRM scheme. 153 * 154 * @return status the status of the call. The status must be OK or 155 * ERROR_DRM_INVALID_STATE if the HAL is in a state where number of 156 * sessions cannot be queried. 157 * @return currentSessions the number of currently opened sessions 158 * @return maxSessions the maximum number of sessions that the device 159 * can support 160 */ 161 getNumberOfSessions() generates (Status status, uint32_t currentSessions, 162 uint32_t maxSessions); 163 164 /** 165 * Return the current security level of a session. A session has an initial 166 * security level determined by the robustness of the DRM system's 167 * implementation on the device. 168 * 169 * @param sessionId the session id the call applies to 170 * @return status the status of the call. The status must be OK or one of 171 * the following errors: ERROR_DRM_SESSION_NOT_OPENED if the 172 * session is not opened, BAD_VALUE if the sessionId is invalid or 173 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the 174 * security level cannot be queried. 175 * @return level the current security level for the session 176 */ 177 getSecurityLevel(vec<uint8_t> sessionId) generates(Status status, 178 SecurityLevel level); 179 180 /** 181 * Returns the plugin-specific metrics. Multiple metric groups may be 182 * returned in one call to getMetrics(). The scope and definition of the 183 * metrics is defined by the plugin. 184 * 185 * @return status the status of the call. The status must be OK or 186 * ERROR_DRM_INVALID_STATE if the metrics are not available to be 187 * returned. 188 * @return metric_groups the collection of metric groups provided by the 189 * plugin. 190 */ 191 getMetrics() generates (Status status, vec<DrmMetricGroup> metric_groups); 192 193 /** 194 * Get the IDs of all secure stops on the device 195 * 196 * @return status the status of the call. The status must be OK or 197 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure stop 198 * IDs cannot be returned. 199 * @return secureStopIds a list of the IDs 200 */ 201 getSecureStopIds() generates 202 (Status status, vec<SecureStopId> secureStopIds); 203 204 /** 205 * Release secure stops given a release message from the key server 206 * 207 * @param ssRelease the secure stop release message identifying one or more 208 * secure stops to release. ssRelease is opaque, it is passed directly from 209 * a DRM license server through the app and media framework to the vendor 210 * HAL module. The format and content of ssRelease must be defined by the 211 * DRM scheme being implemented according to this HAL. The DRM scheme 212 * can be identified by its UUID which can be queried using 213 * IDrmFactory::isCryptoSchemeSupported. 214 * 215 * @return status the status of the call. The status must be OK or one of 216 * the following errors: BAD_VALUE if ssRelease is invalid or 217 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure stop 218 * cannot be released. 219 */ 220 releaseSecureStops(SecureStopRelease ssRelease) generates (Status status); 221 222 /** 223 * Remove a secure stop given its secure stop ID, without requiring 224 * a secure stop release response message from the key server. 225 * 226 * @param secureStopId the ID of the secure stop to release. 227 * 228 * @return status the status of the call. The status must be OK or one of 229 * the following errors: BAD_VALUE if the secureStopId is invalid or 230 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure stop 231 * cannot be released. 232 */ 233 removeSecureStop(SecureStopId secureStopId) generates (Status status); 234 235 /** 236 * Remove all secure stops on the device without requiring a secure 237 * stop release response message from the key server. 238 * 239 * @return status the status of the call. The status must be OK or 240 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure 241 * stops cannot be removed. 242 */ 243 removeAllSecureStops() generates (Status status); 244 }; 245
