drm/1.0/ICryptoPlugin.hal

   1 /*
   2  * Copyright (C) 2016 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.0;
  17
  18 import android.hardware.drm@1.0::types;
  19
  20 /**
  21  * Ref: frameworks/native/include/media/hardware/CryptoAPI.h:CryptoPlugin
  22  *
  23  * ICryptoPlugin is the HAL for vendor-provided crypto plugins.
  24  * It allows crypto sessions to be opened and operated on, to
  25  * load crypto keys for a codec to decrypt protected video content.
  26  */
  27 interface ICryptoPlugin {
  28     /**
  29      * Check if the specified mime-type requires a secure decoder
  30      * component.
  31      *
  32      * @param mime The content mime-type
  33      * @return secureRequired must be true only if a secure decoder is required
  34      * for the specified mime-type
  35      */
  36     requiresSecureDecoderComponent(string mime)
  37         generates(bool secureRequired);
  38
  39     /**
  40      * Notify a plugin of the currently configured resolution
  41      *
  42      * @param width - the display resolutions's width
  43      * @param height - the display resolution's height
  44      */
  45     notifyResolution(uint32_t width, uint32_t height);
  46
  47     /**
  48      * Associate a mediadrm session with this crypto session
  49      *
  50      * @param sessionId the MediaDrm session ID to associate with this crypto
  51      * session
  52      * @return status the status of the call, status must be
  53      * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened, or
  54      * ERROR_DRM_CANNOT_HANDLE if the operation is not supported by the drm
  55      * scheme.
  56      */
  57     setMediaDrmSession(vec<uint8_t> sessionId) generates(Status status);
  58
  59     /**
  60      * Set a shared memory base for subsequent decrypt operations. The buffer
  61      * base is a hidl_memory which maps shared memory in the HAL module.
  62      * After the shared buffer base is established, the decrypt() method
  63      * receives SharedBuffer instances which specify the buffer address range
  64      * for decrypt source and destination addresses.
  65      *
  66      * There can be multiple shared buffers per crypto plugin. The buffers
  67      * are distinguished by the bufferId.
  68      *
  69      * @param base the base IMemory of the memory buffer identified by
  70      * bufferId
  71      * @param bufferId identifies the specific shared buffer for which
  72      * the base is being set.
  73      */
  74     setSharedBufferBase(memory base, uint32_t bufferId);
  75
  76     /**
  77      * Decrypt an array of subsamples from the source memory buffer to the
  78      * destination memory buffer.
  79      *
  80      * @param secure a flag to indicate if a secure decoder is being used. This
  81      * enables the plugin to configure buffer modes to work consistently with
  82      * a secure decoder.
  83      * @param the keyId for the key that should be used to do the
  84      * the decryption. The keyId refers to a key in the associated
  85      * MediaDrm instance.
  86      * @param iv the initialization vector to use
  87      * @param mode the crypto mode to use
  88      * @param pattern the crypto pattern to use
  89      * @param subSamples a vector of subsamples indicating the number
  90      * of clear and encrypted bytes to process. This allows the decrypt
  91      * call to operate on a range of subsamples in a single call
  92      * @param source the input buffer for the decryption
  93      * @param offset the offset of the first byte of encrypted data from
  94      * the base of the source buffer
  95      * @param destination the output buffer for the decryption
  96      * @return status the status of the call. The status must be OK or one of
  97      * the following errors: ERROR_DRM_NO_LICENSE if no license keys have been
  98      * loaded, ERROR_DRM_LICENSE_EXPIRED if the license keys have expired,
  99      * ERROR_DRM_RESOURCE_BUSY if the resources required to perform the
 100      * decryption are not available, ERROR_DRM_INSUFFICIENT_OUTPUT_PROTECTION
 101      * if required output protections are not active,
 102      * ERROR_DRM_SESSION_NOT_OPENED if the decrypt session is not opened, or
 103      * ERROR_DRM_CANNOT_HANDLE in other failure cases.
 104      * @return bytesWritten the number of bytes output from the decryption
 105      * @return detailedError if the error is a vendor-specific error, the
 106      * vendor's crypto HAL may provide a detailed error string to help
 107      * describe the error.
 108      */
 109     decrypt(bool secure, uint8_t[16] keyId, uint8_t[16] iv, Mode mode,
 110         Pattern pattern, vec<SubSample> subSamples,
 111             SharedBuffer source, uint64_t offset, DestinationBuffer destination)
 112         generates(Status status, uint32_t bytesWritten, string detailedError);
 113 };