lincardemu - Linux smart card emluator			August, 2004
Copyright (C) 2000-2004 The Linux Card Emulator Team

This software is placed under the GNU General Public License,
read Copyright.txt for more information.

/*
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
    http://www.fsf.org/
*/



1. Running lincardemu and entering commands:
============================================

Before starting lincardemu, the following configuration files should 
be edited to fit personal preferences :

    One of ~/.lincardemurc,  lincardemu.rc or config.dat should exist,
    anc contain:
	  Devicename and speed for the serial port,
	  path data files and log files,  etc.

          Read the comments in the original file.
          At least one of these files  must exist!
	  These files are not changed by lincardemu.

	  With the option "-f [cfg_file]" the specified "[cfg_file]" will 
	  be used as configuration file instead of the above file names.

    lincardemu.dat contains system default settings like above files,
	and should not be modified. Use above configuration file
	for personal settings.

  eckeys.dat :  Eurocrypt station names, idents, and keys,
	        format similar to d2keys.dat from decrypt,
		though not alle commands are implemented.
		Check the comments at the top of the file for more
		information of the syntax.
		This file is updated/written by lincardemu, so
		any extra comments will be removed, except
		comments beginning with "#;" . These comments will
		not appear on the same lines as they were added.
		This file must exist, but may be empty.


  seca.dat           : Seca --"--
  viaccess.dat       : Viaccess --"--
  irdeto.dat         : Irdeto --"--  (also betacrypt and nagra)
  conax.dat          : Conax --"--
  newcamd-client.dat : (optional) for newcamd/radegast cardservers


1.0 Running lincardemu:
-----------------------

To start lincardemu, go to the directory with the data files and enter:

   ./lincardemu  [options]      # linux #


If called from shortcut/icon in desktop (windows, Gnome, KDE,...), 
make sure to set the working directory to the directory containing
the data files.

Tip: use "-c" if lincardemu is compiled with ncurses support, 
see section 1.4.


1.1 Run-time commands:
----------------------

While running lincardemu, following commands (from keyboard)
are available:

        c  : toggle system (eurocrypt, seca,....)
        d  : toggle debug , 4 different values
        z  : toggle serial debug, 4 different values
	x  : extended command, exactly one command line may be entered
        l  : toggle on/off to main log file defined in config.data
        u  : toggle on/off to update log file defined in config.data
        m  : toggle between ECM/ECS2 mode
	n  : read add_XXXkeys.dat files and write updated data to key files,
	     can be used just to write/update *.dat files.
        r  : request for manual reset
        s  : toggle SA-hunt timer   (eurocrypt/viaccess)
        a  : toggle SA-hunt auto incremenent (eurocrypt/viaccess)
        i  : SA-hunt: increase SA (eurocrypt/viaccess)
        1..5 : show different delays
        + -  : increase/decrease last shown delay
        q  / Ctrl-C: stop lincardemu


For Win32:
"q" will stop and save data. ^C will just kill and not save data.
No fancy ncurses og advanced editing during "x" command.

For Linux/UNIX:
Lincardemu stops and closes down (saving data) on following
signals:  SIGHUP, SIGINT (^C), SIGQUIT, SIGTERM.

1.2 Extended command menu:
--------------------------

Pressing "x" gives a special extended-commands menu. Currently this 
only exists for eurocrypt, viaccess, conax, irdeto. 
Entire  command lines may be entered .
Use "x" or "main" to return to the ordinary command menu.


1.2.1 extra menu for Viaccess:
------------------------------
Commands in Viaccess mode:

     [ID.index] hex = x0 x1 x2 x3 x4 x5 x6 x7
     [ID.index] mm2 = key0 key1 key3 key4 key5 key6 key7
        if there is no ID.key_index , current working ID&key is used
     group = nm : set groups to n and m
     iss        : print current issuer ident
     iss  = nn nn nn  : set issuer to ident= nn nn nn
     help / ?   : this text
     show / showkey  : show current keys
     main / x   : back to main menu


1.2.2 Entering Eurocrypt/viaccess keys:
--------------------------------------

This only works when in native Eurocrypt or Viaccess mode.

Hex, mm2 or Nordic4 keys may be entered:

   2cf0.8 hex = 01 02 03 04 05 06 07
   2cf0.9 mm2 = 1100 1201 1302 1403 1504 1605 1706
   nordic4 = 2428 5511 1131 2114 1211 3517  # Only for EuroCrypt !


When entering MM2 or hex codes, if no leading ID and ndex
is entered, the current ID and key index is used:

   mm2 = 1100 1201 1302 1403 1504 1605 1706 # use current ID & index

For tripple-DES double keys, both set be entered with
(assuming current channel is with tripple DES):

   mm2 = 1100 1201 1302 1403 1504 1605 1706 1840 1151 1252 2143 2244 2345 2446

If only one set is entered the other will be zero's.
Entering the leading "ID.index" will allow entering only one set of keys.


1.2.3 extra menu for irdeto
---------------------------
For 6-in-1 etc. the extra menu can select one of betacrypt, irdeto,
viaccess, or seca :
  use: (b)etacrypt, (i)rdeto, (v)iaccess, (s)eca, (a)uto,
          (n)agra, (c)onax   e(x)it

1.2.4 extra menu for conax
---------------------------
For 6-in-1 etc. the extra menu can select one of betacrypt, irdeto,
viaccess, nagravision, or seca :

  use: (c)onax (b)etacrypt, (i)rdeto, (v)iaccess, (s)eca, (n)agra,  
           (w)videoguard, (a)uto   e(x)it
          z XXXXXXXXXXXX

Each selection of "b" toggles between one of 3 betacrypt modes.
Betacrypt modes may be directly selected with "0", "2" and "6"
for betacrypt 1702, 1722 abd 1762.

Each selection of "w" toggles between each videoguard mode. Videoguard
mode isnt able to decrypt. Its used instead for ECM logging.

The "z" extended command allows setting the card address
or part of the card address for the filter function in conax.
The filter function is used to filter out the wanted card addresses.
Some Conax CAM (the old 3.03) and some embedded Conax implementations
may work better with an empty filter or only 2 filters.


1.3 using the command line:
---------------------------

Calling lincardemu with the option "-h" will give following message:

  usage: lincardemu [options] strings ...
     -c   use ncurses
     -o   use stdout
     -wN[slc]* set command window size=N, and optional sequence of windows
     -lN   log card communication (use N=0,1,2,3,6,7,8)
     -h   this help
     -sN  set default system to N (0=eurocrypt, 3=Seca)
     -r   read only, don't write/update to *.dat files!
     -f cfgfile  Use cfgfile instead of ~/.lincardemurc or lincardemu.rc
    strings  sent as commands

Under windows [options] must be placed before the commands in "strings".

Commands may be sent from then command line to perform some initialization,
just add the commands to the main/extended menu:

  lincardemu  -s0 h "xn4=1234 2345 3456 5678 6789 7890" "xhelp" q

  -s0       : select system=eurocrypt
  h         : show main menu commands
  "xn4=..." : add the nordic4 codes and show current key and quit.
  help      : show extended commands
  q         : quit

When adding extended commands from command line, don't use
"main" or "x" to return to main menu, just add a leading "x" .


1.4 Output / using ncurses or stdout
------------------------------------

To have separate windows for debug log and commands, use an extra 
console or xterm.
Setup lincardemu with L command to send debug output "only to log file", 
and use "tail -f filename.log" in the other xterm/console .

If you want to use ncurses (console windows), call with "lincardemu -c", 
thereby dividing the screen in 3 windows:
    log window, status line, and command window.

The size, place and colors may be changed in the configuration file
(for example in lincardemu.rc)
Size of command windows, and then place of the windows may also be
entered at commandline with "-wN[cls]*]", an example:

    lincardemu -w5slc -c 

will set the command windows to 5 lines and place the
windows in the order: status line, log windows, and command window.

1.5 Running more than one lincardemu on different serial ports:
---------------------------------------------------------------
Create different configuration files each with
its own port/unixdev settings.
Also use separate datadir= and logdir= 
for separate copies of data and log files.

Examples:
for lincardemu1.rc:
logdir="data1"
datadir="log1"

for lincardemu2.rc:
logdir="data2"
datadir="log2"

The same data directory may be used if the option "-r" is used
with lincardemu. "-r" disables writing updates to the *.dat files.
(only one instance of lincardemu should write to data files)


2 Updating codes/keys from files:
=================================

While running lincardemu, the "N" command can be used to 
update the existing keys or settings in the key files.

If one or more of "add_eckeys.dat", "add_viaccess.dat", "add_seca.dat" 
or "add_conax.dat" exists, they  will be read and  the corresponding 
updated key files will be saved  with the updated values.

The value of "timecheck" in lincardemu.rc will determine how often
lincardmenu checks for these files.


2.1 Format of key files:
------------------------

The syntax/format of the key files is added at the top of the
file the first time running lincardemu.

These files are automatically saved depending on the value
of "timesave" in lincardemu.rc, and if "-r" is *not* added
to the command line.


2.2 Format of add_*.dat files:
------------------------------

The format of these files is the same as for the correspondig key files.
One difference is that the section name (label name) may be empty,
since the ident is used, actually the name is ignored:

    #update ident 001234:
    []
    ident=001234
    index=2
    hex=01 02 03 04 05 06 07

The same section name may be repeated (in both add_*.dat and in the 
ordinary key files):

    [MyChannel]
    ident=001234
    index=2
    hex=01 02 03 04 05 06 07

    []
    ident=001234
    index=3
    hex=01 02 03 04 05 06 07

    [this text is ignored but key index 2 of 001234 is updated]
    ident=001234
    index=2
    hex=07 06 05 04 03 02 01

After the update files (add_*.dat) have been read they are deleted.


2.3 Special Nordic4 format for eckeys.dat and add_eckeys.dat:
-------------------------------------------------------------

Since the nordic4 format contains both the ident ant key index,
these keys may be added in a special [Nordic4] section after
the ordinary section names have been defined:

   [Nordic4]
   nordic4= 1121 2222 3333 4444 5555 6666    # ident 000080
   nordic4= 1131 2223 3333 4444 5555 6666    # ident 000100 
   nordic4= 1141 2224 3333 4444 5555 6666    # ident 000180

2.4 Special "addfilter" for seca/irdeto/betacrypt/nagra in conax CAM
--------------------------------------------------------------------

In conax.dat for each of irdeto, betacrypt, seca, conax and nagra
filters may be added to match updates .

  addfilter = system xx xx xx ... ; system= [irdeto|beta|nagra|seca|conax]

For irdeto first byte is 02, and the rest from the ident, for
betacrypt first byte is 0a.

example:
  addfilter = beta 0a 22 33
  addfilter = irdeto 02 22 33
  addfilter = nagra 00 00    ; gives all updates

For seca.dat an filter may also be added the syntax is simpler:
 
  addfilter = 00 00 UU UU UU  ; UU UU UU = unique address


2.5 Nagra_rom and emm for updates on Nagra/RSA.
-----------------------------------------------

For irdeto.dat, add one or more sets of:

nagra_rom_emm = xx xx xx xx     ; nagra emm for ROM
nagra_rom = "ROMfilename.bin"   ; nagra ROM file name

These are used for  auto-update on nagravision/RSA.


3 Entering codes and commands from remote control:
==================================================

3.1 Eurocrypt/ec/d2mac:
-----------------------

 In Prebooked-PPV menu the current/last-used-key are shown in mm2 
 and nordic4.  For tripple-des both sets of keys are shown.

 From Secret/New PIN Code menu following commands are available:
	1119: select EC-M (eurocrypt M)
	1xx9: (xx != 11) : select EC-M and force reset
	2229: select EC-S (eurocrypt S)
	2xx9: (xx != 22) : select EC-S and force reset
	3xx9 : Select input mode to mm2
	4xx9 or
	9xx9 : Select input mode to nordic4 (and reset counter)

 When in mm2-mode (the default)  "9" may be substituted with "7" in above.

 In nordic4-mode keys are between 1111 and 8888
 In multimac2-mode keys are of the form ABCN, 
	AB=11..88
	C= 0..3 (or 4..6 for 3DES in ECS)
	N= 0..6 position of key
 In multimac2 illegal values are ignored.
 In nordic4 illegal values are ignored, but enter 9999 to reset counter, 
 before re-entering the nordic4 codes

3.3 Viaccess:
-------------
 From Secret/New PIN Code menu following commands are available:

  99mn : Select group n and m.  (n and m group numbers from 0..8)
        Group 0 is always selected , so 2 different groups may 
	be defined.
	This can be used for receivers that not to well handle
	more than 16 idents per card. Adding a group number to a Ident
	makes it possible to select which groups should be active
	after a card/receiver reset (ATR or off/on).
	Group 0 is always added to the ident list, so at most to 
	two extra groups may be specified.
	Automatically an "Force Reset" is issued after PIN 99xx 
	has been entered.

  9999 : Force reset / ATR
  900N : Remove group N
  910N : Add group N

  Active groups may be seen in decoder/card information menu.
  The Ceilling/Limit field lists the aktive groups.  
  Example:
     "Ceiling: 410"   -> aktive groups 4, 1 and 0.

3.4 Conax (6in1):
-----------------
The OSD menus should be selfexplanatory.
The first 2 are for status, and the third selects 
the system with an one digit code (0-9).

 0: Conax           1: Seca            2: Viaccess        
 3: Nagra           4: Irdero   
 5: Betacrypt_1702  6: Betacrypt_1722  7: Betacrypt_1726 
 8: Auto  (auto may not work well on conax CAM and some embedded Conax)


4.1 hexupd        :
=================
Still very experimental, but with appropriate hexupd.dat file
it can be used to update eeprom hexfiles with the data 
from viaccess.dat
Use "./hexupd -h" for list of commands.

4.2 hexmmn4       :
=================
Command line tool that converts to/from hex, multimax2, nordic4.
Input format is autodetected.

 ./hexmmn4 [ -x | -m ] [ -n | -i | -e] "...data...." 
  -x: hex
  -m: mm2
  -n: nordic4
  -i: print ident/key
  -e: print hex bytes read


Examples:

 ./hexmmn4 -m "01 02 03 04 05 06 07"
 1200 1301 1402 1503 1604 1705 1806

 ./hexmmn4 -x "1200 1301 1402 1503 1604 1705 1806"
 01 02 03 04 05 06 07



5. Automatic updating from web (D2MAC):
=======================================

Now *obsolete*, the update URL's do not exist.

These shell scripts will probably only work for unix/linux.
Gnu awk, bash (shell) and lynx (text-browser) are needed.

Following awk and shell scripts may be used as "skeleton" to 
build own scripts to aid updating keys:

   geronimo.sh   gets new keys from geronimo's and adds the keys
                 by calling lincardmenu 

   mmcodes.sh    gets new keys from geronimo's mmcodes.html and 
                 adds the keys  by calling lincardmenu 

   mmcodes.awk   awk script, may be used to generate an add_eckeys.dat file
		 or a whole new eckeys.dat. 
		 Check the comments at the top of mmcodes.awk.

   geronimo.awk  awk script, may be used to generate an add_eckeys.dat file
                 using the nordic4 codes from geronimo's.
	 	 Check the comments at the top of geronimo.awk.


:----------------------------------------------------------------------:

5.1 Automatic updating from web (softcam.key):
==============================================

This shell script will probably only work for unix/linux.
bash (shell) and lynx (text-browser) are needed.

   softcam2lce.sh -u URL
                 may be used to generate an add_*.dat file(s)
		 Check the comments at the top of mmcodes.awk.

   softcam2lce.sh -f filename
                 as -u option except local file is parsed.

:----------------------------------------------------------------------:

6. Compiling lincardemu:
========================

Linux:  gcc and gnu make is needed (and pthread)
	All linux distributions include the needed tools.
	( look at http://www.linux.org for links )



Win32:  Cygnus GnuC (gcc) with unix utilities (gnu make etc.)
        can be downloaded from mirrors ftp://sunsite.auc.dk/cygnus/ 
	Look at http://www.redhat.com or http://www.cygnus.com for
	full list of mirrors.
	CygWin also includes utilities like gnu tar and gzip.

	Any tekst editor may be used, that is capable of reading 
	UNIX text files	with only LF (not CR LF as in DOS/WINDOZE).
	'ntemacs' might be a good choise:
		ftp://ftp.cs.washington.edu/pub/ntemacs/

	Be aware that the Win32 version will not work well with
	the current serial port access (SerialWin.C) !!!
	The interface to win32 serial port driver must be
	improved. !! ;-(
	Currently it is far to slow for some receivers....

When compiling check the top of the Makefile for instructions.
Usually the following commands may be used:
	make clean
	make dep
	make   (or make static)

"make static" will compile a version with libraries included,
remember to comment USE_READLINE and USE_NCUURSES in "Makefile"
to reduce binary size for floppy version.

For "hexupd" :
	make hexupd

for "hexmmn4" / conversion utility :
	make hexmmn4

6.1 Floppy version
==================

- With a linux bootfloppy system, lincardemu can run on old laptops
  with little RAM and harddisk. Search for LCE disk.

  
:----------------------------------------------------------------------:

7. Running lincardemu from Dreambox/dbox2
=========================================

It is possible to run lincardemu within a Dreambox/dbox2 receiver. This
allows lincardemu to act as an emulator to another receiver without the
need for a PC near either. To compile lincardemu for Dreambox/dbox2,
the tuxbox CDK is needed. The CC and CCXX flags must be changed within
Makefile and nagra-rsa/Makefile to reflect the path and filename for
the powerpc gcc compiler, as lincardemu must be cross compiled in this
case. 

In all features, lincardemu can run as within an i386 PC, with the
exception that the required libraries are present within the 
Dreambox/dbox2 image.

The RS232 serial port on Dreambox receivers is parsed as 
/dev/tts/0, COM1.

The RS232 serial port on dbox2 receivers is parsed as 
/dev/rtscts, COM1.

:----------------------------------------------------------------------:

Some comments/ To Do list:

- The reset detection needs improvement under windows, 
  sometimes it takes several retries before the reset/ATR is processed.
- Reset/ATR detection may be difficult or impossible with
  newer receivers.
- Card-log is not implemented under windows.
- File log's and debug may need some improvement

- card-log short list :
    -lN   log card communication (use N=0,2,3,4,5,6,7,8)
     2: log card std.
    +1: log card (all, card acks.)
    +4: log sync/ATR
    +8: log passively all data in 16 byte packets

Credits:
  John MacDonald for his information on eurocrypt-M/S2/S3.
  Paul Arnold for making Decrypt (for DOS) - well at least for inspiration :)
  William Jansen 

..............

< The Linux Card Emulator Team >



