Simplified KabelDeutschland streaming proxy

Review

A few days go i wrote about How to reverse engineer the KabelDeutschland API. Attached to this post there was a PHP script hosted on github to get your own streaming proxy running.

After testing and spreading the word with some people i came to the decision that the procedure was far too complicated. The need of a webserver and the large number of configuration options were unnecessary.

That’s why i build a single binary version, written in go.

Limitation

This tool does not remove the restrictions made by KabelDeutschland. You will need an internet and a TV contract with them. It only give you the ability to use their streams besides the iOS app.

Download

Binaries for all major platforms can be found at the shared folder.

Shared Folder at mega.co.nz (mirror at dropbox)

Select the binary suitable for your machine.

Tested environments

  • Macbook Pro Mid 2012, OSX 10.10.2
  • Synology DS215j (arm)
  • RaspberryPi (arm)
  • Windows XP 32bit

Please drop me a line if it works or not on your system.

Installation

Grab the config.json and edit it with your customer-service-center credentials. You can also change the port if you like.

On windows, double-click the executable file. On Linux/Mac you have to use your terminal, navigate to the folder you downloaded the binary and type the following command.

If you got a permission denied error, you have to set the executable bit for the binary

On all systems you will see the same output if everything went fine.

You will see the list of interfaces, the proxy listens to. All of them are ready to use to serve the channel playlist.

On certain Windows systems, it is not possible to display the interface list. The proxy will work nevertheless. Simply paste your known IP-Adress or one of your loopback addresses.

Installation on a Synology Diskstation

By now the easiest way to install the KabelDeutschland proxy is to download the arm-version of the binary and put it to your home-folder on the diskstation. Put the edited config.json next to it. Now you have to log into your nas  using ssh as your user and run the following command.

This creates a new screen, starts the proxy and immediately detaches the screen. That means the process runs in the background.

In order to be able to use the screen command, your box has to be bootsrapped. You can find the instructions to do this here: Bootrap the DS215j. Installation of screen will be done with this command as root.

You can connect to the proxy using the IP-address of your diskstation. http://[diskstation]:8787.

To stop the process, attach to the screen and press control+c. Attaching works using this command.

Predefined package

Synology has its own package manager and I’ll try to build a repository containing the proxy as a installable package. This will provide a way more easier solution. I will keep you updated.

Usage

Copy one of the links form the terminal output and paste it into your desired media player. It should load the playlist automatically. In VLC it looks like on the screenshot. You can now switch between the channels. The playlist contains links pointing to the proxy. This link handles the license generation, KabelDeutschland used to verify the stream.

How to reverse-engineer the KabelDeutschland tv-streaming API

The main intention

As a paying customer for many years, with both cable-tv and cable-internet, i found it very frustrating to not be able to watch tv on my smartphone or tablet but only on my tv. Back in 2014 my provider KabelDeutschland pulled out an tv-app for iOS that enables exactly this functionality but only for Apple mobile-devices. I always hoped that they would release an Android version shortly after but until today every customer-service-request regarding this topic leads to a “it will be available somewhere in the future” and “we can’t provide it because of some technical difficulties”. As a software developer and hardware engineer i know that this answer is just nonsense. If it runs in iOS there shouldn’t be any problem to get it up and running on Android and even on desktop.

Besides the intention to simply prove, that it is possible to get the streaming working on other devices, i had a more direct need. I bought a whole home-cinema setup including an Epson EH-TW 6100 beamer, an Onkyo Dolby Atmos capable surround-system and an Amazon Fire TV. I was not able to watch TV on this setup, because i had no DVB-C receiver to attach it to the system. But being able to install XBMC/Kodi paired with the IPTV plugin, it would be easy to do so, if there were any streaming sources.

Important Information

You need to have two contracts with KD. One for cable-tv and one for internet over cable. The second one is necessary because the streams are only available inside of their own network.

If you like to go further please be sure to met both dependencies.

Reverse-engineer the API

Final conclusion

I am aware that this part of this article should be at the end but i think some of you are not that interested in the hard details on how to do a man-in-the-middle-attack to uncover the KD API. So i decided to write this first. You can grab the fully functional streaming-proxy script as a repository in my github account: edi-design/kd-streaming-proxy. There is a README on how to get it up and running but i will provide a more detailed version below.

But by now i will continue with the description of the whole information-gathering-process.

Needed hardware and tools

Setup Burp and the iDevice

The first step is to download Burp and start it using the command line. Because Burp is written in Java you need at least the Java Runtime Environment.

Open your preferred console and type the following command to start Burp.

You will the following window. First we need to disable the intercept-function, push the button until it says intercept is of.

Burp Suite - intercept is off

Burp Suite – intercept is off

Next we go to the Options Tab and change the interface from 127.0.0.1:8080 to *:8080. This can be done by clicking the edit-button and select the All interfaces checkbox.

Burp interfaces

Burp interfaces

This is the complete part of configuring Burp. Now we switch over to our iPhone and connect it to the same network the computer running Burp is connected to. The next step is configuring Burp as proxy for this network. Go to Settings -> Wifi -> click on your Network -> HTTP Proxy Manual and add your computers IP-Adress as server.

iPhone proxy configuration

iPhone proxy configuration

Because part of the communication between the app and the KabelDeutschland API is SSL-encrypted, we need to install the Burp-provided SSL certificate. This provides us with the possibility to read the encrypted communication in plain text.

Open Safari on your iPhone and browse to http://burp. Click on CA Certificate. This will download the cert and asks you if you want to install it. Ignore the possible security risk. You can delete it afterwards.

Capturing some data

After the preparation has been finished we can now start the TV-app and collect the data it sends and gets from their backend services.

Burp should now look like this.

Captured data

Captured data

Analyzing the data

Starting to analyze the data by reading every call with its request and response, step by step.

The first call before even asking for credentials goes against an getconfig endpoint. It provides the app with all the necessary information regarding the api.

The response.

In this data we see the JsonGateway, this is the main entry-point. The second relevant information is the initObj. If you take a look at all further calls this object is needed as a mandatory param to identify against their api.

The sign-in

Before we can do any further calls, we need to have a valid session. The app does a SSOSignIn request to gather information about a SiteGuid and a DomainId. Both of these have to be appended to our formerly captured initObj. At this point you need your KD-CSC credentials. These are typically username and password you need to view your contract or invoice. KD use it to determine wether you are a cable customer or not.

The response.

Get the channel-list

Since we now have all the information to query the channel-list endpoint, lets do it. Finding the call inside of the Burp result is easy, search for GetChannelMediaList. Thanks to KD almost all of there methods are self-explanatory.

The list of all possible tv-channel will be returned, including a streaming link. I will only show an excerpt of it, because the whole response is nearly 3000 lines of json. The first element in my case contains all information about Das Erste (ARD).

Watching the stream?

Seeing the output above, it should be very easy to watch the stream. We’ve got an url that looks like a valid stream, but if you click on it, it gives you an access denied.

After some more digging into the log of Burp, i saw that there was another call named GetLicensedLinks, always called after selecting a channel to view. It provides as response the valid streaming link.

This call takes, next to the obvious initObj, two other params, the FileId and the Link. Both can be gathered from the above channel-list call.

Seeing the response, there is our most-wanted information.

You can paste one of the two urls into VLC media player and you will be able to watch the channel.

Conclusion

Because the whole process is a bit tricky and time-consuming, especially if you just want to sit down and watch tv, thats why i provided a little PHP-script at github (https://github.com/edi-design/kd-streaming-proxy). This script will do all of the work for you. You will need a webserver running inside of your home, because of the mandatory KD internet contract. Calling the script without params will provide you with the download of a playlist, containing all of the channels provided. This playlist contains links to the script itself with the channel id as param. Every time it gets called, it generate a new valid licensed link and redirects to it, that enables you to watch the stream.

I hope it is easy enough to set up and handle. As a simple webserver i can recommend the Synology NAS or a raspberry pi.

If you have any questions, feel free to ask.

How to create a vagrant base-box for VirtualBox

Introduction

What is vagrant?

Vagrant is a tool to run and maintain lightweight and flexible development environments. It is often used in software companies to enable all of their developer to work with the same standardized virtual machines that fit to their production environments. If it is configured right, you can simply type vagrant up and you have a running dev environment.

Why do we need a base-box

To be able to work with vagrant as the management system of your development environment there are two parts necessary. One is the environment configuration based on chef or puppet recipes. These recipes will provide a list of packages and set-ups to configure the virtual machine according to their current needs. For example you can install a web-server and MySQL, set up the user accounts and get it up running.

The base-box itself contains only the very rudimentary system. In our example it is a nearly plain Ubuntu Server 14.04. This image will be used to ground all of our development systems. Vagrant boots it up and runs the recipes from chef or puppet to install the needed software.

Create the base-box

Software requirements

To set up a base-box for using with vagrant we at least need vagrant itself and VirtualBox. You can grab all of them by following the next links. As you might see there is also a link to download the actual Ubuntu Server image. This will be needed to install the operating system of your base-box.

I will not write about the installation and configuration of VirtualBox but it should be self-explanatory.

Another way to install vagrant and VirtualBox on Mac OSX is to use homebrew in addition with cask. Brew should be known by every advanced user of OSX and cask is a simple addition to not only install command-line tools but also to handle full GUI software packages. With it you can install software like VirtualBox or IntelliJ Idea for example.

The following command will install our necessary software.

Hardware settings of the virtual machine

My specifications.

Harddisk
  • VDI self growing image (43Gb)
Chipset
  •  PIIX3
RAM
  • 512Mb
 Network
  •  eth0: NAT
  • eth1: Host-only
 Hardware virtualization
  •  VT-x / AMD-V
  • Nested Paging
 Video
  •  12Mb
  • no 2D / 3D acceleration
 Audio
  • none

The following screens will guide you through the set up of the virtual machine.

Installation of the base system

With the Ubuntu Server image mounted to your virtual disc drive, boot up the machine using the start button and press F12 followed by pressing to select the CD as your boot device. The Ubuntu installation wizard will pop up and asks you for your preferred language and keyboard settings. This part can be configured the way you like it. At the point where you will be asked for the partition layout, select use the whole disk  but without the logical volume manager (LVM). This is convenient and fits to all of our needs.

The next step is setting up the primary user account. For vagrant to be able to run, this user has to be vagrant set up with the same as password.

  • username: vagrant
  • password:  vagrant

We will leave the next step with no automatic updates and proceed onto the software selection. The only prerequisite vagrant has for a base-box is the presence of a ssh-server. After selecting the openssh-server press return to continue. It will take a few minutes to complete the package installation and setting up the system.

That’s it. After ejecting the disk image from the virtual cd-drive we can continue with our last step.

Configure the base-system

We already installed the openssh-server during the ubuntu installation wizard but it is not yet configured to be used by vagrant.

Log in into your newly created machine with the credentials we set up earlier.

Ubuntu first login

Ubuntu first login

Vagrant uses an insecure keypair to be able to log in to your machine. To set up this key we have to copy its public part to the virtual machine. First we need to determine the ip-address of the system by running ifconfig.

ifconfig

ifconfig

With this address in mind we can user the following command to add the key to the server.

If this does not work, simply paste the content of the vagrant.pub file into the VMs vagrant users home folder under .ssh/authorized_keys with the following commands.

Paste the content and press ctrl + o  followed by ctrl + x. For openssh to be able to user this key it needs to have a specific combination of access right. Run the following commands to fix them.

The next step is very important because vagrant uses the sudo command to do all its stuff as a privileged user but does not want to type a password every time it uses it. To configure sudo passwordless type sudo visudo and add the following line right behind the privileges of the root user.

And also edit the line about the sudo user group to be able to user it without a password.

Install the guest additions

To get the best out of your virtual machine experience it is recommended to install to VirtualBox guest additions.

Before you can do this, there are a few packages needed to be able to compile the kernel packages.

The next step is to mount the guest additions image to your machine by going to the main menu, select the devices tab and click on Insert Guest Additions CD Image followed by typing into your machines console the next command.

Finally run the script that matches to your selected system architecture. In my case it is a 64bit system so i had to use the following command.

Install puppet or chef

Last but not least we need to install one of the environment configuration management clients. If you prefer chef or puppet is completely up to you. I will use puppet because of some company dependencies.

If everything succeeds we are ready to go.

Packaging the box

This step sounds like one of the hardest but it is very simple because vagrant provides us with all of the needed tools. We only have to type one command and vagrant will provide you with a base-box in the current working directory. The base-box-14.04 is the name of your virtual machine.

Final result.

Download my base-box

If your are interested in using my newly created base-box image, simply download it from the following link.

Sources