1Digital TV Conditional Access Interface (CI API)
2================================================
3
4
5.. note::
6
7   This documentation is outdated.
8
9This document describes the usage of the high level CI API as
10in accordance to the Linux DVB API. This is a not a documentation for the,
11existing 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
20ca_zap
21~~~~~~
22
23A userspace application, like ``ca_zap`` is required to handle encrypted
24MPEG-TS streams.
25
26The ``ca_zap`` userland application is in charge of sending the
27descrambling related information to the Conditional Access Module (CAM).
28
29This application requires the following to function properly as of now.
30
31a) Tune to a valid channel, with szap.
32
33  eg: $ szap -c channels.conf -r "TMC" -x
34
35b) 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
42c) 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
47d) 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
56Cards that fall in this category
57~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
58
59At present the cards that fall in this category are the Twinhan and its
60clones, these cards are available as VVMER, Tomato, Hercules, Orange and
61so on.
62
63CI modules that are supported
64~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
65
66The CI module support is largely dependent upon the firmware on the cards
67Some cards do support almost all of the available CI modules. There is
68nothing much that can be done in order to make additional CI modules
69working with these cards.
70
71Modules 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
77The High level CI API
78~~~~~~~~~~~~~~~~~~~~~
79
80For the programmer
81^^^^^^^^^^^^^^^^^^
82
83With the High Level CI approach any new card with almost any random
84architecture can be implemented with this style, the definitions
85inside the switch statement can be easily adapted for any card, thereby
86eliminating the need for any additional ioctls.
87
88The disadvantage is that the driver/hardware has to manage the rest. For
89the application programmer it would be as simple as sending/receiving an
90array to/from the CI ioctls as defined in the Linux DVB API. No changes
91have been made in the API to accommodate this feature.
92
93
94Why the need for another CI interface?
95~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
96
97This is one of the most commonly asked question. Well a nice question.
98Strictly speaking this is not a new interface.
99
100The 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
119This CI interface follows the CI high level interface, which is not
120implemented by most applications. Hence this area is revisited.
121
122This CI interface is quite different in the case that it tries to
123accommodate all other CI based devices, that fall into the other categories.
124
125This means that this CI interface handles the EN50221 style tags in the
126Application layer only and no session management is taken care of by the
127application. The driver/hardware will take care of all that.
128
129This interface is purely an EN50221 interface exchanging APDU's. This
130means that no session management, link layer or a transport layer do
131exist in this case in the application to driver communication. It is
132as simple as that. The driver/hardware has to take care of that.
133
134With this High Level CI interface, the interface can be defined with the
135regular ioctls.
136
137All 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
147
148On querying the device, the device yields information thus:
149
150.. code-block:: none
151
152	CA_GET_SLOT_INFO
153	----------------------------
154	Command = [info]
155	APP: Number=[1]
156	APP: Type=[1]
157	APP: flags=[1]
158	APP: CI High level interface
159	APP: CA/CI Module Present
160
161	CA_GET_CAP
162	----------------------------
163	Command = [caps]
164	APP: Slots=[1]
165	APP: Type=[1]
166	APP: Descrambler keys=[16]
167	APP: Type=[1]
168
169	CA_SEND_MSG
170	----------------------------
171	Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1]
172	Found CA descriptor @ program level
173
174	(20) ES type=[2] ES pid=[201]  ES length =[0 (0x0)]
175	(25) ES type=[4] ES pid=[301]  ES length =[0 (0x0)]
176	ca_message length is 25 (0x19) bytes
177	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]
178
179
180Not all ioctl's are implemented in the driver from the API, the other
181features of the hardware that cannot be implemented by the API are achieved
182using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is
183used to exchange the data to maintain compatibility with other hardware.
184
185.. code-block:: c
186
187	/* a message to/from a CI-CAM */
188	typedef struct ca_msg {
189		unsigned int index;
190		unsigned int type;
191		unsigned int length;
192		unsigned char msg[256];
193	} ca_msg_t;
194
195
196The flow of data can be described thus,
197
198.. code-block:: none
199
200	App (User)
201	-----
202	parse
203	  |
204	  |
205	  v
206	en50221 APDU (package)
207   --------------------------------------
208   |	  |				| High Level CI driver
209   |	  |				|
210   |	  v				|
211   |	en50221 APDU (unpackage)	|
212   |	  |				|
213   |	  |				|
214   |	  v				|
215   |	sanity checks			|
216   |	  |				|
217   |	  |				|
218   |	  v				|
219   |	do (H/W dep)			|
220   --------------------------------------
221	  |    Hardware
222	  |
223	  v
224
225
226
227
228The High Level CI interface uses the EN50221 DVB standard, following a
229standard ensures futureproofness.
230