dvb_si/tables/
cat.rs

1//! Conditional Access Table — ISO/IEC 13818-1 §2.4.4.6.
2//!
3//! Carried on PID 0x0001 with table_id 0x01. Contains a flat
4//! list of CA descriptors (tag 0x09) identifying every CA system
5//! in use plus the EMM PID on which Entitlement Management
6//! Messages for that system are carried.
7//!
8//! A single-section table per CAS standard.
9
10use crate::descriptors::ca::CaDescriptor;
11use crate::descriptors::DescriptorLoop;
12use crate::error::{Error, Result};
13use crate::traits::Table;
14use dvb_common::{Parse, Serialize};
15
16/// CAT table_id (ISO/IEC 13818-1 Table 2-30).
17pub const TABLE_ID: u8 = 0x01;
18/// CAT well-known PID.
19pub const PID: u16 = 0x0001;
20
21const MIN_HEADER_LEN: usize = 3;
22const EXTENSION_HEADER_LEN: usize = 5;
23const CRC_LEN: usize = 4;
24
25/// One CA descriptor entry from the CAT, in owned form so it
26/// outlives the source section bytes.
27#[derive(Debug, Clone, PartialEq, Eq, Default)]
28#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
29pub struct CatCaEntry {
30    /// CA System ID — the CAID. e.g. 0x0500 Viaccess, 0x0650
31    /// Irdeto ORF-ICE, 0x0100 Seca/Mediaguard.
32    pub ca_system_id: u16,
33    /// EMM PID for this CA system.
34    pub ca_pid: u16,
35    /// Optional private data after the standard CA fields.
36    pub private_data: Vec<u8>,
37}
38
39/// Conditional Access Table.
40#[derive(Debug, Clone, Default, PartialEq, Eq)]
41#[cfg_attr(feature = "serde", derive(serde::Serialize))]
42pub struct Cat<'a> {
43    /// 5-bit version_number from the section header.
44    pub version_number: u8,
45    /// current_next_indicator bit.
46    pub current_next_indicator: bool,
47    /// section_number in the sub-table sequence (typically 0 — single-section).
48    pub section_number: u8,
49    /// last_section_number (typically 0).
50    pub last_section_number: u8,
51    /// Descriptor loop (byte 8 → CRC), preserved verbatim. ISO/IEC 13818-1
52    /// §2.4.4.6 permits descriptors other than CA in this loop; keeping the loop
53    /// raw makes parse → serialize identity hold for all of them. Serializes as
54    /// the typed descriptor sequence; `.raw()` yields the wire bytes. Use
55    /// [`Cat::ca_descriptors`] for the typed CA (tag 0x09) view.
56    pub descriptors: DescriptorLoop<'a>,
57}
58
59impl<'a> Cat<'a> {
60    /// Typed view of the CA descriptors (tag 0x09) in the descriptor loop.
61    /// Non-CA descriptors are skipped; a truncated trailing descriptor ends
62    /// the walk.
63    #[must_use]
64    pub fn ca_descriptors(&self) -> Vec<CatCaEntry> {
65        let mut out = Vec::new();
66        let mut pos = 0;
67        while pos + 2 <= self.descriptors.len() {
68            let tag = self.descriptors[pos];
69            let length = self.descriptors[pos + 1] as usize;
70            let end = pos + 2 + length;
71            if end > self.descriptors.len() {
72                break;
73            }
74            if tag == crate::descriptors::ca::TAG {
75                if let Ok(ca) = CaDescriptor::parse(&self.descriptors[pos..end]) {
76                    out.push(CatCaEntry {
77                        ca_system_id: ca.ca_system_id,
78                        ca_pid: ca.ca_pid,
79                        private_data: ca.private_data.to_vec(),
80                    });
81                }
82            }
83            pos = end;
84        }
85        out
86    }
87}
88
89impl<'a> Parse<'a> for Cat<'a> {
90    type Error = Error;
91
92    fn parse(bytes: &'a [u8]) -> Result<Self> {
93        if bytes.len() < MIN_HEADER_LEN + EXTENSION_HEADER_LEN + CRC_LEN {
94            return Err(Error::BufferTooShort {
95                need: MIN_HEADER_LEN + EXTENSION_HEADER_LEN + CRC_LEN,
96                have: bytes.len(),
97                what: "Cat",
98            });
99        }
100
101        if bytes[0] != TABLE_ID {
102            return Err(Error::UnexpectedTableId {
103                table_id: bytes[0],
104                what: "Cat",
105                expected: &[TABLE_ID],
106            });
107        }
108
109        let section_length = (((bytes[1] & 0x0F) as u16) << 8) | bytes[2] as u16;
110        let total = MIN_HEADER_LEN + section_length as usize;
111        if bytes.len() < total {
112            return Err(Error::SectionLengthOverflow {
113                declared: section_length as usize,
114                available: bytes.len() - MIN_HEADER_LEN,
115            });
116        }
117
118        // Skip the 2-byte reserved + extension (bytes 3-4), read version+cni at 5,
119        // section/last_section at 6,7. CAT's "table_id_extension" (bytes 3-4) is
120        // reserved per spec — we don't expose it.
121        let version_number = (bytes[5] >> 1) & 0x1F;
122        let current_next_indicator = (bytes[5] & 0x01) != 0;
123        let section_number = bytes[6];
124        let last_section_number = bytes[7];
125
126        // Descriptor loop runs from byte 8 up to (but not including) the 4-byte
127        // CRC. Kept raw — see the field doc; typed CA view via ca_descriptors().
128        let descriptors_end = total - CRC_LEN;
129
130        Ok(Cat {
131            version_number,
132            current_next_indicator,
133            section_number,
134            last_section_number,
135            descriptors: DescriptorLoop::new(&bytes[8..descriptors_end]),
136        })
137    }
138}
139
140impl Serialize for Cat<'_> {
141    type Error = Error;
142
143    fn serialized_len(&self) -> usize {
144        MIN_HEADER_LEN + EXTENSION_HEADER_LEN + self.descriptors.len() + CRC_LEN
145    }
146
147    fn serialize_into(&self, buf: &mut [u8]) -> Result<usize> {
148        let len = self.serialized_len();
149        if buf.len() < len {
150            return Err(Error::OutputBufferTooSmall {
151                need: len,
152                have: buf.len(),
153            });
154        }
155        let section_length = (len - MIN_HEADER_LEN) as u16;
156        buf[0] = TABLE_ID;
157        buf[1] = 0xB0 | ((section_length >> 8) as u8 & 0x0F);
158        buf[2] = (section_length & 0xFF) as u8;
159        // table_id_extension is reserved for the CAT — conventionally 0xFFFF.
160        buf[3] = 0xFF;
161        buf[4] = 0xFF;
162        buf[5] = 0xC0 | ((self.version_number & 0x1F) << 1) | u8::from(self.current_next_indicator);
163        buf[6] = self.section_number;
164        buf[7] = self.last_section_number;
165        let desc_start = MIN_HEADER_LEN + EXTENSION_HEADER_LEN;
166        buf[desc_start..desc_start + self.descriptors.len()]
167            .copy_from_slice(self.descriptors.raw());
168        let crc_pos = len - CRC_LEN;
169        let crc = dvb_common::crc32_mpeg2::compute(&buf[..crc_pos]);
170        buf[crc_pos..len].copy_from_slice(&crc.to_be_bytes());
171        Ok(len)
172    }
173}
174
175impl<'a> Table<'a> for Cat<'a> {
176    const TABLE_ID: u8 = TABLE_ID;
177    const PID: u16 = PID;
178}
179
180impl<'a> crate::traits::TableDef<'a> for Cat<'a> {
181    const TABLE_ID_RANGES: &'static [(u8, u8)] = &[(TABLE_ID, TABLE_ID)];
182    const NAME: &'static str = "CONDITIONAL_ACCESS";
183}
184
185#[cfg(test)]
186mod tests {
187    use super::*;
188
189    /// Build a CAT section with the given CA descriptors and placeholder CRC.
190    fn build_cat(version: u8, descriptors: &[u8]) -> Vec<u8> {
191        let section_length: u16 =
192            (EXTENSION_HEADER_LEN as u16) + descriptors.len() as u16 + (CRC_LEN as u16);
193        let mut v = Vec::new();
194        v.push(TABLE_ID);
195        v.push(0xB0 | ((section_length >> 8) as u8 & 0x0F));
196        v.push((section_length & 0xFF) as u8);
197        // table_id_extension (reserved for CAT) — typically 0xFFFF in the wild.
198        v.extend_from_slice(&[0xFF, 0xFF]);
199        v.push(0xC0 | ((version & 0x1F) << 1) | 0x01); // version + cni=1
200        v.push(0x00); // section_number
201        v.push(0x00); // last_section_number
202        v.extend_from_slice(descriptors);
203        v.extend_from_slice(&[0, 0, 0, 0]); // placeholder CRC
204        v
205    }
206
207    fn ca_descriptor(ca_system_id: u16, ca_pid: u16) -> [u8; 6] {
208        [
209            0x09,
210            0x04,
211            (ca_system_id >> 8) as u8,
212            (ca_system_id & 0xFF) as u8,
213            0xE0 | ((ca_pid >> 8) as u8 & 0x1F),
214            (ca_pid & 0xFF) as u8,
215        ]
216    }
217
218    #[test]
219    fn parse_empty_cat_zero_descriptors() {
220        let bytes = build_cat(5, &[]);
221        let cat = Cat::parse(&bytes).expect("parse");
222        assert_eq!(cat.version_number, 5);
223        assert!(cat.current_next_indicator);
224        assert!(cat.descriptors.is_empty());
225        assert_eq!(cat.ca_descriptors().len(), 0);
226    }
227
228    #[test]
229    fn parse_single_ca_descriptor_extracts_caid_and_pid() {
230        let mut desc = Vec::new();
231        desc.extend_from_slice(&ca_descriptor(0x0500, 0x0050));
232        let bytes = build_cat(0, &desc);
233        let cat = Cat::parse(&bytes).unwrap();
234        let cas = cat.ca_descriptors();
235        assert_eq!(cas.len(), 1);
236        assert_eq!(cas[0].ca_system_id, 0x0500);
237        assert_eq!(cas[0].ca_pid, 0x0050);
238        assert!(cas[0].private_data.is_empty());
239    }
240
241    #[test]
242    fn parse_multiple_ca_descriptors_preserves_order() {
243        let mut desc = Vec::new();
244        desc.extend_from_slice(&ca_descriptor(0x0500, 0x0050));
245        desc.extend_from_slice(&ca_descriptor(0x0650, 0x0062));
246        desc.extend_from_slice(&ca_descriptor(0x0100, 0x0080));
247        let bytes = build_cat(2, &desc);
248        let cat = Cat::parse(&bytes).unwrap();
249        let cas = cat.ca_descriptors();
250        assert_eq!(cas.len(), 3);
251        assert_eq!(cas[0].ca_system_id, 0x0500);
252        assert_eq!(cas[1].ca_system_id, 0x0650);
253        assert_eq!(cas[2].ca_system_id, 0x0100);
254        assert_eq!(cas[1].ca_pid, 0x0062);
255    }
256
257    #[test]
258    fn parse_rejects_wrong_table_id() {
259        let mut bytes = build_cat(0, &[]);
260        bytes[0] = 0x02; // PMT table_id
261        let err = Cat::parse(&bytes).unwrap_err();
262        assert!(matches!(
263            err,
264            Error::UnexpectedTableId { table_id: 0x02, .. }
265        ));
266    }
267
268    #[test]
269    fn parse_rejects_short_buffer() {
270        let err = Cat::parse(&[0x01, 0x00]).unwrap_err();
271        assert!(matches!(err, Error::BufferTooShort { .. }));
272    }
273
274    /// §2.4.4.6 permits non-CA descriptors in the CAT loop: the typed view
275    /// skips them, but parse → serialize MUST preserve them byte-for-byte.
276    #[test]
277    fn non_ca_descriptors_skipped_by_view_but_round_trip() {
278        let mut desc = Vec::new();
279        desc.extend_from_slice(&ca_descriptor(0x0500, 0x0050));
280        desc.extend_from_slice(&[0x12, 0x02, 0xAA, 0xBB]); // unknown tag 0x12, len 2
281        desc.extend_from_slice(&ca_descriptor(0x0650, 0x0062));
282        let bytes = build_cat(0, &desc);
283        let cat = Cat::parse(&bytes).unwrap();
284        let cas = cat.ca_descriptors();
285        assert_eq!(cas.len(), 2);
286        assert_eq!(cas[0].ca_system_id, 0x0500);
287        assert_eq!(cas[1].ca_system_id, 0x0650);
288        // The unknown descriptor survives the round trip verbatim.
289        assert_eq!(cat.descriptors.raw(), desc);
290        let mut buf = vec![0u8; cat.serialized_len()];
291        cat.serialize_into(&mut buf).unwrap();
292        let re = Cat::parse(&buf).unwrap();
293        assert_eq!(re.descriptors.raw(), desc);
294    }
295
296    #[test]
297    fn serialize_round_trip() {
298        let mut desc = Vec::new();
299        desc.extend_from_slice(&ca_descriptor(0x0500, 0x0050));
300        desc.extend_from_slice(&ca_descriptor(0x0650, 0x0062));
301        let bytes = build_cat(3, &desc);
302        let cat = Cat::parse(&bytes).unwrap();
303        let mut buf = vec![0u8; cat.serialized_len()];
304        cat.serialize_into(&mut buf).unwrap();
305        assert_eq!(Cat::parse(&buf).unwrap(), cat);
306    }
307
308    #[test]
309    fn table_trait_constants() {
310        assert_eq!(<Cat<'_> as Table>::TABLE_ID, 0x01);
311        assert_eq!(<Cat<'_> as Table>::PID, 0x0001);
312    }
313
314    /// CAT now borrows its descriptor loop (3.0): the loop serializes as the
315    /// typed descriptor sequence and the struct is serialize-only (no
316    /// Deserialize). Verify the CA descriptor decodes inside the JSON.
317    #[test]
318    fn serde_json_serializes_typed_loop() {
319        let bytes = build_cat(1, &ca_descriptor(0x0500, 0x0050));
320        let cat = Cat::parse(&bytes).unwrap();
321        let v = serde_json::to_value(&cat).unwrap();
322        let loop_ = v["descriptors"]
323            .as_array()
324            .expect("typed descriptor sequence");
325        assert_eq!(loop_.len(), 1);
326        assert_eq!(loop_[0]["ca"]["ca_system_id"], 0x0500);
327        assert_eq!(loop_[0]["ca"]["ca_pid"], 0x0050);
328    }
329}
dvb_si/tables/cat.rs

dvb_si/tables/
cat.rs
