Beveiligingsrichtlijnen

De winapp CLI maakt lokale Windows ontwikkeling eenvoudig: het kan een handtekeningcertificaat genereren, vertrouwen op uw computer en de ontwikkelaarsmodus voor u inschakelen. Elk van deze stappen wijzigt de computerstatus of maakt een bestand dat een persoonlijke sleutel bevat, zodat het helpt precies te weten wat ze doen.

Op deze pagina wordt het gevolg van elke opdracht uitgelegd, hoe u deze ongedaan maakt en wat u anders moet doen wanneer u verzendt. Ontwikkelingscertificaten en ontwikkelaarsmodus zijn het normale, ondersteunde pad voor lokale tests. Het doel hier is dat u begrijpt wat u aan het kiezen bent, niet dat u ze vermijdt.

Ontwikkelingscertificaten

MSIX-pakketten moeten zijn ondertekend voordat Windows ze installeert. Voor lokale tests winapp cert generate maakt u een zelfondertekend certificaat, zodat u uw eigen pakket kunt ondertekenen en installeren zonder iets te kopen.

Wat winapp cert generate creëert

Het gegenereerde certificaat is een zelfondertekend codeondertekeningscertificaat voor eindentiteiten:

Property Value
Key RSA 2048-bits, gemarkeerd als exporteerbaar
Handtekening-algoritme SHA-256 met RSA (PKCS#1 v1.5)
Sleutelgebruik Digitale handtekening
Uitgebreid sleutelgebruik Ondertekening van code (1.3.6.1.5.5.7.3.3)
Basisbeperkingen Geen certificeringsinstantie
Geldigheid Standaard 365 dagen (--valid-days)
Onderwerp Moet overeenkomen met het Publisher in uw manifest

Met de opdracht worden twee dingen geschreven:

  • devcert.pfx in de huidige map (of het pad dat je doorgeeft aan --output). Dit bestand bevat zowel het certificaat als de bijbehorende persoonlijke sleutel.
  • Een kopie van het certificaat in uw persoonlijke certificaatarchief (Cert:\CurrentUser\My).

Met --export-cer, schrijft het ook een .cer bestand naast de .pfx. Dit bestand bevat alleen het openbare certificaat, geen persoonlijke sleutel, waardoor het het juiste is om een teamgenoot of een testmachine te overhandigen die uw builds moet vertrouwen.

Note

Een zelfondertekend certificaat wordt door niemand vertrouwd totdat iemand het expliciet vertrouwt. Het is prima voor uw eigen machine en uw eigen testmachines; het is geen vervanging voor een echte identiteit voor ondertekening van programmacode wanneer u uw app distribueert.

Het standaardwachtwoord

winapp cert generate gebruikt password als het PFX-wachtwoord, tenzij u --password opgeeft. Dezelfde standaardinstelling is van toepassing wanneer u dat certificaat later aan winapp sign doorgeeft, waarvoor de wachtwoordoptie ook --password is, en aan winapp pack, dat --cert-password gebruikt.

Een bekend wachtwoord betekent dat de persoonlijke sleutel devcert.pfx effectief onbeveiligd is: iedereen die het bestand verkrijgt, kan er code mee ondertekenen. Dat is een acceptabele afweging voor een wegwerpcertificaat dat alleen ooit wordt gebruikt om lokale testbuilds op uw eigen computer te ondertekenen, en daarom is dit de standaardinstelling.

Important

Behandel het standaardwachtwoord als een signaal dat het certificaat wegwerpbaar is. Als een certificaat ooit wordt gebruikt om iets te ondertekenen dat iemand anders gaat installeren, mag het geen certificaat met het standaardwachtwoord zijn winapp cert generate . Zie Ondertekening voor productie.

Scripts en agents hoeven het wachtwoord niet zelf te vergelijken: winapp cert generate --json rapporteert "defaultPasswordIsPublic": true en herhaalt de openbaarmaking in een warnings matrix wanneer de standaardinstelling van kracht is. Zie de JSON-uitvoer van het certificaat genereren.

Waar het certificaatbestand zich bevindt

devcert.pfx is een persoonlijke sleutel op schijf. Twee regels houden het uit de problemen:

Leg het niet vast.winapp cert generate voegt automatisch de bestandsnaam van het certificaat toe aan de .gitignore ernaast, zodat de standaardstroom al wordt gedekt. Als u het bestand verplaatst, de naam wijzigt of het genereert in een map die door een andere .gitignore wordt beheerd, controleer dan of de vermelding is meegegaan:

git check-ignore -v devcert.pfx

Als er niets wordt afgedrukt, wordt het bestand niet genegeerd. Voeg het toe voordat u het doorvoert.

Neem het niet op in het pakket.winapp pack verpakt alles in de invoermap, zodat een devcert.pfx in de uitvoermap van uw app in de geleverde MSIX terechtkomt. Genereer het certificaat buiten de map die u verpakt, zoals de handleiding voor het verpakken van een EXE/CLI laat zien, en controleer of het niet aanwezig is voordat u het verspreidt:

# Unpack the package and check that no certificate is inside
winapp tool makeappx unpack /p .\MyApp.msix /d .\inspect /o
Get-ChildItem .\inspect -Recurse -Include *.pfx, *.cer

Tip

Als een .pfx met een echte privésleutel ooit wordt gecommit of gepubliceerd, vervang het dan onmiddellijk: genereer een nieuw certificaat, onderteken het opnieuw en vertrouw het oude certificaat niet meer met behulp van de stappen in Een vertrouwd certificaat verwijderen. Als u het bestand uit een latere doorvoering verwijdert, wordt het niet uit de geschiedenis verwijderd.

Wat winapp cert install toekent

winapp cert install voegt het certificaat toe aan het LocalMachine\TrustedPeople archief. Hiervoor zijn beheerdersbevoegdheden vereist, omdat deze de vertrouwensrelatie voor elke gebruiker op de computer wijzigt.

Zodra een certificaat binnen isTrustedPeople, accepteert Windows elk MSIX-pakket dat door dat certificaat is ondertekend als vertrouwd genoeg om te installeren, niet alleen het pakket dat u test. Voor een certificaat waarvan u de persoonlijke sleutel bewaart en lokaal bewaart, is dat precies het beoogde effect. Het is ook de reden om er bewust over te zijn:

  • Vertrouw certificaten die u zelf hebt gegenereerd of die afkomstig zijn van iemand die u software op de computer zou laten installeren.
  • Installeer geen ontwikkelaarcertificaat op gedeelde, productie- of buildmachines waar anderen van afhankelijk zijn.
  • Geef er de voorkeur aan om de .cer (alleen de openbare sleutel) te verspreiden in plaats van de .pfx, wanneer een collega uw testpakket moet installeren. Ze krijgen de mogelijkheid om uw builds te vertrouwen zonder de mogelijkheid te krijgen om zich als u aan te melden.

Om een .cer op een andere testmachine te vertrouwen, voert u winapp cert install daar rechtstreeks op uit — deze opdracht accepteert zowel een .pfx als een uitsluitend openbare .cer:

# Run as Administrator
winapp cert install .\devcert.cer

Het equivalent waarbij alleen ingebouwde Windows hulpprogramma's worden gebruikt, is:

# Run as Administrator
Import-Certificate -FilePath .\devcert.cer -CertStoreLocation Cert:\LocalMachine\TrustedPeople

Een vertrouwd certificaat verwijderen

Ontwikkelingscertificaten verlopen standaard na een jaar, maar verlopen betekent niet dat ze worden verwijderd. Wanneer u een certificaat niet meer nodig hebt — het project is beëindigd, de machine wordt opnieuw ingezet of de sleutel is mogelijk uitgelekt — verwijder het dan expliciet.

Zoek eerst de vingerafdruk:

Get-ChildItem Cert:\LocalMachine\TrustedPeople |
    Where-Object { $_.Subject -like '*CN=Contoso*' } |
    Format-List Subject, Thumbprint, NotAfter

Verwijder het vervolgens uit de vertrouwensopslag van het apparaat. Voor deze stap is uitbreiding nodig:

# Run as Administrator. Replace with the thumbprint from the previous command.
$thumbprint = 'ABCD...'
Remove-Item -Path "Cert:\LocalMachine\TrustedPeople\$thumbprint"

cert generate heeft het certificaat ook, samen met de privésleutel, in uw persoonlijke opslag geplaatst. Verwijder dat vanuit een normale, niet-verhoogde opdrachtprompt, aangemeld met het account waarmee cert generate is uitgevoerd:

$thumbprint = 'ABCD...'
Remove-Item -Path "Cert:\CurrentUser\My\$thumbprint"

Important

Voer de twee bovenstaande opdrachten uit in de weergegeven contexten. Als u verhoogde bevoegdheden hebt verkregen met een ander beheerdersaccount, is Cert:\CurrentUser in die sessie met verhoogde bevoegdheden de certificaatopslag van die beheerder — niet die van u — zodat de persoonlijke sleutel achterblijft in de opslag van de gebruiker die de sleutel heeft gegenereerd.

Verwijder ten slotte .pfx en alle eventuele .cer-kopieën die u hebt verspreid, en maak de registratie ongedaan van pakketten die u daarmee hebt gesideload:

winapp unregister

Note

Als u het certificaat verwijdert, worden er geen pakketten verwijderd die er al mee zijn geïnstalleerd. Verwijder deze afzonderlijk via Instellingen > Apps > Geïnstalleerde apps, of met winapp unregister voor pakketten die in de ontwikkelmodus zijn geregistreerd.

Ontwikkelaarsmodus

Windows vereist dat de ontwikkelaarsmodus een app-pakket rechtstreeks vanuit een map op schijf registreert, een losse indeling, in plaats van een ingebouwde, ondertekende MSIX te installeren. Opdrachten zoals winapp run en create-debug-identity vertrouwen erop en mislukken zonder, en winapp init biedt aan om deze voor u in te schakelen.

Wat er verandert als u dit inschakelt

De CLI maakt de ontwikkelaarsmodus mogelijk door twee DWORD waarden te schrijven onder HKEY_LOCAL_MACHINE:

HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock
    AllowDevelopmentWithoutDevLicense = 1
    AllowAllTrustedApps               = 1

Omdat dit instellingen voor de hele machine zijn, start de CLI een helperproces met verhoogde bevoegdheden en Windows een prompt voor gebruikersaccountbeheer weergeeft. Er wordt niets gewijzigd als u de prompt weigert.

Praktisch betekent dit dat de machine:

  • Registreer app-pakketten rechtstreeks vanuit een map op schijf, zonder dat ze zijn ingebouwd in een MSIX of helemaal zijn aangemeld (AllowDevelopmentWithoutDevLicense).
  • Installeer app-pakketten van buiten de Microsoft Store zolang ze zijn ondertekend door een certificaat dat de machine vertrouwt, inclusief elk ontwikkelingscertificaat in TrustedPeople (AllowAllTrustedApps).

Important

De ontwikkelaarsmodus plus een vertrouwd ontwikkelingscertificaat is een opzettelijke versoepeling van de standaardinstallatiebeperkingen. Die combinatie hoort thuis op ontwikkel- en testmachines. Laat deze uitgeschakeld op productiemachines, kiosken en gedeelde infrastructuur.

Bepalen wanneer het is ingeschakeld

winapp init vraagt voordat u iets wijzigt en --use-defaults slaat de vraag volledig over, waardoor de ontwikkelaarsmodus ongewijzigd blijft. Dat maakt gescripte uitvoeringen en CI-uitvoeringen standaard veilig:

winapp init --use-defaults

Als u de instelling liever zelf beheert, schakelt u deze eenmalig in via Instellingen > Systeem > Voor ontwikkelaars > Ontwikkelaarsmodus en de CLI zal dit detecteren en doorgaan.

Uitschakelen

Gebruik instellingensysteem >> voor ontwikkelaars en schakel de ontwikkelaarsmodus uit. Dit is het aanbevolen pad, omdat instellingen ook de bijbehorende besturingssysteemstatus opschonen. Ga als volgt te werk om de registerwaarde achteraf te bevestigen:

Get-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' `
    -Name AllowDevelopmentWithoutDevLicense, AllowAllTrustedApps

Als u de ontwikkelaarsmodus uitschakelt, worden vertrouwde certificaten of reeds geïnstalleerde pakketten niet verwijderd. Zie Een vertrouwd certificaat verwijderen.

Ondertekenen voor productie

Een ontwikkelingscertificaat werkt alleen voor personen die het expliciet hebben vertrouwd. Als u uw app wilt distribueren, ondertekent u deze met een identiteit die Windows al vertrouwt.

Een handtekeningidentiteit kiezen

  • Vertrouwde ondertekening van Azure: een in de cloud beheerde ondertekeningsservice. De persoonlijke sleutel staat nooit op uw buildcomputer, dus is er geen .pfx om met de hand te beveiligen, te lekken of te roteren. Gebruik winapp az-sign, waarmee wordt geverifieerd met de standaard-Azure referentieketen en werkt met GitHub Actions OIDC of een beheerde identiteit.

    winapp az-sign .\MyApp.msix

  • Een certificaat voor ondertekening van programmacode van een vertrouwde certificeringsinstantie : geef het winapp sign door als het tweede positionele argument, met het bijbehorende wachtwoord in --password. Vervolgens bent u verantwoordelijk voor het veilig opslaan van het sleutelmateriaal; bewaar het in een hardwaretoken, een sleutelkluis of het geheime archief van uw CI-provider en nooit in de opslagplaats.

  • De Microsoft Store — als u uitsluitend via de Store distribueert, ondertekent het het pakket voor u en hoeft u zich niet te ondertekenen voordat u het inzendt.

In elk geval moet het certificaatonderwerp overeenkomen met de Publisher waarde in uw manifest, inclusief voor sparse-pakketten.

Houd ondertekeningsgeheimen uit de repository

Certificaatwachtwoorden horen bij uw CI-geheimarchief, niet in een configuratiebestand. Lees ze uit de omgeving in plaats van ze hard te coderen:

winapp sign .\MyApp.msix $env:SIGNING_CERT_PATH --password $env:SIGNING_CERT_PASSWORD

Hetzelfde geldt voor de buildconfiguratie die is ingecheckt bij broncodebeheer, zoals een Electron Forge-configuratie - zie Electron-verpakking. winapp az-sign vermijdt het probleem volledig, omdat er geen wachtwoord is om door te geven.

Voordat u publiceert

Een korte controlelijst voor de overgang van lokaal testen naar distributie:

  • Het pakket is ondertekend met een door een CA uitgegeven certificaat, Vertrouwde ondertekening van Azure of verzonden naar de Store, niet met devcert.pfx.
  • Er zit geen .pfx- of .cer-bestand in de verpakte uitvoer.
  • Er wordt geen certificaatwachtwoord weergegeven in vastgelegde bestanden, buildscripts of CI-logboeken.
  • Het certificaatonderwerp komt overeen met het manifest Publisher.
  • Ontwikkelingscertificaten en ontwikkelaarsmodus zijn niet ingeschakeld op computers die de app alleen hoeven uit te voeren .

Een beveiligingsprobleem melden

Als u een beveiligingsprobleem in de winapp CLI zelf wilt melden, volgt u het proces in SECURITY.md. Maak geen openbare GitHub-issue aan voor het melden van beveiligingsproblemen.

  • Last updated on