diff --git a/README.md b/README.md index 7800cd8..6d95edc 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ ## Table of Contents - [Overview](#overview) + - [Deployment Security Model](#deployment-security-model) - [Notices](#notices) - [Features](#features) - [Building](#building) @@ -56,6 +57,21 @@ dvledtx reads a video source file (e.g., MP4), decodes it using FFmpeg, and tran | **Memory** | Hugepages configured (typically 2GB+) | | **Kernel** | IOMMU and VFIO support enabled | +### Deployment Security Model + +dvledtx is intended for deployment on a physically secured, network-isolated media segment: the +TX host, a dedicated L2 switch and the receivers all sit inside a locked cabinet, with all NICs +on the TX host used for transmission onto that switch. + +The transport (SMPTE ST 2110-20) and its PTP timing provide no authentication, encryption or +integrity protection — security is delegated to MTL/ST 2110 and to physical and Layer 2 +isolation. Integrators must therefore verify the deployment assumptions before relying on this +model. + +See **[Deployment Assumptions and Security Model](docs/assumptions.md)** for the trust boundary, +the required deployment assumptions, the security properties the toolkit does not provide, and +the residual risk and mitigations. + ## Notices ### FFmpeg @@ -106,10 +122,7 @@ FFmpeg is an open source project licensed under LGPL and GPL. See https://www.ff ``` If this prints nothing, FFmpeg needs to be reconfigured/rebuilt after installing the packages above — screen capture will otherwise fail at runtime with `x11grab input format not found`. - **`x11grab` only works against an X11 (Xorg) display, not Wayland** — see [Ensuring an X11 session](#ensuring-an-x11-session-required-for-screen-capture) below if you're capturing from a machine's own physical desktop session. - - **Headless machines (no physical monitor)** additionally need a virtual display to capture from — see [Screen capture on a headless machine](#screen-capture-on-a-headless-machine-no-physical-monitor) below, which requires: - ```bash - sudo apt-get install -y xserver-xorg-video-dummy ubuntu-desktop - ``` + - **Headless machines (no physical monitor)** additionally need a virtual display to capture from. This is an optional, environment-specific setup — not a dependency of dvledtx — so it is documented as an example in [Screen capture on a headless machine](#screen-capture-on-a-headless-machine-no-physical-monitor) below. - The stock `mtl_st20p` muxer only exposes `p_port`/`r_port` (2 physical NIC ports). To use more than 2 NICs with the default (non-`ENABLE_MTL_TX`) build, the plugin's `libavdevice/mtl_common.h` must be patched to add `p2_port`..`p7_port` (and matching `p2_sip`..`p7_sip`) AVOptions mapped to `devArgs.port[MTL_PORT_2..MTL_PORT_7]` / `devArgs.sip[...]`, then FFmpeg rebuilt and reinstalled. Without this patch, `nic_count` is effectively capped at 2 for the FFmpeg TX path (the `ENABLE_MTL_TX` direct-pipeline build already supports up to 8 NICs without any patch). ### Build Steps @@ -250,7 +263,12 @@ To capture from a machine's own physical display, make sure that desktop session `x11grab` needs a real X11 display to attach to — it does not work against a raw framebuffer or DRM device. On a machine with no monitor connected, create a virtual display using Xorg with the `dummy` video driver and run a desktop session on it so there's actual content to capture. Unlike Xvfb, a real Xorg server claims physical input devices — your keyboard and mouse work directly on the virtual display. -1. **Install prerequisites** (once): see [Software Requirements](#software-requirements) for the `xserver-xorg-video-dummy`/`ubuntu-desktop` packages and the `x11grab`-enabled FFmpeg build. +> The packages below are **not dvledtx dependencies** — they are only needed to construct a virtual display on a headless host. The following is an example of one way to set this up on Ubuntu; adapt it to your environment as needed. + +1. **Install the virtual-display packages** (once), along with the `x11grab`-enabled FFmpeg build. As an example, on Ubuntu: + ```bash + sudo apt-get install -y xserver-xorg-video-dummy ubuntu-desktop + ``` 2. **Create an Xorg config** for the dummy driver: ```bash @@ -680,6 +698,19 @@ sudo pkill -9 -f dvledtx # Group should be 'vfio' with rw permissions ``` +6. **`pip install` fails with `externally-managed-environment`** + - On newer systems (Ubuntu 24.04+, PEP 668) `pip` refuses to install packages system-wide, which breaks installing the Python build tools (`meson`, `ninja`, `pyelftools`) required by DPDK/MTL. Re-run the install with `--break-system-packages`: + ```bash + pip install --break-system-packages meson ninja pyelftools + ``` + +7. **FFmpeg `./configure` fails with `nasm/yasm not found or too old`** + - Building FFmpeg (and DPDK) requires the NASM assembler. If configuring FFmpeg errors out looking for `nasm`, install it: + ```bash + sudo apt install -y nasm + ``` + - Then re-run FFmpeg's `./configure`. + ## Contributing Contributions are welcome. Please open an issue or submit a pull request on [GitHub](https://github.com/OpenVisualCloud/directview-led-software-toolkit). diff --git a/Security.md b/Security.md index d5f1e5e..21f1f88 100644 --- a/Security.md +++ b/Security.md @@ -1,6 +1,23 @@ # Security Policy Intel is committed to rapidly addressing security vulnerabilities affecting our customers and providing clear guidance on the solution, impact, severity and mitigation. +## Security Model + +dvledtx is designed for deployment on a physically secured, network-isolated media segment. The +transport (SMPTE ST 2110-20) and its PTP timing provide no authentication, encryption or +integrity protection; security is delegated to MTL/ST 2110 and to the physical and Layer 2 +isolation of that segment. + +**In scope:** the dvledtx transmitter application, its JSON configuration parsing, and its use +of FFmpeg and the Media Transport Library. + +**Out of scope:** the receivers (customer-designed, typically FPGA-based, and not delivered with +this toolkit), the LED panels, and the physical and network controls of the installation site. + +The trust boundary, the deployment assumptions this model depends on, and the residual risk if +those assumptions are broken are documented in +[Deployment Assumptions and Security Model](docs/assumptions.md). + ## Reporting a Vulnerability Please report any security vulnerabilities in this project [utilizing the guidelines here](https://www.intel.com/content/www/us/en/security-center/vulnerability-handling-guidelines.html). diff --git a/docs/assumptions.md b/docs/assumptions.md new file mode 100644 index 0000000..b1f594a --- /dev/null +++ b/docs/assumptions.md @@ -0,0 +1,94 @@ +# Deployment Assumptions and Security Model + +dvledtx transmits uncompressed video using the SMPTE ST 2110-20 standard. That transport, and +the PTP timing it depends on, carry no authentication, encryption or integrity protection. The +security of a deployment therefore rests on the **physical and Layer 2 isolation of the media +segment**, not on controls inside this application. + +This document records that trust boundary, the assumptions it depends on, and the risk that +remains if those assumptions are broken. + +## Table of Contents + +- [Trust Boundary and Topology](#trust-boundary-and-topology) +- [Deployment Assumptions](#deployment-assumptions) +- [Security Properties Not Provided by This Toolkit](#security-properties-not-provided-by-this-toolkit) +- [Residual Risk and Defence in Depth](#residual-risk-and-defence-in-depth) + +## Trust Boundary and Topology + +``` + ┌───────────────────── locked cabinet ──────────────────────┐ + │ │ + │ TX host Dedicated Receivers │ + │ (dvledtx) ──▶ L2 switch ──▶ (FPGA) ──▶ LED wall + │ all NICs = TX media + PTP customer- │ + │ VLAN only designed │ + └───────────────────────────────────────────────────────────┘ + ▲ + └── isolation boundary: + no uplink to any other network +``` + +| Element | Role | Position relative to the boundary | +|---------|------|-----------------------------------| +| **TX host** (dvledtx) | Decodes, crops and transmits ST 2110-20 streams | Inside the locked cabinet | +| **Dedicated L2 switch** | Carries media (ST 2110-20) and PTP traffic only | The isolation boundary itself — no uplink to a corporate or building network | +| **Receivers** | Receive streams and drive the LED panels | Inside the cabinet; **customer-designed (typically FPGA-based) and out of scope for this toolkit** | +| **Administrator** | Configures and operates the TX host | Enters through the physical cabinet lock | + +**All NICs on the TX host are used for transmission.** `interfaces[]` may declare up to 8 NICs, +and every one of them is consumed by ST 2110-20 TX onto the dedicated switch. The TX host does +not bridge the media segment to any other network. + +## Deployment Assumptions + +The model above is only valid while all of the following hold. They are the responsibility of +the integrator, and should be verified at installation and after any change to the +installation: + +| # | Assumption | Why it matters | +|---|------------|----------------| +| 1 | The TX host, switch and receivers are installed in a **physically locked cabinet**, with keyed access restricted to authorised administrators | Physical access to the equipment is equivalent to full control over what is displayed on the wall | +| 2 | The switch is **dedicated to the media segment** and has **no uplink** to a corporate, building or guest network | An uplink extends the trust boundary to every network it reaches | +| 3 | **All unused switch ports are administratively disabled** | A live port reachable outside the cabinet — for example a patched wall socket believed to be disconnected — places an attacker directly inside the boundary | +| 4 | Media and PTP traffic run on a **dedicated VLAN**, with no DHCP server and no general-purpose hosts attached to it | Prevents an attached device from being addressed onto the media network, and keeps unrelated traffic off the transmission path | + +## Security Properties Not Provided by This Toolkit + +Transmission is delegated to the +[Media Transport Library (MTL)](https://github.com/OpenVisualCloud/Media-Transport-Library) and +follows the SMPTE ST 2110 standards. dvledtx hands decoded frames to MTL and does not add +security controls above it — the security of the wire is offloaded to physical and Layer 2 +isolation. + +State the following explicitly when assessing a deployment: + +- **No authentication** of ST 2110-20 senders or receivers. +- **No encryption** of the video payload on the wire. +- **No integrity or replay protection** on the media path. +- **No authentication on the PTP path** — PTP is a broadcast protocol with no grandmaster + validation. + +## Residual Risk and Defence in Depth + +Physical isolation reduces exposure but does not eliminate it. If an adversary obtains Layer 2 +access to the media VLAN — for example by connecting to an overlooked live switch port — the +following become feasible and are **not** mitigated in software: + +| Risk | Effect | Mitigation | +|------|--------|------------| +| Injection of a rogue ST 2110-20 stream | Unauthorised or offensive content displayed on the LED wall | Physically block access to the L2 media VLAN (locked cabinet, disabled unused ports, switch port security / 802.1X); operator visual detection of anomalous wall output | +| Rogue PTP grandmaster | TX pacing skew and stream disruption | Keep PTP on the isolated VLAN; leave PTP disabled (default TSC pacing) unless a trusted grandmaster is present | +| Traffic flooding on the media VLAN | Frame loss and visible artefacts on the wall | Dedicated switch with no other traffic; IGMP snooping | +| Passive capture of video | Loss of content confidentiality | Physical isolation only — no encryption is available on the ST 2110-20 path | + +**Detection and response are physical and visual.** There is no in-band alerting: an operator +observes anomalous output on the LED wall, and an administrator unlocks the cabinet to inspect, +disconnect or power-cycle the affected equipment. + +> **Known accepted risk.** Because all authentication and encryption are absent by design of the +> transport, an adversary who defeats the physical and L2 isolation has no further software +> barrier. This is accepted for the current deployment profile and is pending validation by an +> adversarial-testing exercise. This document will be revisited if authentication or encryption +> become available in the underlying transport.