widevine-partner/android
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update docs about subsamples

Browse Source 
We should talk about protected and unprotected regions in a
subsample instead of talking about encrypted and clear subsamples.

Bug: 148230379
Change-Id: Id19e693948cdbd332fa965c9d8775148d10e8368
This commit is contained in:
Fred Gylys-Colwell
2023-11-21 20:58:05 -08:00
committed by Robert Shih
parent adfaf69d1a
commit d867518bea
1 changed files with 36 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h
View File

@@ -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)
*