Line data Source code
1 : /*
2 : * If not stated otherwise in this file or this component's LICENSE file the
3 : * following copyright and licenses apply:
4 : *
5 : * Copyright 2022 Sky UK
6 : *
7 : * Licensed under the Apache License, Version 2.0 (the "License");
8 : * you may not use this file except in compliance with the License.
9 : * You may obtain a copy of the License at
10 : *
11 : * http://www.apache.org/licenses/LICENSE-2.0
12 : *
13 : * Unless required by applicable law or agreed to in writing, software
14 : * distributed under the License is distributed on an "AS IS" BASIS,
15 : * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 : * See the License for the specific language governing permissions and
17 : * limitations under the License.
18 : */
19 :
20 : #ifndef FIREBOLT_RIALTO_I_MEDIA_KEYS_H_
21 : #define FIREBOLT_RIALTO_I_MEDIA_KEYS_H_
22 :
23 : /**
24 : * @file IMediaKeys.h
25 : *
26 : * The definition of the IMediaKeys interface.
27 : *
28 : * This interface defines the public API of Rialto for EME decryption of AV content.
29 : */
30 :
31 : #include <memory>
32 : #include <string>
33 : #include <vector>
34 :
35 : #include "IMediaKeysClient.h"
36 : #include "MediaCommon.h"
37 :
38 : namespace firebolt::rialto
39 : {
40 : class IMediaKeys;
41 :
42 : /**
43 : * @brief IMediaKeys factory class, returns a concrete implementation of IMediaKeys
44 : */
45 : class IMediaKeysFactory
46 : {
47 : public:
48 100 : IMediaKeysFactory() = default;
49 100 : virtual ~IMediaKeysFactory() = default;
50 :
51 : /**
52 : * @brief Create a IMediaKeysFactory instance.
53 : *
54 : * @retval the factory instance or null on error.
55 : */
56 : static std::shared_ptr<IMediaKeysFactory> createFactory();
57 :
58 : /**
59 : * @brief IMediaKeys factory method, returns a concrete implementation of IMediaKeys
60 : *
61 : * @param[in] keySystem : The key system for which to create a Media Keys instance.
62 : *
63 : * @retval the new media keys instance or null on error.
64 : */
65 : virtual std::unique_ptr<IMediaKeys> createMediaKeys(const std::string &keySystem) const = 0;
66 : };
67 :
68 : /**
69 : * @brief The definition of the IMediaKeys interface.
70 : *
71 : * This interface defines the public API of Rialto for EME decryption of AV content
72 : * which should be implemented by both Rialto Client & Rialto Server.
73 : */
74 : class IMediaKeys
75 : {
76 : public:
77 310 : IMediaKeys() = default;
78 310 : virtual ~IMediaKeys() = default;
79 :
80 : IMediaKeys(const IMediaKeys &) = delete;
81 : IMediaKeys &operator=(const IMediaKeys &) = delete;
82 : IMediaKeys(IMediaKeys &&) = delete;
83 : IMediaKeys &operator=(IMediaKeys &&) = delete;
84 :
85 : /**
86 : * @brief Selects the specified keyId for the key session. Netflix specific API.
87 : *
88 : * @param[in] keySessionId : The key session id for the session.
89 : * @param[in] keyId : The key id to select.
90 : *
91 : * @retval an error status.
92 : */
93 : virtual MediaKeyErrorStatus selectKeyId(int32_t keySessionId, const std::vector<uint8_t> &keyId) = 0;
94 :
95 : /**
96 : * @brief Returns true if the Key Session object contains the specified key.
97 : *
98 : * @param[in] keySessionId : The key session id for the session.
99 : * @param[in] keyId : The key id.
100 : *
101 : * @retval true if it contains the key.
102 : */
103 : virtual bool containsKey(int32_t keySessionId, const std::vector<uint8_t> &keyId) = 0;
104 :
105 : /**
106 : * @brief Creates a session and returns the session id.
107 : *
108 : * This method creates a new session and returns the session id in
109 : * the specified string. Any other errors will result in MediaKeyErrorStatus:FAIL.
110 : *
111 : * @param[in] sessionType : The session type.
112 : * @param[in] client : Client object for callbacks
113 : * @param[out] keySessionId: The key session id
114 : *
115 : * @retval an error status.
116 : */
117 : virtual MediaKeyErrorStatus createKeySession(KeySessionType sessionType, std::weak_ptr<IMediaKeysClient> client,
118 : int32_t &keySessionId) = 0;
119 :
120 : /**
121 : * @brief Generates a licence request.
122 : *
123 : * This method triggers generation of a licence request. If the session
124 : * id does not exist an MediaKeyErrorStatus:BAD_SESSION_ID is returned. If the
125 : * session type or init data type is not supported a
126 : * MediaKeyErrorStatus:NOT_SUPPORTED value is be returned. Any other
127 : * errors will result in MediaKeyErrorStatus:FAIL.
128 : *
129 : * @param[in] keySessionId : The key session id for the session.
130 : * @param[in] initDataType : The init data type.
131 : * @param[in] initData : The init data.
132 : * @param[in] ldlState : The Limited Duration License state. Most of key systems do not need this parameter,
133 : * so the default value is NOT_SPECIFIED.
134 : *
135 : * @retval an error status.
136 : */
137 : virtual MediaKeyErrorStatus
138 : generateRequest(int32_t keySessionId, InitDataType initDataType, const std::vector<uint8_t> &initData,
139 10 : const LimitedDurationLicense &ldlState = LimitedDurationLicense::NOT_SPECIFIED) = 0;
140 :
141 : /**
142 : * @brief Loads an existing key session
143 : *
144 : * This method loads an existing key session. If the session id does
145 : * not exist an MediaKeyErrorStatus:BAD_SESSION_ID is returned. If the
146 : * session type or init data type is not supported a
147 : * MediaKeyErrorStatus:NOT_SUPPORTED value must be returned. If the session
148 : * state is invalid an MediaKeyErrorStatus:INVALID_STATE is returned. Any
149 : * other errors will result in MediaKeyErrorStatus:FAIL.
150 : *
151 : * @param[in] keySessionId : The key session id for the session.
152 : *
153 : * @retval an error status.
154 : */
155 : virtual MediaKeyErrorStatus loadSession(int32_t keySessionId) = 0;
156 :
157 : /**
158 : * @brief Updates a key session's state.
159 : *
160 : * This method updates a session's state. If the session id does
161 : * not exist an MediaKeyErrorStatus:BAD_SESSION_ID is returned. If the session
162 : * state is invalid an MediaKeyErrorStatus:INVALID_STATE is returned. Any
163 : * other errors will result in MediaKeyErrorStatus:FAIL.
164 : *
165 : * @param[in] keySessionId : The key session id for the session.
166 : * @param[in] responseData : The license response data.
167 : *
168 : * @retval an error status.
169 : */
170 : virtual MediaKeyErrorStatus updateSession(int32_t keySessionId, const std::vector<uint8_t> &responseData) = 0;
171 :
172 : /**
173 : * @brief Set DRM Header for a key session
174 : *
175 : * This method updates a key session's DRM header. If the session id does
176 : * not exist an MediaKeyErrorStatus:BAD_SESSION_ID is returned.If the session
177 : * state is invalid an MediaKeyErrorStatus:INVALID_STATE is returned. Any
178 : * other errors will result in MediaKeyErrorStatus:FAIL.
179 : *
180 : * @param[in] keySessionId : The session id for the session.
181 : * @param[in] requestData : The request data.
182 : *
183 : * @retval an error status.
184 : */
185 : virtual MediaKeyErrorStatus setDrmHeader(int32_t keySessionId, const std::vector<uint8_t> &requestData) = 0;
186 :
187 : /**
188 : * @brief Closes a key session
189 : *
190 : * This method closes an open session. If the session id does
191 : * not exist an MediaKeyErrorStatus:BAD_SESSION_ID is returned. Any other
192 : * errors will result in MediaKeyErrorStatus:FAIL.
193 : *
194 : * @param[in] keySessionId : The key session id.
195 : *
196 : * @retval an error status.
197 : */
198 : virtual MediaKeyErrorStatus closeKeySession(int32_t keySessionId) = 0;
199 :
200 : /**
201 : * @brief Removes a key session
202 : *
203 : * This method removes an open session. If the session id does
204 : * not exist an MediaKeyErrorStatus:BAD_SESSION_ID is returned. Any other
205 : * errors will result in MediaKeyErrorStatus:FAIL.
206 : *
207 : * @param[in] keySessionId : The key session id.
208 : *
209 : * @retval an error status.
210 : */
211 : virtual MediaKeyErrorStatus removeKeySession(int32_t keySessionId) = 0;
212 :
213 : /**
214 : * @brief Delete the DRM store for the object's key system
215 : *
216 : * @retval the return status value.
217 : */
218 : virtual MediaKeyErrorStatus deleteDrmStore() = 0;
219 :
220 : /**
221 : * @brief Delete the key store for the object's key system
222 : *
223 : * @retval the return status value.
224 : */
225 : virtual MediaKeyErrorStatus deleteKeyStore() = 0;
226 :
227 : /**
228 : * @brief Gets a hash of the DRM store for the object's key system
229 : *
230 : * @param[out] drmStoreHash : the hash value
231 : *
232 : * @retval the return status value.
233 : */
234 : virtual MediaKeyErrorStatus getDrmStoreHash(std::vector<unsigned char> &drmStoreHash) = 0;
235 :
236 : /**
237 : * @brief Gets a hash of the Key store for the object's key system
238 : *
239 : * @param[out] keyStoreHash : the hash value
240 : *
241 : * @retval the return status value.
242 : */
243 : virtual MediaKeyErrorStatus getKeyStoreHash(std::vector<unsigned char> &keyStoreHash) = 0;
244 :
245 : /**
246 : * @brief Get the limit on the number of ldl key sessions for the object's key system
247 : *
248 : * @param[out] ldlLimit : the limit on the number of ldl key sessions.
249 : *
250 : * @retval the return status value.
251 : */
252 : virtual MediaKeyErrorStatus getLdlSessionsLimit(uint32_t &ldlLimit) = 0;
253 :
254 : /**
255 : * @brief Get the last cdm specific DRM error code
256 : *
257 : * @param[in] keySessionId : The key session id.
258 : * @param[out] errorCode : the error code.
259 : *
260 : * @retval the return status value.
261 : */
262 : virtual MediaKeyErrorStatus getLastDrmError(int32_t keySessionId, uint32_t &errorCode) = 0;
263 :
264 : /**
265 : * @brief Get the DRM system time for the object's key system
266 : *
267 : * @param[out] drmTime : the DRM system time
268 : *
269 : * @retval the return status value.
270 : */
271 : virtual MediaKeyErrorStatus getDrmTime(uint64_t &drmTime) = 0;
272 :
273 : /**
274 : * @brief Get the internal CDM key session ID
275 : *
276 : * @param[in] keySessionId : The key session id for the session.
277 : * @param[out] cdmKeySessionId : The internal CDM key session ID
278 : *
279 : * @retval the return status value.
280 : */
281 : virtual MediaKeyErrorStatus getCdmKeySessionId(int32_t keySessionId, std::string &cdmKeySessionId) = 0;
282 :
283 : /**
284 : * @brief Releases a key session
285 : *
286 : * This method releases an open session. If the session id does
287 : * not exist an MediaKeyErrorStatus:BAD_SESSION_ID is returned. Any other
288 : * errors will result in MediaKeyErrorStatus:FAIL.
289 : *
290 : * @param[in] keySessionId : The key session id.
291 : *
292 : * @retval an error status.
293 : */
294 : virtual MediaKeyErrorStatus releaseKeySession(int32_t keySessionId) = 0;
295 :
296 : /**
297 : * @brief Get metrics for a DRM system
298 : *
299 : * @param[out] buffer : Buffer that can hold the metric data
300 : *
301 : * @retval an error status.
302 : */
303 : virtual MediaKeyErrorStatus getMetricSystemData(std::vector<uint8_t> &buffer) = 0;
304 : };
305 :
306 : }; // namespace firebolt::rialto
307 :
308 : #endif // FIREBOLT_RIALTO_I_MEDIA_KEYS_H_
|
