MP4BOX HELP

A rather complete description of MP4Box functionalities and various switches.

MPEG-4 SYSTEMS

Documentation of GPAC specific handling of MPEG-4 scene description textual formats: BT and XMT-A.

NHNT & NHML

Generic multiplexing languages to manipulate any media format with GPAC and MP4Box.

TIMED TEXT

Description of 3GPP/MPEG-4 Timed Text tracks for subtitles, tickers ...

ISMA E&A - OMA DRM

Encrypting and decrypting content according to ISMA E&A and OMA DRM 2.0 specifications.

Introduction

As of version 0.2.4, GPAC supports the ISMA E&A specification, better known as ISMACryp. This specification provides reliable transmission of encrypted media data with key signaling and cryptographic resynchronization in case of packet loss or random access.

As of version 0.4.4, GPAC supports the OMA DRM PDCF specification available here. This specification is derived from the ISMA E&A specification and OMA DRM PDCF files have a structure almost equivalent to ISMA protected files. GPAC does NOT support the ROAP protocol and other tools from the OMA DRM framework, but has a dedicated module API (still at beta stage) allowing for pluging a decryption agent in the streaming core.

Note that, unlike OMA DRM, ISMACryp does not mandate anything regarding how keys are to be distributed (hereafter refered to as KMS - Key Management System) which is up to the content provider/distributor. In other words, ISMACryp is concerned with cryptographic interoperability only, not rights management.

The current version of the specification uses for encryption the AES 128 bit algorithm in counter mode (AES-CTR). You do not need to know of all these things, the only thing you need to know is that ISMACryp uses a 128 bit key and a 64 bit salt, which would need to be fetched by the client at some point for decryption.
In this document, the key and the salt will simply be refered to as key unless specified otherwise.

One interesting feature of the ISMACryp specification is that it allows for selective encryption, in other words you may decide to encrypt only specific samples in the media track rather than the whole media. Selective encryption will reduce the complexity of the decryption process, and may also be very nice in demonstrations - for example, encrypting only I-frames in a video can give very nice effects ...

If you are familiar with MPEG-4 IPMPX specification, you must be aware that ISMACryp selective encryption is different from IPMP-X one: in ISMACryp, selective encryption means whether or not a sample is encrypted while in IPMP-X selective encryption usually means whether specific bitstream syntax elements (motion vectors, DCT, audio codewords, etc) are encrypted or not.

Another interesting feature of ISMACryp is the possibility to roll keys, eg have more than one key needed for stream decryption. ISMACryp provides for sample-based synchronization of keys and media which is much more reliable than a clock-based synchronization (relying on media/key timestamps). GPAC does not currently support usage of multiple keys in ISMACryp, only one key can be used in the stream lifetime.

Note: Usage of ISMACryp with MPEG-4 AVC/H264 video in GPAC is only supported as of version 0.4.4

ISMACryp authoring

In order to encrypt an MP4 file, MP4Box will need a specific file containing all cryptographic information, usually refered to as drm_file in MP4Box documentation. This file is an XML document containing mainly key information, KMS information, encryption instructions and eventually MPEG-4 IPMP(X) indications. The syntax is very basic and will likelly be subject to many changes in the near future.

Just like any XML file, the file must begin with the usual xml header. The file encoding SHALL BE UTF-8. The file is then a collection of ISMACrypTrack elements placed at under an ISMACryp document root. Each element describes all ISMACryp information needed to encrypt a given track.

XML Syntax

<ISMACryp>

<ISMACrypTrack trackID="..." key="..." salt="..." scheme_URI="..." kms_URI="..." selectiveType="..." ipmpType="..." ipmpDescriptorID="..." />

</ISMACryp>

Semantics

• trackID : specifies the track ID to encrypt. This is a mandatory field, not specifing it will result in an error.
• key : the AES-128 bit key to use. The key must be specified as an 32 bytes hex string, like 0x2b7e151628aed2a6abf7158809cf4f3c. This is a mandatory field, not specifing it or using an improper length will result in an error.
• salt : the 64 bit salt key to use for the counter mode. The salting key must be specified as an 16 bytes hex string, like 0xf8f9fafbfcfdfeff. This is a mandatory field, not specifing it or using an improper length will result in an error.
• scheme_URI : the URI of the scheme used for protection (for example the cryptographic tool provider). The default value is urn:gpac:isma:encryption_scheme. This URI is added to the track meta-data.
• kms_URI : the URI of the key management system. This is the URI to which an ISMACryp client will request the keys. This URI is added to the track meta-data. Apart from regular URLs and URIs, two specific values are interpreted by GPAC:
  • self : the keys will be written in the media track meta-data using base64 encoding. This is mainly useful for testing :)
  • file : the URI will be set to this drm_file name as given to MP4Box - in other words, if you indicate a relative path for the drm_file, then the relative path will be used for the KMS URI.
• 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).
  • 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.
• ipmpType : specifies what kind of MPEG-4 IPMP signaling must be used for this media. The possible values are:
  • None : no MPEG-4 IPMP signaling.
  • IPMP : use MPEG-4 IPMP (the hooks) signaling.
  • IPMPX : use MPEG-4 IPMP-X (ISO-IEC 14496-13 signaling.
• ipmpDescriptorID : specifies the IPMP(X) descriptor ID for this media. If not set, defaults to the media track 1-based index. Ignored when IPMP(X) signaling is not used.

Decrypting a file with GPAC

MP4Box/GPAC players will attempt to load the keys from a KMS URI as follows:

• if kms_URI begins with (key), the keys are Base64 encoded in the track and can be fetched. This corresponds to the case of special value kms_URI="self" when encrypting.
• if the scheme URI is GPAC default one (urn:gpac:isma:encryption_scheme) and the kms_URI points to a file (ONLY LOCAL FILES FOR MP4BOX), the key and salt will be fetched from this file. This corresponds to the case of special value kms_URI="file" when encrypting. In this case only the trackID, key and salt attributes of the ISMACrypTrack element are needed.
• if kms_URI is AudioKey or VideoKey, KMS is assumed to be MPEG4IP one and the file ~/.kms_data is checked (cf MPEG4IP documentation).

In all other cases:

• For MP4Box: You will need to provide a drm_file for decryption (eg, MP4Box -decrypt drm_file myfile.mp4).
• For GPAC client: key fetching will fail and the stream will be decoded WITHOUT being decrypted.

OMA DRM authoring

In order to encrypt a 3GP/MP4 file into a PDCF file, MP4Box uses the same process as ISMA encryption, only the drm file syntax changes.

Just like any XML file, the file must begin with the usual xml header. The file encoding SHALL BE UTF-8. The file is then a collection of OMATrack elements placed under an OMADRM document root (currently ignored). Each element describes all OMA DRM information needed to encrypt a given track. An OMATrack element may have children describing the optional textual headers defined in OMA DRM 2.0. Each textual header is inserted as is during OMA encryption, so be carefull not to specify twice the same header. More information on textual headers can be found in the OMA (P)DCF specification.

XML Syntax

<OMADRM>

<OMATrack trackID="..." key="..." selectiveType="..." rightsIssuerURL="..." contentID="..." transactionID="..." >

<OMATextHeader>textual header</OMATextHeader>

</OMATrack>

</OMADRM>

Semantics

• trackID : specifies the track ID to encrypt. This is a mandatory field, not specifing it will result in an error.
• key : the AES-128 bit key to use. The key must be specified as an 32 bytes hex string, like 0x2b7e151628aed2a6abf7158809cf4f3c. This is a mandatory field, not specifing it or using an improper length will result in an error.
• rightsIssuerURL : the URL of the OMA DRM licence server. This is the URL to which an OMA client will request the keys using the ROAP protocol.
• contentID : a string identifier for the content, passed during ROAP exchanges.
• transactionID : a string identifier for the transaction, passed during ROAP exchanges.
• 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).
  • 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.

Sample GPAC drm files

The following example shows how to encrypt a file with one track, using selective encryption of RAP samples, embedded keys and no IPMP signaling.

<?xml version="1.0" encoding="UTF-8" >

<ISMACryp>

<ISMACrypTrack trackID="1" key="0x2b7e151628aed2a6abf7158809cf4f3c" salt="0xf8f9fafbfcfdfeff" selectiveType="RAP" KMS_URI="self"/>

</ISMACryp>

The following example shows how to encrypt a file with one track, using random encryption over 30 samples, using the source file as KMS URI and IPMP-X signaling.

<?xml version="1.0" encoding="UTF-8" >

<ISMACryp>

<ISMACrypTrack trackID="1" key="0x2b7e151628aed2a6abf7158809cf4f3c" salt="0xf8f9fafbfcfdfeff" selectiveType="Rand30" KMS_URI="file" ipmpType="IPMPX" ipmpDescriptorID="20" />

</ISMACryp>

The following example shows how to encrypt a file with one track, without slective encryption, a KMS URI and no IPMP signaling.

<?xml version="1.0" encoding="UTF-8" >

<ISMACryp>

<ISMACrypTrack trackID="1" key="0x2b7e151628aed2a6abf7158809cf4f3c" salt="0xf8f9fafbfcfdfeff" selectiveType="None" KMS_URI="https://gpac.sourceforge.net/kms/file.xml" />

</ISMACryp>

The following example shows how to encrypt a file with one track, without slective encryption, using OMA DRM.

<?xml version="1.0" encoding="UTF-8" >

<OMADRM>

<OMATrack trackID="1" key="0x2b7e151628aed2a6abf7158809cf4f3c" selectiveType="None" rightsIssuerURL="https://gpac.sourceforge.net/kms" contentID="WatchMe1984" transactionID="14fd12zd3q" >

<OMATextHeader>Preview=instant;http://other.content.com/sonaive</OMATextHeader>

</OMATrack>

</OMADRM>