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