Merge "Update Docs for OEMCrypto v14.1" into pi-dev

libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h

@@ -289,6 +289,8 @@ typedef enum OEMCrypto_Usage_Entry_Status {
  * Platforms that have compilers that support packed structures, may use the
  * following definition.  Other platforms may use the header pst_report.h which
  * defines a wrapper class.
+ *
+ * All fields are in network byte order.
  */
 #if 0  // If your compiler supports __attribute__((packed)).
 typedef struct {
@@ -371,11 +373,14 @@ typedef enum OEMCrypto_ProvisioningMethod {
 #define OEMCrypto_Initialize               _oecc01
 #define OEMCrypto_Terminate                _oecc02
 #define OEMCrypto_InstallKeybox            _oecc03
+#define OEMCrypto_InstallRootKeyCertificate _oecc03
 #define OEMCrypto_GetKeyData               _oecc04
 #define OEMCrypto_IsKeyboxValid            _oecc05
+#define OEMCrypto_IsRootKeyCertificateValid _oecc05
 #define OEMCrypto_GetRandom                _oecc06
 #define OEMCrypto_GetDeviceID              _oecc07
 #define OEMCrypto_WrapKeybox               _oecc08
+#define OEMCrypto_WrapRootKeyCertificate   _oecc08
 #define OEMCrypto_OpenSession              _oecc09
 #define OEMCrypto_CloseSession             _oecc10
 #define OEMCrypto_DecryptCTR_V10           _oecc11
@@ -1493,36 +1498,38 @@ OEMCryptoResult OEMCrypto_CopyBuffer(const uint8_t* data_addr,
                                      uint8_t subsample_flags);
 
 /*
- * OEMCrypto_WrapKeybox
+ * OEMCrypto_WrapRootKeyCertificate
  *
  * Description:
- *   During manufacturing, the keybox should be encrypted with the OEM root key
- *   and stored on the file system in a region that will not be erased during
- *   factory reset. As described in section 5.5.4, the keybox may be directly
- *   encrypted and stored on the device in a single step, or it may use the
- *   two-step WrapKeybox/InstallKeybox approach. When the Widevine DRM plugin
- *   initializes, it will look for a wrapped keybox in the file
- *   /factory/wv.keys and install it into the security processor by calling
- *   OEMCrypto_InstallKeybox().
  *
- *   OEMCrypto_WrapKeybox() is used to generate an OEM-encrypted keybox that
+ *   A device should be provisioned at the factory with either an OEM
- *   may be passed to OEMCrypto_InstallKeybox() for provisioning. The keybox
+ *   Certificate or a keybox.  We will call this data the root of trust.  During
- *   may be either passed in the clear or previously encrypted with a transport
+ *   manufacturing, the root of trust should be encrypted with the OEM root key
- *   key. If a transport key is supplied, the keybox is first decrypted with
+ *   and stored on the file system in a region that will not be erased during
- *   the transport key before being wrapped with the OEM root key. This
+ *   factory reset.  This function may be used by legacy systems that use the
- *   function is only needed if the provisioning method involves saving the
+ *   two-step WrapRootKeyCertificate/InstallRootKeyCertificate approach.  When
- *   keybox to the file system.
+ *   the Widevine DRM plugin initializes, it will look for a wrapped root of
+ *   trust in the file /factory/wv.keys and install it into the security
+ *   processor by calling OEMCrypto_InstallRootKeyCertificate().
+ *
+ *   OEMCrypto_WrapRootKeyCertificate() is used to generate an OEM-encrypted
+ *   root of trust that may be passed to OEMCrypto_InstallRootKeyCertificate()
+ *   for provisioning.  The root of trust may be either passed in the clear or
+ *   previously encrypted with a transport key.  If a transport key is supplied,
+ *   the keybox is first decrypted with the transport key before being wrapped
+ *   with the OEM root key.  This function is only needed if the root of trust
+ *   provisioning method involves saving the keybox to the file system.
  *
  * Parameters:
- *   keybox (in) - pointer to Keybox data to encrypt. May be NULL on the first
+ *   rot (in) - pointer to root of trust data to encrypt. May be NULL on the
- *       call to test size of wrapped keybox. The keybox may either be clear or
+ *       first call to test size of wrapped keybox. The keybox may either be
- *       previously encrypted.
+ *       clear or previously encrypted.
- *   keyboxLength (in) - length the keybox data in bytes
+ *   rotLength (in) - length the rot data in bytes
- *   wrappedKeybox (out) – Pointer to wrapped keybox
+ *   wrappedRot (out) – Pointer to wrapped rot
- *   wrappedKeyboxLength (out) – Pointer to the length of the wrapped keybox in
+ *   wrappedRotLength (out) – Pointer to the length of the wrapped keybox in
  *       bytes
- *   transportKey (in) – Optional. AES transport key. If provided, the keybox
+ *   transportKey (in) – Optional. AES transport key. If provided, the rot
- *       parameter was previously encrypted with this key. The keybox will be
+ *       parameter was previously encrypted with this key. The rot will be
  *       decrypted with the transport key using AES-CBC and a null IV.
  *   transportKeyLength (in) – Optional. Number of bytes in the transportKey, if
  *       used.
@@ -1541,26 +1548,29 @@ OEMCryptoResult OEMCrypto_CopyBuffer(const uint8_t* data_addr,
  * Version:
  *   This method is supported by all API versions.
  */
-OEMCryptoResult OEMCrypto_WrapKeybox(const uint8_t* keybox, size_t keyBoxLength,
+OEMCryptoResult OEMCrypto_WrapRootKeyCertificate(const uint8_t* rot, size_t rotLength,
-                                     uint8_t* wrappedKeybox,
+                                                 uint8_t* wrappedRot,
-                                     size_t* wrappedKeyBoxLength,
+                                                 size_t* wrappedRotLength,
-                                     const uint8_t* transportKey,
+                                                 const uint8_t* transportKey,
-                                     size_t transportKeyLength);
+                                                 size_t transportKeyLength);
 
 /*
- * OEMCrypto_InstallKeybox
+ * OEMCrypto_InstallRootKeyCertificate
  *
  * Description:
- *   Decrypts a wrapped keybox and installs it in the security processor. The
+ *
- *   keybox is unwrapped then encrypted with the OEM root key. This function is
+ *   Decrypts a wrapped root of trust and installs it in the security processor.
- *   called from the Widevine DRM plugin at initialization time if there is no
+ *   The root of trust is unwrapped then encrypted with the OEM root key.  This
- *   valid keybox installed. It looks for a wrapped keybox in the file
+ *   function is called from the Widevine DRM plugin at initialization time if
- *   /factory/wv.keys and if it is present, will read the file and call
+ *   there is no valid root of trust installed.  It looks for wrapped data in
- *   OEMCrypto_InstallKeybox() with the contents of the file.
+ *   the file /factory/wv.keys and if it is present, will read the file and call
+ *   OEMCrypto_InstallRootKeyCertificate() with the contents of the file.  This
+ *   function is only needed if the factory provisioning method involves saving
+ *   the keybox to the file system.
  *
  * Parameters:
- *   keybox  (in) - pointer to encrypted Keybox data as input
+ *   rot  (in) - pointer to encrypted data as input
- *   keyboxLength  (in) - length of the keybox data in bytes
+ *   rotLength  (in) - length of the data in bytes
  *
  * Threading:
  *   This function is not called simultaneously with any other functions.
@@ -1575,8 +1585,8 @@ OEMCryptoResult OEMCrypto_WrapKeybox(const uint8_t* keybox, size_t keyBoxLength,
  * Version:
  *   This method is supported in all API versions.
  */
-OEMCryptoResult OEMCrypto_InstallKeybox(const uint8_t* keybox,
+OEMCryptoResult OEMCrypto_InstallRootKeyCertificate(const uint8_t* rot,
-                                        size_t keyBoxLength);
+                                                    size_t rotLength);
 
 /*
  * OEMCrypto_GetProvisioningMethod
@@ -1671,10 +1681,12 @@ OEMCryptoResult OEMCrypto_GetOEMPublicCertificate(OEMCrypto_SESSION session,
 OEMCryptoResult OEMCrypto_LoadTestKeybox(const uint8_t *buffer, size_t length);
 
 /*
- * OEMCrypto_IsKeyboxValid
+ * OEMCrypto_IsRootKeyCertificateValid
  *
  * Description:
- *   Validate the Widevine Keybox stored on the device.
+ *
+ * If the device has a keybox, this validates the Widevine Keybox loaded into
+ * the security processor device.
  *
  * The API performs two verification steps on the Keybox. It first verifies
  * the MAGIC field contains a valid signature (must be 'kbox'). The API then
@@ -1682,6 +1694,9 @@ OEMCryptoResult OEMCrypto_LoadTestKeybox(const uint8_t *buffer, size_t length);
  * checksum to the CRC stored in the Keybox. The CRC is computed over the
  * entire Keybox excluding the 4 CRC bytes (i.e. Keybox[0..123]).
  *
+ * If the device has an OEM Certificate, this validates the certificate private
+ * key.
+ *
  * Parameters:
  *   none
  *
@@ -1692,11 +1707,13 @@ OEMCryptoResult OEMCrypto_LoadTestKeybox(const uint8_t *buffer, size_t length);
  *   OEMCrypto_SUCCESS
  *   OEMCrypto_ERROR_BAD_MAGIC
  *   OEMCrypto_ERROR_BAD_CRC
+ *   OEMCrypto_ERROR_KEYBOX_INVALID
+ *   OEMCrypto_ERROR_NOT_IMPLEMENTED
  *
  * Version:
  *   This method is supported by all API versions.
  */
-OEMCryptoResult OEMCrypto_IsKeyboxValid(void);
+OEMCryptoResult OEMCrypto_IsRootKeyCertificateValid(void);
 
 /*
  * OEMCrypto_GetDeviceID