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