dvb_csa/lib.rs
1//! DVB Common Scrambling Algorithm (CSA2) — the cipher underneath conditional
2//! access on DVB-S, DVB-T, and DVB-C.
3//!
4//! # Status: reverse-engineered, not spec-cited
5//!
6//! **DVB-CSA has no public normative specification.** The algorithm was
7//! confidential and licensed through the ETSI custodian; every open
8//! implementation is reverse-engineered. This crate therefore cannot follow
9//! the workspace's usual cite-the-spec-clause discipline. Correctness is
10//! established by agreement with **independent implementations** instead of
11//! a standard reference:
12//!
13//! - **libdvbcsa** 1.1.0 — VideoLAN's reference free implementation.
14//! Committed known-answer vectors: encrypt with libdvbcsa, require
15//! byte-identical output from this crate (and the reverse).
16//! - **TSDuck** 3.44 — a DVB test tool. Committed scrambled TS fixture:
17//! scramble an FTA capture with an invented control word using TSDuck,
18//! descramble with this crate, require byte-identical recovery.
19//!
20//! A round-trip test (`descramble(scramble(x)) == x`) proves nothing for a
21//! cipher: it passes for any invertible function. The oracle fixtures are
22//! the gate.
23//!
24//! # Algorithm overview
25//!
26//! DVB-CSA2 combines a **block cipher** and a **stream cipher**, both keyed
27//! by the same 8-byte control word:
28//!
29//! - **Block cipher**: 56-round substitution/permutation network on 64-bit
30//! (8-byte) blocks, applied in a CBC-like chained mode across all
31//! complete 8-byte blocks of the payload.
32//! - **Stream cipher**: LFSR-based byte-stream generator seeded from the
33//! nibble-swapped control word and the encrypted first block as IV,
34//! XOR'd with bytes 8..end of the payload.
35//!
36//! The combination order matters:
37//! - **Encrypt**: block-cipher CBC (last block first), then stream-cipher XOR.
38//! - **Decrypt**: stream-cipher XOR first, then block-cipher CBC undo.
39//!
40//! Payloads shorter than 8 bytes are passed through unchanged (per
41//! libdvbcsa's behaviour).
42//!
43//! # Performance
44//!
45//! The default scalar path processes one 64-bit block at a time. The
46//! `bitsliced` feature enables a bitsliced parallel path that processes
47//! 64 blocks at once, differentially tested against the scalar reference.
48#![cfg_attr(not(feature = "std"), no_std)]
49#![cfg_attr(docsrs, feature(doc_cfg))]
50#![warn(missing_docs)]
51
52mod block;
53pub mod csa;
54pub mod error;
55pub mod key;
56mod stream;
57mod tables;
58pub mod ts;
59
60pub use csa::{descramble, scramble};
61pub use error::Error;
62pub use key::ControlWord;