This is a "plugin" for the Video Disk Recorder (VDR).

See the file COPYING for license information.

Description: SoftCAM for Irdeto, Seca, Viaccess, Nagra, Conax & Cryptoworks

-----------------------------------------------------------------------



What is it ?
------------

First: Most certainly it's not legal to use this software in most countries of
the world. But probably you already know this...

SC means softcam, which means a software CAM emulation.

This piece of software is originaly based on (and still contains code from)
mgcam (a standalone CAM emulation). Many thanks to the (anonymous) author for
his really fine piece of software :-)

The plugin only decrypts the scrambling codewords from the incomming ECM
stream. The actual descrambling of the video stream is done by a special chip
on the DVB card. This chip is available with "premium" technotrend chipset
cards like FujitsuSiemens or Hauppauge only. Budget cards like the WinTV Nova
lack the chip. In this case you have to use software decrypt (SoftCSA) which
requires a decent CPU.



Requirements
------------

* DVB driver from dvb-kernel 2.6 or 2.4 branch with applied patches
* a patched firmware version 261f or newer
* VDR 1.3.29 or newer with applied vdr-sc patch
* SoftCSA 0.1.0 or newer for software decryption



How to setup ?
--------------

First you should start with a recent dvb-kernel driver (cvs recomended). Copy
the patched firmware in place and apply at least the dvb-cwidx patch. Make sure
that you use the latest patched firmware. Failing to do so, will break
concurrent feature! Recompile the driver, unload the modules, install the new
ones and reload the DVB driver. If you suffer from ARM crashes, add
"hw_sections=0" while loading the dvb-ttpci module.

Second you should apply the vdr-sc patch to your VDR sources. Select the
appropriate patch for your VDR version. Recomplie VDR and use the new binary.

Now follow the VDR instruction to compile plugins (make plugins). The plugin
has several options which can be enabled at compile time:
  IRDETO=1         to enable Irdeto/Betacrypt support.
  SECA=1           to enable Seca support (needs OpenSSL).
  VIACCESS=1       to enable Viaccess support.
  NAGRA=1          to enable Nagra support (needs OpenSSL)
  CONAX=1          to enable Conax support (needs OpenSSL)
  SHL=1            to enable @SHL (SkyCrypt) support (needs OpenSSL)
  CONSTCW=1        to enable constant CW support
  SC_SECA=1        to enable Seca smartcard support (needs Phoenix ISO
                   interface)
  SC_CRYPTOWORKS=1 to enable Cryptoworks smartcard support (needs Phoenix ISO
                   interface)
  SC_IRDETO=1      to enable Irdeto smartcard support (needs Phoenix ISO
                   interface and OpenSSL)
  SC_CONAX=1       to enable Conax smartcard support (needs Phoenix ISO
                   interface)
  SC_VIACCESS=1    to enable Viaccess smartcard support (needs Phoenix ISO
                   interface)
  CARDCLIENT=1     to enable cardserver clients (needs OpenSSL) (see below)
  DBG=1            to compile with debugging information
For permanent activation add the options to the Make.config file in the VDR base
directory. If OpenSSL is needed, you have to install the openssl-devel package
for most distributions too.

All config files  must be located in a subdirectory (of your VDR config
directory) called "plugins". The private plugin cache file is saved to this
directory too. The keyfile must be named "SoftCam.Key".

For Seca2 support you need binary files which contain the hash & mask tables.
The file format is the same as for Yankse. The files must be located in the
"plugins/seca" subdirectory. The name sheme is s2_TTTT_XXXX.bin where TTTT is
one of "hash","mt" and XXXX is the provider ID (e.g. s2_hash_0064.bin,
s2_mt_0070.bin). The hash file must be 1536 bytes long. The mt file is normaly
16384 bytes long, but this may differ for your actual provider. For advanced
Seca2 providers you may need additional table files. At the moment this are
s2_sse.bin, s2_sse_XXXX.bin and s2_cw_XXXX.bin.

Note, that for this @SHL implementation the key must be in Z 00 00 <key> format
(the V 000000 00 <key> format doesn't work).

For key logger (autoupdate, AU) with Irdeto, Seca and Viaccess you need valid
subscription card data, which have to be located in the files "Ird-Beta.KID",
"Seca.KID" or "Viaccess.KID". See the files in the "examples" subdirectory for
file formats.

To make the Nagra AU work, you must have appropriate binary Rom and Eeprom
files available. The files should be named "ROMX.bin", "ROMXext.bin" or
"eepX_Z.bin" where X is the ROM number (decimal) and Z is the upper part of the
provider ID (hexadecimal). The Eeprom files may be updated from the EMM data,
take care that the permissions are set right. The plugin searches for these
files in the "plugins/nagra" subdirectory.

For testing purpose you should start VDR in foreground always. The plugin gives
a lot of additional information to the console. This may be helpful in case it
doesn't work at once.



VDR CICAM setup:
----------------

The activation of the SC is controlled by your CICAM setup. As general setup
(which is not SC specific) you should leave the CA values (in channels.conf)
set to zero and let VDR's channel scanner (autopid) fill in the correct values.
Don't touch the CA values afterwards.
In the plugin setup menu, you now have to specify for which DVB cards the SC
should be activated. The first two cards can be setup from the menu. If you
need more, you can edit the setup.conf file manualy and add up to 10 cards.



SoftCSA/FFdecsa support:
------------------------

If you want to use the SoftCSA or FFdecsa feature, you have to apply the patch
BEFORE compiling the plugin. When compiling the plugin, the patch will be
detected and the plugin-specific code parts will be activated.



Concurrent Recordings:
----------------------

There are two entries in the plugin setup menu to control concurrent usage of a
DVB card.
"Concurrent streams per FF card" limits the number of concurrent streams on a
full-featured DVB card. Set this to 1 to disable FF concurrency, e.g. when not
using the special firmware.
"Concurrent streams SoftCSA" limits the number of concurrent streams decrypted
in software. This setting is global not on a per card basis. If you allow too
many software decrypted streams you can easily overload your CPU and ruin all
recordings.



Smartcard support:
------------------

For most encrpytion systems this plugin supports original subscription
smartcards on a Phoenix/Smartmouse ISO interface connected to a serial port.

To enable smartcard support you have to select one or more of the smartcard
systems on the make commandline. To actually activate the smartcard interface,
you should use the commandline option "-s" to specify one or more serial
devices to which the Phoenix interface are connected e.g. use "-s /dev/ttyS0 -s
/dev/ttyS1" to use two intefaces at COM1/COM2.
If you want to add a default smartcard interface at compile time use the make
option DEFAULT_PORT, e.g. DEFAULT_PORT='"/dev/ttyS0",0,0'. Note the quotes and
double quotes. The two numeric values are identical to the -I and -R options
below (set to 1 to enable).

Appearently there are "broken" card readers which swap the meaning of the CD
line (used for card detection). For these readers use the option "-I". This
enables inverse CD detection for the next interface e.g. "-I -s /dev/ttyS0 -s
/dev/ttyS1" will use inverse CD on COM1 and normal CD on COM2 while "-I -s
/dev/ttyS0 -I -s /dev/ttyS1" will use inverse CD on both.
Some other card readers have a reversed logic with the reset line (card won't
reset with default settings). You can use the option "-R" for these readers.

Some smartcards need additional information to establish communication with the
card (e.g. certificate or box key for camcrypt). These information must be
available in the "smartcard.conf" file (see example file for format) or you card
won't work correctly.

If you insert a card into a interface the card is autodetected (your interface
should use the CD line to signal card presence or it won't work) and
initialised (this may take some seconds to complete). You can use the setup
menu to see which cards are currently inserted and detected. You can remove a
smartcard at any time without prior action, but of course this will disrupt
decryption if you are tuned to a channel which requires the card.



Cardserver client
-----------------

The cardclient is a client for several cardservers. Supported cardservers are :
radegast, newcamd, camd33 (tcp), camd35 (udp), cardd, buffy and aroureos.

You can configure as many clients for different servers as you want. The client
configuration is read from the file "cardclient.conf". Every line in the file
defines a client-server connection. The line starts with the client name and is
followed by additional arguments which depend on the client type. See the file
"examples/cardclient.conf.example" for format and arguments.

The connections are tried in the order they are defined in the conf file until
a valid decryption is obtained. After that, the decryption sticks to that
particular connection until next channel switch.

The network code supports dialup on demand. To use this you have to provide an
external script to connect/disconnect your dialup link. Use commandline option
-d to set the script name and enable the feature, e.g. "-d dialup.sh". See the
example script "examples/dialup.sh.example". The network is brought up as soon
as an server connection is requested. All server connections will be
disconnected if they are idle too long (normaly after 120 seconds). The network
is brought down after the last connection has terminated and an additional
network timeout has expired. The network timeout is configurable with the
commandline option -t and defaults to 60 seconds, e.g. "-l 120".

The current cardclient implementation is loosely based on the Streamboard
client (contributed by S.Laurel from the Streamboard), which was included in
earlier releases.
