diff --git a/libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h b/libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h index 29a3d8fb..9ffa2808 100644 --- a/libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h +++ b/libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h @@ -300,9 +300,9 @@ typedef struct { * region. * * @param[in] num_bytes_clear: The number of unprotected bytes in this - * subsample. The clear bytes come before the encrypted bytes. + * subsample. The unprotected bytes come before the protected bytes. * @param[in] num_bytes_encrypted: The number of protected bytes in this - * subsample. The protected bytes come after the clear bytes. + * subsample. The protected bytes come after the unprotected bytes. * @param[in] subsample_flags: bitwise flags indicating if this is the first, * middle, or last subsample in a sample. 1 = first subsample, 2 = last * subsample, 3 = both first and last subsample, 0 = neither first nor last @@ -319,8 +319,8 @@ typedef struct { * This struct changed in API version 16. */ typedef struct { - size_t num_bytes_clear; - size_t num_bytes_encrypted; + size_t num_bytes_clear; // Number of bytes in the unprotected region. + size_t num_bytes_encrypted; // Number of bytes in the protected region. uint8_t subsample_flags; // is this the first/last subsample in a sample? size_t block_offset; // used for CTR "cenc" mode only. } OEMCrypto_SubSampleDescription; @@ -2032,17 +2032,19 @@ OEMCryptoResult OEMCrypto_GetKeyHandle(OEMCrypto_SESSION session, * buffers in its input_data and output fields, respectively. * * Each sample contains an array of subsample descriptions in its subsamples - * field. Each subsample is defined as a number of clear bytes followed by a - * number of encrypted bytes. Subsamples are consecutive inside the sample; - * the clear bytes of the second subsample begin immediately after the - * encrypted bytes of the first subsample. This follows the definition in the - * ISO-CENC standard. + * field. Each subsample is defined as a number of unprotected bytes followed by + * a number of protected bytes. Subsamples are consecutive inside the sample; + * the unprotected bytes of the second subsample begin immediately after the + * protected bytes of the first subsample. This follows the definition in the + * ISO-CENC standard. The protected bytes are encrypted, and the unprotected + * bytes are not encrypted. * * Decryption mode is AES-128-CTR or AES-128-CBC depending on the value of * cipher_mode previously passed in to OEMCrypto_GetKeyHandle(). For the * encrypted portion of subsamples, the content key associated with the handle * is latched in the active hardware key ladder and is used for the decryption - * operation. For the clear portion of subsamples, the data is simply copied. + * operation. For the unprotected portion of subsamples, the data is simply + * copied. * * After decryption, all the input_data bytes are copied to the location * described by the output field. The output field is an @@ -2103,10 +2105,10 @@ OEMCryptoResult OEMCrypto_GetKeyHandle(OEMCrypto_SESSION session, * data will not be used until after the subsample with the flag * OEMCrypto_LastSubsample has been sent to OEMCrypto. This can be relied on by * OEMCrypto for optimization by not doing decrypt until the last subsample has - * been received. However, a device that can do decrypt of more than one - * subsample at a time will always have better performance if it can receive - * those subsamples in one OEMCrypto_DecryptCENC() call rather than as - * individual subsamples. + * been received. However, a device that can decrypt of more than one subsample + * at a time will always have better performance if it can receive those + * subsamples in one OEMCrypto_DecryptCENC() call rather than as individual + * subsamples. * * Although the exact way that the CDM code breaks up the samples array when * it receives OEMCrypto_ERROR_BUFFER_TOO_LARGE is not guaranteed by this @@ -2146,15 +2148,15 @@ OEMCryptoResult OEMCrypto_GetKeyHandle(OEMCrypto_SESSION session, * 'cenc' SCHEME: * * The 'cenc' scheme is OEMCrypto_CipherMode_CENC without an encryption - * pattern. All the bytes in the encrypted portion of each subsample are + * pattern. All the bytes in the protected portion of each subsample are * encrypted. In the pattern parameter, both the encrypt and skip fields will * be zero. * - * The length of a crypto block in AES-128 is 16 bytes. In the 'cenc' scheme, - * if an encrypted subsample has a length that is not a multiple of 16 bytes, - * then all the bytes of the encrypted subsample must be decrypted, but the - * next encrypted subsample will begin by completing the incomplete crypto - * block from the previous encrypted subsample. The following diagram + * The length of a crypto block in AES-128 is 16 bytes. In the 'cenc' scheme, if + * the protected region of a subsample has a length that is not a multiple of 16 + * bytes, then all the bytes of the protected region must be decrypted, but the + * protected region of next subsample will begin by completing the incomplete + * crypto block from the previous protected region. The following diagram * provides an example: * * ![Drawing of block offset](fig5.svg) @@ -2169,18 +2171,18 @@ OEMCryptoResult OEMCrypto_GetKeyHandle(OEMCrypto_SESSION session, * 'cbcs' SCHEME: * * The 'cbcs' scheme is OEMCrypto_CipherMode_CBCS with an encryption pattern. - * Only some of the bytes in the encrypted portion of each subsample are + * Only some of the bytes in the protected portion of each subsample are * encrypted. In the pattern parameter, the encrypt and skip fields will * usually be non-zero. This mode allows devices to decrypt FMP4 HLS content, * SAMPLE-AES HLS content, as well as content using the DASH 'cbcs' scheme. * * The skip field of OEMCrypto_CENCEncryptPatternDesc may also be zero. If * the skip field is zero, then patterns are not in use and all crypto blocks - * in the encrypted part of the subsample are encrypted. It is not valid for + * in the protected part of the subsample are encrypted. It is not valid for * the encrypt field to be zero. * * The length of a crypto block in AES-128 is 16 bytes. In the 'cbcs' scheme, - * if the encrypted part of a subsample has a length that is not a multiple + * if the protected part of a subsample has a length that is not a multiple * of 16 bytes, then the final bytes that do not make up a full crypto block * are clear and should never be decrypted. The following diagram provides an * example: @@ -2193,9 +2195,10 @@ OEMCryptoResult OEMCrypto_GetKeyHandle(OEMCrypto_SESSION session, * the pattern says to decrypt every protected block, these bytes are clear * and should not be decrypted. * - * Of course, if the encrypted subsample has a length that is a multiple of - * 16 bytes, all the bytes in it are protected, and they may need to be - * decrypted following the pattern. The following diagram provides an example: + * Of course, if the protected region of a subsample has a length that is a + * multiple of 16 bytes, all the bytes in it are protected, and they may need to + * be decrypted following the pattern. The following diagram provides an + * example: * * ![CBCS Scheme - final partial block](fig7.svg) * @@ -2220,7 +2223,7 @@ OEMCryptoResult OEMCrypto_GetKeyHandle(OEMCrypto_SESSION session, * subsample should start with the IV that was passed into * OEMCrypto_DecryptCENC(). * - * To phrase it another way: In 'cenc', the encrypted portions of the + * To phrase it another way: In 'cenc', the protected regions of the * subsamples can be concatenated to form one continuous ciphertext. In * 'cbcs', each encrypted portion of a subsample is a separate ciphertext. * Each separate ciphertext begins with the IV specified in the iv field of @@ -2256,18 +2259,18 @@ OEMCryptoResult OEMCrypto_GetKeyHandle(OEMCrypto_SESSION session, * OEMCrypto cannot assume that the buffers of consecutive samples are * consecutive in memory. * - * A subsample may consist entirely of encrypted bytes or clear bytes. In - * this case, the clear or the encrypted part of the subsample will be zero, - * indicating that no bytes of that kind appear in the subsample. + * A subsample may consist entirely of protected bytes or unprotected bytes. In + * this case, the unprotected or the encrypted part of the subsample will be + * zero, indicating that no bytes of that kind appear in the subsample. * * The ISO-CENC spec implicitly limits both the skip and encrypt values to be * 4 bits, so they are at most 15. * * ![CTR Mode - no skip pattern](fig8.svg) * - * If OEMCrypto assembles all of the encrypted subsample portions into a - * single buffer and then decrypts it in one pass, it can assume that the - * block offset is 0. + * If OEMCrypto assembles the protected regions of all the subsamples into a + * single buffer and then decrypts it in one pass, it can assume that the block + * offset is 0. * * ![CTR Mode - with skip pattern](fig9.svg) *