Basic ClearKey support

[CSilivestru]

Hello!

I was experiencing the similar issues as in #2249

Why am I Submitting this?

After quite a bit of digging, I discovered that the ClearKey ContentProtection information in my manifest was being ignored since they did not have pssh entry. This is not the case with the Shaka player so I am submitting this as a fix. My understanding is that ClearKeys only need the key id specified and the actual key used should simply be provided to the player for use at the time of playback.

What did I do?

In the case of a ClearKey key system, I would still push that as a supported KeySystem. Since, at that time, I do not yet have the actual decryption key, I need to set initData to null so that I can properly set it later with my key. I'm not sure if this is the best way of doing it but it seems to follow the correct event handlers since ClearKey doesn't need to communicate with a CDM

I'm extremely new to everything involved in dash and DRM systems in general so please please let me know if I'm way off base here with my proposed solution.

My Testing

I tested this solution by encrypting a video file with the following very simple crypt.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<GPACDRM type="CENC AES-CTR">
  <CrypTrack IV_size="16" isEncrypted="1" saiSavedBox="senc" trackID="1">
    <key KID="0x02030507011013017019023029031037" value="0x03050701302303204201080425098033"/>
  </CrypTrack>
</GPACDRM>

The command I used was:

mp4box -segment-name oceans_encrypted_%s -profile live -dash-strict 10000 -sample-groups-traf -bs-switching no -out "manifest.mpd" audio_only_encrypted.m4a video_only_encrypted.mp4

This would produce the following manifest (after I switched the generic xmlns to the proper keyids one:

<?xml version="1.0"?>
<!-- MPD file Generated with GPAC version 0.7.2-DEV-revUNKNOWN-master  at 2017-11-01T20:11:12.294Z-->
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500S" type="static" mediaPresentationDuration="PT0H0M46.614S" maxSegmentDuration="PT0H0M13.430S" profiles="urn:mpeg:dash:profile:isoff-live:2011" xmlns:cenc="urn:mpeg:cenc:2013">
 <ProgramInformation moreInformationURL="http://gpac.io">
  <Title>manifest.mpd generated by GPAC</Title>
 </ProgramInformation>

 <Period duration="PT0H0M46.614S">
  <AdaptationSet segmentAlignment="true" lang="und">
   <ContentProtection schemeIdUri="urn:uuid:1077efec-c0b2-4d02-ace3-3c1e52e2fb4b" cenc:default_KID="02030507-0110-1301-7019-023029031037"/>
   <Representation id="1" mimeType="audio/mp4" codecs="mp4a.40.2" startWithSAP="1" bandwidth="97849">
    <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
    <SegmentTemplate media="oceans_encrypted_audio_only_encrypted$Number$.m4s" timescale="48000" startNumber="1" duration="479232" initialization="oceans_encrypted_audio_only_encryptedinit.mp4"/>
   </Representation>
  </AdaptationSet>
  <AdaptationSet segmentAlignment="true" maxWidth="960" maxHeight="400" maxFrameRate="24000/1001" par="960:400" lang="und">
   <ContentProtection schemeIdUri="urn:uuid:1077efec-c0b2-4d02-ace3-3c1e52e2fb4b" cenc:default_KID="02030507-0110-1301-7019-023029031037"/>
   <Representation id="2" mimeType="video/mp4" codecs="avc1.42C01E" width="960" height="400" frameRate="24000/1001" sar="1:1" startWithSAP="1" bandwidth="3866238">
    <SegmentTemplate media="oceans_encrypted_video_only_encrypted$Number$.m4s" timescale="24000" startNumber="1" duration="269019" initialization="oceans_encrypted_video_only_encryptedinit.mp4"/>
   </Representation>
  </AdaptationSet>
 </Period>
</MPD>

After all this, I'm currently using the related video-dash-contrib plugin and initializing it like so:

player.ready(() => {
  player.src({
    src: 'http://localhost:8080/serve/files/manifest.mpd',
    type: 'application/dash+xml',
    keySystemOptions: [
      {
        name: 'org.w3.clearkey',
        options: {
          clearkeys: {
            'AgMFBwEQEwFwGQIwKQMQNw' : 'AwUHATAjAyBCAQgEJQmAMw'
          }
        }
      }
    ]
  });
})

This all works on my current branch when loading all libraries locally. On the development branch, the video buffers forever and no DRM events are logged.

[epiclabsDASH]

Great contribution @CSilivestru. Thanks for the detailed explanation.

[sandersaares]

I am happy to see movement on Clear Key support improvement! As promised over email, I will try to review from a perspective of interoperability.

I would first request that the PR description include some basic guidelines on how this new feature is meant to be used. It is not clear what the new feature even is - is the expectation that by specifying the org.w3.clearkey protection data, clear key is always(?) used? Or as a fallback? What is the PR actually supposed to do? It is difficult to evaluate the correctness of the behavior without this information.

The test content shown in the PR description does not conform to DASH-IF IOP guidelines. Therefore it is difficult to evaluate this PR from an interoperability standpoint. I would recommend using some well-known conforming content to test instead.

On a cursory review, I note at least the following interoperability issues with this test content:

• The mp4protection ContentProtection scheme is not signaled. This is required in all CENC-encrypted DASH content (see IOP 7.7.2).
• There is nothing in the manifest that signals Clear Key use. This is not a problem as such - I would any day support the view that a DRM system does not need to be signaled in the manifest in order to be used - but this would perhaps be an "advanced case". For a basic test content to verify implementation, something more "usual" should be used (see IOP 7.6.2.4).
• The usage of the W3C "Common" PSSH SystemID in the ContentProtection element is suspect, as it does not signal anything more than "this content is encrypted". I would not expect the presence or absence of such a ContentProtection element to have any effect in basic use cases.

I would encourage you to test with already existing content that is known to be conforming to IOP, such as https://github.com/Axinom/dash-test-vectors. This content has the appropriate Clear Key signaling and will likely be far more useful to you as a benchmark than creating custom test content. This content is also in the builtin streams menu of the sample player, located here in the menu:

When I try to play this video as-is from the player in your branch, I do not get any DRM activity and no keys are acquired, so I assume the implementation does not work with this Clear Key content for whatever reason.

When I try to add the org.w3.clearkey protection data element to the video, I see no change in behavior. Perhaps I do not understand how this feature is meant to be used? This is what I wrote in the sources.json file:

        {
          "name": "1080p with W3C Clear Key, single key with W3C protData",
          "url": "https://media.axprod.net/TestVectors/v7-MultiDRM-SingleKey/Manifest_1080p_ClearKey.mpd",
          "moreInfo": "https://github.com/Axinom/dash-test-vectors",
          "protData": {
            "org.w3.clearkey": {
              "clearkeys": {
                "nrQFDeRLSAKTLifXUIPiZg": "FmY0xnWCPCNaSpRG-tUuTQ"
              }
            }
          }
        },

[CSilivestru]

@sandersaares thank you so much for the detailed review and questions! This is great and I really appreciate the time you took to write that all out.

The purpose of this PR is for someone to be able to produce encrypted dash content with a simple key and to provide that key back to the player for decryption. I wanted to avoid the use of an actual CDM or any requests out to a server to fetch the key. My understanding is that ClearKey should be able to be used without the need of a fetch if the key is provided to the player.

The manifest was automatically created by mp4box when I dashed my encrypted content. I only replace the schemeIdUI property after the fact.

You're correct that I did not test this using the vectors provided and I'm sorry about that. I believe that part of the problem here might be how I am actually producing the content using mp4box which is why I detailed my steps.

However, going to the ClearKey vector example you provided, I noticed that the ContentProtection nodes containing the ClearKey KID attribute are using the schemeIdUri of urn:mpeg:dash:mp4protection:2011. This appears to be a generic identifier for encrypted content and looking through the source code here, it's not accounted for in establishing that the encryption system is ClearKey. My understanding is that the correct schemeIdUri should be urn:uuid:1077efec-c0b2-4d02-ace3-3c1e52e2fb4b indicating that the ContentProtection node is in reference to ClearKey for that adaption set. Is this correct?

I did see that there are ContentProtection nodes that reference ClearKey1.0 and specify a server to fetch the key from. This is honestly the first I've seen of that while looking into ClearKey and mpeg-dash in general. Again, my changes are purely to use the key provided that matches up to the keyID in the manifest for that adaption set specified by the correlated ContentProtection node.

I was under the impression that this is technically all I would need (in terms of structure). This plays in Shaka as is currently.

<ContentProtection schemeIdUri="urn:uuid:1077efec-c0b2-4d02-ace3-3c1e52e2fb4b" cenc:default_KID="02030507-0110-1301-7019-023029031037"/>

I am able to play the vector you pointed to on my branch if I simply provide the keys you posted and change the schemeUri to be urn:mpeg:dash:mp4protection:2011:
https://github.com/Dash-Industry-Forum/dash.js/blob/development/src/streaming/protection/drm/KeySystemClearKey.js#L38

It looks like if I do that, then the player properly identifies the key system as ClearKey now and executes the rest of my code that takes that KeyID and uses the supplied key that is provided to the player upon load :).

My main purpose for going down this path was because I produced encrypted dash content with mp4box that played in the shaka player but not in dash.js and I would guess that I'm probably not the only one producing encrypted content in that way.

[sandersaares]

I will try to explain some of the effects you are seeing by describing the general principles and then seeing how they apply here.

The goal of key-related interactions in the player is to activate a CDM (whether Clear Key CDM or some other) that can use content keys to decrypt content.

To activate a CDM, it must be provided initialization data, which is a CDM-specific data structure with freeform contents. A CDM may then request the player to mediate a license request if one is required in order to obtain the keys. Alternatively, a license request may not be necessary (if the keys are already provided in the init data or have been stored previously in another location accessible to the CDM).

The player needs to know what initialization data to provide to a CDM in order to activate it. There are three ways that initialization data can be obtained:

1. The player may synthesize initialization data on the fly.
2. The content author may have embedded initialization data into the content manifest. (Sidenote: it used to be acceptable to embed it into the initialization segments but this approach is deprecated)
3. The app may have configured it in the player's configuration.

Note that there is a possibility that initialization data for the same CDM is available using several of the above approaches. In that case, I would expect more specific data to override any more general data (synthesis is overridden by content is overridden by app configuration).

As browsers can contain any number of CDM implementations, the player needs to make a choice - which one does it use?

The simple answer is: it uses whatever CDM it has initialization data for! I believe most players just pick the first one that matches without much futher thought, although there can definitely be situations where some smart logic is needed.

In the situation of interest for this PR, we can reasonably assume that no other CDM besides Clear Key can be used because the player has no initialization data for them.

Now let's explore how the player should activate the Clear Key CDM.

1. It could synthesize initialization data.
2. It could get the initialization data from the content.
3. It could get the initialization data from the app configuration.

With Clear Key, we also have the additional consideration that EME does not define any required format of initialization data that must be supported by browsers. To support different browsers, the player may need to be able to use different initialization data. In practice, most EME implementations support the "keyids" format.

To ensure interoperability in this regard, DASH-IF IOP requires that the player synthesize the initialization data on the fly, as only this way can be browser-specific init data needs be considered.

But if the player is meant to synthesize the initialization data on its own initiative, how is it to know that it is appropriate to do so? It needs some signal that Clear Key is meant to be used.

For this, DASH-IF IOP specifies a ContentProtection element with the systemID e2719d58-a985-b3c9-781a-b030af78d30e. This element is a signal for the player that it is supposed to activate the Clear Key CDM and synthsize initialization data for it. The element may also provide optional metadata to assist in key acquisition (e.g. license server URL).

Alternatively, the app configuration can always be used to instruct the player on correct behavior, overriding any other inputs. This mechanism should be usable to activate Clear Key even if not specified in the manifest.

Now we know how the CDM should be activated but wait - where do the keys come from? Initialization data does not contain keys, just the key IDs. EME defines a license request protocol for acquiring content keys for use with Clear Key.

When the Clear Key CDM signals a license request, it is the duty of the player to fulfill it. Now, the player could just forward this license request to a license server. For this it needs to know the license server URL (either from the ContentProtection element defined by DASH-IF IOP or the configuration defined by the app).

Alternatively, since Clear Key requires no protection of keys, the player could just synthesize the license response directly. This, of course, assumes the player already knows the content keys - which could just be embedded into the app configuration (as, of course, they do not need to be protected).

And there you go - once the license request gets a response, Clear Key CDM has the keys and will decrypt content. The above workflow is how Clear Key is supposed to work.

Now, I will try to directly address some of the other points you raised above.

The purpose of this PR is for someone to be able to produce encrypted dash content with a simple key and to provide that key back to the player for decryption. I wanted to avoid the use of an actual CDM or any requests out to a server to fetch the key. My understanding is that ClearKey should be able to be used without the need of a fetch if the key is provided to the player.

A worthy goal, indeed, though I would also consider Clear Key an "actual CDM" - there is really not that big of a difference there. I agree with your interpretation about key management - if the player knows the content keys, it can generate the license response without contacting any external service.

However, going to the ClearKey vector example you provided, I noticed that the ContentProtection nodes containing the ClearKey KID attribute are using the schemeIdUri of urn:mpeg:dash:mp4protection:2011. This appears to be a generic identifier for encrypted content and looking through the source code here, it's not accounted for in establishing that the encryption system is ClearKey.

The mp4protection element just means "this content uses Common Encryption and the key ID is written here in the default_KID attribute". It does not participate in CDM selection logic, though it does provide the authoritative key ID that the player should use.

My understanding is that the correct schemeIdUri should be urn:uuid:1077efec-c0b2-4d02-ace3-3c1e52e2fb4b indicating that the ContentProtection node is in reference to ClearKey for that adaption set. Is this correct?

That GUID is the system ID of the W3C Generic PSSH and it should have no relevance on CDM selection. It is basically an equivalent of mp4protection - all it does it say "This content is encrypted using Common Encryption".

I do know that there are players that misinterpret this GUID to mean "the player should select Clear Key" but that is a mistake from a DASH-IF IOP viewpoint. Possibly Shaka Player makes this mistake - I have not checked but from what you say it sounds like it does.

My main purpose for going down this path was because I produced encrypted dash content with mp4box that played in the shaka player but not in dash.js and I would guess that I'm probably not the only one producing encrypted content in that way.

Well, the purpose of DASH-IF IOP is to provide a single interoperable way to do things. Unfortunately, many player/packager/etc manufacturers invent their own ways to do things, which means that we end up in "it works only with X but not Y" situations. The more we follow IOP, the more interoperable we can all be.

Let's consider what the minimum scenario would be to get Clear Key CDM activated and working with some keys:

1. The content just needs to signal CENC support (via mp4protection). That's it - Clear Key needs nothing else from content.
2. The player needs to be configured by the app to activate Clear Key CDM. The player needs to be provided the content keys by the app.

And that's it. If those two things are done, the player should activate the Clear Key CDM, synthesizing it initialization data and generating the license response.

I think ensuring that dash.js can do the second step here would be a good scope/goal for this PR. Not sure how exactly it currently matches. But I would emphasize that the app configuration and data in the manifest are just alternative ways of signaling the CDM activation and should not both be required at the same time.

The alternative approach, without player configuration by the app, would be:

1. Content signals Clear Key activation using the DASH-IF IOP ClearKey ContentProtection element, providing license server URL.
2. Player sees the ContentProtection element, activates Clear Key CDM, synthesizing it initialization data, and forwards the license request to the license server configured in the manifest.

As a third option, the content could signal Clear Key but not the license server URL. The app would then need to specify the license server URL in the player configuration (or just provide the keys inline).

[davemevans]

Correct me if I'm wrong, but wouldn't this be a breaking change for people relying on the existing, non-DASH-IF uuid?

[CSilivestru]

Yes you're correct in this regard.
I believe this is to follow the IOP spec regarding ClearKey which states that the 1077... id shall not be used to indicate ClearKey usage.

I'm not entirely sure what the correct approach is here in terms of what we want to see going forward. Allowing both is technically against the IOP spec but I agree that it may be the correct implementation for this PR.

[sandersaares]

I would perhaps suggest accepting both but emitting a warning in the log about it being IOP-non-conforming content when the W3C Common PSSH systemID is used.

[davemevans]

I think both should be acceptable as Sander suggests, possibly with a warning. Given the existing architecture, this probably requires a new KeySystem implementation so there are two for clearkey - one for DASH-IF, one for W3C. In time the W3C implementation could possibly be deprecated, but I think removal would be inappropriate at this stage.

[CSilivestru]

Again, thank you thank you thank you for your patience in this endeavour. Your explanation packed a lot and was very helpful!

I made a small change in my latest commit to change the uuid in the ClearKey module to match that of the IOP spec you linked to as well as always treating a matched key system as supported if it matched one that is in the list of all supported key systems.

I have also changed my manifest to the following. After your comments and reading the spec, I understand that the ContentProtection node signalled with the urn:mpeg:dash:mp4protection:2011 scheme URI simply means that this adaption set is encrypted using Common Encryption. I would need another ContentProtection node to signal the use of ClearKey and init that CDM.

<?xml version="1.0"?>
<!-- MPD file Generated with GPAC version 0.7.2-DEV-revUNKNOWN-master  at 2017-11-02T18:33:08.056Z-->
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500S" type="static" mediaPresentationDuration="PT0H0M46.277S" maxSegmentDuration="PT0H0M13.680S" profiles="urn:mpeg:dash:profile:isoff-live:2011" xmlns:cenc="urn:mpeg:cenc:2013">
 <ProgramInformation moreInformationURL="http://gpac.io">
  <Title>manifest2.mpd generated by GPAC</Title>
 </ProgramInformation>

 <Period duration="PT0H0M46.277S">
  <AdaptationSet segmentAlignment="true" lang="und">
   <ContentProtection schemeIdUri="urn:mpeg:dash:mp4protection:2011" value="cenc" cenc:default_KID="68a12b5c-7346-6f78-1a0d-b61bfeba1ca7"/>
   <ContentProtection schemeIdUri="urn:uuid:e2719d58-a985-b3c9-781a-b030af78d30e" value="ClearKey1.0"/>
   <Representation id="1" mimeType="audio/mp4" codecs="mp4a.40.2" startWithSAP="1" bandwidth="136204">
    <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
    <SegmentTemplate media="v2_audio_only_encrypted2$Number$.m4s" timescale="44100" startNumber="1" duration="440320" initialization="v2_audio_only_encrypted2init.mp4"/>
   </Representation>
  </AdaptationSet>
  <AdaptationSet segmentAlignment="true" maxWidth="1280" maxHeight="720" maxFrameRate="11988/500" par="16:9" lang="und">
   <ContentProtection schemeIdUri="urn:mpeg:dash:mp4protection:2011" value="cenc" cenc:default_KID="68a12b5c-7346-6f78-1a0d-b61bfeba1ca7"/>
   <ContentProtection schemeIdUri="urn:uuid:e2719d58-a985-b3c9-781a-b030af78d30e" value="ClearKey1.0"/>
   <Representation id="2" mimeType="video/mp4" codecs="avc1.64001F" width="1280" height="720" frameRate="11988/500" sar="1:1" startWithSAP="1" bandwidth="1555150">
    <SegmentTemplate media="v2_video_only_encrypted2$Number$.m4s" timescale="11988" startNumber="1" duration="122625" initialization="v2_video_only_encrypted2init.mp4"/>
   </Representation>
  </AdaptationSet>
 </Period>
</MPD>

This plays as expected on my branch. In addition, the test vector linked earlier for ClearKey encrypted data also plays on my branch.

[CSilivestru]

I modified my changes to add a new KeySystem for support of the W3C Common UUID. Initially I was thinking of adding the barebones to that module and actually using the other ClearKey System for all of the function calls but I opted to do a copy because I thought it might be more readable in the end. I also added the correct protection data to the sources for the single key ClearKey vectors -- I have not tested multiple keys but I'm not entirely sure where to find the decryptions keys for those test streams. I'd be happy to test against those and add them in to complete the ClearKey samples :).

Other than that I tested this branch with a manifest using only the one ContentProtection node per adaption set using the W3C systemID as well as a manifest that follows the IOP spec and both played successfully.

[sandersaares]

I confirm that in my quick testing with your branch the videos I tried seemed to play without issues using clear key.

I'm not entirely sure where to find the decryptions keys for those test streams. I'd be happy to test against those and add them in to complete the ClearKey samples :).

The Axinom test vector keys are listed at https://github.com/axinom/dash-test-vectors, although in a slightly different format so there is some annoying conversion needed to make them the base64url format used by this particular configuration block.

Do I understand it right that this implementation expects the keys to be provided in the configuration block? That is, Clear Key license requests are not implemented - only pre-provided keys? I did not see license requests discussed, so I assume not but thought I would ask just in case (I am not very familiar with the codebase, so I imagine I could easily miss it).

[CSilivestru]

Sounds good I will add in that test data as well then :).

And yes this PR is only focused on providing the keys in the initialization data to the player and does not add support for ClearKey license requests from an external server.

[CSilivestru]

I've added the keys to the protData for the multi-clearkey sources.

The media refuses to play in Chrome for the multi key sources but with debugging it looks like the video codes is not currently supported on those. The multi key audio source does play in Chrome and all but the 1080p multi-key source plays in Firefox.

I'm guessing this would point to a browser support issue and not a clearkey decryption issue?

[sandersaares]

There are known issues with multi-key playback in dash.js (e.g. #2280), so failure to play that content might be normal. I think it is unlikely that this PR has broken any of that, at least.

[CSilivestru]

@sandersaares @epiclabsDASH would this mean that this PR is in a good state to be scheduled for merge and release?

[sandersaares]

I would perhaps also add "See DASH-IF IOP v4.1 section 7.6.2.4" to the emitted warning if non-IOP-conforming content is used, just to make it easier for users to understand why they are being told something is wrong.

Otherwise, LGTM from an interoperability perspective.

[epiclabsDASH]

Small fix. To avoid possible future issues related with variables scope, could you please declare initData using const instead of var?

[epiclabsDASH]

Could you please add unit tests for this class? That helps us a lot to detect possible regression in future releases.

[epiclabsDASH]

I think makes sense declaring a new Constants file, focused on EME stuff, where we declare system strings of the different keySystems so we have just one place to define them all. I am afraid of having these strings (ex: "org.w3.clearkey") in different places.

[epiclabsDASH]

@CSilivestru, in the meantime and given this is your first contribution (fix me if I am wrong but I didn't find you in the list of contributors), could you please sign the Contribution License Agreement and send it to me? You can find it here: http://dashif.org/wp-content/uploads/2015/04/DASH-IF-Feedback-Agreement-3-7-2014.pdf

Many thanks for your contribution

[epiclabsDASH]

Right added a change related with management of key strings constants and a bit of reformat. PR looks good to me. There is some pending work related with ClearKey working with license requests but that can be managed in a different PR.

[epiclabsDASH]

@CSilivestru, PR ready to be merged. I just need you to sign the CLA and send it to me ([email protected]) to proceed. You can find the CLA here: http://dashif.org/wp-content/uploads/2015/04/DASH-IF-Feedback-Agreement-3-7-2014.pdf

Thanks

[CSilivestru]

Looks like everything is ready to go (I rebased to avoid a merge commit in this PR) :)

[epiclabsDASH]

Ooops, seems there is something wrong after the rebase. Some changes has dissapeared (the ones related with KEY constants management) and there are new files added that shouldn't be part of development branch (dist files).

By the way, ClearKey is not working now for sample streams.

[CSilivestru]

Whoa yeah something very wrong happened. Ok I will get this cleared up asap. Sorry about that.

My guess would be the streams are failing due to this as well but I will re-test to make sure.

[epiclabsDASH]

No problem, take your time.

[CSilivestru]

My bad -- force of habit that I pulled down the master branch versus the correct development branch.

I have re-stested the vectors and the ones that worked before are still working now. The multi period test streams don't work but that is due to a video codec problem.