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 */ 16 17 #ifndef DRM_HAL_VENDOR_MODULE_API_H 18 #define DRM_HAL_VENDOR_MODULE_API_H 19 20 #include <stdint.h> 21 #include <map> 22 #include <string> 23 #include <vector> 24 25 /** 26 * The DRM and Crypto HALs interact with vendor-provided HAL implementations 27 * that have DRM-specific capabilities. Since the VTS tests cannot contain 28 * DRM-specific functionality, supporting modules are required to enable VTS 29 * to validate HAL implementations in a generic way. If the vendor-specific 30 * VTS module is not provided for a given drm HAL implementation, only very 31 * small subset of functionality can be verified. 32 * 33 * As an example, a DRM HAL implementation interacts with a DRM-specific 34 * license server to obtain licenses for decrypting content. The DRM HAL 35 * implementation generates a key request message, delivers it to the server 36 * and receives a key response message which is then loaded into the HAL. Once 37 * the keys are loaded, the Crypto HAL decryption functionality and performance 38 * and other associated APIs can be tested by the common VTS test suite. 39 * 40 * Vendor-specific VTS modules are shared libraries used by the DRM VTS test. 41 * They provide a set of functions to support VTS testing of the DRM HAL module. 42 * 43 * The modules are placed in a common location on the file system. The VTS test 44 * scans through all vendor-provided support libraries and runs the VTS test 45 * suite on each library that is found. 46 * 47 * The vendor-specific module exposes an extern C vendorModuleFactory() 48 * function that returns a DrmHalVTSVendorModule instance. DrmHalVTSVendorModule 49 * instances are versioned, where each version is represented by subclass of 50 * DrmHalVTSVendorModule that corresponds to the API version. For example, a 51 * vendor-specific module that implements version 1 of the API would return a 52 * DrmHalVTSVendorModule_V1 from the vendorModuleFactory() function. 53 */ 54 55 class DrmHalVTSVendorModule; 56 57 extern "C" { 58 /** 59 * The factory method for creating DrmHalVTSVendorModule instances. The returned 60 * instance will be a subclass of DrmHalVTSVendorModule that corresponds to the 61 * supported API version. 62 */ 63 DrmHalVTSVendorModule* vendorModuleFactory(); 64 }; 65 66 class DrmHalVTSVendorModule { 67 public: 68 DrmHalVTSVendorModule() : installed(true) {} 69 virtual ~DrmHalVTSVendorModule() {} 70 71 /** 72 * Return the vendor-specific module API version. The version is an integer 73 * value with initial version 1. The API version indicates which subclass 74 * version DrmHalVTSVendorModule this instance is. 75 */ 76 virtual uint32_t getAPIVersion() const = 0; 77 78 /** 79 * Return the UUID for the DRM HAL implementation. Protection System 80 * Specific 81 * UUID (see http://dashif.org/identifiers/protection/) 82 */ 83 virtual std::vector<uint8_t> getUUID() const = 0; 84 85 /** 86 * Return the service name for the DRM HAL implementation. If the hal is a 87 * legacy 88 * drm plugin, i.e. not running as a HIDL service, return the empty string. 89 */ 90 virtual std::string getServiceName() const = 0; 91 92 /** 93 * Set a flag in the vendor module to indicate whether or not the drm 94 * scheme corresponding to this module is installed on the device. 95 */ 96 void setInstalled(bool flag) {installed = flag;} 97 bool isInstalled() const {return installed;} 98 99 private: 100 bool installed; 101 DrmHalVTSVendorModule(const DrmHalVTSVendorModule&) = delete; 102 void operator=(const DrmHalVTSVendorModule&) = delete; 103 }; 104 105 /** 106 * API Version 1. This is the baseline version that supports a minimal set 107 * of VTS tests. 108 */ 109 class DrmHalVTSVendorModule_V1 : public DrmHalVTSVendorModule { 110 public: 111 DrmHalVTSVendorModule_V1() {} 112 virtual ~DrmHalVTSVendorModule_V1() {} 113 114 virtual uint32_t getAPIVersion() const { return 1; } 115 116 /** 117 * Handle a provisioning request. This function will be called if the HAL 118 * module's getProvisionRequest returns a provision request. The vendor 119 * module should process the provisioning request, either by sending it 120 * to a provisioning server, or generating a mock response. The resulting 121 * provisioning response is returned to the VTS test. 122 * 123 * @param provisioningRequest the provisioning request recieved from 124 * the DRM HAL 125 * @param url the default url the HAL implementation provided with the 126 * provisioning request 127 * @return the generated provisioning response 128 */ 129 virtual std::vector<uint8_t> handleProvisioningRequest( 130 const std::vector<uint8_t>& provisioningRequest, 131 const std::string& url) = 0; 132 133 /** 134 * Content configuration specifies content-specific parameters associated 135 * with a key request/response transaction. It allows the VTS test to 136 * request keys and use them to perform decryption. 137 */ 138 struct ContentConfiguration { 139 /** 140 * Assign a name for this configuration that will be referred to 141 * in log messages. 142 */ 143 const std::string name; 144 145 /** 146 * Server to use when requesting a key response. This url will be 147 * passed as a parameter to the vendor vts module along with the 148 * key request to perform the key request transaction. 149 */ 150 const std::string serverUrl; 151 152 /** 153 * Initialization data provided to getKeyRequest, e.g. PSSH for CENC 154 * content 155 */ 156 const std::vector<uint8_t> initData; 157 158 /** 159 * Mime type provided to getKeyRequest, e.g. "video/mp4", or "cenc" 160 */ 161 const std::string mimeType; 162 163 /** 164 * Optional parameters to be associated with the key request 165 */ 166 const std::map<std::string, std::string> optionalParameters; 167 168 /** 169 * Define license policy attributes for the content configuration. 170 * These attributes can affect which tests are able to be applied. 171 */ 172 struct Policy { 173 /** 174 * Indicate if the license policy allows offline playback. 175 * Content configurated with this policy supports KeyType::OFFLINE 176 * key requests/responses. A vendor module should provide at least 177 * one content configuration where allowOffline is true if the drm 178 * scheme supports offline content. 179 */ 180 bool allowOffline; 181 } policy; 182 183 /** 184 * The keys that will be available once the keys are loaded 185 */ 186 struct Key { 187 /** 188 * Indicate if the key content is configured to require secure 189 * buffers, where the output buffers are protected and cannot be 190 * accessed by the non-secure cpu. A vendor module should provide 191 * at least one content configurations where isSecure is false, to 192 * allow decrypt result verification tests to be run. 193 */ 194 bool isSecure; 195 196 /** 197 * A key ID identifies a key to use for decryption 198 */ 199 const std::vector<uint8_t> keyId; 200 201 /** 202 * The clear content key is provided to generate expected values for 203 * validating decryption. 204 */ 205 const std::vector<uint8_t> clearContentKey; 206 }; 207 std::vector<Key> keys; 208 }; 209 210 /** 211 * Return a list of content configurations that can be exercised by the 212 * VTS test. 213 */ 214 virtual std::vector<ContentConfiguration> 215 getContentConfigurations() const = 0; 216 217 /** 218 * Handle a key request. This function will be called if the HAL 219 * module's getKeyRequest returns a key request. The vendor 220 * module should process the key request, either by sending it 221 * to a license server, or by generating a mock response. The resulting 222 * key response is returned to the VTS test. 223 * 224 * @param keyRequest the key request recieved from the DRM HAL 225 * @param serverUrl the url of the key server that was supplied 226 * by the ContentConfiguration 227 * @return the generated key response 228 */ 229 virtual std::vector<uint8_t> handleKeyRequest( 230 const std::vector<uint8_t>& keyRequest, 231 const std::string& serverUrl) = 0; 232 }; 233 234 #endif // DRM_HAL_VENDOR_MODULE_API_H 235
