readme

VDR softcam plugin 0.9.1

Additional files
----------------

All config files are expected to be located in the subdirectory "sc" of VDRs
plugin config directory. The user executing VDR should have write permissions
for this directory, as the plugin will create cache files there.

The keyfile must be named "SoftCam.Key". Any updated keys are saved back to this
file. At this the structure of the file (e.g. comments) is preserved as far as
possible. Updated key are inserted near to the old one (there is a setup option
to selected if the old key is commented out or deleted), while new keys are
inserted close to the top of the file.

For Irdeto, Seca and Viaccess AU 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.

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 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
"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 provider. For advanced Seca2
providers you may need additional table files. At the moment these are
s2_sse.bin, s2_sse_XXXX.bin and s2_cw_XXXX.bin.

For Nagra1 AU you need appropriate binary Rom and Eeprom files. The files have
to 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 "nagra" subdirectory.

For Nagra2 AU some providers need binary Rom and Eeprom files. The files have to
be named "ROMxxx.bin" and "EEPyy_xxx.bin", where xxx is the ROM version (e.g.
102) and yy is the upper part of the provider ID (e.g. 09 for BEV). The files
must contain the joined contents of all Rom/Eeprom pages. The plugin searches
for these files in the "nagra" subdirectory.



External key updates
--------------------

If key updates are available from external sources (e.g. website) only, they may
be feed from a shell script. To enable this, you have to specify the script name
with commandline option "-E". The script will be called at a regular interval
(currently 15 minutes) or whenever a needed key is not available (but not more
often than every 2 minutes). The script has to output the keys to it's stdout in
the same format as for the key file. The script may output several keys in one
call (each key on a seperate line). You can find an example script in the
"examples" subdirectory.



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 copy one or more of the smartcard
systems to the VDR plugin lib directory. 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,0'. Note the quotes and double quotes. The
three numeric values are identical to the -I and -R options (set to 1 to enable)
and -C option (set to 0 for default clock) below.

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.
In some cases it's mandatory to know the exact clock frequency at which your
cardreader runs (e.g. for baudrate calculations). With the option "-C" you can
give a clock frequency (in Hz) which will be used instead of the default
(3571200 Hz) for the next interface e.g. "-C 3579545 -s /dev/ttyS1".

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 are 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. "-t 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.



Summary of commandline options
------------------------------

-B N      --budget=N     forces DVB device N to budget mode (using FFdecsa)
-I        --inverse-cd   use inverse CD detection for the next serial device
-R        --inverse-rst  use inverse RESET for the next serial device
-C FREQ   --clock=FREQ   use FREQ as clock for the card reader on the next
                         serial device (rather than 3.5712 MHz
-s DEV    --serial=DEV   activate Phoenix ISO interface on serial device DEV
                         (default: none)
-d CMD    --dialup=CMD   call CMD to start/stop dialup-network
                         (default: none)
-t SECS   --timeout=SECS shutdown timeout for dialup-network
                         (default: 60 secs)



SVDR interface
--------------

The plugin implements a SVDR interface. Supported commands are:
   RELOAD
     Reload all configuration files (only if the softcam isn't active at the
     moment).
     Return codes: 550 - Softcam active, can't reload files.
                   901 - Reloading files not entirely successfull. Most of the
                         time this will leave you with an unusable softcam.
                   900 - Reload successfull.

   KEY string
     Parse the given string and add the key to the key database (as if it was
     received from EMM stream).
     Return codes: 501 - Syntax error.
                   900 - Key added.
                   901 - Invalid key format or key already known.

   LOG <on|off> module.option[,module.option][,...]
     Enables or disables all given message classes.
     Return codes: 501 - Syntax error or unknown message class.
                   900 - Options set and saved.

   LOGCFG
     Display all available message classes and report their status. This can be
     usefull if you want to provide an external GUI or whatever to handle the
     message classes.
     Return codes: 901 - No message classes available.
                   900 - Message class status (multi line reply).

   LOGFILE <on|off> [filename]
     Enables or disables logging to file and optionaly sets the filename.",
     Return codes: 501 - Syntax error.
                   900 - Logfile option set and saved.