Add additional error conditions to MediaDrm
New codes are being added to handle resource
contention, lost session state, frame size too
large and insufficient security level for
decryption. Also cleans up inconsistent use of
tamper detected error where invalid state error
should have been used.
bug:111504510
bug:111505796
test: cts and gts media test cases
Change-Id: I8581aed1871d728f7af80b246d0dba28b40fa4a3
diff --git a/drm/1.2/IDrmPlugin.hal b/drm/1.2/IDrmPlugin.hal
index 88338d6..88ace0b 100644
--- a/drm/1.2/IDrmPlugin.hal
+++ b/drm/1.2/IDrmPlugin.hal
@@ -15,13 +15,19 @@
*/
package android.hardware.drm@1.2;
-import @1.1::IDrmPlugin;
+import @1.0::KeyedVector;
+import @1.0::KeyType;
+import @1.0::SessionId;
import @1.0::Status;
+import @1.1::IDrmPlugin;
+import @1.1::KeyRequestType;
+import @1.2::IDrmPluginListener;
/**
- * IDrmPlugin is used to interact with a specific drm plugin that was created by
- * IDrm::createPlugin. A drm plugin provides methods for obtaining drm keys that
- * may be used by a codec to decrypt protected video content.
+ * IDrmPlugin is used to interact with a specific drm plugin that was
+ * created by IDrm::createPlugin. A drm plugin provides methods for
+ * obtaining drm keys to be used by a codec to decrypt protected video
+ * content.
*/
interface IDrmPlugin extends @1.1::IDrmPlugin {
@@ -32,24 +38,25 @@
* request/response exchange when the key request KeyType is
* OFFLINE. Normally each app is responsible for keeping track of
* the KeySetIds it has created. In some situations however, it
- * may be necessary to request the list of stored offline license
+ * will be necessary to request the list of stored offline license
* KeySetIds. If an app loses the KeySetId for any stored licenses
* that it created, for example, it must be able to recover the
- * stored KeySetIds so those licenses can be removed when they
+ * stored KeySetIds so those licenses will be removed when they
* expire or when the app is uninstalled.
* <p>
* This method returns a list of the KeySetIds for all offline
- * licenses. The offline license KeySetId may be used to query
+ * licenses. The offline license KeySetId allows an app to query
* the status of an offline license or remove it.
*
- * @return status the status of the call. May be OK or
+ * @return status the status of the call. Must be OK or
* ERROR_DRM_INVALID_STATE if the HAL is in a state where the
* KeySetIds can't be returned.
* @return a list of offline license keySetIds. If there are no offline
* licenses, the list must be empty and OK must be returned as the
* status.
*/
- getOfflineLicenseKeySetIds() generates (Status status, vec<KeySetId> keySetIds);
+ getOfflineLicenseKeySetIds() generates (@1.0::Status status,
+ vec<KeySetId> keySetIds);
/**
* Normally offline licenses are released using a key
@@ -59,20 +66,20 @@
* removed and then adjust the count of offline licenses allocated
* to the device.
* <p>
- * In some exceptional situations it may be necessary to directly
- * remove offline licenses without notifying the server, which may
- * be performed using this method.
+ * In some exceptional situations it will be necessary to directly
+ * remove offline licenses without notifying the server, which is
+ * performed by this method.
*
* @param keySetId the id of the offline license to remove
- * @return status the status of the call. May be one of OK on
+ * @return status the status of the call. Must be one of OK on
* success, BAD_VALUE if the license is not found or
* ERROR_DRM_INVALID_STATE if the HAL is in a state where the
* KeySetIds can't be returned.
*/
- removeOfflineLicense(KeySetId keySetId) generates (Status status);
+ removeOfflineLicense(KeySetId keySetId) generates (@1.0::Status status);
/**
- * Request the state of an offline license. An offline license may
+ * Request the state of an offline license. An offline license must
* be usable or inactive. The keys in a usable offline license are
* available for decryption. When the offline license state is
* inactive, the keys have been marked for release using
@@ -81,7 +88,7 @@
* usable for decryption.
*
* @param keySetId the id of the offline license
- * @return status the status of the call. May be one of OK on
+ * @return status the status of the call. Must be one of OK on
* success, BAD_VALUE if the license is not found or
* ERROR_DRM_INVALID_STATE if the HAL is in a state where the
* offline license state can't be queried.
@@ -89,6 +96,100 @@
* If the return status is not OK then state must be set to
* UNKNOWN.
*/
- getOfflineLicenseState(KeySetId keySetId) generates (Status status,
- OfflineLicenseState state);
+ getOfflineLicenseState(KeySetId keySetId) generates (
+ @1.0::Status status, OfflineLicenseState state);
+
+ /**
+ * A key request/response exchange occurs between the app and a License
+ * Server to obtain the keys required to decrypt the content.
+ * getKeyRequest_1_2() is used to obtain an opaque key request blob that is
+ * delivered to the license server.
+ *
+ * getKeyRequest_1_2() only differs from getKeyRequest_1_1() in that
+ * additional status codes must be returned.
+ *
+ * @param scope either a sessionId or a keySetId, depending on the
+ * specified keyType. When the keyType is OFFLINE or STREAMING, scope
+ * must be set to the sessionId the keys will be provided to. When the
+ * keyType is RELEASE, scope must be set to the keySetId of the keys
+ * being released.
+ * @param initData container-specific data, its meaning is interpreted
+ * based on the mime type provided in the mimeType parameter. It could
+ * contain, for example, the content ID, key ID or other data obtained
+ * from the content metadata that is required to generate the key
+ * request. initData must be empty when keyType is RELEASE.
+ * @param mimeType identifies the mime type of the content
+ * @param keyType specifies if the keys are to be used for streaming,
+ * offline or a release
+ * @param optionalParameters included in the key request message to
+ * allow a client application to provide additional message parameters
+ * to the server.
+ * @return status the status of the call. The status must be OK or one of
+ * the following errors: ERROR_DRM_SESSION_NOT_OPENED if the session is
+ * not opened, ERROR_DRM_NOT_PROVISIONED if the device requires
+ * provisioning before it is able to generate a key request,
+ * ERROR_DRM_RESOURCE_CONTENTION if client applications using the hal
+ * are temporarily exceeding the available crypto resources such that a
+ * retry of the operation is likely to succeed, ERROR_DRM_CANNOT_HANDLE
+ * if getKeyRequest is not supported at the time of the call, BAD_VALUE
+ * if any parameters are invalid or ERROR_DRM_INVALID_STATE if the HAL
+ * is in a state where a key request cannot be generated.
+ * @return request if successful, the opaque key request blob is returned
+ * @return requestType indicates type information about the returned
+ * request. The type must be one of INITIAL, RENEWAL, RELEASE, NONE or
+ * UPDATE. An INITIAL request is the first key request for a
+ * license. RENEWAL is a subsequent key request used to refresh the
+ * keys in a license. RELEASE corresponds to a keyType of RELEASE,
+ * which indicates keys are being released. NONE indicates that no
+ * request is needed because the keys are already loaded. UPDATE
+ * indicates that the keys need to be refetched after the initial
+ * license request.
+ * @return defaultUrl the URL that the request may be sent to, if
+ * provided by the drm HAL. The app can choose to override this URL.
+ */
+ getKeyRequest_1_2(vec<uint8_t> scope, vec<uint8_t> initData,
+ string mimeType, KeyType keyType, KeyedVector optionalParameters)
+ generates (Status status, vec<uint8_t> request,
+ KeyRequestType requestType, string defaultUrl);
+
+ /**
+ * A provision request/response exchange occurs between the app and a
+ * provisioning server to retrieve a device certificate. getProvisionRequest
+ * is used to obtain an opaque provisioning request blob that is delivered
+ * to the provisioning server.
+ *
+ * getProvisionRequest_1_2() only differs from getProvisionRequest_1_0() in
+ * that additional status codes must be returned.
+ *
+ * @param certificateType the type of certificate requested, e.g. "X.509"
+ * @param certificateAuthority identifies the certificate authority. A
+ * certificate authority (CA) is an entity which issues digital
+ * certificates for use by other parties. It is an example of a trusted
+ * third party.
+ * @return status the status of the call. The status must be OK or one of
+ * the following errors: ERROR_DRM_RESOURCE_CONTENTION if client
+ * applications using the hal are temporarily exceeding the available
+ * crypto resources such that a retry of the operation is likely to
+ * succeed, ERROR_DRM_CANNOT_HANDLE if the drm scheme does not require
+ * provisioning or ERROR_DRM_INVALID_STATE if the HAL is in a state
+ * where the provision request cannot be generated.
+ * @return request if successful the opaque certificate request blob
+ * is returned
+ * @return defaultUrl URL that the provisioning request may be
+ * sent to, if known by the HAL implementation. An app can choose to
+ * override this URL. If the HAL implementation does not provide a
+ * defaultUrl, the returned string must be empty.
+ */
+ getProvisionRequest_1_2(string certificateType, string certificateAuthority)
+ generates (Status status, vec<uint8_t> request, string defaultUrl);
+
+ /**
+ * Send a session lost state event to the listener. This event
+ * indicates that a session's state has become invalid because the
+ * device crypto hardware is incapable of retaining crypto session
+ * state across suspend and resume cycles.
+ *
+ * @param sessionId identifies the session the event originated from
+ */
+ sendSessionLostState(SessionId sessionId);
};