ISMACryp

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. The command line is as follows:

The DRM 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 may be subject to changes in the 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 ISMACrypdocument root. Each element describes all ISMACryp information needed to encrypt a given track.

XML Syntax

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 trackIDkey and salt attributes of the ISMACrypTrackelement 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.