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

```rust
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

```bash
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

```bash
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.