Commit | Line | Data |
---|---|---|
c1eaa6c4 MCC |
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 | |
50b215a0 JS |
10 | in accordance to the Linux DVB API. This is a not a documentation for the, |
11 | existing low level CI API. | |
50b215a0 | 12 | |
c1eaa6c4 MCC |
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. | |
50b215a0 | 19 | |
c1eaa6c4 MCC |
20 | ca_zap |
21 | ~~~~~~ | |
50b215a0 | 22 | |
c1eaa6c4 MCC |
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). | |
50b215a0 JS |
28 | |
29 | This application requires the following to function properly as of now. | |
30 | ||
c1eaa6c4 MCC |
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. | |
50b215a0 | 41 | |
c1eaa6c4 MCC |
42 | c) after running a szap, you have to run ca_zap, for the |
43 | descrambler to function, | |
50b215a0 | 44 | |
c1eaa6c4 | 45 | eg: $ ca_zap channels.conf "TMC" |
50b215a0 | 46 | |
c1eaa6c4 MCC |
47 | d) Hopefully enjoy your favourite subscribed channel as you do with |
48 | a FTA card. | |
50b215a0 | 49 | |
c1eaa6c4 | 50 | .. note:: |
50b215a0 | 51 | |
c1eaa6c4 | 52 | Currently ca_zap, and dst_test, both are meant for demonstration |
50b215a0 JS |
53 | purposes only, they can become full fledged applications if necessary. |
54 | ||
55 | ||
c1eaa6c4 MCC |
56 | Cards that fall in this category |
57 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
58 | ||
a33f3224 | 59 | At present the cards that fall in this category are the Twinhan and its |
50b215a0 JS |
60 | clones, these cards are available as VVMER, Tomato, Hercules, Orange and |
61 | so on. | |
62 | ||
c1eaa6c4 MCC |
63 | CI modules that are supported |
64 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
65 | ||
25985edc | 66 | The CI module support is largely dependent upon the firmware on the cards |
50b215a0 JS |
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 | ||
c1eaa6c4 MCC |
77 | The High level CI API |
78 | ~~~~~~~~~~~~~~~~~~~~~ | |
79 | ||
80 | For the programmer | |
81 | ^^^^^^^^^^^^^^^^^^ | |
50b215a0 | 82 | |
50b215a0 JS |
83 | With the High Level CI approach any new card with almost any random |
84 | architecture can be implemented with this style, the definitions | |
2fe0ae78 | 85 | inside the switch statement can be easily adapted for any card, thereby |
50b215a0 JS |
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 | |
4ae0edc2 | 91 | have been made in the API to accommodate this feature. |
50b215a0 JS |
92 | |
93 | ||
c1eaa6c4 MCC |
94 | Why the need for another CI interface? |
95 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
96 | ||
50b215a0 JS |
97 | This is one of the most commonly asked question. Well a nice question. |
98 | Strictly speaking this is not a new interface. | |
99 | ||
c1eaa6c4 | 100 | The CI interface is defined in the DVB API in ca.h as: |
50b215a0 | 101 | |
c1eaa6c4 | 102 | .. code-block:: c |
50b215a0 | 103 | |
c1eaa6c4 MCC |
104 | typedef struct ca_slot_info { |
105 | int num; /* slot number */ | |
50b215a0 | 106 | |
c1eaa6c4 MCC |
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 */ | |
50b215a0 | 113 | |
c1eaa6c4 MCC |
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; | |
50b215a0 JS |
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 | |
4ae0edc2 | 123 | accommodate all other CI based devices, that fall into the other categories. |
50b215a0 JS |
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 | ||
50b215a0 JS |
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 | ||
c1eaa6c4 MCC |
149 | On querying the device, the device yields information thus: |
150 | ||
151 | .. code-block:: none | |
50b215a0 | 152 | |
c1eaa6c4 MCC |
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 | |
50b215a0 | 161 | |
c1eaa6c4 MCC |
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] | |
50b215a0 | 169 | |
c1eaa6c4 MCC |
170 | CA_SEND_MSG |
171 | ---------------------------- | |
172 | Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1] | |
173 | Found CA descriptor @ program level | |
50b215a0 | 174 | |
c1eaa6c4 MCC |
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] | |
50b215a0 JS |
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 | ||
c1eaa6c4 | 186 | .. code-block:: c |
50b215a0 | 187 | |
c1eaa6c4 MCC |
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; | |
50b215a0 JS |
195 | |
196 | ||
197 | The flow of data can be described thus, | |
198 | ||
c1eaa6c4 | 199 | .. code-block:: none |
50b215a0 JS |
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. |