New DRM Config property implementation rework

[CastagnaIT]

Description

I remind everyone that the DRM configuration transition is designed to be backward compatible,
with some particular exceptions, specified on "breaking changes" section.

New inputstream.adaptive.drm property

The property has been for now limited to support only a unique DRM configuration.
Support to multiple DRM configurations, will be implemented at later time, with future PR's

Since there is no automatic drm selection yet, it is necessary for now to always add the keysystem with protected streams, even with empty parameters if there is no need to change the default values.

JSON structure example (just a unique key system for now):

{
    "[key system string]": {
        "persistent_storage": bool,
        "secure_decoder_disabled": bool,
        "init_data": str,
        "optional_key_req_params": dict,
        ...
        "license": {
            "server_certificate": str,
            "server_url": str,
            "req_headers": str,
            ...
        }
    }
}

In order not to do double work for the documentation, I will write directly on the wiki integration page the instructions on how to use it

Here is an example of a working STRM to compare the old with the new:

OLD PROPERTIES:

#KODIPROP:mimetype=application/dash+xml
#KODIPROP:inputstream=inputstream.adaptive
#KODIPROP:inputstream.adaptive.license_type=com.widevine.alpha
#KODIPROP:inputstream.adaptive.license_key=https://cwip-shaka-proxy.appspot.com/no_auth||R{SSM}|R
https://bitmovin-a.akamaihd.net/content/art-of-motion_drm/mpds/11331.mpd

NEW DRM PROPERTY:

#KODIPROP:mimetype=application/dash+xml
#KODIPROP:inputstream=inputstream.adaptive
#KODIPROP:inputstream.adaptive.drm={"com.widevine.alpha": {"license": {"server_url": "https://cwip-shaka-proxy.appspot.com/no_auth"}}}
https://bitmovin-a.akamaihd.net/content/art-of-motion_drm/mpds/11331.mpd

ofc python addons can take the advantage to use python dict and use json.dumps to set the "drm" property value

Add XML license wrapper support

License wrapper term i mean the things that are set in to inputstream.adaptive.license_key [Response-Data] field, where we currently support base64 and JSON, wrappers

Since here the code that manage the license wrapper has been reworked (for widevine), add the XML wrapper support its a very small change, so is included here
fix #267

Breaking changes

1. Removed old undocumented specific use case of inputstream.adaptive.license_data to inject PRCustomData to the Playready DRM. This was available only for smoothstreaming manifest Playready protected, this old feature has been never documented, because confusing. Currently im not aware of addons that could use it. This use case will not works anymore from inputstream.adaptive.license_data, but same feature can be used with the new inputstream.adaptive.drm property, with an appropriate configuration (see optional_key_req_params).

2. HLS "renew license url" add-on callbacks, has been removed. This was an old undocumented feature, that seem to allow addons to provide an updated license url for the AES128 encryption. Currently im not aware of addons that could use it, also im not aware of possible HLS use cases that could use it. I am not even aware if this functionality really works since i have no pratical test case. If anyone is using it, please mention, and also link its python implementation. The code was however only commented on, for future removal or reintroduction.

3. On inputstream.adaptive.license_key property in the [Response-Data] field, the HB type has been removed. This because we have no info about this addition, i have not found info on web, nor addon that use it, therefore if in future someone will complain about this removal, we can obtain more info about it to reimplement it.

Other changes, due to cleanups

1) Changes on behaviours to disable the secure decoder. This is currently partially documented on wiki, anyway the change is backward compatible:

Old behaviour: only the Try avoiding the use of secure decoder ISA setting can allow to disable secure decoder, but its applied globally (to all addons), and so each single addon that require decoder must find a way to disable this setting, there are 3 ways:
1] set inputstream.adaptive.license_flags with force_secure_decoder flag
2] if dash, can use a proxy to add a custom ContentProtection tag (hard to do)
3] "brute force" to modify ISA addon setting

New behaviour: You can use Try avoiding the use of secure decoder ISA setting to disable secure decoder, its always applied globally, but now each addon can use following ways to override ISA setting (enable or disable as they wish):
1] with inputstream.adaptive.drm property set to "license" dict, the following item:
"secure_decoder" : [bool] set to True/False the bool value to enable or disable secure decoder
2] for DASH manifest the custom ISA ContentProtection tag:
<widevine:license robustness_level="[value]">
[value] can be: HW_SECURE_CODECS_REQUIRED to enable secure decoder (existing behaviour)
[value] can be: HW_SECURE_CODECS_NOT_ALLOWED to disable secure decoder (new)
3] set inputstream.adaptive.license_flags with force_secure_decoder flag (deprecated, and only to enable it)
4] "brute force" to modify ISA addon setting

2) More easy debug license data with wrappers/unwrappers.
On the license saved files for debug, now there will be saved a new file [UUID].request,
the ".request" file will contain the data already wrapped, ready for the HTTP license server request, while ".response" file will contain the data already unwrapped, ready to be sent to widevine CDM. This makes it easier to see if there is a problem in the wrap or unwrap methods.

3) Initialization PSSH placeholder now available for all systems
With the old inputstream.adaptive.license_key the b{PSSH} and B{PSSH} was available only for android OS, with the new "drm" config that data can be used on all operative systems, by using the new placeholders: {PSSH-B64} {PSSH-B64U}

Motivation and context

This is a first partial implementation of #1415 that concern only the new DRM config, and not the drm auto-selection

this step is a first transition to adapt the existing code to the new drm config,
because there is too much source code that need to be changed,
more likely part of the code implemented here could also be revisited more times with future PR's

How has this been tested?

i tested common widevine, playready, clearkey use cases

not tested:

• wrappers/unwrappers (for provider customized license requests, like am@zon iirc)
• custom init data
• custom license data partially tested
• pre-init data partially tested (miss to test android case)

It would be helpful to have someone who can provide feedback for testing for the more special cases mentioned on the list "not tested"

Screenshots (if appropriate):

Types of change

• Bug fix (non-breaking change which fixes an issue)
• Clean up (non-breaking change which removes non-working, unmaintained functionality)
• Improvement (non-breaking change which improves existing functionality)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that will cause existing functionality to change)
• Cosmetic change (non-breaking change that doesn't touch code)
• None of the above (please explain below)

Checklist:

• I have read the Contributing document
• My code follows the Code Guidelines of this project
• My change requires a change to the Wiki documentation
• I have updated the documentation accordingly

[CastagnaIT]

since this PR is a first big step for Kodi 22,
would be useful to have some feedback for particular use cases like:

• wrappers/unwrappers (for provider customized license requests, like am@zon iirc)
• custom init data (referred to old inputstream.adaptive.license_data)
• custom license data (referred to [Post-Data] field in the old inputstream.adaptive.license_key)
• pre-init data (n@tflix but atm its almost full broken, i will test myself next months if i have chance)

or other special cases that idr

The new inputstream.adaptive.drm property is more cleaner, but also totally different configuration interface,
you can find instructions on how to implement it on this temporary Wiki page:
https://github.com/xbmc/inputstream.adaptive/wiki/Integration-DRM-(NEW)
(that after will replace the current one)

pings some of you if you have a chance to test for regressions
@glennguy @matthuisman @Sandmann79
test builds (link updated): https://jenkins.kodi.tv/blue/organizations/jenkins/xbmc%2Finputstream.adaptive/detail/PR-1672/10/pipeline

surely there are other video addons that make use of particular use cases but idk, feel free to ping other devs if you think it is worthwhile.

@Arias800 if you are still around for your add-on that use XML data on license, i added the xml wrapper support with the new "drm" property, if you can do some tests, open wiki page linked above to get examples for wrappers/unwrappers (should allow you to remove the proxy server)

[matthuisman]

"This DRM has been implemented at later time of Kodi 21 so can be configured only by using the drm_legacy property of the "simple method". This choice was made because the current "advanced method" will in future be deprecated and removed in favour of more advanced functionality. We want to encourage the use of the new methods to limit future changes needed."

Im confused by this.
Its saying use drm_legacy for clearkey and not this new property?
Or has this text not being updated yet?

[CastagnaIT]

@matthuisman you have opened the current (old) wiki page and not the new one,
the current page is not updated, since the PR is not yet merged,
you have to open the wiki link i posted above, the new page dont exists on the wiki menu

[matthuisman]

I went to the new one. It's at the bottom under clear stream

[CastagnaIT]

I went to the new one. It's at the bottom under clear stream

ouch i haven't seen it, yes my mistake i will edit it

[matthuisman]

I assumed it was just artifact from old one :)

…

On Thu, 26 Sept 2024, 18:10 Stefano Gottardo, ***@***.***> wrote: I went to the new one. It's at the bottom under clear stream ouch i haven't seen it, yes my mistake i will edit it — Reply to this email directly, view it on GitHub <#1672 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABPQAKKYBAFHKVIRGYN5SRLZYOQOTAVCNFSM6AAAAABNT4SVSCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGNZWGAZDAMBTHE> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[glennguy]

wow, lots and lots of work!!!!

[CastagnaIT]

first days of next week i will merge
if someone want more time to test and provide a feedback, please leave a message