lightbulb_outline Please take our October 2018 developer survey. Start survey

MediaCodec.CryptoInfo

public static final class MediaCodec.CryptoInfo
extends Object

java.lang.Object
   ↳ android.media.MediaCodec.CryptoInfo


Metadata describing the structure of an encrypted input sample.

A buffer's data is considered to be partitioned into "subSamples". Each subSample starts with a run of plain, unencrypted bytes followed by a run of encrypted bytes. Either of these runs may be empty. If pattern encryption applies, each of the encrypted runs is encrypted only partly, according to a repeating pattern of "encrypt" and "skip" blocks. numBytesOfClearData can be null to indicate that all data is encrypted, and numBytesOfEncryptedData can be null to indicate that all data is clear. At least one of numBytesOfClearData and numBytesOfEncryptedData must be non-null.

This information encapsulates per-sample metadata as outlined in ISO/IEC FDIS 23001-7:2016 "Common encryption in ISO base media file format files".

ISO-CENC Schemes

ISO/IEC FDIS 23001-7:2016 defines four possible schemes by which media may be encrypted, corresponding to each possible combination of an AES mode with the presence or absence of patterned encryption.
  AES-CTR AES-CBC
Without Patterns cenc cbc1
With Patterns cens cbcs
For CryptoInfo, the scheme is selected implicitly by the combination of the mode field and the value set with setPattern(MediaCodec.CryptoInfo.Pattern). For the pattern, setting the pattern to all zeroes (that is, both blocksToEncrypt and blocksToSkip are zero) is interpreted as turning patterns off completely. A scheme that does not use patterns will be selected, either cenc or cbc1. Setting the pattern to any nonzero value will choose one of the pattern-supporting schemes, cens or cbcs. The default pattern if setPattern(MediaCodec.CryptoInfo.Pattern) is never called is all zeroes.

HLS SAMPLE-AES Audio

HLS SAMPLE-AES audio is encrypted in a manner compatible with the cbcs scheme, except that it does not use patterned encryption. However, if setPattern(MediaCodec.CryptoInfo.Pattern) is used to set the pattern to all zeroes, this will be interpreted as selecting the cbc1 scheme. The cbc1 scheme cannot successfully decrypt HLS SAMPLE-AES audio because of differences in how the IVs are handled. For this reason, it is recommended that a pattern of 1 encrypted block and 0 skip blocks be used with HLS SAMPLE-AES audio. This will trigger decryption to use cbcs mode while still decrypting every block.

Summary

Nested classes

class MediaCodec.CryptoInfo.Pattern

Metadata describing an encryption pattern for the protected bytes in a subsample. 

Fields

public byte[] iv

A 16-byte initialization vector

public byte[] key

A 16-byte key id

public int mode

The type of encryption that has been applied, see MediaCodec.CRYPTO_MODE_UNENCRYPTED, MediaCodec.CRYPTO_MODE_AES_CTR and MediaCodec.CRYPTO_MODE_AES_CBC

public int[] numBytesOfClearData

The number of leading unencrypted bytes in each subSample.

public int[] numBytesOfEncryptedData

The number of trailing encrypted bytes in each subSample.

public int numSubSamples

The number of subSamples that make up the buffer's contents.

Public constructors

MediaCodec.CryptoInfo()

Public methods

void set(int newNumSubSamples, int[] newNumBytesOfClearData, int[] newNumBytesOfEncryptedData, byte[] newKey, byte[] newIV, int newMode)

Set the subsample count, clear/encrypted sizes, key, IV and mode fields of a MediaCodec.CryptoInfo instance.

void setPattern(MediaCodec.CryptoInfo.Pattern newPattern)

Set the encryption pattern on a MediaCodec.CryptoInfo instance.

String toString()

Returns a string representation of the object.

Inherited methods

Fields

iv

added in API level 16
public byte[] iv

A 16-byte initialization vector

key

added in API level 16
public byte[] key

A 16-byte key id

mode

added in API level 16
public int mode

The type of encryption that has been applied, see MediaCodec.CRYPTO_MODE_UNENCRYPTED, MediaCodec.CRYPTO_MODE_AES_CTR and MediaCodec.CRYPTO_MODE_AES_CBC

numBytesOfClearData

added in API level 16
public int[] numBytesOfClearData

The number of leading unencrypted bytes in each subSample. If null, all bytes are treated as encrypted and numBytesOfEncryptedData must be specified.

numBytesOfEncryptedData

added in API level 16
public int[] numBytesOfEncryptedData

The number of trailing encrypted bytes in each subSample. If null, all bytes are treated as clear and numBytesOfClearData must be specified.

numSubSamples

added in API level 16
public int numSubSamples

The number of subSamples that make up the buffer's contents.

Public constructors

MediaCodec.CryptoInfo

added in API level 16
public MediaCodec.CryptoInfo ()

Public methods

set

added in API level 16
public void set (int newNumSubSamples, 
                int[] newNumBytesOfClearData, 
                int[] newNumBytesOfEncryptedData, 
                byte[] newKey, 
                byte[] newIV, 
                int newMode)

Set the subsample count, clear/encrypted sizes, key, IV and mode fields of a MediaCodec.CryptoInfo instance.

Parameters
newNumSubSamples int

newNumBytesOfClearData int

This value must never be null.

newNumBytesOfEncryptedData int

This value must never be null.

newKey byte

This value must never be null.

newIV byte

This value must never be null.

newMode int

setPattern

added in API level 24
public void setPattern (MediaCodec.CryptoInfo.Pattern newPattern)

Set the encryption pattern on a MediaCodec.CryptoInfo instance. See MediaCodec.CryptoInfo.Pattern.

Parameters
newPattern MediaCodec.CryptoInfo.Pattern

toString

added in API level 16
public String toString ()

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Returns
String a string representation of the object.