1.. SPDX-License-Identifier: GPL-2.0
2
3Digital TV Conditional Access Interface (CI API)
4================================================
5
6
7.. note::
8
9   This documentation is outdated.
10
11This document describes the usage of the high level CI API as
12in accordance to the Linux DVB API. This is a not a documentation for the,
13existing low level CI API.
14
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.
21
22ca_zap
23~~~~~~
24
25A userspace application, like ``ca_zap`` is required to handle encrypted
26MPEG-TS streams.
27
28The ``ca_zap`` userland application is in charge of sending the
29descrambling related information to the Conditional Access Module (CAM).
30
31This application requires the following to function properly as of now.
32
33a) Tune to a valid channel, with szap.
34
35  eg: $ szap -c channels.conf -r "TMC" -x
36
37b) 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.
43
44c) after running a szap, you have to run ca_zap, for the
45   descrambler to function,
46
47  eg: $ ca_zap channels.conf "TMC"
48
49d) Hopefully enjoy your favourite subscribed channel as you do with
50   a FTA card.
51
52.. note::
53
54  Currently ca_zap, and dst_test, both are meant for demonstration
55  purposes only, they can become full fledged applications if necessary.
56
57
58Cards that fall in this category
59~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
60
61At present the cards that fall in this category are the Twinhan and its
62clones, these cards are available as VVMER, Tomato, Hercules, Orange and
63so on.
64
65CI modules that are supported
66~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
67
68The CI module support is largely dependent upon the firmware on the cards
69Some cards do support almost all of the available CI modules. There is
70nothing much that can be done in order to make additional CI modules
71working with these cards.
72
73Modules 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
79The High level CI API
80~~~~~~~~~~~~~~~~~~~~~
81
82For the programmer
83^^^^^^^^^^^^^^^^^^
84
85With the High Level CI approach any new card with almost any random
86architecture can be implemented with this style, the definitions
87inside the switch statement can be easily adapted for any card, thereby
88eliminating the need for any additional ioctls.
89
90The disadvantage is that the driver/hardware has to manage the rest. For
91the application programmer it would be as simple as sending/receiving an
92array to/from the CI ioctls as defined in the Linux DVB API. No changes
93have been made in the API to accommodate this feature.
94
95
96Why the need for another CI interface?
97~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98
99This is one of the most commonly asked question. Well a nice question.
100Strictly speaking this is not a new interface.
101
102The CI interface is defined in the DVB API in ca.h as:
103
104.. code-block:: c
105
106	typedef struct ca_slot_info {
107		int num;               /* slot number */
108
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 */
115
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;
120
121This CI interface follows the CI high level interface, which is not
122implemented by most applications. Hence this area is revisited.
123
124This CI interface is quite different in the case that it tries to
125accommodate all other CI based devices, that fall into the other categories.
126
127This means that this CI interface handles the EN50221 style tags in the
128Application layer only and no session management is taken care of by the
129application. The driver/hardware will take care of all that.
130
131This interface is purely an EN50221 interface exchanging APDU's. This
132means that no session management, link layer or a transport layer do
133exist in this case in the application to driver communication. It is
134as simple as that. The driver/hardware has to take care of that.
135
136With this High Level CI interface, the interface can be defined with the
137regular ioctls.
138
139All 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)
148
149
150On querying the device, the device yields information thus:
151
152.. code-block:: none
153
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
162
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]
170
171	CA_SEND_MSG
172	----------------------------
173	Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1]
174	Found CA descriptor @ program level
175
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]
180
181
182Not all ioctl's are implemented in the driver from the API, the other
183features of the hardware that cannot be implemented by the API are achieved
184using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is
185used to exchange the data to maintain compatibility with other hardware.
186
187.. code-block:: c
188
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;
196
197
198The flow of data can be described thus,
199
200.. code-block:: none
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
230The High Level CI interface uses the EN50221 DVB standard, following a
231standard ensures futureproofness.
232