simulcrypt 0.2.2

DVB SimulCrypt (ETSI TS 103 197) head-end protocol: ECMG client, EMMG server, control words
Documentation

simulcrypt

Async Rust implementation of the DVB SimulCrypt head-end protocol (ETSI TS 103 197) for the scrambler (SCS) side:

  • ECMG client: channel and stream setup, CW_provision, ECM_response, channel_test keepalive, reconnect with CW replay.
  • EMMG server: channel and stream setup, bandwidth allocation, data_provision over TCP, and over UDP when EmmgConfig::udp is set.
  • Control word generation and rotation per crypto period, one CW group shared by any number of CAS.
  • ECM carousel: the current ECM of each stream as TS packets on its ecm_pid, repeated at the ECMG's ECM_rep_period (100 ms by default).
  • EMM as TS packets on EmmgConfig::pid.

Scrambling and PSI/SI belong to the caller.

Usage

use std::time::Duration;

use simulcrypt::{
    CasConfig,
    EcmgConfig,
    EmmgConfig,
    Event,
    ServiceCas,
    ServiceConfig,
    Simulcrypt,
};

let simulcrypt = Simulcrypt::new();

let lease = simulcrypt.acquire_cas(CasConfig {
    id: "cas-1".into(),
    name: "CAS 1".into(),
    super_cas_id: 0x0B00_0001,
    first_stream_id: 1,
    ecmg: EcmgConfig::new(1, "10.0.0.5:2222".parse()?),
    emmg: Some(EmmgConfig::new(9000)),
})?;

let mut service = simulcrypt.open_service(&ServiceConfig {
    name: "channel-1".into(),
    crypto_period: Duration::from_secs(10),
    cas: vec![ServiceCas { cas: lease.cas(), ecm_pid: 100, access_criteria: vec![] }],
})?;

while let Some(event) = service.recv().await {
    match event {
        Event::Cw { parity, cw, .. } => { /* load cw into the parity slot */ }
        Event::Ts(packets) => { /* ECM and EMM packets: insert into the stream */ }
        Event::Ecm { .. } => { /* raw ECM, when packetizing it yourself */ }
        Event::Emm { data, .. } => { /* packetize into emm_pid */ }
        Event::State { cas, state } => { /* log */ }
    }
}

The crate spawns its tasks on the ambient Tokio runtime and does not own one. acquire_cas registers a CAS and returns a CasLease; the CAS stays registered while any lease of it lives. acquire_cas with the id of a registered CAS applies the new settings to it and returns one more lease: open services keep running, the ECMG connection restarts and the EMMG channel moves when their settings change. When the last lease drops, the CAS is detached from open services, which keep running on their other CAS, and an EMMG listener closes with the last CAS on its port.

Every service runs its own ECM carousel with its own continuity counters. It reads the latest ECM of each stream at every repetition and advances while the application polls recv. With EmmgConfig::pid set, each EMM also goes out once as TS packets on that PID, with one continuity counter per CAS; with broadcast, a service takes each EMM from its first stream of the CAS. An ecm_pid or EMM PID outside 0x0020..=0x1FFE gets raw Event::Ecm/Event::Emm only.

status reports each CAS: connection state, the last ECMG error (kept after a reconnect), handshake count and, per stream, readiness, the crypto period on air and ECM/EMM counters. emmg_status reports each EMMG port: open connections and UDP datagrams dropped without a reply.

Dropping the last Service of a CAS closes its streams and the ECMG channel; the CAS stays registered and reconnects on the next open_service. An EMMG channel belongs to the connection that set it up until CHANNEL_CLOSE or disconnect.

With EmmgConfig::udp the EMMG port also accepts data_provision datagrams on UDP, one message per datagram. Channel and stream setup stay on TCP: a datagram is delivered only to a stream currently set up over a TCP connection from the same IP, addressed by its channel and stream ids or, when they are absent, by client_id and data_id. Anything else is dropped without a reply.

Examples

cargo run --example service     # one CAS, prints all events
cargo run --example multi_cas   # one service, two CAS
cargo run --example status      # periodic Simulcrypt::status()

Each example reads the ECMG address and service settings from environment variables (ECMG_HOST, ECMG_PORT, SUPER_CAS_ID, ...) with loopback defaults. TSDuck tsecmg --port 2222 works as a test ECMG.

Development

cargo +nightly fmt --all
cargo clippy --all-targets -- -D warnings
cargo test --all-targets

Formatting uses unstable options from rustfmt.toml, so rustfmt needs the nightly toolchain. tests/integration/ runs the crate against fake ECMG and EMM generator peers on loopback.