1 /******************************************************************************* 2 * 3 * Reference APIs needed to support Widevine's crypto algorithms. 4 * 5 ******************************************************************************/ 6 7 #ifndef _OEMCRYPTO_AES_H 8 #define _OEMCRYPTO_AES_H 9 10 typedef unsigned char OEMCrypto_UINT8; 11 typedef char OEMCrypto_INT8; 12 typedef unsigned int OEMCrypto_UINT32; 13 typedef unsigned int OEMCrypto_SECURE_BUFFER; 14 15 16 typedef enum OEMCryptoResult { 17 OEMCrypto_SUCCESS = 0, 18 OEMCrypto_ERROR_INIT_FAILED, 19 OEMCrypto_ERROR_TERMINATE_FAILED, 20 OEMCrypto_ERROR_ENTER_SECURE_PLAYBACK_FAILED, 21 OEMCrypto_ERROR_EXIT_SECURE_PLAYBACK_FAILED, 22 OEMCrypto_ERROR_SHORT_BUFFER, 23 OEMCrypto_ERROR_NO_DEVICE_KEY, 24 OEMCrypto_ERROR_NO_ASSET_KEY, 25 OEMCrypto_ERROR_KEYBOX_INVALID, 26 OEMCrypto_ERROR_NO_KEYDATA, 27 OEMCrypto_ERROR_NO_CW, 28 OEMCrypto_ERROR_DECRYPT_FAILED, 29 OEMCrypto_ERROR_WRITE_KEYBOX, 30 OEMCrypto_ERROR_WRAP_KEYBOX, 31 OEMCrypto_ERROR_BAD_MAGIC, 32 OEMCrypto_ERROR_BAD_CRC, 33 OEMCrypto_ERROR_NO_DEVICEID, 34 OEMCrypto_ERROR_RNG_FAILED, 35 OEMCrypto_ERROR_RNG_NOT_SUPPORTED, 36 OEMCrypto_ERROR_SETUP 37 } OEMCryptoResult; 38 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 #define OEMCrypto_Initialize _oec01 45 #define OEMCrypto_Terminate _oec02 46 #define OEMCrypto_SetEntitlementKey _oec03 47 #define OEMCrypto_DeriveControlWord _oec04 48 #define OEMCrypto_DecryptVideo _oec05 49 #define OEMCrypto_DecryptAudio _oec06 50 #define OEMCrypto_InstallKeybox _oec07 51 #define OEMCrypto_GetKeyData _oec08 52 #define OEMCrypto_IsKeyboxValid _oec09 53 #define OEMCrypto_GetRandom _oec10 54 #define OEMCrypto_GetDeviceID _oec11 55 #define OEMCrypto_EnterSecurePlayback _oec12 56 #define OEMCrypto_ExitSecurePlayback _oec13 57 #define OEMCrypto_WrapKeybox _oec14 58 59 /* 60 * OEMCrypto_Initialize 61 * 62 * Description: 63 * Initializes the crypto hardware 64 * 65 * Parameters: 66 * N/A 67 * 68 * Returns: 69 * OEMCrypto_SUCCESS success 70 * OEMCrypto_ERROR_INIT_FAILED failed to initialize crypto hardware 71 */ 72 OEMCryptoResult OEMCrypto_Initialize(void); 73 74 75 /* 76 * OEMCrypto_Terminate 77 * 78 * Description: 79 * The API closes the crypto operation and releases all resources used. 80 * 81 * Parameters: 82 * N/A 83 * 84 * Returns: 85 * OEMCrypto_SUCCESS success 86 * OEMCrypto_ERROR_TERMINATE_FAILED failed to de-initialize crypto hardware 87 */ 88 OEMCryptoResult OEMCrypto_Terminate(void); 89 90 /* 91 * OEMCrypto_EnterSecurePlayback 92 * 93 * Description: 94 * Configures the security processor for secure decryption. This may involve 95 * setting up firewall regions. It is called when the decrypt session for an 96 * asset is established. 97 * 98 * Parameters: 99 * N/A 100 * 101 * Returns: 102 * OEMCrypto_SUCCESS success 103 * OEMCrypto_ERROR_ENTER_SECURE_PLAYBACK_FAILED 104 */ 105 OEMCryptoResult OEMCrypto_EnterSecurePlayback(void); 106 107 /* 108 * OEMCrypto_ExitSecurePlayback 109 * 110 * Description: 111 * Exit the secure playback mode. This may involve releasing the firewall regions. It is 112 * called when the decrypt session for an asset is closed. 113 * 114 * Parameters: 115 * N/A 116 * 117 * Returns: 118 * OEMCrypto_SUCCESS success 119 * OEMCrypto_ERROR_EXIT_SECURE_PLAYBACK_FAILED 120 */ 121 OEMCryptoResult OEMCrypto_ExitSecurePlayback(void); 122 123 /* 124 * OEMCrypto_SetEntitlementKey 125 * 126 * Description: 127 * Decrypt the entitlement (EMM) key, also known as the asset key, 128 * using the encrypted device key (Device Key field) in the Widevine Keybox. 129 * 130 * As shown in Figure 1 on the next page, Step 1 uses an OEM root key to decrypt 131 * (AES-128-ECB) the Device Key in the Keybox; the result is “latched” in hardware 132 * key ladder. 133 * 134 * Step 2 uses the “latched” clear device key to decrypt (AES-128-ECB) the 135 * entitlement key passed in as the *emmKey parameter and “latched” the clear 136 * entitlement key in hardware for the next operation. 137 * 138 * Parameters: 139 * emmKey (in) - pointer to the encrypted entitlement key 140 * emmKeyLength (in) – length of entitlement key in bytes 141 * 142 * Returns: 143 * OEMCrypto_SUCCESS success 144 * OEMCrypto_ERROR_NO_DEVICE_KEY failed to decrypt device key 145 * OEMCrypto_ERROR_NO_ASSET_KEY failed to decrypt asset key 146 * OEMCrypto_ERROR_KEYBOX_INVALID cannot decrypt and read from Keybox 147 */ 148 149 OEMCryptoResult OEMCrypto_SetEntitlementKey(const OEMCrypto_UINT8* emmKey, 150 const OEMCrypto_UINT32 emmKeyLength); 151 152 /* 153 * OEMCrypto_DeriveControlWord 154 * 155 * Description: 156 * Using the active key ladder key from OEMCrypto_SetEntitlementKey(), decrypts 157 * (AES-128-CBC, iv=0) the 32-byte ECM referenced by the *ecm parameter; returns in 158 * *flags the first clear 4 bytes data. “Latched” the clear bytes [4..20] as the 159 * clear control word for subsequent payload decryption operation. 160 * 161 * Parameters: 162 * ecm (in) - points to encrypted ECM data 163 * length (in) – length of encrypted ECM data in bytes 164 * flags (out) - points to buffer to receive 4 byte clear flag value 165 * 166 * Returns: 167 * OEMCrypto_SUCCESS success 168 * OEMCrypto_ERROR_NO_CW cannot decrypt control word 169 */ 170 171 OEMCryptoResult OEMCrypto_DeriveControlWord(const OEMCrypto_UINT8* ecm, 172 const OEMCrypto_UINT32 length, 173 OEMCrypto_UINT32* flags); 174 175 176 /* 177 * OEMCrypto_DecryptVideo 178 * 179 * Description: 180 * 181 * The API decrypts (AES-128-CBC) the video payload in the buffer referenced by 182 * the *input parameter into the secure buffer referenced by the output 183 * parameter, using the control word “latched” in the active hardware key 184 * ladder. If inputLength is not a multiple of the crypto block size (16 bytes), 185 * the API handles the residual bytes using CipherText Stealing (CTS). 186 * 187 * Parameters: 188 * iv (in/out) - If iv is NULL, then no decryption is required, i.e. the packets are 189 * already clear. Otherwise, iv references the AES initialization 190 * vector. Note that the updated IV after processing the final crypto 191 * block must be passed back out in *iv. 192 * input (in) - buffer containing the encrypted data 193 * inputLength (in) - number of bytes in the input payload, which may not be a multiple of 16 bytes 194 * output (in) – reference to the secure buffer which will receive the decrypted data 195 * outputLength (out) - number of bytes written into the secure buffer 196 * 197 * Returns: 198 * OEMCrypto_SUCCESS success 199 * OEMCrypto_ERROR_DECRYPT_FAILED failed decryption 200 */ 201 202 OEMCryptoResult 203 OEMCrypto_DecryptVideo(const OEMCrypto_UINT8* iv, 204 const OEMCrypto_UINT8* input, const OEMCrypto_UINT32 inputLength, 205 OEMCrypto_UINT32 output_handle, OEMCrypto_UINT32 output_offset, OEMCrypto_UINT32 *outputLength); 206 207 208 /* 209 * OEMCrypto_DecryptAudio 210 * 211 * Description: 212 * The API decrypts (AES-128-CBC) the audio payload in the buffer referenced by 213 * the *input parameter into the non-secure buffer referenced by the output 214 * parameter, using the control word “latched” in the active hardware key 215 * ladder. If inputLength is not a multiple of the crypto block size (16 bytes), 216 * the API handles the residual bytes using CipherText Stealing (CTS). 217 * 218 * OEMCrypto_DecryptAudio must make sure that it cannot be used to decrypt a video 219 * stream into non-firewalled buffers, by verifying that no video packets are 220 * processed. 221 * 222 * Parameters: 223 * iv (in/out) - If iv is NULL, then no decryption is required, i.e. the packets are 224 * already clear. Otherwise, iv references the AES initialization 225 * vector. Note that the updated IV after processing the final crypto 226 * block must be passed back out in *iv. 227 * input (in) - buffer containing the encrypted data 228 * inputLength (in) - number of bytes in the input payload, which may not be a multiple of 16 bytes 229 * output (in) – reference to the non-secure buffer which will receive the decrypted data 230 * outputLength (out) - number of bytes written into the non-secure buffer 231 * 232 * Returns: 233 * OEMCrypto_SUCCESS success 234 * OEMCrypto_ERROR_DECRYPT_FAILED failed decryption 235 */ 236 OEMCryptoResult 237 OEMCrypto_DecryptAudio(const OEMCrypto_UINT8* iv, 238 const OEMCrypto_UINT8* input, const OEMCrypto_UINT32 inputLength, 239 OEMCrypto_UINT8 *output, OEMCrypto_UINT32 *outputLength); 240 241 242 /* 243 * OEMCrypto_InstallKeybox 244 * 245 * Description: 246 * Unwrap and store the keybox to persistent memory. The device key must be stored 247 * securely. The device key will be decrypted and 248 * “latched” into hardware key ladder by OEMCrypto_SetEntitlementKey. 249 * 250 * This function is used once to load the keybox onto the device at provisioning time. 251 * 252 * Parameters: 253 * keybox (in) - Pointer to clear keybox data. Must have been wrapped with OEMCrypto_WrapKeybox 254 * keyboxLength (in) - Length of the keybox data in bytes 255 * 256 * Returns: 257 * OEMCrypto_SUCCESS success 258 * OEMCrypto_ERROR_WRITE_KEYBOX failed to handle and store Keybox 259 */ 260 261 OEMCryptoResult OEMCrypto_InstallKeybox(OEMCrypto_UINT8 *keybox, 262 OEMCrypto_UINT32 keyBoxLength); 263 264 265 /* 266 * OEMCrypto_IsKeyboxValid 267 * 268 * Description: 269 * Validate the Widevine Keybox stored on the device. 270 * 271 * The API performs two verification steps on the Keybox. It first verifies the MAGIC 272 * field contains a valid signature (i.e. ‘k’’b’’o’’x’). The API then computes the 273 * CRC using CRC-32-IEEE 802.3 standard and compares the checksum to the CRC stored 274 * in the Keybox. The CRC is computed over the entire Keybox excluding the 4 bytes 275 * CRC (i.e. Keybox[0..123]. 276 * 277 * Parameters: 278 * none 279 * 280 * Returns: 281 * OEMCrypto_SUCCESS 282 * OEMCrypto_ERROR_BAD_MAGIC 283 * OEMCrypto_ERROR_BAD_CRC 284 */ 285 286 OEMCryptoResult OEMCrypto_IsKeyboxValid(void); 287 288 289 /* 290 * OEMCrypto_GetDeviceID 291 * 292 * Description: 293 * Retrieve the device's unique identifier from the Keybox. 294 * 295 * Parameters: 296 * deviceId (out) - pointer to the buffer that receives the Device ID 297 * idLength (in/out) - on input, size of the caller's device ID buffer. 298 * On output, the number of bytes written into the buffer. 299 * 300 * Returns: 301 * OEMCrypto_SUCCESS success 302 * OEMCrypto_ERROR_SHORT_BUFFER if the buffer is too small to return the device ID 303 * OEMCrypto_ERROR_NO_DEVICEID failed to return Device Id 304 */ 305 OEMCryptoResult OEMCrypto_GetDeviceID(OEMCrypto_UINT8* deviceID, 306 OEMCrypto_UINT32 *idLength); 307 308 309 /* 310 * OEMCrypto_GetKeyData 311 * 312 * Description: 313 * Returns the Key Data field from the Keybox. The Key Data field does not need to be 314 * encrypted by an OEM root key, but may be if desired. 315 * 316 * If the Key Data field was encrypted with an OEM root key when the Keybox was stored 317 * on the device, then this function should decrypt it and return the clear Key Data. 318 * If the Key Data was not encrypted, then this function should just access and return 319 * the clear Key data. 320 * 321 * Parameters: 322 * keyData (out) - pointer to the buffer to hold the Key Data field from the Keybox 323 * dataLength (in/out) - on input, the allocated buffer size. On output, the number 324 * of bytes in KeyData. 325 * 326 * Returns: 327 * OEMCrypto_SUCCESS success 328 * OEMCrypto_ERROR_SHORT_BUFFER if the buffer is too small to return the KeyData 329 * OEMCrypto_ERROR_NO_KEYDATA failed to return KeyData 330 */ 331 OEMCryptoResult OEMCrypto_GetKeyData(OEMCrypto_UINT8* keyData, 332 OEMCrypto_UINT32 *keyDataLength); 333 334 335 /* 336 * OEMCrypto_GetRandom 337 * 338 * Description: 339 * Returns a buffer filled with hardware-generated random bytes, if supported by the hardware. 340 * 341 * Parameters: 342 * randomData (out) - Points to the buffer that should recieve the random data. 343 * dataLength (in) - Length of the random data buffer in bytes. 344 * 345 * Returns: 346 * OEMCrypto_SUCCESS success 347 * OEMCrypto_ERROR_RNG_FAILED failed to generate random number 348 * OEMCrypto_ERROR_RNG_NOT_SUPPORTED function not supported 349 */ 350 351 OEMCryptoResult OEMCrypto_GetRandom(OEMCrypto_UINT8* randomData, 352 OEMCrypto_UINT32 dataLength); 353 354 /* 355 * OEMCrypto_WrapKeybox 356 * 357 * Description: 358 * Wrap the Keybox with a key derived for the device key. 359 * 360 * Parameters: 361 * keybox (in) - Pointer to keybox data. 362 * keyboxLength - Length of the Keybox data in bytes 363 * wrappedKeybox (out) - Pointer to wrapped keybox 364 * wrappedKeyboxLength (out) - Pointer to the length of the wrapped keybox in bytes 365 * transportKey (in) - An optional AES transport key. If provided, the parameter 366 * keybox is passed encrypted with this transport key with AES-CBC 367 * and a null IV 368 * transportKeyLength - number of bytes in the transportKey 369 * 370 * Returns: 371 * OEMCrypto_SUCCESS success 372 * OEMCrypto_ERROR_WRAP_KEYBOX failed to wrap Keybox 373 */ 374 375 OEMCryptoResult OEMCrypto_WrapKeybox(OEMCrypto_UINT8 *keybox, 376 OEMCrypto_UINT32 keyBoxLength, 377 OEMCrypto_UINT8 *wrappedKeybox, 378 OEMCrypto_UINT32 *wrappedKeyBoxLength, 379 OEMCrypto_UINT8 *transportKey, 380 OEMCrypto_UINT32 transportKeyLength); 381 382 #ifdef __cplusplus 383 } 384 #endif 385 386 #endif 387 388 /***************************** End of File *****************************/ 389