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