Eerste start: inschrijving voor een vloot WireGuard-apparaten

Het bord start van de gemeenschappelijke image, krijgt een DHCP-lease, en een provisioning-script draait voordat iemand het apparaat heeft aangeraakt. Ergens in dat script moet het een WireGuard-identiteit verkrijgen die bij dit bord hoort en bij geen ander, die identiteit laten autoriseren, en een profiel schrijven dat de gateway accepteert. De image mag de clientsoftware, een nagekeken sjabloon en de publieke sleutel van de gateway bevatten. Wat er nooit in mag zitten, is één privésleutel die de hele vloot deelt, want dat maakt van één gestolen bord een incident voor de hele vloot. De onderstaande volgorde houdt de identiteit lokaal en de autorisatie expliciet.

Wat de image wel en niet bevat

Lever het pakket, het sjabloon met plaatsaanduidingen, de publieke sleutel van de gateway en de inschrijvingsclient mee. Het sjabloon is een vorm, geen geheim: het moet leesbaar zijn voor de provisioning-gebruiker en geen sleutelmateriaal bevatten.

De privésleutel wordt bij de eerste start op het apparaat gegenereerd en verlaat het nooit. Alleen de publieke helft reist mee, in een inschrijvingsverzoek dat wordt geautoriseerd door iets anders dan de eigen bewering van het apparaat over wie het is. Dat onderscheid is wat voorkomt dat een gestolen bord een probleem voor de hele vloot wordt. Het is ook het deel dat de meeste first-boot-scripts verkeerd doen.

Stap 1: de sleutel lokaal genereren

Voer de generatie uit in een beschermde map nadat de onderliggende netwerkverbinding is goedgekeurd en werkt. De subshell houdt de umask-wijziging beperkt tot deze bewerking, en set -C weigert een bestaand bestand te overschrijven:

(
    umask 077
    set -C
    wg genkey > /etc/wireguard/device.key &&
        wg pubkey < /etc/wireguard/device.key > /etc/wireguard/device.pub
)

De WireGuard-snelstart documenteert de sleutelgeneratie-relatie waarop deze twee opdrachten steunen. Wordt de generatie onderbroken, laat het apparaat dan niet-ingeschreven en laat de workflow de bestanden met elkaar in overeenstemming brengen. Verwijder geen bestaande identiteit alleen om het script netjes vanaf het begin te laten lopen.

Bewaar de openstaande sleutel over nieuwe pogingen heen. Bij elke tijdelijke netwerkstoring een identiteit opnieuw genereren is hoe een vloot achterblijft met verweesde peers die niemand aan een apparaat kan koppelen.

Stap 2: een apparaatrecord autoriseren

Stel dat de inventaris dit bord device-042 noemt en er 10.90.0.42/32 aan toekent. De inschrijvingsdienst moet verifiëren dat deze aanvrager recht heeft op dat record. Een serienummer dat in een formulier is getypt is geen bewijs, want serienummers staan op de buitenkant van de doos.

Een bootstraptoken per apparaat, een goedkeuring door een operator of een hardware-ondersteunde attestatie kunnen de claim vestigen. Bescherm de integriteit van het verzoek en de authenticiteit van het antwoord, en vervang niet één gedeeld VPN-geheim door één gedeeld fabrieksgegeven.

Het geregistreerde record verbindt het apparaat, zijn publieke sleutel, zijn toegewezen adres en zijn toegestane beheerrol. WireGuard zelf definieert geen inschrijvings-API, dus die dienst is iets dat je bewust bouwt en beheert.

Stap 3: twee bij elkaar passende configuraties schrijven

Het apparaat heeft een profiel nodig dat de beheerprefixen in de tunnel routeert, en de gateway heeft een peer-entry nodig die alleen het eigen bronadres van dit apparaat toestaat. Met een gateway op 10.90.0.1 en een beheernetwerk van 10.60.0.0/16 ziet de apparaatkant er zo uit:

[Interface]
PrivateKey = <device-042 private key>
Address = 10.90.0.42/32

[Peer]
PublicKey = <trusted gateway public key>
Endpoint = vpn.example.com:51820
AllowedIPs = 10.90.0.1/32, 10.60.0.0/16
PersistentKeepalive = 25

De waarden tussen haken zijn plaatsaanduidingen, geen sleutels. De keepalive is belangrijk wanneer het bord achter NAT zit en bereikbaar moet blijven; hij is niet overal nodig, en hem uit gewoonte toevoegen houdt een radio zonder reden wakker.

Op de gateway is de peer-entry bewust smal:

[Peer]
PublicKey = <device-042 public key>
AllowedIPs = 10.90.0.42/32

Kopieer de bestemmingslijst van het apparaat niet naar de gateway-peer. Op het apparaat zegt die lijst wat er in de tunnel gerouteerd moet worden; op de gateway zegt ze welke bronadressen deze peer mag gebruiken, en dat zijn verschillende uitspraken.

Doorsturen, firewallregels en de terugweg naar het beheernetwerk moeten de goedgekeurde toegang nog steeds toestaan. Een geregistreerde peer is geen toestemming voor elke toepassing erachter.

Stap 4: inschrijving vastleggen als een lifecycle-toestand

Pas het gatewayrecord en het apparaatprofiel toe via wie de bijbehorende configuratie bezit, en markeer de inschrijving pas als voltooid wanneer de bedoelde identiteit en het adres zijn geaccepteerd. Nieuwe pogingen moeten datzelfde record met elkaar in overeenstemming brengen in plaats van een tweede peer of een tweede adres toe te wijzen.

Houd een herstelpad achter de hand voor onderbroken provisioning, inclusief het geval waarin de gateway de sleutel heeft geaccepteerd en het apparaat zijn profiel nooit heeft geschreven.

Wanneer een bord wordt vervangen of uit dienst gaat, verwijder dan zijn publieke sleutel en zijn autorisatie samen. Een nieuwe sleutel is een bewust herinschrijvingsmoment, geen bijwerking van een reimage. Volgorde van werk: lokaal genereren, autoriseren tegen de inventaris, beide kanten schrijven, de toestand vastleggen en dan één beheerverzoek door de tunnel testen.