Follow up on "Treble HAL interfaces for drm+crypto"
Responding to post-submit feedback on previous CL.
b/32815560
Change-Id: Iaf412dc5c39c0595a0486a1220caf4e1c844e824
Tests: Make completes successfully
diff --git a/drm/crypto/1.0/ICryptoFactory.hal b/drm/crypto/1.0/ICryptoFactory.hal
index 58f86df..c1ff31f 100644
--- a/drm/crypto/1.0/ICryptoFactory.hal
+++ b/drm/crypto/1.0/ICryptoFactory.hal
@@ -25,7 +25,7 @@
* which are used by a codec to decrypt protected video content.
*/
interface ICryptoFactory {
- /*
+ /**
* Determine if a crypto scheme is supported by this HAL
*
* @param uuid identifies the crypto scheme in question
@@ -33,20 +33,21 @@
*/
isCryptoSchemeSupported(uint8_t[16] uuid) generates(bool isSupported);
- /*
+ /**
* Create a crypto plugin for the specified uuid and scheme-specific
* initialization data.
*
* @param uuid uniquely identifies the drm scheme. See
* http://dashif.org/identifiers/protection for uuid assignments
* @param initData scheme-specific init data.
- * @return the status of the call
- * @return the created ICryptoPlugin
- */
+ * @return status the status of the call. If the plugin can't
+ * be created, the HAL implementation must return ERROR_DRM_CANNOT_HANDLE.
+ * @return cryptoPlugin the created ICryptoPlugin
+ */
createPlugin(uint8_t[16] uuid, vec<uint8_t> initData)
generates (Status status, ICryptoPlugin cryptoPlugin);
- /*
+ /**
* Destroy a previously created crypto plugin
*
* @return status the status of the call
diff --git a/drm/crypto/1.0/ICryptoPlugin.hal b/drm/crypto/1.0/ICryptoPlugin.hal
index 1255fdb..ee4c1dc 100644
--- a/drm/crypto/1.0/ICryptoPlugin.hal
+++ b/drm/crypto/1.0/ICryptoPlugin.hal
@@ -25,7 +25,7 @@
* load crypto keys for a codec to decrypt protected video content.
*/
interface ICryptoPlugin {
- /*
+ /**
* Check if the specified mime-type requires a secure decoder
* component.
*
@@ -36,7 +36,7 @@
requiresSecureDecoderComponent(string mime)
generates(bool secureRequired);
- /*
+ /**
* Notify a plugin of the currently configured resolution
*
* @param width - the display resolutions's width
@@ -44,16 +44,19 @@
*/
notifyResolution(uint32_t width, uint32_t height);
- /*
+ /**
* Associate a mediadrm session with this crypto session
*
* @param sessionId the MediaDrm session ID to associate with this crypto
* session
- * @return the status of the call
+ * @return the status of the call, status must be
+ * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened, or
+ * ERROR_DRM_CANNOT_HANDLE if the operation is not supported by the drm
+ * scheme.
*/
setMediaDrmSession(vec<uint8_t> sessionId) generates(Status status);
- /*
+ /**
* Decrypt an array of subsamples from the source memory buffer to the
* destination memory buffer.
*
@@ -71,7 +74,14 @@
* call to operate on a range of subsamples in a single call
* @param source the input buffer for the decryption
* @param destination the output buffer for the decryption
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * the following: ERROR_DRM_NO_LICENSE if no license keys have been
+ * loaded, ERROR_DRM_LICENSE_EXPIRED if the license keys have expired,
+ * ERROR_DRM_RESOURCE_BUSY if the resources required to perform the
+ * decryption are not available, ERROR_DRM_INSUFFICIENT_OUTPUT_PROTECTION
+ * if required output protections are not active,
+ * ERROR_DRM_SESSION_NOT_OPENED if the decrypt session is not opened, or
+ * ERROR_DRM_CANNOT_HANDLE in other failure cases.
* @return bytesWritten the number of bytes output from the decryption
* @return detailedError if the error is a vendor-specific error, the
* vendor's crypto HAL may provide a detailed error string to help
diff --git a/drm/drm/1.0/IDrmFactory.hal b/drm/drm/1.0/IDrmFactory.hal
index a4ee0f1..80cb941 100644
--- a/drm/drm/1.0/IDrmFactory.hal
+++ b/drm/drm/1.0/IDrmFactory.hal
@@ -27,7 +27,7 @@
*/
interface IDrmFactory {
- /*
+ /**
* Determine if a crypto scheme is supported by this HAL
*
* @param uuid identifies the crypto scheme in question
@@ -35,20 +35,21 @@
*/
isCryptoSchemeSupported(uint8_t[16] uuid) generates(bool isSupported);
- /*
+ /**
* Create a drm plugin instance for the specified uuid and scheme-specific
* initialization data.
*
* @param uuid uniquely identifies the drm scheme. See
* http://dashif.org/identifiers/protection for uuid assignments
* @param initData scheme-specific init data.
- * @return the status of the call
+ * @return status the status of the call. If the plugin can't
+ * be created, the HAL implementation must return ERROR_DRM_CANNOT_HANDLE.
* @return the created IDrmPlugin
*/
createPlugin(uint8_t[16] uuid, vec<uint8_t> initData)
generates (Status status, IDrmPlugin drmPlugin);
- /*
+ /**
* Destroy a previously created drm plugin
* @return status the status of the call
*/
diff --git a/drm/drm/1.0/IDrmPlugin.hal b/drm/drm/1.0/IDrmPlugin.hal
index 7f396d9..cc15cfd 100644
--- a/drm/drm/1.0/IDrmPlugin.hal
+++ b/drm/drm/1.0/IDrmPlugin.hal
@@ -30,7 +30,13 @@
/**
* Open a new session with the DrmPlugin object. A session ID is returned
* in the sessionId parameter.
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * ERROR_DRM_NOT_PROVISIONED if the device requires provisioning before
+ * it can open a session, ERROR_DRM_RESOURCE_BUSY if there are insufficent
+ * resources available to open a session, ERROR_DRM_CANNOT_HANDLE,
+ * if openSession is not supported at the time of the call or
+ * ERROR_DRM_INVALID_STATE if the HAL is in a state where a session cannot
+ * be opened.
*/
openSession() generates (SessionId sessionId, Status status);
@@ -38,7 +44,10 @@
* Close a session on the DrmPlugin object
*
* @param sessionId the session id the call applies to
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+ * BAD_VALUE if the sessionId is invalid or ERROR_DRM_INVALID_STATE
+ * if the HAL is in a state where the session cannot be closed.
*/
closeSession(SessionId sessionId) generates (Status status);
@@ -72,7 +81,13 @@
* subsequent key request used to refresh the keys in a license. RELEASE
* corresponds to a keyType of RELEASE, which indicates keys are being
* released.
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+ * ERROR_DRM_NOT_PROVISIONED if the device requires provisioning before
+ * it can generate a key request, ERROR_DRM_CANNOT_HANDLE if keyKeyRequest
+ * 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 defaultUrl the URL that the request may be sent to, if
* provided by the drm HAL. The app may choose to override this
* URL.
@@ -98,8 +113,14 @@
* to later restore the keys to a new session with the method restoreKeys.
* When the response is for a streaming or release request, no keySetId is
* returned.
- *
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+ * ERROR_DRM_NOT_PROVISIONED if the device requires provisioning before
+ * it can handle the key response, ERROR_DRM_DEVICE_REVOKED if the device
+ * has been disabled by the license policy, ERROR_DRM_CANNOT_HANDLE if
+ * provideKeyResponse 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 response cannot be handled.
*/
provideKeyResponse(vec<uint8_t> scope,
vec<uint8_t> response) generates (vec<uint8_t> keySetId, Status status);
@@ -108,7 +129,10 @@
* Remove the current keys from a session
*
* @param sessionId the session id the call applies to
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+ * BAD_VALUE if the sessionId is invalid or ERROR_DRM_INVALID_STATE
+ * if the HAL is in a state where the keys cannot be removed.
*/
removeKeys(SessionId sessionId) generates (Status status);
@@ -118,12 +142,15 @@
* @param sessionId the session id the call applies to
* @param keySetId identifies the keys to load, obtained from a prior
* call to provideKeyResponse().
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+ * BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
+ * if the HAL is in a state where keys cannot be restored.
*/
restoreKeys(SessionId sessionId,
vec<uint8_t> keySetId) generates (Status status);
- /*
+ /**
* Request an informative description of the license for the session. The
* status is in the form of {name, value} pairs. Since DRM license policies
* vary by vendor, the specific status field names are determined by each
@@ -132,7 +159,10 @@
*
* @param sessionId the session id the call applies to
* @return infoList a list of name value pairs describing the license
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+ * BAD_VALUE if the sessionId is invalid or ERROR_DRM_INVALID_STATE
+ * if the HAL is in a state where key status cannot be queried.
*/
queryKeyStatus(SessionId sessionId)
generates (KeyedVector infoList, Status status);
@@ -148,7 +178,10 @@
* 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 if successful the opaque certirequest blob is returned
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * BAD_VALUE if the sessionId is invalid or ERROR_DRM_INVALID_STATE
+ * if the HAL is in a state where the provision request cannot be
+ * generated.
*/
getProvisionRequest(string certificateType, string certificateAuthority)
generates (vec<uint8_t> request, string defaultUrl, Status status);
@@ -165,7 +198,11 @@
* @return wrappedKey an opaque object containing encrypted private key
* material to be used by signRSA when computing an RSA signature on a
* message, see the signRSA method.
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * ERROR_DRM_DEVICE_REVOKED if the device has been disabled by the license
+ * policy, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
+ * if the HAL is in a state where the provision response cannot be
+ * handled.
*/
provideProvisionResponse(vec<uint8_t> response)
generates (vec<uint8_t> certificate, vec<uint8_t> wrappedKey,
@@ -194,40 +231,48 @@
* Get all secure stops on the device
*
* @return secureStops a list of the secure stop opaque objects
- * @return status the status of the call
+ * @return status the status of the call. The status must be
+ * ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure stops
+ * cannot be returned.
*/
getSecureStops() generates
(vec<SecureStop> secureStops, Status status);
/**
- * Get all secure stops by secure stop ID
- *
- * @param secureStopId the ID of the secure stop to return. The
- * secure stop ID is delivered by the key server as part of the key
- * response and must also be known by the app.
- *
- * @return the secure stop opaque object
- * @return status the status of the call
- */
+ * Get all secure stops by secure stop ID
+ *
+ * @param secureStopId the ID of the secure stop to return. The
+ * secure stop ID is delivered by the key server as part of the key
+ * response and must also be known by the app.
+ *
+ * @return secureStop the secure stop opaque object
+ * @return status the status of the call. The status must be one of
+ * BAD_VALUE if the secureStopId is invalid or ERROR_DRM_INVALID_STATE
+ * if the HAL is in a state where the secure stop cannot be returned.
+ */
getSecureStop(SecureStopId secureStopId)
generates (SecureStop secureStop, Status status);
/**
* Release all secure stops on the device
*
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure
+ * stops cannot be released.
*/
releaseAllSecureStops() generates (Status status);
/**
- * Release a secure stop by secure stop ID
- *
- * @param secureStopId the ID of the secure stop to release. The
- * secure stop ID is delivered by the key server as part of the key
- * response and must also be known by the app.
- *
- * @return status the status of the call
- */
+ * Release a secure stop by secure stop ID
+ *
+ * @param secureStopId the ID of the secure stop to release. The
+ * secure stop ID is delivered by the key server as part of the key
+ * response and must also be known by the app.
+ *
+ * @return status the status of the call. The status must be one of
+ * BAD_VALUE if the secureStopId is invalid or ERROR_DRM_INVALID_STATE
+ * if the HAL is in a state where the secure stop cannot be released.
+ */
releaseSecureStop(vec<uint8_t> secureStopId) generates (Status status);
/**
@@ -252,8 +297,11 @@
* Read a string property value given the property name.
*
* @param propertyName the name of the property
- * @return the property value string
- * @return status the status of the call
+ * @return value the property value string
+ * @return status the status of the call. The status must be one of
+ * BAD_VALUE if the property name is invalid, ERROR_DRM_CANNOT_HANDLE
+ * if the property is not supported, or ERROR_DRM_INVALID_STATE if the
+ * HAL is in a state where the property cannot be obtained.
*/
getPropertyString(string propertyName)
generates (string value, Status status);
@@ -262,8 +310,11 @@
* Read a byte array property value given the property name.
*
* @param propertyName the name of the property
- * @return the property value byte array
- * @return status the status of the call
+ * @return value the property value byte array
+ * @return status the status of the call. The status must be one of
+ * BAD_VALUE if the property name is invalid, ERROR_DRM_CANNOT_HANDLE
+ * if the property is not supported, or ERROR_DRM_INVALID_STATE if the
+ * HAL is in a state where the property cannot be obtained.
*/
getPropertyByteArray(string propertyName)
generates (vec<uint8_t> value, Status status);
@@ -273,7 +324,10 @@
*
* @param propertyName the name of the property
* @param value the value to write
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * BAD_VALUE if the property name is invalid, ERROR_DRM_CANNOT_HANDLE
+ * if the property is not supported, or ERROR_DRM_INVALID_STATE if the
+ * HAL is in a state where the property cannot be set.
*/
setPropertyString(string propertyName, string value )
generates (Status status);
@@ -283,7 +337,10 @@
*
* @param propertyName the name of the property
* @param value the value to write
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * BAD_VALUE if the property name is invalid, ERROR_DRM_CANNOT_HANDLE
+ * if the property is not supported, or ERROR_DRM_INVALID_STATE if the
+ * HAL is in a state where the property cannot be set.
*/
setPropertyByteArray(string propertyName, vec<uint8_t> value )
generates (Status status);
@@ -301,7 +358,10 @@
* @param algorithm the algorithm to use. The string conforms to JCA
* Standard Names for Cipher Transforms and is case insensitive. An
* example algorithm is "AES/CBC/PKCS5Padding".
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+ * BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
+ * if the HAL is in a state where the algorithm cannot be set.
*/
setCipherAlgorithm(SessionId sessionId, string algorithm)
generates (Status status);
@@ -313,7 +373,10 @@
* @param algorithm the algorithm to use. The string conforms to JCA
* Standard Names for Mac Algorithms and is case insensitive. An example MAC
* algorithm string is "HmacSHA256".
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+ * BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
+ * if the HAL is in a state where the algorithm cannot be set.
*/
setMacAlgorithm(SessionId sessionId, string algorithm)
generates (Status status);
@@ -328,7 +391,11 @@
* @param input the input data to encrypt
* @param iv the initialization vector to use for encryption
* @return output the decrypted data
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+ * BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
+ * if the HAL is in a state where the encrypt operation cannot be
+ * performed.
*/
encrypt(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> input,
vec<uint8_t> iv)
@@ -344,7 +411,11 @@
* @param input the input data to decrypt
* @param iv the initialization vector to use for decryption
* @return output the decrypted data
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+ * BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
+ * if the HAL is in a state where the decrypt operation cannot be
+ * performed.
*/
decrypt(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> input,
vec<uint8_t> iv) generates (vec<uint8_t> output, Status status);
@@ -357,8 +428,12 @@
* @param sessionId the session id the call applies to
* @param keyId the ID of the key to use for decryption
* @param message the message to compute a signature over
- * @return the computed signature
- * @return status the status of the call
+ * @return signature the computed signature
+ * @return status the status of the call. The status must be one of
+ * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+ * BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
+ * if the HAL is in a state where the sign operation cannot be
+ * performed.
*/
sign(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> message)
generates (vec<uint8_t> signature, Status status);
@@ -371,7 +446,11 @@
* @param sessionId the session id the call applies to
* @param keyId the ID of the key to use for decryption
* @param message the message to compute a hash of
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+ * BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
+ * if the HAL is in a state where the verify operation cannot be
+ * performed.
*/
verify(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> message,
vec<uint8_t> signature) generates (bool match, Status status);
@@ -383,10 +462,14 @@
* @param algorithm the signing algorithm, such as "RSASSA-PSS-SHA1"
* or "PKCS1-BlockType1"
* @param sessionId the session id the call applies to
- * @param wrappedKey the private key returned during provisioning
- * as returned by provideProvisionResponse.
+ * @param wrappedKey the private key returned during provisioning as
+ * returned by provideProvisionResponse.
* @return signature the RSA signature computed over the message
- * @return status the status of the call
+ * @return status the status of the call. The status must be one of
+ * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+ * BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
+ * if the HAL is in a state where the signRSA operation cannot be
+ * performed.
*/
signRSA(SessionId sessionId, string algorithm, vec<uint8_t> message,
vec<uint8_t> wrappedkey)