Debian Codegraph @

README

raw
1
2
3 Introduction
4 ============
5
6 libdvbcsa is a free and portable implementation of the DVB Common
7 Scrambling algorithm with decryption and encryption capabilities.
8
9 It comes in two flavors: a classical single packet implementation and
10 a faster parallel bitslice implementation.
11
12
13 Installation
14 ============
15
16 Some configuration options are available to tune performance of the
17 parallel implementation. See INSTALL.
18
19
20 Algorithm overview
21 ==================
22
23 The DVB CSA is composed of a two distinct ciphers which are applied to
24 scrambled content data packets. The block cipher and the stream cipher
25 both use the same 64 bits key. This key is called a control word.
26
27
28 Classical implementation API
29 ============================
30
31 The classical implementation can process a single packet on each
32 function call. It is the slowest implementation and must be used when
33 data packets are not available as a large batch at the same time.
34
35 This implementation average processing bitrate is between 20 Mbits/s
36 and 50 Mbits/s on modern PCs.
37
38 #include <dvbcsa/dvbcsa.h>
39
40 Two functions are available to allocate and free expanded key context:
41
42 struct dvbcsa_key_s * dvbcsa_key_alloc();
43 void dvbcsa_key_free(struct dvbcsa_key_s *key);
44
45 The control word can be changed as needed using this function:
46
47 void dvbcsa_key_set (const dvbcsa_cw_t cw,
48 struct dvbcsa_key_s *key);
49
50 Data encryption and decryption is done with these functions:
51
52 void dvbcsa_decrypt (const struct dvbcsa_key_s *key,
53 unsigned char *data, unsigned int len);
54
55 void dvbcsa_encrypt (const struct dvbcsa_key_s *key,
56 unsigned char *data, unsigned int len);
57
58
59 Parallel implementation API
60 ===========================
61
62 The parallel implementation is faster but data packets need to be
63 batched together.
64
65 This implementation average processing bitrate is between 80 Mbits/s
66 and 200 Mbits/s on modern PCs. Performance heavily depends on bitslice
67 word width used, see install section.
68
69 #include <dvbcsa/dvbcsa.h>
70
71 Two functions are available to allocate and free expanded key context:
72
73 struct dvbcsa_bs_key_s * dvbcsa_bs_key_alloc();
74
75 void dvbcsa_bs_key_free(struct dvbcsa_bs_key_s *key);
76
77 The control word can be changed as needed using this function:
78
79 void dvbcsa_bs_key_set(const dvbcsa_cw_t cw,
80 struct dvbcsa_bs_key_s *key);
81
82 Packet batch must be available as an array of struct dvbcsa_bs_batch_s
83 to invoke encryption or decryption functions.
84
85 struct dvbcsa_bs_batch_s
86 {
87 unsigned char *data; /* pointer to payload */
88 unsigned int len; /* payload bytes lenght */
89 };
90
91 The array must not be greater than the maximum batch size returned by:
92
93 unsigned int dvbcsa_bs_batch_size(void);
94
95 An extra entry with NULL data pointer must be added to terminate the
96 array. Arrays with less entries than the maximum batch size will take
97 the _same_ time to process as a full batch array.
98
99 An additional maximum packet lenght parameter must be provided to the
100 processing functions. Packet greater than this limit will only be
101 partially processed. It must be a multiple of 8. This parameter
102 directly control algorithm cycles count (and processing time) and
103 should be kept as low as possible. When processing Mpeg TS packets,
104 it should be 184.
105
106 Encryption and decryption batch processing functions are:
107
108 void dvbcsa_bs_decrypt(const struct dvbcsa_bs_key_s *key,
109 const struct dvbcsa_bs_batch_s *pcks,
110 unsigned int maxlen);
111
112 void dvbcsa_bs_encrypt(const struct dvbcsa_bs_key_s *key,
113 const struct dvbcsa_bs_batch_s *pcks,
114 unsigned int maxlen);
115
116 Example:
117
118 int i, s = dvbcsa_bs_batch_size();
119 struct dvbcsa_bs_batch_s b[s + 1];
120
121 struct dvbcsa_bs_key_s *key = dvbcsa_bs_key_alloc();
122 unsigned char cw[8] = "testtest";
123
124 dvbcsa_bs_key_set(cw, key);
125
126 for (i = 0; i < s; i++)
127 {
128 b[i].data = ... ;
129 b[i].len = ... ;
130 }
131
132 b[i].data = NULL;
133
134 dvbcsa_bs_encrypt(key, b, 184);
135
136
137 Portability
138 ===========
139
140 This library has been successfully tested on different platforms with
141 32 bits and 64 bits word width, little-endian and big-endian bytes
142 ordering.
143