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 */
16package android.hardware.drm@1.2;
17
18import @1.0::DestinationBuffer;
19import @1.0::ICryptoPlugin;
20import @1.0::Mode;
21import @1.0::Pattern;
22import @1.0::SessionId;
23import @1.0::SharedBuffer;
24import @1.0::SubSample;
25
26/**
27 * ICryptoPlugin is the HAL for vendor-provided crypto plugins.
28 * It allows crypto sessions to be opened and operated on, to
29 * load crypto keys for a codec to decrypt protected video content.
30 */
31interface ICryptoPlugin extends @1.0::ICryptoPlugin {
32
33    /**
34     * Decrypt an array of subsamples from the source memory buffer to the
35     * destination memory buffer.
36     *
37     * decrypt_1_2() only differs from decrypt() in that additional status
38     * codes must be returned.
39     *
40     * @param secure a flag to indicate if a secure decoder is being used. This
41     *     enables the plugin to configure buffer modes to work consistently with
42     *     a secure decoder.
43     * @param the keyId for the key that is used to do the the decryption. The
44     *     keyId refers to a key in the associated MediaDrm instance.
45     * @param iv the initialization vector to use
46     * @param mode the crypto mode to use
47     * @param pattern the crypto pattern to use
48     * @param subSamples a vector of subsamples indicating the number
49     *     of clear and encrypted bytes to process. This allows the decrypt
50     *     call to operate on a range of subsamples in a single call
51     * @param source the input buffer for the decryption
52     * @param offset the offset of the first byte of encrypted data from
53     *     the base of the source buffer
54     * @param destination the output buffer for the decryption
55     * @return status the status of the call. The status must be OK or one
56     *     of the following errors:
57     *     ERROR_DRM_NO_LICENSE if no license keys have been loaded
58     *     ERROR_DRM_LICENSE_EXPIRED if the license keys have expired
59     *     ERROR_DRM_RESOURCE_BUSY if the resources required to perform
60     *         the decryption are not available
61     *     ERROR_DRM_INSUFFICIENT_OUTPUT_PROTECTION if required output
62     *         protections are not active
63     *     ERROR_DRM_INSUFFICIENT_SECURITY if the security level of the
64     *         device is not sufficient to meet the requirements in
65     *         the license policy
66     *     ERROR_DRM_FRAME_TOO_LARGE if the frame being decrypted into
67     *         the secure output buffer exceeds the size of the buffer
68     *     ERROR_DRM_SESSION_NOT_OPENED if the decrypt session is not
69     *         opened
70     *     ERROR_DRM_DECRYPT if the decrypt operation fails
71     *     ERROR_DRM_INVALID_STATE if the device is in a state where it
72     *         is not able to perform decryption
73     *     ERROR_DRM_CANNOT_HANDLE in other failure cases.
74     *
75     * @return bytesWritten the number of bytes output from the decryption
76     * @return detailedError if the error is a vendor-specific error, the
77     *     vendor's crypto HAL may provide a detailed error string to help
78     *     describe the error.
79     */
80    decrypt_1_2(bool secure, uint8_t[16] keyId, uint8_t[16] iv, Mode mode,
81        Pattern pattern, vec<SubSample> subSamples,
82            SharedBuffer source, uint64_t offset, DestinationBuffer destination)
83        generates(Status status, uint32_t bytesWritten, string detailedError);
84};
85