Security model

vNet is built for an event where the contestant machines are not trusted: a contestant may be root on the machine, may stop or replace the agent, and may send any packet. The organizer machines (conductor and switches) are trusted. This page says what vNet guarantees under that assumption and what it leaves to you.

What a contestant machine cannot do

Reach a machine the rules do not allow

Every packet is checked by a switch against the access list, and checked again by the receiving switch when it crosses between switches. Nothing the machine does changes which rules apply to it.

Pretend to be another machine

A switch binds each connection to the virtual address the conductor assigned to that name, and drops every packet with another source address. The name comes from the conductor, which checked the machine’s key, never from the machine (How a machine joins).

Join without a key and a certificate

The key is checked against the auth file, the certificate against the CA and its role. The certificate’s name is not compared with the machine name: what ties a machine to its name is the key. Keep each machine’s key on that machine only.

Pose as a switch or as the conductor

With VNET_TLS=1 every link is mutual TLS, and each program checks the role written in the peer certificate’s OU field: an agent certificate cannot open a switch or conductor link. A switch also refuses a hello from a peer the conductor did not pair it with, with a per-pair token.

Flood a switch

The per-agent rate limit caps what one machine can send; the switch serves connections in turns, so one busy link does not hold the others.

Read other machines’ traffic on the wire

The links are TLS; packets between machines travel inside them.

What vNet does not do

Filter the physical network

The switch only sees what enters the TUN. A machine can still reach its physical LAN, and the internet over IPv6, unless the host firewall blocks it. That is what lockdown is for (Lock down contestant machines). Lockdown is enforced by the agent on a machine you do not trust: it stops honest mistakes and casual attempts, not a contestant who is root and removes it. For a hard guarantee, filter at the physical network as well (switch ports, VLANs, the room’s firewall), so that a machine’s only way out is the overlay.

Filter ports

An allowed pair of machines may use any protocol and port.

Inspect content

vNet decides by addresses only.

Protect a compromised organizer machine

A switch or conductor with a stolen key and certificate is trusted. Keep ca.key off every machine: it is needed only to issue certificates.

Keys and certificates

  • Each machine has a key (a random string in the auth file and in the machine’s environment) and, with TLS, its own certificate and private key. vnet-roster generates both (Roster and vnet-roster); the certificates come from tools/vnet-certs.sh (Manage certificates).

  • Give the key in VNET_AUTH_KEY_FILE or VNET_AUTH_KEY rather than on the command line, where every local user can read it in the process list.

  • Keys are compared in constant time.

  • The conductor refuses to start without an auth file and TLS, and the switch and agent refuse to start without TLS, unless VNET_ALLOW_INSECURE=1 is set. Use that only in a lab.