Source release 19.5.0

oemcrypto/include/OEMCryptoCENC.h

@@ -3,7 +3,7 @@
 // License Agreement.
 
 /**
- * @mainpage OEMCrypto API v19.4
+ * @mainpage OEMCrypto API v19.5
  *
  * OEMCrypto is the low level library implemented by the OEM to provide key and
  * content protection, usually in a separate secure memory or process space. The
@@ -764,6 +764,8 @@ typedef enum OEMCrypto_SignatureHashAlgorithm {
 #define OEMCrypto_WrapClearPrivateKey         _oecc154
 #define OEMCrypto_SetSessionUsage             _oecc155
 #define OEMCrypto_GetBCCSignatureType         _oecc156
+#define OEMCrypto_GetPVRKey                   _oecc157
+#define OEMCrypto_LoadPVRKey                  _oecc158
 // clang-format on
 
 /// @addtogroup initcontrol
@@ -1984,6 +1986,72 @@ OEMCryptoResult OEMCrypto_GetOEMKeyToken(OEMCrypto_SESSION key_session,
 OEMCryptoResult OEMCrypto_SetSessionUsage(OEMCrypto_SESSION session,
                                           uint32_t intent, uint32_t mode);
 
+/**
+ * Retrieves the key used for Personal Video Recorder (PVR) re-encrypting
+ * recorded content. The returned key is encrypted by a device specific key for
+ * storage on the filesystem. The format of the wrapped key is
+ * platform-specific. This method is currently used exclusively by CAS with PVR
+ * support.
+ *
+ * @param[in] session: session id.
+ * @param[out] wrapped_pvr_key: pointer to a buffer where the wrapped PVR key
+ *    will be stored. May be null on the first call to determine the required
+ *    buffer size.
+ * @param[in,out] wrapped_pvr_key_length: length of the buffer for the wrapped
+ *    PVR key, in bytes.
+ *
+ * @retval OEMCrypto_SUCCESS on success
+ * @retval OEMCrypto_ERROR_INVALID_SESSION
+ * @retval OEMCrypto_ERROR_SHORT_BUFFER
+ * @retval OEMCrypto_ERROR_UNKNOWN_FAILURE
+ * @retval OEMCrypto_ERROR_NOT_IMPLEMENTED
+ *
+ * @threading
+ *   This is a "Session Function" and may be called simultaneously with session
+ *   functions for other sessions but not simultaneously with other functions
+ *   for this session. It is as if the CDM holds a write lock for this session,
+ *   and a read lock on the OEMCrypto system.
+ *
+ * @version
+ *   This method is new in API version 18.
+ */
+OEMCryptoResult OEMCrypto_GetPVRKey(OEMCrypto_SESSION session,
+                                    uint8_t* wrapped_pvr_key,
+                                    size_t* wrapped_pvr_key_length);
+
+/**
+ * Loads a wrapped PVR key into secure memory. This key is used for decrypting
+ * content that has been re-encrypted for PVR storage. The wrapped PVR key
+ * is typically obtained from persistent storage, having been previously
+ * retrieved using OEMCrypto_GetPVRKey(). This method is currently used
+ * exclusively by CAS with PVR support.
+ *
+ * @param[in] session: session id.
+ * @param[in] wrapped_pvr_key: Pointer to the buffer containing the wrapped PVR
+ *    key.
+ * @param[in] wrapped_pvr_key_length: Length of the wrapped PVR key buffer, in
+ *     bytes.
+ *
+ * @retval OEMCrypto_SUCCESS on success.
+ * @retval OEMCrypto_ERROR_INVALID_SESSION
+ * @retval OEMCrypto_ERROR_INVALID_KEY
+ * @retval OEMCrypto_ERROR_INSUFFICIENT_RESOURCES
+ * @retval OEMCrypto_ERROR_UNKNOWN_FAILURE
+ * @retval OEMCrypto_ERROR_NOT_IMPLEMENTED
+ *
+ * @threading
+ *   This is a "Session Function" and may be called simultaneously with session
+ *   functions for other sessions but not simultaneously with other functions
+ *   for this session. It is as if the CDM holds a write lock for this session,
+ *   and a read lock on the OEMCrypto system.
+ *
+ * @version
+ *   This method is new in API version 18.
+ */
+OEMCryptoResult OEMCrypto_LoadPVRKey(OEMCrypto_SESSION session,
+                                     const uint8_t* wrapped_pvr_key,
+                                     size_t wrapped_pvr_key_length);
+
 /// @}
 
 /// @addtogroup decryption
@@ -5206,11 +5274,15 @@ OEMCryptoResult OEMCrypto_ShrinkUsageTableHeader(uint32_t new_entry_count,
  * @param[in,out] bcc_length - on input, size of the caller's bcc buffer. On
  *    output, the number of bytes written into the buffer.
  * @param[out] additional_signature: pointer to the buffer that receives
- *    additional device key signature (certificate chain). This field is only
- *    used by the signing model where either a vendor certificate or a keybox is
- * available on the device. Please work with your Widevine Partner Engineer
- * before implementing this field to make sure the generated signature is in the
- * expected format.
+ *    additional device key signature (Unique Device Secret certificate chain).
+ *    This field is used by (1) the signing model where either a vendor
+ *    certificate or a keybox is available on the device, or (2) the
+ *    Provisioning 4.0 phase 3 uploading model. For details on the format of
+ *    additional_signature in the scenarios mentioned above, please refer to the
+ *    definition of enum OEMCrypto_BCCSignatureType and
+ *    OEMCrypto_GetBCCSignatureType(). Please work with your Widevine Partner
+ *    Engineer before implementing this field to make sure the generated
+ *    signature is in the expected format.
  * @param[in,out] additional_signature_length - on input, size of the caller's
  *    additional_signature buffer. On output, the number of bytes written into
  *    the buffer.