1/**
2 * Copyright (C) 2017 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.1;
17
18import @1.0::IDrmPlugin;
19import @1.0::IDrmPluginListener;
20import @1.0::KeyedVector;
21import @1.0::KeyType;
22import @1.0::Status;
23import @1.1::DrmMetricGroup;
24import @1.1::HdcpLevel;
25import @1.1::KeyRequestType;
26import @1.0::SecureStopId;
27import @1.1::SecureStopRelease;
28import @1.1::SecurityLevel;
29import @1.0::SessionId;
30
31/**
32 * IDrmPlugin is used to interact with a specific drm plugin that was created by
33 * IDrm::createPlugin. A drm plugin provides methods for obtaining drm keys that
34 * may be used by a codec to decrypt protected video content.
35 */
36interface IDrmPlugin extends @1.0::IDrmPlugin {
37    /**
38     * Open a new session at a requested security level. The security level
39     * represents the robustness of the device's DRM implementation. By default,
40     * sessions are opened at the native security level of the device which is
41     * the maximum level that can be supported. Overriding the security level is
42     * necessary when the decrypted frames need to be manipulated, such as for
43     * image compositing. The security level parameter must be equal to or lower
44     * than the native level. If the requested level is not supported, the next
45     * lower supported security level must be set. The level can be queried
46     * using {@link #getSecurityLevel}. A session ID is returned.  When the
47     * drm@1.0 openSession is called, which has no securityLevel parameter, the
48     * security level is defaulted to the native security level of the device.
49     *
50     * @return status the status of the call. The status must be OK or one of
51     *     the following errors: ERROR_DRM_NOT_PROVISIONED if the device
52     *     requires provisioning before it can open a session,
53     *     ERROR_DRM_RESOURCE_BUSY if there are insufficent resources available
54     *     to open a session, ERROR_DRM_CANNOT_HANDLE if the requested security
55     *     level is higher than the native level or lower than the lowest
56     *     supported level or if openSession is not supported at the time of
57     *     the call, or ERROR_DRM_INVALID_STATE if the HAL is in a state where
58     *     a session cannot be opened.
59     * @param level the requested security level
60     * @return sessionId the session ID for the newly opened session
61     */
62    openSession_1_1(SecurityLevel securityLevel) generates (Status status,
63            SessionId sessionId);
64
65    /**
66     * A key request/response exchange occurs between the app and a License
67     * Server to obtain the keys required to decrypt the content.
68     * getKeyRequest_1_1() is used to obtain an opaque key request blob that is
69     * delivered to the license server.
70     *
71     * getKeyRequest_1_1() only differs from getKeyRequest() in that additional
72     * values are returned in 1.1::KeyRequestType as compared to
73     * 1.0::KeyRequestType
74     *
75     * @param scope may be a sessionId or a keySetId, depending on the
76     *        specified keyType. When the keyType is OFFLINE or STREAMING,
77     *        scope should be set to the sessionId the keys will be provided
78     *        to. When the keyType is RELEASE, scope should be set to the
79     *        keySetId of the keys being released.
80     * @param initData container-specific data, its meaning is interpreted
81     *        based on the mime type provided in the mimeType parameter.
82     *        It could contain, for example, the content ID, key ID or
83     *        other data obtained from the content metadata that is
84     *        required to generate the key request. initData may be empty
85     *        when keyType is RELEASE.
86     * @param mimeType identifies the mime type of the content
87     * @param keyType specifies if the keys are to be used for streaming,
88     *        offline or a release
89     * @param optionalParameters included in the key request message to
90     *        allow a client application to provide additional message
91     *        parameters to the server.
92     * @return status the status of the call. The status must be OK or one of
93     *         the following errors: ERROR_DRM_SESSION_NOT_OPENED if the
94     *         session is not opened, ERROR_DRM_NOT_PROVISIONED if the device
95     *         requires provisioning before it can generate a key request,
96     *         ERROR_DRM_CANNOT_HANDLE if getKeyRequest is not supported
97     *         at the time of the call, BAD_VALUE if any parameters are
98     *         invalid or ERROR_DRM_INVALID_STATE if the HAL is in a
99     *         state where a key request cannot be generated.
100     * @return request if successful, the opaque key request blob is returned
101     * @return requestType indicates type information about the returned
102     *         request. The type may be one of INITIAL, RENEWAL, RELEASE,
103     *         NONE or UPDATE. An INITIAL request is the first key request
104     *         for a license. RENEWAL is a subsequent key request used to
105     *         refresh the keys in a license. RELEASE corresponds to a
106     *         keyType of RELEASE, which indicates keys are being released.
107     *         NONE indicates that no request is needed because the keys are
108     *         already loaded. UPDATE indicates that the keys need to be
109     *         refetched after the initial license request.
110     * @return defaultUrl the URL that the request may be sent to, if
111     *         provided by the drm HAL. The app may choose to override this URL.
112     */
113    getKeyRequest_1_1(vec<uint8_t> scope, vec<uint8_t> initData,
114            string mimeType, KeyType keyType, KeyedVector optionalParameters)
115        generates (Status status, vec<uint8_t> request,
116                KeyRequestType requestType, string defaultUrl);
117
118    /**
119     * Return the currently negotiated and max supported HDCP levels.
120     *
121     * The current level is based on the display(s) the device is connected to.
122     * If multiple HDCP-capable displays are simultaneously connected to
123     * separate interfaces, this method returns the lowest negotiated HDCP level
124     * of all interfaces.
125     *
126     * The maximum HDCP level is the highest level that can potentially be
127     * negotiated. It is a constant for any device, i.e. it does not depend on
128     * downstream receiving devices that could be connected. For example, if
129     * the device has HDCP 1.x keys and is capable of negotiating HDCP 1.x, but
130     * does not have HDCP 2.x keys, then the maximum HDCP capability would be
131     * reported as 1.x. If multiple HDCP-capable interfaces are present, it
132     * indicates the highest of the maximum HDCP levels of all interfaces.
133     *
134     * This method should only be used for informational purposes, not for
135     * enforcing compliance with HDCP requirements. Trusted enforcement of HDCP
136     * policies must be handled by the DRM system.
137     *
138     * @return status the status of the call. The status must be OK or
139     *         ERROR_DRM_INVALID_STATE if the HAL is in a state where the HDCP
140     *         level cannot be queried.
141     * @return connectedLevel the lowest HDCP level for any connected
142     *         displays
143     * @return maxLevel the highest HDCP level that can be supported
144     *         by the device
145     */
146    getHdcpLevels() generates (Status status, HdcpLevel connectedLevel,
147            HdcpLevel maxLevel);
148
149    /**
150     * Return the current number of open sessions and the maximum number of
151     * sessions that may be opened simultaneosly among all DRM instances for the
152     * active DRM scheme.
153     *
154     * @return status the status of the call. The status must be OK or
155     *         ERROR_DRM_INVALID_STATE if the HAL is in a state where number of
156     *         sessions cannot be queried.
157     * @return currentSessions the number of currently opened sessions
158     * @return maxSessions the maximum number of sessions that the device
159     *         can support
160     */
161    getNumberOfSessions() generates (Status status, uint32_t currentSessions,
162             uint32_t maxSessions);
163
164    /**
165     * Return the current security level of a session. A session has an initial
166     * security level determined by the robustness of the DRM system's
167     * implementation on the device.
168     *
169     * @param sessionId the session id the call applies to
170     * @return status the status of the call. The status must be OK or one of
171     *         the following errors: ERROR_DRM_SESSION_NOT_OPENED if the
172     *         session is not opened, BAD_VALUE if the sessionId is invalid or
173     *         ERROR_DRM_INVALID_STATE if the HAL is in a state where the
174     *         security level cannot be queried.
175     * @return level the current security level for the session
176     */
177    getSecurityLevel(vec<uint8_t> sessionId) generates(Status status,
178            SecurityLevel level);
179
180    /**
181     * Returns the plugin-specific metrics. Multiple metric groups may be
182     * returned in one call to getMetrics(). The scope and definition of the
183     * metrics is defined by the plugin.
184     *
185     * @return status the status of the call. The status must be OK or
186     *         ERROR_DRM_INVALID_STATE if the metrics are not available to be
187     *         returned.
188     * @return metric_groups the collection of metric groups provided by the
189     *         plugin.
190     */
191    getMetrics() generates (Status status, vec<DrmMetricGroup> metric_groups);
192
193    /**
194     * Get the IDs of all secure stops on the device
195     *
196     * @return status the status of the call. The status must be OK or
197     * ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure stop
198     * IDs cannot be returned.
199     * @return secureStopIds a list of the IDs
200     */
201    getSecureStopIds() generates
202        (Status status, vec<SecureStopId> secureStopIds);
203
204    /**
205     * Release secure stops given a release message from the key server
206     *
207     * @param ssRelease the secure stop release message identifying one or more
208     * secure stops to release. ssRelease is opaque, it is passed directly from
209     * a DRM license server through the app and media framework to the vendor
210     * HAL module. The format and content of ssRelease must be defined by the
211     * DRM scheme being implemented according to this HAL. The DRM scheme
212     * can be identified by its UUID which can be queried using
213     * IDrmFactory::isCryptoSchemeSupported.
214     *
215     * @return status the status of the call. The status must be OK or one of
216     * the following errors: BAD_VALUE if ssRelease is invalid or
217     * ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure stop
218     * cannot be released.
219     */
220    releaseSecureStops(SecureStopRelease ssRelease) generates (Status status);
221
222    /**
223     * Remove a secure stop given its secure stop ID, without requiring
224     * a secure stop release response message from the key server.
225     *
226     * @param secureStopId the ID of the secure stop to release.
227     *
228     * @return status the status of the call. The status must be OK or one of
229     * the following errors: BAD_VALUE if the secureStopId is invalid or
230     * ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure stop
231     * cannot be released.
232     */
233    removeSecureStop(SecureStopId secureStopId) generates (Status status);
234
235    /**
236     * Remove all secure stops on the device without requiring a secure
237     * stop release response message from the key server.
238     *
239     * @return status the status of the call. The status must be OK or
240     * ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure
241     * stops cannot be removed.
242     */
243    removeAllSecureStops() generates (Status status);
244};
245