Documentation/media/dvb-drivers/ci.rst

   1 Digital TV Conditional Access Interface (CI API)
   2 ================================================
   3
   4
   5 .. note::
   6
   7    This documentation is outdated.
   8
   9 This document describes the usage of the high level CI API as
  10 in accordance to the Linux DVB API. This is a not a documentation for the,
  11 existing low level CI API.
  12
  13 .. note::
  14
  15    For the Twinhan/Twinhan clones, the dst_ca module handles the CI
  16    hardware handling.This module is loaded automatically if a CI
  17    (Common Interface, that holds the CAM (Conditional Access Module)
  18    is detected.
  19
  20 ca_zap
  21 ~~~~~~
  22
  23 An userspace application, like ``ca_zap`` is required to handle encrypted
  24 MPEG-TS streams.
  25
  26 The ``ca_zap`` userland application is in charge of sending the
  27 descrambling related information to the Conditional Access Module (CAM).
  28
  29 This application requires the following to function properly as of now.
  30
  31 a) Tune to a valid channel, with szap.
  32
  33   eg: $ szap -c channels.conf -r "TMC" -x
  34
  35 b) a channels.conf containing a valid PMT PID
  36
  37   eg: TMC:11996:h:0:27500:278:512:650:321
  38
  39   here 278 is a valid PMT PID. the rest of the values are the
  40   same ones that szap uses.
  41
  42 c) after running a szap, you have to run ca_zap, for the
  43    descrambler to function,
  44
  45   eg: $ ca_zap channels.conf "TMC"
  46
  47 d) Hopefully enjoy your favourite subscribed channel as you do with
  48    a FTA card.
  49
  50 .. note::
  51
  52   Currently ca_zap, and dst_test, both are meant for demonstration
  53   purposes only, they can become full fledged applications if necessary.
  54
  55
  56 Cards that fall in this category
  57 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  58
  59 At present the cards that fall in this category are the Twinhan and its
  60 clones, these cards are available as VVMER, Tomato, Hercules, Orange and
  61 so on.
  62
  63 CI modules that are supported
  64 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  65
  66 The CI module support is largely dependent upon the firmware on the cards
  67 Some cards do support almost all of the available CI modules. There is
  68 nothing much that can be done in order to make additional CI modules
  69 working with these cards.
  70
  71 Modules that have been tested by this driver at present are
  72
  73 (1) Irdeto 1 and 2 from SCM
  74 (2) Viaccess from SCM
  75 (3) Dragoncam
  76
  77 The High level CI API
  78 ~~~~~~~~~~~~~~~~~~~~~
  79
  80 For the programmer
  81 ^^^^^^^^^^^^^^^^^^
  82
  83 With the High Level CI approach any new card with almost any random
  84 architecture can be implemented with this style, the definitions
  85 inside the switch statement can be easily adapted for any card, thereby
  86 eliminating the need for any additional ioctls.
  87
  88 The disadvantage is that the driver/hardware has to manage the rest. For
  89 the application programmer it would be as simple as sending/receiving an
  90 array to/from the CI ioctls as defined in the Linux DVB API. No changes
  91 have been made in the API to accommodate this feature.
  92
  93
  94 Why the need for another CI interface?
  95 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  96
  97 This is one of the most commonly asked question. Well a nice question.
  98 Strictly speaking this is not a new interface.
  99
 100 The CI interface is defined in the DVB API in ca.h as:
 101
 102 .. code-block:: c
 103
 104         typedef struct ca_slot_info {
 105                 int num;               /* slot number */
 106
 107                 int type;              /* CA interface this slot supports */
 108         #define CA_CI            1     /* CI high level interface */
 109         #define CA_CI_LINK       2     /* CI link layer level interface */
 110         #define CA_CI_PHYS       4     /* CI physical layer level interface */
 111         #define CA_DESCR         8     /* built-in descrambler */
 112         #define CA_SC          128     /* simple smart card interface */
 113
 114                 unsigned int flags;
 115         #define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */
 116         #define CA_CI_MODULE_READY   2
 117         } ca_slot_info_t;
 118
 119 This CI interface follows the CI high level interface, which is not
 120 implemented by most applications. Hence this area is revisited.
 121
 122 This CI interface is quite different in the case that it tries to
 123 accommodate all other CI based devices, that fall into the other categories.
 124
 125 This means that this CI interface handles the EN50221 style tags in the
 126 Application layer only and no session management is taken care of by the
 127 application. The driver/hardware will take care of all that.
 128
 129 This interface is purely an EN50221 interface exchanging APDU's. This
 130 means that no session management, link layer or a transport layer do
 131 exist in this case in the application to driver communication. It is
 132 as simple as that. The driver/hardware has to take care of that.
 133
 134 With this High Level CI interface, the interface can be defined with the
 135 regular ioctls.
 136
 137 All these ioctls are also valid for the High level CI interface
 138
 139 #define CA_RESET          _IO('o', 128)
 140 #define CA_GET_CAP        _IOR('o', 129, ca_caps_t)
 141 #define CA_GET_SLOT_INFO  _IOR('o', 130, ca_slot_info_t)
 142 #define CA_GET_DESCR_INFO _IOR('o', 131, ca_descr_info_t)
 143 #define CA_GET_MSG        _IOR('o', 132, ca_msg_t)
 144 #define CA_SEND_MSG       _IOW('o', 133, ca_msg_t)
 145 #define CA_SET_DESCR      _IOW('o', 134, ca_descr_t)
 146 #define CA_SET_PID        _IOW('o', 135, ca_pid_t)
 147
 148
 149 On querying the device, the device yields information thus:
 150
 151 .. code-block:: none
 152
 153         CA_GET_SLOT_INFO
 154         ----------------------------
 155         Command = [info]
 156         APP: Number=[1]
 157         APP: Type=[1]
 158         APP: flags=[1]
 159         APP: CI High level interface
 160         APP: CA/CI Module Present
 161
 162         CA_GET_CAP
 163         ----------------------------
 164         Command = [caps]
 165         APP: Slots=[1]
 166         APP: Type=[1]
 167         APP: Descrambler keys=[16]
 168         APP: Type=[1]
 169
 170         CA_SEND_MSG
 171         ----------------------------
 172         Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1]
 173         Found CA descriptor @ program level
 174
 175         (20) ES type=[2] ES pid=[201]  ES length =[0 (0x0)]
 176         (25) ES type=[4] ES pid=[301]  ES length =[0 (0x0)]
 177         ca_message length is 25 (0x19) bytes
 178         EN50221 CA MSG=[ 9f 80 32 19 03 01 2d d1 f0 08 01 09 06 06 04 05 50 ff f1 02 e0 c9 00 00 04 e1 2d 00 00]
 179
 180
 181 Not all ioctl's are implemented in the driver from the API, the other
 182 features of the hardware that cannot be implemented by the API are achieved
 183 using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is
 184 used to exchange the data to maintain compatibility with other hardware.
 185
 186 .. code-block:: c
 187
 188         /* a message to/from a CI-CAM */
 189         typedef struct ca_msg {
 190                 unsigned int index;
 191                 unsigned int type;
 192                 unsigned int length;
 193                 unsigned char msg[256];
 194         } ca_msg_t;
 195
 196
 197 The flow of data can be described thus,
 198
 199 .. code-block:: none
 200
 201         App (User)
 202         -----
 203         parse
 204           |
 205           |
 206           v
 207         en50221 APDU (package)
 208    --------------------------------------
 209    |      |                             | High Level CI driver
 210    |      |                             |
 211    |      v                             |
 212    |    en50221 APDU (unpackage)        |
 213    |      |                             |
 214    |      |                             |
 215    |      v                             |
 216    |    sanity checks                   |
 217    |      |                             |
 218    |      |                             |
 219    |      v                             |
 220    |    do (H/W dep)                    |
 221    --------------------------------------
 222           |    Hardware
 223           |
 224           v
 225
 226
 227
 228
 229 The High Level CI interface uses the EN50221 DVB standard, following a
 230 standard ensures futureproofness.