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 */
16package android.hardware.drm@1.0;
17
18import 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 */
27interface 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,
103     * ERROR_DRM_DECRYPT if the decrypt operation fails, and
104     * ERROR_DRM_CANNOT_HANDLE in other failure cases.
105     * @return bytesWritten the number of bytes output from the decryption
106     * @return detailedError if the error is a vendor-specific error, the
107     * vendor's crypto HAL may provide a detailed error string to help
108     * describe the error.
109     */
110    decrypt(bool secure, uint8_t[16] keyId, uint8_t[16] iv, Mode mode,
111        Pattern pattern, vec<SubSample> subSamples,
112            SharedBuffer source, uint64_t offset, DestinationBuffer destination)
113        generates(Status status, uint32_t bytesWritten, string detailedError);
114};
115