Common Encryption

MP4Box is able to encrypt and decrypt ISOBMFF files according to CENC specification (ISO/IEC 23001-7:2016), including latest pattern encryption tools introduced in the standard.

In order to encrypt or decrypt an MP4 file, MP4Box will need a side file containing all informations about crypto/DRM system and the informations needed to encrypt a given track, hereafter refered as drm_file. It is an XML file whose syntax is:

XML Syntax

Semantics

  • type : is the protection scheme type used for this MP4 file. The possible values are (full name or 4 char code):
    • ISMA or iAEC: ISMA E&A (ISMACryp) Scheme
    • Adobe or adkm: Adobe Scheme
    • CENC AES-CTR or cenc: CENC Protection Scheme using AES 128-bit keys in Counter Mode (AES-128 CTR),
    • CENC AES-CBC or cbc1: CENC Protection Scheme using AES 128-bit keys in Cipher-block chaining mode (AES-128 CBC),
    • CENC AES-CTR Pattern or cens: CENC Protection Scheme using AES 128-bit keys in Counter Mode (AES-128 CTR) using pattern of unencrypted/encrypted bytes,
    • CENC AES-CBC Pattern or cbcs: CENC Protection Scheme using AES 128-bit keys in Cipher-block chaining mode (AES-128 CBC) using pattern of unencrypted/encrypted bytes,
  • DRMInfo : contains information needed by a Content Protection System to play back the content such as SystemID, the URL of license server(s) or rights issuer(s) used, embedded licenses/rights, embedded keys(s), and/or other protection system specific metadata. Note that it is possible to specify  more than one DRM system, each one correspond to one tag DRMInfo. The following example shows a simple GPAC DRM system info:

    Simple GPAC DRM system info

  • trackID : specifies the track ID to encrypt. This is a mandatory field, not specifing it will result in an error.
  • IsEncrypted : is the flag which indicates the encryption state of the samples in this track
  • IV_size : is the size in bytes of the InitializationVector field. It should be 0 (if track is not encrypted i.e the IsEncrypted flag is 0x0), 8 or 16
  • first_IV : is the first InitializationVector used for this track.
  • selectiveType : specifies how selective encryption is to be used. The possible values are:
    • None : no selective encryption, all samples encrypted (this is the default behavior).
    • Clear: samples are not encrypted but track is signaled as using encryption.
    • RAP : only Random Access Samples (key frames) will be encrypted. If all media samples are RAPs, this defaults to None.
    • Non-RAP : only non-Random Access Samples (non-key frames) will be encrypted. If all media samples are RAPs, this defaults to None.
    • Rand : random selection of samples to encrypt is performed.
    • X : encrypts the first sample every X samples. X must be an integer greater than 2.
    • RandX : encrypts one random samples out of X samples. X must be an integer greater than 2.
  • saiSavedBox : type of the box where we save the CENC sample auxiliary information. The possible values are:
    • uuid_psec : box type ‘uuid’, extend-type = 0xA2394F52-5A9B-4f14-A244-6C427C648DF4, according to The Protected Interoperable File Format (PIFF) specification of Microsoft.
    • senc : box type ‘senc’, according to HbbTV 1.5 and CFF 1.0.5 specifications.
  • keyRoll : key selection policy and key rolling configuration. The possible values are:
    • IDX=N : use only key whose index is N for encrypting this track. By default, the first key is used. (Note: we use the zero-based index)
    • roll=N : Common Encryption allows groups of samples within the track to use different keys. The encryption parameters (i.e KID, initialization vector size and encryption flag) are contained in a ‘SampleGroupDescriptionBox’ and will override the default parameters for this track. If this option is set, each N encrypted samples

    will share the same key supported by the DRM system.

  • key : the AES-128 bit keys to use. The key ID and key value must be specified as an 32 bytes hex string. This is a mandatory field, not specifing it or using an improper length will result in an error. Note that we support the multiple key encryption. Key selection policy and key rolling are determinated by ‘keyRoll’ attribute.
  • skip_byte_block : number of 16-bytes blocks in the clear at the begining of the encryption pattern.
  • crypt_byte_block : number of 16-bytes blocks encrypted at the begining of the encryption pattern.
  • constant_IV_size : size of constant IV used in pattern encryption mode.
  • constant_IV : constant IV used for all samples in cbcs pattern encryption mode. If IV_size is set, constant IV is ignored and each sample has a dedicated IV.
  • Encrypting/Decrypting a MP4 file with GPAC

    The command line is as follows:

    The following example shows an example file drm_file_gpac_clear.xml for encrypting all samples in a track, using only one key, and with GPAC ‘clear’ DRM System:

    drm_file_gpac_clear.xml

    In the above XML, the BS element from NHML syntax is used to describe what needs to be written in the PSSH box. In this example, the PSSH block contains:

    • 128 bit system ID
    • key IDs count (2) on 32 bits
    • two key IDs on 128 bits each
    • 8 byte string prefixed with a length size on 8 bits
    • two keys on 128 bits each

    For more information on what is supported by the BS element, check the NHML documentation.

    Another example drm_file_2_drms.xml shows how to use 2 DRM Systems:

    drm_file_2_drms.xml

    In the above XML, there are 2 PSSH blocks. For a non-GPAC DRM block, the opaque DRM specific data can be generated using the BS syntax or read from a data attribute or from a file indicated in dataFile attribute.

    Another example drm_file_rap.xml shows an advanced case: we will encrypt only the RAP and we use also key rolling policy.

    drm_file_rap.xml

    Adobe’s Protection Scheme Support in MP4Box

    Adobe’s Protection Scheme is now supported in GPAC (dump/encrypt/decrypt) using the base syntax. The below example shows a drm_file using for Adobe cryto:

    drm_file.xml

    In this example, metadata is a string used by the DRM client to retrieve decryption
    key

    Playing an encrypted file with GPAC Player

    GPAC Player can play protected files which use the GPAC SystemID, in which keys are carried in an unencrypted PSSH box  🙂

    If you want to play with the sample decryption module to add your own CENC system, have a look at gpac/modules/ismacryp/isma_ea.c