xbmcdrm

Kodi’s DRM class.

Classes

CryptoSession(UUID, cipherAlgorithm, ...)

Kodi's DRM class.
class xbmcdrm.CryptoSession(UUID: str, cipherAlgorithm: str, macAlgorithm: str)[source]

Bases: object

Kodi’s DRM class.

Offers classes and functions that allow a developer to work with DRM-protected contents like Widevine.

This type of functionality is closely related to the type of DRM used and the service to be implemented.

Using the CryptoSession constructor allow you to have access to a DRM session. With a DRM session you can read and write the DRM properties GetPropertyString,`SetPropertyString` and establish session keys with GetKeyRequest and ProvideKeyResponse, or resume previous session keys with RestoreKeys.

When the session keys are established you can use these methods to perform various operations:Encrypt /Decrypt for data encryption / decryption,`Sign` /Verify for make or verify data-signature. Useful for example to implement encrypted communication between a client and the server.

An example where such functionality is useful is the Message Security Layer (MSL) transmission protocol used in some VOD applications. This protocol (or rather framework) is used to increase the level of security in the exchange of messages (such as licences, manifests or other data), which defines a security extension / layer on top of the HTTP protocol.

Constructor for DRM crypto session

Parameters:

  • UUID – string - 16 byte UUID of the DRM system to use

  • cipherAlgorithm – string - Algorithm used for encryption / decryption ciphers

  • macAlgorithm – string - Algorithm used for sign / verify

Raises:

RuntimeException – If the session can not be established

@python_v18 New class added.

Example:

..
uuid_widevine = 'edef8ba9-79d6-4ace-a3c8-27dcd51d21ed'
crypto_session = xbmcdrm.CryptoSession(uuid_widevine, 'AES/CBC/NoPadding', 'HmacSHA256')
..
GetKeyRequest(init: str | bytes | bytearray, mimeType: str, offlineKey: bool, optionalParameters: Dict[str, str]) → bytearray[source]

Generate a key request

Generate a key request, used for request/response exchange between the app and a license server to obtain or release keys used to decrypt encrypted content. After the app has received the key request response from the license server, it should deliver to the response to the DRM instance using the method ProvideKeyResponse, to activate the keys.

Parameters:

  • init – byte - Initialization bytes container-specific data, its meaning is interpreted based on the mime type provided in the mimeType parameter. It could contain, for example, the content ID, key ID or other data required in generating the key request.

  • mimeType – string - Type of media which is exchanged (e.g. “application/xml”, “video/mp4”)

  • offlineKey – bool - Specifies the type of the request. The request may be to acquire keys for Streaming or Offline content

  • optionalParameters – [opt] map - Will be included in the key request message to allow a client application to provide additional message parameters to the server

Returns:

byte - The opaque key request data (challenge) which is send to key server

@python_v18 New function added.

@python_v19 With python 3 the init param must be a bytearray instead of byte.

GetPropertyString(name: str) → str[source]

Request a system specific property value of the DRM system.

Parameters:

Name – string - Name of the property to query

Returns:

Value of the requested property

@python_v18 New function added.

ProvideKeyResponse(response: str | bytes | bytearray) → str[source]

Provide a key response

When a key response is received from the license server, must be sent to the DRM instance by using provideKeyResponse. See also GetKeyRequest.

Parameters:

response – byte - Key data returned from the license server

Returns:

A keySetId if the response is for an offline key requests which can be used later with restoreKeys, else return empty for streaming key requests.

@python_v18 New function added.

@python_v19 With python 3 the response argument must be a bytearray instead of byte.

RemoveKeys() → None[source]

Removes all keys currently loaded in a session.

@python_v18 New function added.

RestoreKeys(keySetId: str) → None[source]

Restores session keys stored during previous ProvideKeyResponse call.

Parameters:

keySetId – string - Identifies the saved key set to restore. This value must never be null.

@python_v18 New function added.

SetPropertyString(name: str, value: str) → None[source]

Set a system specific property value in the DRM system.

Parameters:

  • name – string - Name of the property. This value must never be null.

  • value – string - Value of the property to set. This value must never be null.

@python_v18 New function added.

Decrypt(cipherKeyId: str | bytes | bytearray, input: str | bytes | bytearray, iv: str | bytes | bytearray) → bytearray[source]

Decrypt an encrypted data by using session keys.

Parameters:

  • cipherKeyId – byte - Encryption key id (provided from a service handshake)

  • input – byte - Cipher text to decrypt

  • iv – byte - Initialization vector of cipher text

Returns:

Decrypted input data

@python_v18 New function added.

@python_v19 With python 3 all arguments need to be of type bytearray instead of byte.

Encrypt(cipherKeyId: str | bytes | bytearray, input: str | bytes | bytearray, iv: str | bytes | bytearray) → bytearray[source]

Encrypt data by using session keys.

Parameters:

  • cipherKeyId – byte - Encryption key id (provided from a service handshake)

  • input – byte - Encrypted text

  • iv – byte - Initialization vector of encrypted text

Returns:

byte - Encrypted input data

@python_v18 New function added.

@python_v19 With python 3 all arguments need to be of type bytearray instead of byte.

Sign(macKeyId: str | bytes | bytearray, message: str | bytes | bytearray) → bytearray[source]

Generate a DRM encrypted signature for a text message.

Parameters:

  • macKeyId – byte - HMAC key id (provided from a service handshake)

  • message – byte - Message text on which to base the signature

Returns:

byte - Signature

@python_v18 New function added.

@python_v19 With python 3 all arguments need to be of type bytearray instead of byte.

Verify(macKeyId: str | bytes | bytearray, message: str | bytes | bytearray, signature: str | bytes | bytearray) → bool[source]

Verify the validity of a DRM signature of a text message.

Parameters:

  • macKeyId – byte - HMAC key id (provided from a service handshake)

  • message – byte - Message text on which the signature is based

  • signature – byte - The signature to verify

Returns:

true when the signature is valid

@python_v18 New function added.

@python_v19 With python 3 for all arguments is needed to pass bytearray instead of byte.